İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Wasm eklenti sözleşmesi

Aggrega’nın derleme hattı, WebAssembly (Wasm) eklentilerinin derleyicinin davranışını genişlettiği belirlenmiş soket noktaları içerir: yönetişim soketinin dört rolü, bunlar arasında topoloji oluşturma aşamasında bir Mutation Gate ve statik analiz aşamasında bir Validation Gate; FeatureRecipe ve Recipe adımları için bir render sonrası eklenti hattı; bir provider-rendering soketi; bir ayrıştırıcı soketi; bir içe aktarıcı soketi; ve bant dışı bir linting soketi. Bu sayfa herkese açık Wasm eklenti sözleşmesini belgeler: hangi soketlerin bulunduğu, her soketin neyi tüketip neyi ürettiği, her soketin derleme hattında nerede yer aldığı ve her eklentinin içinde çalıştığı sandbox.

Bu sayfa soketleri, yani hat noktalarını ve bunların girdi/çıktı biçimlerini ele alır. Eklenti için, yani Plugin varlığı, dışa aktarım başına yetenek talepleri, çalışma zamanı sınırları ve yayımlama→çekme→derleme yaşam döngüsü için Wasm eklenti geliştirici kılavuzuna bakın.

Aggrega, eklentileri bir AOT saflığı güvenlik duvarının arkasında yükleyip yürüten bir Wasm ana makine çalışma zamanı — Wazero motoru üzerinde Extism — barındırır: ana makine konuğa sıfır ortam yeteneği verir — ağ yok, dosya sistemi yok, ortam yok, atılan stdio, derlemeden bağımsız sabit bir ana dondurulmuş gözlemlenebilir duvar saati — böylece bir eklenti derleyicinin önceden derleme (ahead-of-time) güvencelerini bozamaz. Yükleme sırasındaki içe aktarma modülü kuralı, örnekleme zamanındaki retler ve seçilmiş ana makine fonksiyonlarıyla tam yetenek yüzeyi aşağıdaki sandbox sözleşmesi bölümündedir. Plugin yazarları ana makineyi üç dilli PDK (Go, Rust, TypeScript) aracılığıyla hedefler. aggrega lint, linter soketini — standart yayımlama linter’ını — ana makine üzerinden yönlendirir. aggrega build, bir çalışma alanı yapılandırdığında yönetişim soketinin derleme zamanı rollerini yönlendirir: çözümleme sırasında açıklama dönüştürme rolü ve topoloji oluşturma sırasında etiket dönüştürme rolü (ikisi de çıktıyı şekillendirir), ayrıca statik analizde IR kararı ve işlenmiş yapıtlar üzerinde işleme kararı. Her biri, o role bağlı bir eklenti olmadığında işlem yapmaz; bu nedenle yönetişim yapılandırması olmayan bir derleme değişmez. aggrega build ayrıca işlemeyi kapatan eklenti hattında FeatureRecipe ve Recipe pipeline: tanımını yönlendirir — bildirilen her adım, işlenmiş belge kümesine karşı ana makine üzerinden çalışır, adımın RFC 6902 yamalarını uygular ve yan etkilerini yayar. Bkz. Dilin durumu → Derleme hattı aşamaları.

Sandbox sözleşmesi

Her soket kendi eklentisini aynı ana makine sandbox’ı üzerinden çalıştırır. Sandbox’ın birbirinden bağımsız iki katmanı vardır — yüklemede yapısal bir denetim ve örneklemede yetenek reddi — ve bu ikisi birlikte bir eklentinin neye erişebileceğini, neye erişemeyeceğini ve neden sorumlu olduğunu tanımlar.

İçe aktarma modülü kuralı (yükleme zamanı). Yükleyici, eklenti ikili dosyasının içe aktarma bölümünü dolaşır ve işlev içe aktarmalarını yalnızca üç modül ad alanı altında kabul eder: wasi_snapshot_preview1 (bir konuk dil çalışma zamanının bağlandığı WASI preview-1 çalışma zamanı), extism:host/env (Extism çalışma zamanı ABI’si — PDK’nın kendi bellek ve IO iç işlevleri) ve extism:host/user (Aggrega’nın seçilmiş ana makine işlevleri). Bir konuk, izin verilen bir modül altında herhangi bir işlev adını içe aktarabilir; başka herhangi bir modül altındaki bir içe aktarma, ana makinenin sağlamadığı bir yüzeyi adlandırır ve eklenti, modülü ve içe aktarmayı adlandıran bir tanılama ile yüklemede reddedilir. Kural, tek tek WASI işlev adlarını bilinçli olarak sansürlemez: statik bağlanmış bir dil çalışma zamanı, canlı kod yollarının hiç çağırmadığı dosya sistemi ve soket işlevlerini içe aktarır — bağımlılıklar üzerinden dolaylı olarak çekilir — ve bir içe aktarmayı adlandırmak hiçbir yetki vermez. G/Ç olmamasını güvence altına alan, içe aktarma sansürü değil, örneklemedeki yetenek reddidir.

Sıfır ortam yeteneği (örnekleme). Ana makine, konuğu gerçek WASI davranışıyla ve sıfır ortam yetkisiyle örnekler:

  • dosya sistemi yok — önceden açılmış dizin yoktur, bu nedenle bir dosya sistemi çağrısı çağrı sınırında başarısız olur;
  • ağ soketi yok;
  • boş bir ortam;
  • atılan stdio — konuğun stdout veya stderr’e yazdığı hiçbir şey ana makinenin akışlarına ulaşmaz;
  • derlemeden bağımsız bir ana sabitlenmiş, dondurulmuş gözlemlenebilir duvar saati; böylece zamanı okuyan bir konuk, derleme zamanını çıktısına sızdıramaz;
  • gerçek, ilerleyen bir monoton saat — bir konuk dil çalışma zamanının önyükleme için buna ihtiyacı vardır ve monoton zaman bir duvar saati anını değil, geçen süreyi ölçer;
  • gerçek ana makine entropisi — sabitlenmiş entropi, bir dil çalışma zamanının iç karma tohumunu sabitler ve konuk belirsizliğinin farklı çıktı olarak ortaya çıkmasına izin vermek yerine onu maskelerdi;
  • argv olarak tek bir yapay program adı.

Bir konuğun gerçekten yaptığı bir G/Ç çağrısı — bir dosya açmak, bir sokete bağlanmak — çağrı sınırında başarısız olur. Bu, WASI’nin kendi yetenek tabanlı güvenlik modelidir: sandbox kodu denetlemek yerine yeteneği reddeder.

Girdiler yalnızca yük ve seçilmiş ana makine işlevleri üzerinden gelir. Bir eklenti, işlediği veya değerlendirdiği her şeyi soketinin taşıdığı yükte alır — grafik ve düğüm izdüşümleri, değerler ve işleme bağlamı. Bir yükün hangi kodlamayla geldiği her soket için sabittir ve aşağıda o soketin kendi bölümünde belirtilir; yayımlanan her yük türü, soketinin kodlaması için bir kodlama ve bir kod çözme giriş noktasıyla gelir, böylece bir konuk bir ayrıştırıcı seçmek yerine tek bir işlevi çağırır. Kaynaklı bir sağlayıcı işlemesi için yük, kaynak baytları yerine bir kaynak listesi taşır: düğümün kaynak kökü altındaki sıralı bir {path, is_dir} girdileri kümesi; ana makine bunu hiçbir sağlayıcı düzenine göre yorumlamaz. Konuk kendi düzen mantığını uygular — tek compose dosyasını seçmek, bir chart köküne inmek, bir Chart.yaml gerektirmek, bir modülü özyinelemeli olarak dahil etmek — ve seçtiği dilimi tam olarak bir ana makine geri çağrısı üzerinden geri okur. Yükün ötesinde ana makine, seçilmiş, en az ayrıcalıklı bir ana makine işlevleri kümesi bağlar ve bir eklentiye tam olarak ikili dosyasının içe aktardıklarını verir:

  • aggrega_log — ana makinenin günlük hedefine bir günlük satırı.
  • aggrega_emit_warning — ana makinenin çağrıdan sonra gösterdiği yapılandırılmış bir uyarı.
  • aggrega_fetch_external_input — harici girdi getirme kanalı (aşağıda).
  • aggrega_pack_source — kaynak seçimi geri çağrısı: konuk, kaynak kökü altında bir {file | dir | tree, path} seçimi adlandırır ve ana makine tam olarak bunu, yolları kök altında çözümleyen ve .. öğesini reddeden bir sandbox altında okuyup paketler.
  • aggrega_read_source_file — içeriğe bağlı kaynak seçimi için aynı sandbox altında tek dosyalık bir içerik okuması.
  • aggrega_parse_source — üretici tüketimi geri çağrısı: konuk sözdizimsel bir biçim adlandırır ve kaynak baytlarını teslim eder; ana makine o biçim için bir ayrıştırıcı çözümler, çalıştırır ve ürettiği kanonik ağacı döndürür. Bir tüketicinin, bir üretici konuğu kendisi çağırmak yerine bir üreticinin çıktısını ana makine üzerinden elde etmesi bu yolla olur; ana makine bunu tek bir düzeyle sınırlar — bu yolla ulaşılan ve onu yeniden çağıran bir üretici reddedilir — bu nedenle bir tüketici onu kaynak başına bir kez çağırır ve birçok kaynağı sırayla tüketebilir.

Ana makine, bir eklentinin içe aktardığı kümeyi .wasm ikili dosyasından türetir, seçilmiş izin listesine göre doğrular ve konuğun describe() işlevinin bildirdiği ana makine işlevleriyle çapraz denetler. aggrega plugin sync bu kümeyi varlığın spec.runtime.hostFunctions alanına kaydeder ve yayımlama, kaydı ikili dosyadan farklı olan bir varlığı reddeder; böylece her eklentinin ana makine yüzeyi katalogda görünür ve ikili dosyadan sapamaz.

Geri çağrı hataları, hostfunc_error_code altında makinece eşleştirilebilir bir kod taşır. Yanıt döndüren ana makine geri çağrıları — aggrega_fetch_external_input, aggrega_pack_source, aggrega_read_source_file ve aggrega_parse_source üretici tüketimi geri çağrısı — hatayı bant içinde iletir: yanıt zarfı, insan tarafından okunabilir bir ileti ve onun yanında, kapalı bir sözlükten alınan, hostfunc_error_code altında isteğe bağlı, makinece eşleştirilebilir bir kod taşır. İleti bir insan için serbest biçimli metindir; kod ise bir konuğun iletiyi ayrıştırmadan üzerinde dallandığı kararlı kimliktir. Başarıda kod yoktur; hatada ana makine ikisini de ayarlar. PDK bu çifti, metni ileti olan ve kod alanı bir konuğun dilin yeniden dışa aktarılan kod sabitleriyle eşleştirdiği türlü bir hata olarak sunar. Bir konuk, eksik bir kodu ve tanımadığı bir kodu iletiye geri dönerek tolere eder — dolayısıyla bir kod üzerinde eşleştirme, her zaman mevcut olan iletinin üzerine eklenen en iyi çaba esaslı bir iyileştirmedir, asla onun yerine geçmez. Kapalı değer kümesi ana makine işlevi hata kodu şemasıdır.

🔴 Bu sınırda bir hatayı iki farklı sözlük adlandırır ve okuduğunuz anahtar hangisini tuttuğunuzu söyler. Bunları karıştırmak burada vurgulanmaya değer tek hatadır, çünkü ikisinden gelen bir değer de düz bir dizedir ve ne ana makine ne de konuk hangi kümeden geldiğini denetler.

  • hostfunc_error_code, ana makinenin bir konuğa gönderdiği bir yanıtta. Değeri, yukarıda bağlantısı verilen kapalı kataloğun bir üyesidir — bir ana makine geri çağrısının başarısız olabileceği yolları adlandıran sabit, yavaş değişen bir liste. Küme kapalı olduğundan bir konuk, bir değeri kitinin yeniden dışa aktardığı adlandırılmış bir sabitle eşleştirip sonuca göre dallanabilir.
  • condition_short_code yanında condition_code, bir konuğun ana makineye döndürdüğü bir soket çıktısında. Bunlar, konuğun kendisinin yükselttiği bir durdurma koşulunun iki tanımlayıcısıdır ve katalogdan değil, derleyicinin kaydettiği açık, büyüyen koşullar kümesinden gelirler. condition_code, koşulun altında kaydedildiği açıklayıcı koddur; condition_short_code ise bir okuyucunun alıntıladığı, aradığı ve bir rapora yapıştırdığı kısa biçimdir — E harfi ve dört rakam. Ana makine kısa kodu, işlediği tanılamanın köşeli parantezli başlığında yazdırır; böylece bir konuğun yükselttiği bir koşul, derleyicinin yükselttiği bir koşul gibi aynen alıntılanabilir. Ana makine iki değeri de türetmez, ancak onları denetler: bu derleyicinin bildirdiği hiçbir koşula ya da numarası kullanımdan kaldırılmış bir koşula çözümlenen kısa bir kod, hiçbir şeye çözümlenmeyen bir tanımlayıcı olarak okuyucuya ulaşmak yerine derlemeyi durdurur.

Konuk tarafındaki iki tanımlayıcı birlikte bildirilir: birini ayarlayıp diğerini ayarlamayan bir konuk, ana makinenin çözümleyemeyeceği bir koşul adlandırmış olur ve ana makine bu durumda bunun yerine kendi genel eklenti hatası koşulunu bildirir; ileti yine hatanın tamamını taşır. Ayrıca bir condition_code hiçbir zaman ana makine işlevi kataloğunun üyesi değildir; dolayısıyla birini yeniden dışa aktarılmış bir sabitle karşılaştırmak hiçbir zaman eşleşmez — her anahtarın genel olarak hatayı değil kendi sözcük dağarcığını adlandırmasının nedeni budur.

Her geri çağırmanın yuvaları belirtilmiş bir kodlama taşır ve bir yük belgesi tutan her yuva onu ikili olarak tutar. aggrega_log’un sayısal düzeyi dışında, bir ana makine geri çağırmasının aldığı her bağımsız değişken konuk belleğine bir işaretçidir; yanıt döndüren bir geri çağırma da bir işaretçiyle yanıt verir. Bu yuvaların her birinin ne tuttuğu her geri çağırma için sabittir:

Geri çağırmaBağımsız değişken yuvalarıYanıt yuvası
aggrega_log, aggrega_emit_warningUTF-8 metin — yük belgesi yokyanıt yok
aggrega_fetch_external_inputyalın bir UTF-8 URL — yük belgesi yokkanonik CBOR
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_sourcekanonik CBOR (RFC 8949 §4.2.1)kanonik CBOR

Tablo, geri çağırmanın kimliğine göre değil her yuvanın ne tuttuğuna göre ayrılır: bir yük belgesi tutan yuva kanonik CBOR taşır, yalın bir dize — bir günlük satırı, bir tanılama alanı, bir URL — tutan yuva ise UTF-8 metin taşır. İki yuvası farklı olan tek geri çağırma aggrega_fetch_external_input’tur: bağımsız değişkeni UTF-8 metin olarak okunan yalın bir URL’dir, yanıtı ise kanonik CBOR biçiminde bir yük belgesidir.

Bir konuğun yük taşıyan bir yuvada ne yaptığı ve ne yapmaması gerektiği. 🔴 Bir yük belgesi tutan yuva UTF-8 metin değil, opak bir bayt dizisi tutar — dolayısıyla bu, yalnızca konuğun oraya koyduğu baytlar değil, konuğun bildirdiği biçimdir. Böyle bir isteği dize olarak ayıran ya da böyle bir yanıtı dize olarak okuyan bir konuk birlikte çalışamaz: her iki yönde de bir metin dönüşümü ikili baytları bozar. Hata kısmi değil belirgindir — ana makinenin çözemediği bir istek, diğer tüm geri çağırma hatalarıyla aynı bant içi biçimde, request_undecodable kodunu taşıyan bir yanıt zarfı olarak geri döner; böylece konuk yarım okunmuş bir yükle devam etmek yerine bunu bildirir. Yük türleri şunlardır: aggrega_pack_source için SourcePackRequest ve SourcePackResponse, aggrega_read_source_file için SourceFileRequest ve SourceFileResponse, aggrega_parse_source için ParseInput ve ParseSourceResponse, URL’si metin olarak ayrılan aggrega_fetch_external_input için ise yalnızca yanıt türü FetchExternalInputResponse. Somut olarak, her kit için:

  • Go — isteği istek türünün EncodeCBOR() işleviyle oluşturun, pdk.AllocateBytes ile ayırın (pdk.AllocateString ile değil) ve yanıtı, yanıt işaretçisinin çözümlendiği bellek üzerinde ReadBytes() ile okuyup yanıt türünün DecodeCBOR işlevine verin. İstek tarafındaki istisna, pdk.AllocateString ile ayrılan getirme URL’sidir; yanıtı diğerleri gibi okunur. //go:wasmimport bildirimi her iki durumda da bir işaretçidir, dolayısıyla imzadaki hiçbir şey biçimi göstermez — biçim ayırma ve okuma adımlarında yer alır.
  • Rust — #[host_fn] bildirimi biçimi doğrudan belirtir: üç yük geri çağırmasının her biri fn <callback>(request: Vec<u8>) -> Vec<u8>; biçimindedir, getirme geri çağırması ise fn aggrega_fetch_external_input(url: String) -> Vec<u8>; biçimindedir. İsteği istek türünün encode_cbor() işleviyle oluşturun ve yanıtı yanıt türünün decode_cbor(&raw) işleviyle okuyun.
  • TypeScript — isteği istek türünün encodeCBOR… işleviyle oluşturun, Memory.fromBuffer ile ayırın (Memory.fromString ile değil) ve yanıtı readBytes() ile okuyup yanıt türünün decodeCBOR… işlevine verin. Getirme URL’si Memory.fromString ile ayrılır; yanıtı diğerleri gibi readBytes() ile okunur. Go’da olduğu gibi, declare module girdisi her iki durumda da bir işaretçidir.

Bir PDK sarmalayıcısını çağıran bir konuğun bunların hiçbirine ihtiyacı yoktur. Sarmalayıcılar — her dilin kendi yazımıyla FetchExternalInput, PackSource, ReadSourceFile ve ParseSource — ayırmayı ve kodlamayı yapar ve imzalarının hiçbiri bir aktarım türü adlandırmaz; bu nedenle bu geri çağırmalara kiti aracılığıyla ulaşan bir konuk kendisi hiçbir şey ayırmaz ve çözmez; ana makine işlevlerini kendisi bildirip çağıran bir konuk ise belleğini yukarıda anlatıldığı gibi ayırır ve okur. Metin olarak ayrılan bir istek yarım hizmet almak yerine reddedilir, metin olarak okunan bir yanıt ise çözülemez; böylece iki taraf arasındaki uyumsuzluk sessiz kalmaz, açıkça ortaya çıkar.

Güvenilebilecek iki özellik vardır. Yanıt, başarılı da olsa başarısız da olsa aynı kodlamayı taşır: bir konuk tek bir yuvayı okur ve çözmeden önce ikisinden hangisini tuttuğunu bilemez; bu nedenle tek bir çözme giriş noktası ikisini de okur ve yukarıda anlatılan hata kodu ile ileti bu nokta üzerinden gelir. Ayrıca bir konuk bayt değerli bir alanı kitinin kendi alan türünde doldurur — Go’da bir bayt dilimi, Rust ve TypeScript’te bir base64 dizesi — çünkü ikili kodlamanın taşıdığı ham bayt dizisine dönüştürme, üretilen kodlayıcının işidir; bu işlem çıkışta yapılır ve girişte tersine çevrilir. Bu; ParseInput’un kaynak baytlarını, aggrega_read_source_file’ın döndürdüğü dosya içeriğini, aggrega_fetch_external_input’un getirdiği içeriği ve bir pack-source yanıtındaki her paketlenmiş dosyanın içeriğini kapsar: bu baytlar sınırı iki kez kodlanmış olarak değil bir kez geçer ve hiçbir konuk, kodlayıcının base64’ten çözmek üzere olduğu bir şeyi base64 ile kodlamaz. Read-source-file ve getirme yanıtlarının content alanı boş olduğunda atlanır; dolayısıyla boş bir dosya ya da sıfır uzunlukta getirilmiş bir yük için yanıt hiç içerik taşımaz; böyle bir yanıt yine de başarıdır, çünkü bir hata her zaman iletisini ve kodunu taşır ve her kitin sarmalayıcısı bunun için boş bayt döndürür. aggrega_parse_source’un döndürdüğü ağaç, kendi JSON belgesini olduğu gibi tutan bir bayt dizisi olarak taşınır; ana makine onu ne okur ne de yeniden biçimlendirir. Bir ayrıştırıcı aynı ParseInput’u aynı kodlamayla kendi parse dışa aktarımında okur — bkz. ayrıştırıcı soketi.

Kanonik, özdeş girdinin her tarafta özdeş baytlar üretmesi demektir; bir yükün yalnızca gidiş-dönüş yapılmakla kalmayıp üç eklenti kiti arasında karşılaştırılabilmesini sağlayan budur ve bir derlemenin çıktısının bayt bayt özdeş kalmasının nedeni de budur. Bir konukta CBOR kitaplığına gerek yoktur ve hiçbir şey baytları elle ayrıştırmaz: yayımlanan her yük türü, yuvasının kodlamasının gerektirdiği kodlama ve çözme giriş noktalarıyla birlikte gelir.

Belirlenimcilik eklenti yazarının sorumluluğundadır. Ana makine bir konuğun çıktı baytlarını olduğu gibi tüketir ve üzerlerinde hiçbir serileştirici çalıştırmaz; dolayısıyla her eklentinin uyması gereken sözleşme şudur: özdeş girdi özdeş çıktı baytları üretir. Korumalı alan, belirlenimsizliğin ortam kaynaklarını — duvar saati zamanı, ortam değişkenleri, dosya sistemi durumu — ortadan kaldırır, ancak geri kalanını bilerek maskelemez: entropiyi ya da geçen monoton zamanı çıktısına kodlayan bir konuk, kararlı biçimde gizlenmiş bir kusur yerine çalıştırmalar arasında gözle görülür biçimde farklı baytlar üretir.

Dış girdi getirme kanalı. aggrega_fetch_external_input, uzak içerik için onaylanmış tek kanaldır ve konuğun ağ erişimi değil, ana makine aracılığıyla yürütülen bir kanaldır: konuk bir URL adlandırır, ana makine de baytları dış girdi sabitleme disiplini altında sunar. Release’in kilit dosyasında sabitlenmiş bir URL yerel içerik adresli depodan sunulur ve kayıtlı özetine karşı doğrulanır; sabitlenmemiş bir URL ise URL’yi ve onu sabitleyen adımı adlandıran bir tanılamayla reddedilir, çünkü bir işleme, kilit dosyasının kaydettiği kapanışı tüketir ve onu hiçbir zaman genişletmez. Sabitlemeler, Release’in bağımlılıkları çözümlendiğinde yazılır; herhangi bir şeyin sabitlendiği tek an budur. Geliştirici kılavuzu, yazma yönergelerini ve sabitleme disiplinini eksiksiz olarak içerir.

Sırasını koruyan eşlemeler

Bir yükün taşıdığı bazı eşlemeler, soketlerinin şemasında sırayı koruyan olarak işaretlenir, çünkü girdilerinin sırası taşıdıkları bilginin bir parçasıdır: bir derlemenin düğümleri, bir düğümün etiketleri, bir düğüme yapılan eklemeler, bir işlem hattı adımının girdileri ve çıktıları, bir sağlayıcının bildirdiği anahtar alanları. Yayımlanan yük türleri bu tür her eşlemeyi, girdilerini atandıkları sırada tutan bir kapsayıcıda saklar:

KitKapsayıcı
Goaggrega.OrderedMap[V] — kitin ABI paketindeki abi.OrderedMap[V] için kullandığı ad
Rustaggrega-abi crate’inden gelen ve kit tarafından yeniden dışa aktarılan OrderedMap<V>
TypeScriptdilin kendi Map<string, V> türü

Go ve Rust kapsayıcıları bir eşlemenin işlemlerini sunar: bir anahtarı aramak, atamak, silmek, anahtarları okumak, girdileri sırayla gezmek ve saymak. Kapsayıcının zaten tuttuğu bir anahtarı atamak değerini değiştirir ve yerini korur; yeni bir anahtar mevcut tüm anahtarların arkasına eklenir.

Sıra her iki kodlamada da korunur. İkili kodlamada işaretli bir eşleme, kanonik kodlamanın normalde anahtarları sıralanmış bir eşleme yazacağı yerde, kapsayıcının sırasıyla sıralı bir girdi listesi olarak yazılır; her girdi, önce anahtar sonra değer olmak üzere iki öğeli bir listedir. Metin kodlamasında ise üyeleri kapsayıcının sırasıyla yazılan bir JSON nesnesidir. Her iki kodlamadaki kod çözücü de bir anahtarı tekrarlayan eşlemeyi, anahtarı adlandırarak reddeder. Şemanın işaretlemediği bir eşleme, ikili kodlamada sıralı eşleme biçimini, yayımlanan türlerde ise dilin olağan eşleme türünü korur.

Bir konuk için üç sonuç:

  • Sıra, çıktının parçasıdır. İşaretli bir eşleme doldurulduğu sırayla yazıldığından, onu sabit sırası olmayan bir kaynaktan, örneğin yerleşik bir Go eşlemesini gezerek dolduran bir konuk, aynı girdiyle yapılan çalıştırmalar arasında farklılaşan baytlar yazar. Eşlemeyi sabit bir sırayla doldurun.
  • Sıra yalnızca eşleme kapsayıcısında kaldığı sürece korunur. Bir yükü kendi dilinin genel bir değer türüne dönüştüren konuk, bunun yerine o türün sırasını alır: Go’daki map[string]any türünün sırası yoktur, Rust’taki serde_json::Value ise crate preserve_order özelliğiyle derlenmedikçe nesne anahtarlarını sıralı tutar.
  • TypeScript’te okuma ve yazmayı üretilen fonksiyonlar üzerinden yapın. İşaretli bir eşleme tutan tür, JSON’unu üye üye çözer; böylece "8080" gibi dizi indisi olarak okunan bir anahtar, JSON.parse onu nesnenin başına taşıyacakken yerini korur; kodlayıcısı da her Map öğesini bir nesne olarak yazar, oysa JSON.stringify bir Map öğesini {} olarak yazar. Bir Map için Object.keys de boştur: bir Map öğesinin anahtarlarını kendi keys() yöntemiyle okuyun.

Bir girdinin hassas olarak işaretlediği değerler

Bir plugin, döndürdüğü bir reddetmede veya uyarıda, girdisinin hassas olarak işaretlediği bir değeri asla aktarmaz — ister anahtarıyla, ister bütünü işaretlenmiş bir yükün parçası olarak. Reddetme, bir çıktının taşıdığı error’dır; uyarı ise önem derecesi ne olursa olsun çıktının taşıdığı bir Diagnostic ya da aggrega_emit_warning aracılığıyla bildirilen bir uyarıdır. Ana makine bu metni, raporladığı her yerde — komut satırı, dil sunucusu ve düzenleyicinin sorun listesi, asistan araçları — değiştirmeden taşır ve içinden hiçbir değer okumaz; dolayısıyla değeri dışarıda tutabilecek tek taraf plugin’dir. Bunun yerine anahtarı, ayarı veya konumu belirtin: okuyucu değeri oradan bulur.

Kural, plugin’in kendi yazdığı metin kadar bir kütüphanenin plugin adına yazdığı metni de kapsar. Bir şablon motoru değerlendirdiği veriyi bildirir, bir şema doğrulayıcı bir pattern’i karşılamayan bir değeri aktarır, bir ayrıştırıcı okuyamadığı belirteci aktarır. Böyle bir hata girdinin işaretlediği bir değer üzerinde oluştuğunda, hatayı değer olmadan bildirin — örneğin, aynı adımı her işaretli değer bir yer tutucuyla değiştirilmiş olarak yeniden çalıştırın, bu çalıştırma aynı yerde başarısız olursa onun hatasını bildirin, aksi halde hata metninin gizlendiğini belirtin. Bütünü işaretlenmiş bir yükte o yükteki her değer işaretli bir değerdir; anahtarları ise — belgenin yapısı — okunabilir kalır.

Bir girdinin bir anahtarı veya bir yükü hassas olarak işaretlediği yerler, aktarım biçiminin adlandırdığı şekliyle:

Soket ve dışa aktarımİşaretin okunduğu yer
provider render_node ve validate_node_input (RenderNodeInput)node.sensitive_rendered_keys: her anahtar, bu değerler Component’in kendi değerleri olup bildirdiği yapraklarla anahtarlandığında node.values içindeki bir girdiyi adlandırır — bir Recipe’in valuesMapping eşlemesi hiçbir bildirimin adlandırmadığı anahtarlar yazar, bu yüzden bunların hiçbiri burada işaretlenmez — ya da bir workload konteynerinin attachments eşlemindeki, hassas olarak bildirilmiş bir yuvayı okuyan bir girdiyi adlandırır. node.sensitive_values, node.values öğesini bir bütün olarak işaretler: bu değerleri bir valuesMapping — Recipe’inki ya da bir ekin FeatureRecipe’ininki — ürettiğinde ve bir yazarın hassas olarak bildirdiği bir değeri okuduğunda true olur. workload_projection.sensitive_workload, workload’un şablonu böyle bir değer okuduğunda workload’un her değerini aynı şekilde işaretler; artifacts_projection.entries içindeki her girdi de kendi içeriği için, o içerikle ilgili bir ayrıştırıcı iletisi dahil, sensitive_content taşır. omits içindeki her girdi, türünden, adından ya da ad alanından herhangi birini üreten şablon böyle bir değer okuduğunda sensitive taşır ve bu durumda o girdinin her alanı işaretli bir değerdir. node.features içindeki her girdi kendi ekinin işaretlemesini taşır: sensitive_payload_leaves (Feature’ının hassas olarak bildirdiği values.<path> ve infra.<path> yaprakları), sensitive_inject (Feature’ının hassas olarak bildirdiği bir provides anahtarını okuyan inject teslim anahtarları) ve sensitive (ekin hassas olarak bildirilmiş materyali hiç işleyip işlemediği).
governance ir-verdict (PolicyInput)graph: her düğümün sensitive_payload_leaves’i ve her ekin sensitive_payload_leaves, sensitive_inject ve sensitive alanları. Bu işaretlerin adlandırdığı her değer zaten {"aggrega_withheld": "declared"} gizleme işaretçisi olarak gelir; böylece değerin kendisi plugin’e hiçbir zaman ulaşmaz.

Başka hiçbir soket girdisi ve başka hiçbir provider dışa aktarımının girdisi işaret taşımaz. Bir anahtar işareti yalnızca bir bildirime tam olarak eşleştirdiği şeyi adlandırır; bu yüzden bir anahtarın işaretsiz olması, değerin aktarılmasının güvenli olduğu anlamına asla gelmez: o anahtara hiçbir bildirimin eşleştirilemediği anlamına gelir. Bir yük işareti, yükü üreten şablonun başvurularından okunur — bildirilmiş bir değere ulaşan bir başvuru, verisinin tamamını aktaran bir şablon ya da ayrıştırılamayan bir şablon — ve asla bir değerden okunmaz; dolayısıyla işaretin olmaması, başvurularının gösterdiği kadarıyla o şablonun hiçbir bildirilmiş değeri okumadığı ya da yükü hiçbir şablonun üretmediği anlamına gelir; yükün hassas hiçbir şey taşımadığına dair bir ifade değildir.

Wasm soketlerinin işlem hattındaki yeri

Derleme işlem hattı aşağıdaki soket noktalarını ayırır. Biçim etiketleri, Durum sayfasındaki dört etiketli sınıflandırmayı izler.

Soketİşlem hattındaki yeriBugünkü durum
Yönetişim soketi, annotation-transform rolüÇözümleme (ek açıklama genişletmesinden önce)kullanılabilir — bir çalışma alanı bir annotation-transform eklentisi bağladığında çağrılır; genişletmenin Feature bağlantılarına dönüştürdüğü ek açıklamaları ekler
Yönetişim soketi, label-transform rolüTopoloji oluşturma (Topology Builder)kullanılabilir — bir çalışma alanı bir label-transform eklentisi bağladığında çağrılır; düğüm etiketlerini JSON Patch ile otomatik olarak etiketler
Yönetişim soketi, ir-verdict rolüStatik analiz (IR grafiği üzerinde Static Analyzer)kullanılabilir — bir çalışma alanı bir ir-verdict eklentisi bağladığında çağrılır; halt kararı derlemeyi durdurur
Yönetişim soketi, render-verdict rolüİşleme (işlenmiş yapıtlar üzerinde)kullanılabilir — bir çalışma alanı bir render-verdict eklentisi bağladığında çağrılır; halt kararı derlemeyi durdurur
FeatureRecipe ve Recipe pipeline: eklentileriEklenti işlem hattı (işleme sonrası değişiklik)kullanılabilir — bildirilen her adım, işlenmiş belge kümesi üzerinde çalışır, RFC 6902 yamalarını uygular ve yan etkiler üretir
Provider oluşturma eklentileri (helm, helm-chart, compose, terraform, cloudformation)Temel işleme (sağlayıcılar)kullanılabilir — her sağlayıcı kendi Wasm konuğu üzerinden işler; işleme yalnızca Wasm ile yapılır, ana makine içi bir işleyiciye geri dönüş yoktur
Ayrıştırıcı eklentileri (parse:<format>)Oluşturma, bir render-verdict politikası için; ve bant dışı, bir içe aktarma içinkullanılabilir — bir render-verdict politikasının yerel olarak okumadığı bir biçimdeki yapıt için, aggrega_parse_source aracılığıyla bir içe aktarıcı için ve biçim belirtmeyen bir içe aktarmanın biçimini tanımak için çağrılır
İçe aktarıcı eklentileri (import:<format>)Bant dışı (aggrega import)kullanılabilir — aggrega import, düzenleyici oturumu ve asistana yönelik araç tarafından yönlendirilir
Linter eklentileri (linter/publishing)Bant dışı (aggrega lint)kullanılabilir — publishing-linter birlikte gelir ve aggrega lint aracılığıyla ana makine üzerinden çalışır

Çözümlemenin parçası olan ek açıklama güdümlü Feature genişletme alt aşaması bir Wasm soketi değil, yerel bir Go işlem hattı geçişidir. Ek açıklama değerlerini hedef Feature’ın spec.schema şemasına göre doğrular ve IR oluşturma sırasında sentetik Feature bağlantıları ekler. Ek açıklama ve etiket taşıyan altı yüzey için vocabulary/labels-and-annotations.md belgesine, bağlama biçimi ve yazım rehberi için providers/well-known-annotations.md belgesine bakın.

Çıktı biçimi sözleşmesi — bugün var olanlar

Yönetişim soketi, dört rolünün her birinde tipli bir sözleşme yüzeyi taşır ve hangisinin geçerli olduğunu rol belirler. Plugin yazarları, belgelenen biçimleri üreten konuk tarafı kodu yazar; bir çalışma alanı o role bir plugin bağladığında konak bunları derleme zamanında, yapılandırılmış her plugin için bir kez okur. Aşağıdaki alt bölümler, işlem hattının bunları çağırdığı sırayı izler.

annotation-transform rolü — ek açıklama ekleme çıktısı

İşlem hattındaki yeri. Çözümleme; bileşenler çözümlendikten sonra ve ek açıklama güdümlü Feature genişletmesi çalışmadan önce.

Girdi biçimi (konak → konuk). Şunları taşıyan bir AnnotationTransformInput belgesi:

  • targets — ekleme hedefleri: konuğun ek açıklama ekleyebileceği çözümlenmiş bileşenler — bir sınırın doğrudan adlandırdıkları ve bir sınırın aggregates: altındaki bir yönlendirme girdisinin, girdi onu adlandırsın ya da adlandırmasın, içeri yönlendirdiği her bileşen —; her biri kendi boundary_path değerini, component_name değerini (yönlendirilmiş bir bileşen için derleme grafiğindeki noktalı kimliği, örneğin metrics.query) ve Release’in üzerine yazdığı annotations öğelerini taşır, böylece konuk, yazılmış bir değerin yerini almadan neyi ekleyeceğine karar verebilir. Her ek açıklama değeri yazıldığı gibi gelir — bir dize, alt anahtarlardan oluşan bir nesne ya da bileşenin devralacağı bir ek açıklamadan çıktığı durumda null — ve bileşenin taşıdığı her anahtar, değeri ne olursa olsun mevcuttur. Konak tarafından deterministik olarak sıralanır.
  • binding_keys — Manifest’in bağlama kaydettiği ek açıklama anahtarları, yazar sırasıyla. Kayıtlı bir anahtar altındaki ekleme bir Feature bağlantısına genişletilir; bu nedenle konuk, etkili olacak anahtarları eklemek için bu listeyi okur. Konak, bir eklemenin kayıtlı bir anahtarı adlandırmasını şart koşmaz: kayıtsız eklenmiş bir ek açıklama, yazılmış bağlanmamış bir ek açıklamayla tamamen aynı şekilde davranır.
  • sources — bağlantının with.sources altında bildirdiği tanım dosyaları; her biri temel ad yolunu ve içeriğini taşır, yola göre sıralanır.
  • settings — bağlantının with.settings altında bildirdiği serbest biçimli ayarlar nesnesi; konuğa olduğu gibi aktarılır.

settings ve sources, diğer her rolün okuduğu motordan bağımsız aynı with kanalıdır ve bağlantı hiçbirini bildirmediğinde ikisi de bulunmaz. Bu rolün çıktısı derlemeyi şekillendirdiğinden, bağlantının ayarları ve kaynak içeriği çekme sırasında release kilit dosyasına sabitlenir ve derleme sırasında oradan yeniden oluşturulur.

Çıktı biçimi (konuk → konak). Şunları taşıyan bir AnnotationTransformOutput belgesi:

  • injections — eklenecek ek açıklamalar, sırasıyla. Her biri var olan bir hedef koordinatını (boundary_path ve component_name) ile birlikte annotation_key anahtarını ve onun annotation_value değerini adlandırır: bir dize ya da birden çok alt anahtarı aynı anda yönlendiren bir bağlamayı besleyen, alt anahtarlardan oluşan bir nesne.

Ana makine yalnızca ek açıklama eklemelerini uygular; yalnızca kendi sağladığı koordinatlara ve her biri bir yazarın o ek açıklamaya yazabileceği bir değerle. Eklenen bir değeri, Release’te yazılan aynı değeri okuduğu gibi okur — bir nesnenin alt anahtarları konuğun yazdığı sırayla — böylece genişletme onu yazılmış bir ek açıklamayla karşılaştığı gibi karşılar. Yükün taşımadığı bir koordinatı adlandıran ya da null, bir liste, bir sayı, bir boole veya alt anahtarı olmayan bir nesne taşıyan bir ekleme, sessizce atılmak ya da uygulanmak yerine koordinatı ve ek açıklamayı adlandıran bir iletiyle derlemeyi durdurur; çıktının herhangi bir kısmı uygulanmadan önce tamamı denetlenir. Rolü sınırlayan bu kısıtlamadır: buraya bir eklenti bağlayan bir operatör ek açıklama eklemeyi bildirmiştir, başka hiçbir şeyi değil. Derleme daha sonra eklenen bir ek açıklamayı yönlendirilme biçimi, bağlı Feature’ın şemasının kabul etmediği bir alt anahtar değeri ya da Release tarafındaki bir ek açıklamanın kullanamayacağı bir sütun nedeniyle reddederse, iletisi onu ekleyen eklentiyi ve eklentinin bağlı olduğu rolü adlandırır.

Kablo kodlaması. Bu rolün yükü ve sonucu her iki yönde de kanonik CBOR (RFC 8949 §4.2.1) olarak iletilir. Konuk bunu, yük türlerinin taşıdığı giriş noktaları aracılığıyla okur ve yazar — Go’da DecodeCBOR ve EncodeCBOR, Rust’ta decode_cbor ve encode_cbor, TypeScript’te decodeCBORAnnotationTransformInput ve encodeCBORAnnotationTransformOutput — böylece hiçbir CBOR kütüphanesi gerekmez ve hiçbir şey baytları elle ayrıştırmaz. Rust’ta dışa aktarım Vec<u8> alır ve döndürür; TypeScript’te Host.inputBytes() okur ve Host.outputBytes(...) yazar. Her hedefin annotations öğesi, şemanın sırayı koruyan olarak işaretlediği bir eşlemdir; bu nedenle hedefin tuttuğu sırayla bir sıralı girdiler listesi olarak iletilir ve konuk bunu kendi kitinin sırayı koruyan kapsayıcısıyla okur; her değer, bir eklemenin annotation_value değerinin diğer yönde iletildiği gibi, JSON’ının baytları olarak iletilir. settings, JSON belgesinin baytları olarak iletilir; konuk içine bakmak için bunu JSON olarak ayrıştırır. Bu kodlamada bir AnnotationTransformOutput olmayan bir yanıt — JSON olarak yazılmış ya da biçimin bildirmediği bir üst düzey alan taşıyan bir yanıt — boş bir ekleme listesi olarak okunmak yerine plugin’i ve dışa aktarımını adlandırarak derlemeyi durdurur. aggrega plugin run-local --export transform_annotations ile doğrudan çağrıldığında konuğa, yazılmış JSON yükünün bu kodlamaya dönüştürülmüş hâli verilir ve yanıtı dışa aktarımın çıktı biçimi olarak okunup JSON olarak yazdırılır — bu biçimde olmayan bir yanıt, bir derlemenin reddettiği gibi, dışa aktarım adlandırılarak reddedilir.

Tür tanımları. annotation-transform kablo türleri — AnnotationTransformInput, AnnotationTransformOutput, AnnotationTarget, AnnotationInjection, AnnotationSource — üç ABI paketinin tümünde yayımlanır ve üçünün birbirine uyumlu kalması için tek bir kodekten üretilir.

label-transform rolü — JSONPatch çıktısı

Hattaki yeri. Topoloji oluşturma; grafik düzleştirildikten sonra ve IR grafiği oluşturulmadan önce, böylece çözümleyicinin değerlendirdiği soket ve Feature seçicileri bu rolün bıraktığı etiketleri okur.

Girdi şekli (host → guest). Şunları taşıyan bir MutatorInput belgesi:

  • compilation_context — sürüm kimliği (release_name, environment).
  • graph — topoloji düğümlerinin bir MutatorGraph izdüşümü: her düğümün Component’i, çözümlenmiş sürümü, etiketleri ve örneğinin bildirdiği values.
  • settings — bağlantının with.settings altında bildirdiği serbest biçimli ayarlar nesnesi; konuğa olduğu gibi aktarılır.
  • sources — eklentinin with.sources altında bildirdiği tanım dosyaları; her biri temel ad yolunu ve içeriğini taşır, böylece bir mutator satır içi ayarlar yerine depoya eklenmiş bir kural veya eşleme dosyasıyla yönlendirilebilir.

Grafik, IR grafiği değil bir izdüşümdür: her düğüm çözümlenmiş etiket kümesini ve örneğinin Aggregate’te bildirdiği değerleri taşır, kenarlar ve feature yükleri ise derleyicinin içinde kalır. Değerler Aggregate’in kendi değerleridir ve şablonları parametrelerine göre önceden değerlendirilmiştir; bu nedenle bir parametreye taşınmış bir değer, Release’in sağladığı değer olarak gelir. Component’in şemasının bildirdiği bir varsayılan ve bir Recipe’in ya da Feature’ın kattığı hiçbir şey bunların arasında değildir; hiç değer bildirmeyen bir düğüm values anahtarı taşımaz. Düğümün Component’inin hassas olarak bildirdiği bir değer, grafik üzerindeki kararın sakladığı gibi saklanır — {"aggrega_withheld": "declared"} olarak okunur — hiçbir bildirimin ulaşmadığı her kardeş değer ise yazıldığı gibi gelir. Geliştiricinin bildirdiği bir yapılandırmanın bir etikete karar vermesini sağlayan budur — örneğin değerleri bir vektör uzantısını etkinleştiren bir veritabanının datastore.aggrega.ai/engine: vector etiketine yükseltilmesi. settings ve sources, karar rollerinin okuduğu, motordan bağımsız aynı with kanalıdır; host bunları olduğu gibi aktarır ve içeriklerini asla yorumlamaz. Bir mutator’ün çıktısı derlemeyi şekillendirdiğinden, eklentinin ayarları ve kaynak içeriği pull sırasında sürüm kilit dosyasına sabitlenir ve derleme sırasında bu dosyadan yeniden oluşturulur; böylece mutator girdisi, bir sonraki pull’a kadar pull sonrasında bunlardan herhangi birinde yapılan değişiklikten etkilenmez.

Çıktı şekli (guest → host). Şunları taşıyan bir MutatorOutput belgesi:

  • patches — host’un yalnızca düğüm etiketlerine uyguladığı opak JSONPatch belgelerinden (RFC 6902) oluşan bir dizi; girdinin taşıdığı değerler salt okunurdur.

Her yama, belirli bir düğümün etiketlerini JSON Pointer (RFC 6901) aracılığıyla adresler; host yamaları dizi sırasıyla uygular ve değiştirilmiş etiket kümesini IR grafiğine yeniden alır. label-transform rolünün işi kurumsal otomatik etiketlemedir: katalog içeriğini değiştirmeden, kurumsal politikanın bildirdiği uyumluluk / gözlemlenebilirlik / maliyet atama etiketlerini eklemek. Etiket yüzeyi bu rolün onaylı tek hedefidir: bir düğümün etiketleri dışındaki bir alanına dokunan, bir düğüm ekleyen veya kaldıran ya da dize olmayan bir etiket değeri ayarlayan bir yama, sessizce kabul edilmek yerine derlemeyi durdurur. RFC 6901, Aggrega’daki her belge yolu yüzeyi için yol dilbilgisi temelidir: buradaki Wasm plugin sözleşmesi, ayrıca .locals *_path dışa aktarımları ve belgelerin başka yerlerindeki *Path şema alanları. Kanonik temel bildirimi ve iki yazım tarafını birbirinden ayıran *Path / *_path sonek disiplini için 02-naming-conventions.md içindeki “Document-path naming-suffix discipline” bölümüne bakın.

Kablo kodlaması. Bu rolün yükü ve sonucu her iki yönde de kanonik CBOR (RFC 8949 §4.2.1) olarak taşınır. Kanonik, özdeş girdinin her tarafta özdeş baytlar üretmesi demektir; bir yükün yalnızca gidiş-dönüş yapmakla kalmayıp üç plugin kiti arasında karşılaştırılabilmesini sağlayan budur ve bir derlemenin çıktısının bayt bayt aynı kalmasının nedeni de budur. Bir guest bunu, kitinin yük türünün zaten taşıdığı giriş noktaları aracılığıyla okur ve yazar: Go’da DecodeCBOR ve EncodeCBOR, Rust’ta decode_cbor ve encode_cbor, TypeScript’te decodeCBORMutatorInput ve encodeCBORMutatorOutput; böylece bir CBOR kütüphanesine gerek kalmaz ve hiçbir şey baytları elle ayrıştırmaz. Rust’ta dışa aktarım Vec<u8> alır ve döndürür; TypeScript’te Host.inputBytes() okur ve Host.outputBytes(...) yazar. Grafiğin nodes alanı, her düğümün labels alanı ve her düğümün values alanı, şemanın sırayı koruyan olarak işaretlediği eşlemlerdir; bu nedenle sıralı girdi listeleri olarak aktarılırlar (düğümler derlemenin tuttuğu sırayla, yani yazar sırasıyla, her düğümün etiketleri düğümün taşıdığı sırayla, her düğümün değerleri de Aggregate’in yazdığı sırayla) ve bir guest üçünü de kitinin sırayı koruyan kapsayıcısı aracılığıyla okur. Her değer, JSON belgesinin baytları olarak aktarılır: Go ve Rust kitleri onu guest’e bu JSON olarak, bir kuralın ihtiyaç duyduğu ölçüde ayrıştırılmak üzere verir; TypeScript kiti ise ayrıştırılmış değer olarak verir.

Bunun değiştirmediği iki şey vardır. patches dizisi JSON olarak kalır: soket her yama belgesini opak içerik olarak olduğu gibi taşır ve hiçbir taraf içine bakmaz; dolayısıyla bir yama belgesinin kendi şekli, soketinin taşıdığı kodlamadan bağımsızdır. Ayrıca settings ve sources hâlâ olduğu gibi aktarılır: settings, eklentinin yazdığı baytlar olarak gelir ve bir guest içine bakması gerekirse bunu JSON olarak ayrıştırır.

Diğer tüm yönetişim rolleri de aynı kodlamayı taşır (annotation-transform rolü ve iki karar rolü bunu kendi bölümlerinde belirtir); bu nedenle birden fazla role hizmet eden bir guest, hizmet ettiği her rolde kanonik CBOR konuşur ve her yükü kendi türünün kod çözme giriş noktası aracılığıyla okur.

Tür tanımları. Mutator kablo türleri (MutatorInput, MutatorOutput, CompilationContext, MutatorGraph, MutatorNode) üç ABI paketinin tümünde (github.com/aggrega-ai/aggrega-abi/go, aggrega-abi crate’i ve @aggrega-ai/aggrega-abi) yayımlanır ve üçü uyum içinde kalsın diye tek bir codec’ten üretilir. Host girdiyi oluşturur ve guest’in döndürdüğü yamaları uygular.

Karar rolleri — karar dizisi çıktısı

Bir politika konuğu bir derlemeyi inceler ve bir karar listesi döndürür; ana makine her kararın önem düzeyine göre işlem yapar ve politikanın kendisini hiçbir zaman yorumlamaz. Ayrıntılı anlatım — dört rol, önem düzeyleri, operatörün sağladığı girdi kanalı, derleyicinin içinde gelen iki motordan biri için politika yazma, yabancı bir politika motorunu sarmalama, referans konuklar ve bir operatörün bir politikayı nasıl bağladığı — yönetişim soketi sayfasındadır. Bu bölüm, işlem hattındaki yerleşimi ve türlendirilmiş iletim biçimlerini kaydeder.

İşlem hattındaki yerleşim. Bir politika tam olarak bir karar rolüne bağlanır ve bu rol, politikanın nerede değerlendirileceğini belirler:

  • ir-verdict — statik analiz sırasında, temel işlemeden önce değerlendirilir. Çözümleyici, yükü her derlemede oluşturur.
  • render-verdict — işlemeden sonra, üretilen yapıtlar üzerinde değerlendirilir.

Bir çalışma alanı bir karar rolü eklentisi bağladığında, işlem hattı o rolün yükünü eklentiye iletir ve kararlarını geri okur.

Girdi biçimi (ana makine → konuk). Yükü rol belirler:

  • ir-verdict PolicyInput, graph alanını — derleyicinin tuttuğu her düğüm, kenar ve bağlama ayrıntısıyla birlikte, yetenekten bağımsız tam IR grafiğini (Topology Builder’ın ürettiği biçimle aynı); ancak bir yazarın hassas olarak bildirdiği bir değer saklanmış olarak gelir (bkz. Bir girdinin hassas olarak işaretlediği değerler) — ve çözümleyicinin yanı sıra numaralandırdığı yönlendirme yolları olan precalculated_paths alanını taşır; böylece bir politika, grafiği yeniden dolaşmadan erişilebilirlik hakkında akıl yürütebilir. Grafik, tek kaynağı ir-v1beta1 şeması olan sürümlü IR grafiğidir; IR biçimi gizli değildir (aggrega inspect komutunun ürettiği grafikle aynıdır) ve içindeki gizli bilgiler düz metin değil, her zaman işaretçidir.
  • render-verdict RenderPolicyInput, artifacts alanını — yola göre sıralanmış işlenmiş çıktı dosyalarını — taşır; böylece iletilen veri, aynı girdinin çalıştırmaları arasında bayt düzeyinde aynı kalır. Her girdi, yapıtın çıktı path değerini ve işlenmiş content değerini taşır; ayrıca, üreten sağlayıcı bir biçim bildirmişse yapıtın işlendiği format değerini ve konuğun doğal olarak okumadığı bir biçimin ayrıştırılmış kanonik görünümü olan, ana makinenin çözümlenen ayrıştırıcıyla ayrıştırıp içeriğine bakmadan aktardığı bir tree değerini de taşır. Uygulanmadıkları durumda ikisi de bulunmaz — konuğun doğal olarak okuduğu bir biçim (JSON, YAML), konuğun content üzerinden okuması için ayrıştırılmadan bırakılır.

Her iki rol ayrıca bağlamanın sources alanını (ana makinenin derleme sırasında okuyup konuğa olduğu gibi verdiği politika tanım dosyaları; yollar temel ad olarak, içerik opak) ve settings alanını (dokunulmadan aktarılan serbest biçimli bir nesne) taşır. Bağlama hiçbirini bildirmediğinde ikisi de bulunmaz.

Çıktı biçimi (konuk → ana makine). Şunları taşıyan bir PolicyOutput belgesi:

  • results — her biri bir severity (halt, warn veya info) ve bir message dizesi içeren Diagnostic girdilerinden oluşan bir dizi. Bir karar aynı girdide code, rule_id, classification, source_ref, location ve suggest alanlarını da ayarlayabilir; ana makine, kararın taşıdığı bu alanlardan hangileri varsa, her önem düzeyi yolunda bunları işlenen karara ekler.

Yalnızca tetiklenen kararlar görünür; izin veren bir değerlendirme boş bir dizi döndürür. Ana makine kararları dolaşır ve her önem düzeyini bir eyleme eşler: halt derlemeyi durdurur (her halt iletisini göstererek), warn kararı işaretler ve derlemenin devam etmesine izin verir, info sonucu etkilemeden kaydeder. Bir halt, bir seçici veya appliesTo ihlalinin kullandığı kapının aynısıyla durdurur.

İletim kodlaması. Her iki rolün yükleri ve bir konuğun ikisinden birinde döndürdüğü PolicyOutput, kanonik CBOR (RFC 8949 §4.2.1) olarak iletilir. Bir konuk bunları yük türlerinin taşıdığı giriş noktalarıyla okur ve yazar — Go’da DecodeCBOR ve EncodeCBOR, Rust’ta decode_cbor ve encode_cbor, TypeScript’te decodeCBORPolicyInput, decodeCBORRenderPolicyInput ve encodeCBORPolicyOutput — bu nedenle hiçbir CBOR kütüphanesi gerekmez ve hiçbir şey baytları elle ayrıştırmaz. Rust’ta her dışa aktarım Vec<u8> alır ve döndürür; TypeScript’te Host.inputBytes() okur ve Host.outputBytes(...) yazar. Grafiğin sırayı koruyan eşlemeleri, aralarında nodes ve her düğümün labels alanı, derlemenin tuttuğu sırada sıralı girdi listeleri olarak iletilir ve bir konuk bunları kitinin sırayı koruyan kapsayıcısıyla okur; bir politikanın her politika motorunda bunlarla hangi sırada karşılaştığı yönetişim soketi sayfasındadır. settings ve bir yapıtın ayrıştırılmış tree değeri, JSON belgelerinin baytları olarak iletilir; konuk içine bakmak için bunları JSON olarak ayrıştırır. Bu kodlamada bir PolicyOutput olmayan bir yanıt — JSON olarak yazılmış ya da biçimin bildirmediği üst düzey bir alan taşıyan bir yanıt — boş bir karar listesi olarak okunmak yerine, eklentiyi ve dışa aktarımını adlandırarak derlemeyi durdurur. aggrega plugin run-local --export verdict_ir veya --export verdict_render ile doğrudan çağrıldığında konuğa, yazılan JSON yükü bu kodlamaya dönüştürülerek verilir ve yanıtı dışa aktarımın çıktı biçimi olarak okunup JSON olarak yazdırılır — bu biçimde olmayan bir yanıt, bir derlemenin reddettiği gibi, dışa aktarım adlandırılarak reddedilir.

Tür tanımları. Politika iletim türleri aynı üç ABI paketinde yayımlanır: PolicyInput (ir-verdict rolü), RenderPolicyInput (render-verdict rolü), ortak PolicySource ve results girdileri Diagnostic değerleri olan PolicyOutput. Bir tanılamanın önem düzeyi, tüm soketlerin paylaştığı üç değerden biridir — halt, warn veya info — ve bu üçü, üç paketin her birinde iletim türlerinin yanında sabitler olarak yayımlanır; böylece bir konuk, ana makinenin yönlendirmede kullandığı kapalı kümenin aynısından bildirimde bulunur. Başka bir değer döndüren bir konuk, eklentiyi ve döndürdüğü değeri adlandıran bir iletiyle derlemeyi durdurur: yönlendirilemeyen bir önem düzeyi, ana makinenin bırakıp geçtiği bir tanılama değil, bildirdiği bir eklenti kusurudur.

Çıktı biçimi sözleşmesi — FeatureRecipe pipeline’ı ve provider soketleri

Aşağıdaki soketler, derleyicinin derleme sırasında çağırdığı tipli sözleşme yüzeyleri taşır. FeatureRecipe ve Recipe pipeline: adımları, işlenmiş belge kümesi üzerinde plugin pipeline’ında çalışır; provider işleme soketi temel işleme aşamasında çalışır; publishing-linter ise bant dışında çalışır.

RFC 6902 yamaları (plugin pipeline’ı)

Plugin pipeline’ında çalışan FeatureRecipe ve Recipe pipeline: adımları, işlenmiş belge kümesine karşı RFC 6902 JSON Patch işlemleri üretir. Ana makine her adıma anahtarlı belge kümesinin tamamını verir; adım hedeflediği belgeleri içeriğe göre seçer ve anahtarla adreslenen yamalar döndürür; uygulama motoru bu yamaları adreslenen belgelere uygular — tipik olarak bir sidecar konteyner ekleyerek, bir secret birimi bağlayarak ya da bir ortam değişkenini yeniden yazarak. Bir adım ayrıca side_effects (aşağıda), diagnostics — her girdisi, her soketin sorunları bildirdiği aynı paylaşılan Diagnostic biçimindedir — ve outputs (aşağıda) döndürür. examples/04-secrets.md sayfasında açıklanmıştır.

Bugünkü durum: kullanılabilir. Bildirilen her adım aggrega build sırasında çalışır.

Kablo kodlaması. Bir adımın girdisi (FRPStepInput) ve yanıtı (FRPStepOutput) her iki yönde de kanonik CBOR (RFC 8949 §4.2.1) olarak taşınır. Bir guest, girdisini çözer ve yanıtını, yük tiplerinin taşıdığı giriş noktaları aracılığıyla kodlar — Go’da DecodeCBOR ve EncodeCBOR, Rust’ta (aggrega-abi crate’inin yayımladığı tipler üzerinde) decode_cbor ve encode_cbor, TypeScript’te decodeCBORFRPStepInput ve encodeCBORFRPStepOutput — bayt okuyup yazarak (Rust’ta Vec<u8>, TypeScript’te Host.inputBytes() ve Host.outputBytes(...)). Hiçbir CBOR kütüphanesi gerekmez ve hiçbir şey baytları elle ayrıştırmaz. Adımın with girdisi (step_input), döndürdüğü outputs ve own ile host belge kümeleri, şemanın sırayı koruyan olarak işaretlediği eşlemelerdir; bu nedenle pipeline’ın tuttuğu sırayla sıralı girdi listeleri olarak geçerler ve bir guest bunları kendi kitinin sırayı koruyan kapsayıcısı aracılığıyla okuyup yazar — bir adımın çıktılarının .steps.<id>.outputs konumuna adımın döndürdüğü sırayla ulaşmasını sağlayan da budur. Her birimin tree alanı, step_input ve outputs içindeki her değer, bir yamanın value alanı, bir yan etkinin crd alanı ve işleme context alanı, JSON belgelerinin baytları olarak geçer; guest içlerine bakmak için bunları JSON olarak ayrıştırır. Bir birimin bytes alanı ise üretilen çözücünün kitin kendi alan tipine doldurduğu ham bir bayt dizisi olarak geçer — Go’da bir bayt dilimi, Rust ve TypeScript’te bir base64 dizesi. Her tanılama, paylaşılan Diagnostic biçiminde geçer. Bu kodlamada bir FRPStepOutput olmayan bir yanıt — JSON olarak yazılmış ya da biçimin bildirmediği bir üst düzey alan taşıyan bir yanıt — adımı başarısız kılar ve çalıştırdığı işlevi adlandırır; adım optional değilse bu, derlemeyi durdurur. aggrega plugin run-local --export step ile doğrudan çağrıldığında adıma, bu kodlamaya dönüştürülmüş yazılmış JSON yükü verilir ve yanıtı dışa aktarımın çıktı biçimi olarak okunup JSON olarak yazdırılır — bu biçimde olmayan bir yanıt, bir derlemenin reddettiği gibi, dışa aktarım adlandırılarak reddedilir.

Yan etkiler — kaynak üretme (plugin pipeline’ındaki kimlik bilgisi plugin’leri)

Kimlik bilgisi FeatureRecipe pipeline’ları (İki Parçalı Plugin İlkesi: Fetcher + Injector), bir adımın side_effects alanı aracılığıyla bir yamanın yanında eksiksiz kaynaklar üretir; her biri sözleşmenin tanımladığı iki türden birini bildirir: emit_crd, kümenin çalışma zamanında getirdiği bir ExternalSecret ya da VaultSecret CRD’si gibi özel bir kaynak belgesi, veya emit_file, yazılmış bir dosya. Başka herhangi bir tür döndüren bir adım, düğümü, yan etkinin dizinini ve bildirdiği türü adlandırarak derlemeyi durdurur. Fetcher’ın adımı kaynağın tamamını üretir; Injector’ın adımı ise ortaya çıkan Kubernetes Secret’ını bağlayan bir yama döndürür. examples/04-secrets.md sayfasında açıklanmıştır.

Bugünkü durum: kullanılabilir.

Adım çıktısı (pipeline: adımının outputs eşlemesi)

Bir plugin pipeline adımı, sonraki adımların {{ .steps.<id>.outputs.<key> }} aracılığıyla tükettiği adlandırılmış çıktılar yayımlar. Çıktı biçimi her plugin için provider tarafından tanımlanır; adım çıktılarının kapsamı aynı pipeline’dır ve yalnızca bildirim sırasındaki sonraki adımlara görünür. templates/expansion-matrix.md sayfasında, 10. satırda belgelenmiştir.

Bugünkü durum: kullanılabilir.

Provider işleme — guest tarafından yürütülen soket

Bir provider, bir Wasm guest’idir. İşleme yalnızca Wasm ile yapılır: bir Recipe’in capability: adı, bu adı kendi spec.provider.capabilities alanında listeleyen ve bir render_node dışa aktarımı ilan eden provider işleme Plugin’ine (pluginType: provider) çözümlenir ve düğümü o plugin’in guest’i işler. Geri dönülecek bir ana makine içi işleyici yoktur; hizmet veren hiçbir Plugin’e çözümlenmeyen bir provider adı, derlemeyi yönlendirme sırasında durdurur. Standart bir provider eklemek, bir .wasm guest’i ve bir katalog Plugin varlığı yayımlamaktır — ana makine provider’a özgü hiçbir kod taşımaz.

Bir provider’ın sunduğu bir yetenek iki nokta üst üste içermez; bir pipeline adımının uyumlu olduğunu bildirdiği bir yetenek de içermez. Bir Recipe’in capability: değeri, son iki nokta üst üsteye kadar olan kısım yetenek, sonrası sürüm sabitlemesi olarak okunur — helm:1.0.0, 1.0.0 sürümünde helm ister — bu nedenle iki nokta üst üste içeren bir ad, hiçbir Recipe’in isteyemeyeceği bir addır. Ana makine, bir provider ya da pipeline-step guest’inin describe() çıktısındaki capabilities içinde böyle bir adı, guest yüklendiğinde ve varlığı yayın için üretildiğinde reddeder ve guest’i ile adı belirtir. Bir ayrıştırıcının parse:<format> ve bir içe aktarıcının import:<format> değerleri iki nokta üst üstelerini korur: bunlar biçime göre aranır, hiçbir zaman bir Recipe’in capability: alanı aracılığıyla aranmaz.

Ana makine genel bir yönlendiricidir. Guest’in describe() öz raporunu — işleme davranışı sözleşmesi dahil — okur ve hiçbir provider biçimini anlamadan guest’in dışa aktarımlarını çağırır. Bu sözleşme, yönlendirmeyi veri olarak yürütür:

  • input_kinds (sourced, synthesized, artifacts_standalone) — guest’in hangi Recipe girdi türlerini işlediği; ana makine bir düğümün girdi türünü bu kümeye göre denetler.
  • boundary_assembly (none | merge | nest) — guest’in bir yönlendirme grubunun çıktısını nasıl birleştirdiği: merge, düğüm başına çıktıyı birleştiricinin tek bir yapıtta birleştirdiği parçalar olarak sınıflandırır; nest, düğüm başına dosyaları birleştirilmiş bir sarmalayıcının altına yerleştirir; none ise her düğümün çıktısını doğrudan yazar.
  • nest_segment (isteğe bağlı) — bir nest derlemesi için, her katkıda bulunanın kendi alt dizininin altına yerleştirildiği dizin, tek bir dizin adı olarak yazılır; yoksa her katkıda bulunanın alt dizini doğrudan yönlendirme konumunda yer alır.
  • assembly_name_annotation (isteğe bağlı) — çözümlenmiş değeri, konuğun bir yönlendirme grubundan bir araya getirdiği yapıtı adlandıran bir sınır ek açıklaması; yoksa konuk birleşimini yalnızca yönlendirme yolundan adlandırır.
  • cross_boundary_linking (isteğe bağlı) — konuğun sınır ötesi bir uses kenarını link_publish ve link_resolve dışa aktarımları aracılığıyla bağlayıp bağlamadığı; bir konuk bunu yalnızca ikisini de dışa aktardığında true olarak bildirir ve yükleme, bayrağı ile dışa aktarımları uyuşmayan bir konuğu reddeder.
  • artifact_delimiters (isteğe bağlı) — guest’in yapıt gövdelerine uyguladığı Go şablonu ayraç çifti.
  • reusable_instance (isteğe bağlı) — yüklenmiş tek bir örneğin derlemenin her geçişine hizmet edip edemeyeceği (aşağıdaki Determinizm ve örneğin yeniden kullanımı bölümüne bakın).
  • omits (isteğe bağlı) — guest’in bir kaynak işlemenin taşıdığı dışarıda bırakma girdilerine uyup uymadığı (aşağıdaki İşlenmiş birimleri dışarıda bırakma bölümüne bakın).
  • boundary_artifacts (isteğe bağlı) — guest’in hedefinin, bir Recipe’in sınırının paylaşılan çıktısına kattığı dosyaları kabul edip etmediği (aşağıdaki Bir Recipe’in sınıra kattığı dosyaları kabul etme bölümüne bakın).
  • source_ignore (isteğe bağlı) — guest’in ekosisteminin, işlediği bir kaynağın yanında hiçbir zaman yayımlamadığı dosyalar (aşağıdaki Bir kaynağın ekosisteminin hiçbir zaman yayımlamadıklarını bildirme bölümüne bakın).

Soket sabit bir dışa aktarım kümesidir — biri zorunlu, geri kalanı isteğe bağlıdır ve describe() içinde ilan edilir:

  • render_node (zorunlu) — bir IR düğümünü provider’a özgü dosyalara işler.
  • assemble_boundary (isteğe bağlı) — bir yönlendirme grubunun düğüm başına çıktısını yol başına tek bir yapıtta birleştirir (boundary_assembly değeri merge ya da nest olduğunda bulunur).
  • validate_node_input (isteğe bağlı) — bir düğümün girdisinin işleme öncesi yapısal doğrulaması; bir halt tanılaması derlemeyi durdurur, bir warn ise derleme sonucuna yansır.
  • carve / reassemble (isteğe bağlı, eşli) — guest’in işleme sonrası pipeline adımları için kendi bayta sadık yama kodeği; yalnızca ikisi de ilan edildiğinde kullanılır.
  • name_bound (isteğe bağlı) — konuk, host’un bir bileşen kimliği olarak önerdiği bir adın hedefinin kabul ettiği adlar üretip üretmediğine karar verir ve kendine ait bir adla değil, bir kısıtla yanıt verir.
  • rendered_name (isteğe bağlı) — konuk, hedefinin bir düğüm için işlediği kaynaklara verdiği adı bildirir.
  • link_publish / link_resolve (isteğe bağlı, eşli) — konuk, sınırlar arası bir uses kenarını bağlar: tüketilen uç bir tanıtıcı yayımlar, tüketen uç ise bunu kendi birleştirilmiş çıktısına çözümler.

Recipe artifacts: öğeleri, girdideki bir artifacts izdüşümü aracılığıyla render_node içine katlanır: $import okumasını, Go şablonu değerlendirmesini ve köken anahtar/değer hesaplamasını host yapar ve her girdiyi konuğa önceden okunmuş ve değerlendirilmiş olarak verir; yerleştirme ve yalnızca konuğun bildiği biçimde yayma işi konuğa aittir. architecture/13-catalog-and-registry.md adresinde belgelenmiştir.

Bir kaynak işlemesinin girdisi düğümün değerlerini node.values üzerinde taşır ve node.values_mapped bunların nereden geldiğini söyler: değerler Recipe’in valuesMapping çıktısı olduğunda — ya da bir ekin kendi işlemesi için, onun FeatureRecipe’inin çıktısı olduğunda — true olur; değerler bileşenin yazıldığı gibi aktarılan kendi değerleri olduğunda ise bulunmaz. Bir konuğun bunu okuyup okumaması o konuğun kendi sözleşmesidir. cloudformation sağlayıcısı, kaynaklı bir şablonun Parameters öğelerini yalnızca bir eşlemenin ürettiği değerlerden bağlar, çünkü bir bileşenin kendi değerleri Recipe’in diğer girdileri için yazılmış olabilir; terraform sağlayıcısı ise kaynaklı bir modülün argümanlarını birleştirmesinin aldığı değerlerden yazar ve bayrağı okumaz. Bu değerler, bir kaynaktan işlenen bir düğüm için bir assemble_boundary girdisinin her işlenmiş düğümünde taşınır — bir bileşeninkiler, bir eşleme üretmiş olsun ya da olmasın; ekli bir Feature’ınkiler ise yalnızca FeatureRecipe’inin valuesMapping öğesi ürettiğinde — ve aynı bayrak bunların yanında ve yalnızca bunların taşındığı yerde taşınır; böylece bir birleştirici, düğümün kendi işlemesinin aldığı yanıtın aynısını okur. cloudformation sağlayıcısı bir düğümün bağlamasının hangi parametreleri doldurduğunu öğrenmek için bayrağı orada okur ve yığının başka herhangi bir yerinden, ekli bir Feature’ın host’u da dahil, bunlardan birine yapılan bir başvuruyu reddeder. Bayrak değerlerin nasıl üretildiğini kaydeder ve asla bir anahtardan ya da değerden türetilmez.

Kablo kodlaması. Bu soketin her dışa aktarımı girdisini alır ve çıktısını her iki yönde de kanonik CBOR (RFC 8949 §4.2.1) olarak döndürür. Bir konuk, girdisini çözer ve çıktısını yük türlerinin zaten taşıdığı giriş noktaları aracılığıyla kodlar — Go’da DecodeCBOR ve EncodeCBOR, Rust’ta decode_cbor ve encode_cbor, TypeScript’te ise her türün decodeCBOR ve encodeCBOR işlevi, örneğin decodeCBORRenderNodeInput ve encodeCBORRenderNodeOutput — ve bayt okuyup yazar (Rust’ta Vec<u8>, TypeScript’te Host.inputBytes() ve Host.outputBytes(...)). Hiçbir CBOR kütüphanesi gerekmez ve hiçbir şey baytları elle ayrıştırmaz. İşlenmiş bir dosyanın content alanı ve diğer her bayt alanı, üretilen çözücünün kitin kendi alan türüne doldurduğu ham bir bayt dizisi olarak geçer: Go’da bir bayt dilimi, Rust ve TypeScript’te bir base64 dizesi. Şemanın sırayı koruyan olarak işaretlediği eşlemeler — bunlar arasında bir düğümün values, features ve uses öğeleri, bir yanıtın derived_keys öğesi ve bir birleştirme katkıcısının values öğesi — derlemenin onları tuttuğu sırayla sıralı girdi listeleri olarak geçer ve bir konuk bunları kitinin sırayı koruyan kapsayıcısı aracılığıyla okur. Bir düğümün values öğesinin her değeri kendi JSON belgesinin baytları olarak geçer; böylece bir değerin içindeki anahtarlar yazıldıkları sırayı korur; features öğesinin her ek girdisi, işleme bağlamı, ayrıştırılmış iş yükü, her zenginleştirilmiş kenar, her oyulmuş birim ve her yama işlemi de aynı şekilde geçer ve bir konuk içlerine bakmak için bunları JSON olarak ayrıştırır. Her tanılama paylaşılan Diagnostic biçiminde geçer. Bu kodlamada dışa aktarımının çıktı biçiminde olmayan bir yanıt — JSON olarak yazılmış ya da biçimin bildirmediği bir üst düzey alan taşıyan bir yanıt — çağrılan dışa aktarımı adlandırarak derlemeyi durdurur. Bu sayfadaki yük örnekleri okunabilmeleri için JSON olarak yazılmıştır. aggrega plugin run-local --export render_node ile ya da soketin başka herhangi bir dışa aktarımıyla doğrudan çağrıldığında, konuğa bu kodlamaya dönüştürülmüş yazılmış JSON yükü verilir ve yanıtı dışa aktarımın çıktı biçimi olarak okunup JSON olarak yazdırılır — bu biçimde olmayan bir yanıt, bir derlemenin reddettiği gibi, dışa aktarımı adlandırarak reddedilir.

Bugünkü durum: beş sağlayıcının tümü için kullanılabilir. helm konuğu kaynaklı chart’ları (chart kökünü çözümleyerek), sentezlenmiş iş yüklerini ve bağımsız yapıtları düz Kubernetes manifestoları olarak işler. helm-chart konuğu bir şemsiye chart birleştirir, her düğümün kaynaklı chart’ını bir alt chart olarak iç içe yerleştirir ve bayta sadık bir yama kodlayıcısı ile köşeli ([[ ]]) yapıt sınırlayıcıları taşır. compose konuğu kaynaklı compose dosyalarını ve sentezlenmiş iş yüklerini işler, bir dağıtım grubunu tek bir docker-compose.yaml dosyasında birleştirir ve bir servisi, x-aggrega-networks-of alanının adlandırdığı bileşenlerin ağlarına katar. terraform konuğu Terraform yapılandırmasını olduğu gibi (HCL ya da JSON) yayar ya da kaynaklı bir modülü dahil edip girdilerini o bileşenin modül bloğu argümanları olarak sağlar, kaynaklı bir modülün HCL’ini işlemeden önce yapısal olarak doğrular ve bir sınırı, her bileşeni o bileşenin kendi alt dizinini kaynak alan bir modül bloğu olarak bildiren tek bir kök yapılandırmada birleştirir. cloudformation konuğu kaynaklı şablonları ve bağımsız yığın parçalarını işler, bir dağıtım grubunu tek bir yığın şablonunda birleştirir ve sınırlar arası bir uses kenarını link_publish ve link_resolve aracılığıyla bağlar. Her biri çevrimdışı ve belirlenimci biçimde işler.

Bir guest’in türettiği adları bildirmek

Bir provider guest’i, çıktısının ihtiyaç duyduğu ama kimsenin yazmadığı adları — bir hedefin tek bir kaynağa eriştiği tanımlayıcıyı, bir çıktının başka birinin başvurması için yayımlandığı adı — genellikle düğüm kimliğinden ve üretmekte olduğu kaynaktan türetir. Türetildikleri parçalar örtüştüğünde iki düğüm aynı ada ulaşabilir ve ad, host’un olduğu gibi yazdığı dosya baytlarının içinde bulunduğundan host bu çakışmayı göremez: bulmak için provider’ın biçimini ayrıştırması gerekirdi ki bu da tam olarak guest’te kalan bilgidir.

Bu nedenle render_node çıktısında isteğe bağlı bir derived_keys döndürür ve yön tersine çevrilir — host’un çıktıyı incelemesi yerine guest bildirir, host denetler:

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"derived_keys": {
"logical-ids": ["paymentsapiQueue", "paymentsapiTopic"],
"export-names": ["aggrega--prod--api--orders-db--host"]
}
}

derived_keys içindeki her anahtar, guest’in adlandırdığı bir anahtar uzayıdır ve her uzay, guest’in ona türettiği adları türetme sırasıyla taşır. Hem uzay adları hem de içlerindeki adlar sizin sözcük dağarcığınızdır: host bunları yalnızca tek bir uzay içinde eşitlik için karşılaştırılacak dizeler olarak okur. Bir adı ayrıştırmaz, bir uzayın ya da adın ne anlama geldiğini öğrenmez ve kendisi hiçbir zaman ad türetmez — böylece tek bir denetim her provider’ın türettiği her tür adı kapsar ve yeni bir provider yeni host koduna ihtiyaç duymaz. Yayımlanan türlerde derived_keys sırayı koruyan bir eşlemedir, dolayısıyla uzaylar guest’inizin onları ayarladığı sırayla aktarılır.

Host’un bunlarla yaptığı tek bir sorudan ibarettir: tek bir uzay içinde, çıktıları tek bir derlemede birleşen katkıda bulunanlar arasında bildirilen her ad benzersiz mi? Tek bir uzayda aynı adı bildiren iki katkıda bulunan derlemeyi durdurur ve durdurma, uzayı, adı ve her iki katkıda bulunanı belirtir; böylece bir yazar provider’ı okumadan harekete geçebilir. Benzersiz adlar ve iki farklı uzayda tesadüfen eşleşen adlar geçer.

Neyi bildireceğinize karar verirken bilinmesi yararlı üç özellik vardır:

  • Kapsam, tek bir derlenmiş çıktıdır — dosyaları birlikte birleşen katkıda bulunanlar kümesi. Bundan daha dar ya da daha geniş bir kapsamda benzersizlik isteyen bir guest, kapsamı bildirdiği uzay adında ifade eder; bu da seçimi host’ta değil sizde bırakır.
  • Tek bir katkıda bulunan bir adı serbestçe tekrarlayabilir. Bir düğüm birkaç geçişte işlenebilir — bir kaynak işleme, bir workload sentezi, bir artifacts yerleştirmesi — ve bildirimler birleşir. Tek bir katkıda bulunanın iki kez bildirdiği aynı ad, o katkıda bulunanın tek bir kaynağı iki kez tanımlamasıdır, çakışma değildir.
  • Bildirmek hiçbir baytı değiştirmez. Alan, guest’in ne türettiğine ilişkin bir beyandır, ürettiği şeyde asla bir değişiklik değildir; dolayısıyla bir guest’in işlenmiş çıktısı bildirse de bildirmese de aynıdır. derived_keys alanını atlamak geçerlidir ve o guest için denetimi etkisiz bırakır.

Bir guest’in ürettikleri hakkında olguları bildirmek

Bir düğümün işlenmesine ilişkin bazı şeyler yalnızca onu üreten provider tarafından görülebilir — yazdığı belgelerin ne içerdiği, hangi adları tanımladıkları, bir şeyden kaç tane ürettiği — çünkü bunları dosya baytlarından okumak provider’ın biçimini anlamayı gerektirir. render_node bu tür şeyleri, dosyalarının yanında isteğe bağlı bir render_facts listesiyle kendisi bildirebilir:

{
"files": [ { "path": "stack.yaml", "content": "..." } ],
"render_facts": [
{ "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] },
{ "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] }
]
}

Her olgu bir name ve bir value’dur ve ikisi de provider’ınıza aittir: hangi olguları bildirdiği, her adın ne anlama geldiği ve her girdinin ne tuttuğu provider’ınızın kendi belgelenmiş sözleşmesinin parçasıdır; bu yüzden bunları okuyacak yazarlar için belgeleyin.

Her olgunun değerini, tek bir girdi tutsa bile bir liste — bir JSON dizisi — olarak bildirin. Bir ad, bir bileşenin birden fazla işlemesi tarafından bildirilebilir: bileşenin kendi işlemesi birkaç çağrı sürebilir — örneğin bir chart işlemesi ve bir artifacts yerleştirmesi — ve bileşene bağlanan her Feature kendi provider çağrısıyla işlenir. Hiçbir provider işleme sırasında raporunun bir ad altındaki tek rapor olup olmayacağını bilemez; bu yüzden her rapor bir listedir ve derleyici bir adın aldığı listeleri tek bir listede birleştirir. Değeri başka bir şey olan — bir nesne, bir dize, bir sayı, bir boolean, null — bir olgu, guest’iniz onu döndürdüğünde reddedilir: derleme E0325 kısa koduyla durur; olguyu, düğümü ve guest’inizi belirtir ve değerin ne olduğunu söyler. Bir listenin içindeki girdiler, belgelediğiniz biçimdeki herhangi bir JSON değeridir.

Bir değerin liste olması, derleyicinin onun hakkında öğrendiği tek şeydir. Olguları ada göre anahtarlar ve her listeyi onu okuyan şablonlara verir — host bileşenin olgularını ona bağlı her Feature’a, her çağıranın olgularını çağıranlarının render olgularını okuduğunu bildiren bir Feature’a ve her hedefin olgularını host’unun bağlandığı bileşenlerin render olgularını okuduğunu bildiren bir Feature’a, şablon bağlamının açıkladığı gibi — ve her listeyi bir şablonun üzerinde dolaşabileceği bir değere çözer. Bir adın ya da girdinin ne anlama geldiğini hiçbir zaman öğrenmez ve kendisi hiçbir zaman olgu türetmez; böylece yeni bir provider, derleyici tarafında hiçbir değişiklik olmadan yeni olgular bildirebilir. Düğüme bağlı bir Feature’ın kendi işlemesinden bildirdiği olgular, düğümün kendi işlemesinin bildirdiklerinden ayrı tutulur.

Neyi bildireceğinize karar verirken bilinmesi yararlı dört özellik vardır:

  • Sıra sizindir. Olgular guest’inizin onları listelediği sırayı korur ve her değer kendi baytlarını korur — bir listenin girdilerinin ve her nesnenin anahtarlarının sırası guest’inizin yazdığı sıradır. Olguları sabit bir sırayla listeleyin ve her girdiyi sabit bir anahtar sırasıyla yazın; böylece aynı girdi aynı baytları üretir. Olgular için bir eşleme yerine bir listenin bulunmasının nedeni tam da sıranın, işaretlenecek hiçbir şey olmadan her kitin kendi dizi türünde korunmasıdır; oysa bir eşleme, guest’in yazdığı sırayı yalnızca şeması onu sırayı koruyan olarak işaretlediğinde ve guest kitinin sırayı koruyan kapsayıcısını doldurduğunda korur.
  • Bildirmek hiçbir baytı değiştirmez. Derleyicinin yazdığı dosyalar, yanlarında olgular olsun ya da olmasın, guest’inizin döndürdüğü dosyalardır.
  • Bir düğüm birkaç geçişte bildirimde bulunabilir. Bir düğüm bir kaynak işleme, bir workload sentezi ve bir artifacts yerleştirmesi olarak işlenebilir; her birinin bildirdiği olgular geçişlerin çalıştığı sırayla tutulur ve birden fazlası tarafından bildirilen bir ad, onları bu sırayla birleştiren tek bir liste olarak okunur.
  • Hiçbir şey bildirmemek eksiksizdir. render_facts alanını atlamak geçerlidir ve hiçbir şey bildirmeyen bir provider, alan olmasaydı nasıl işleyecekse tam olarak öyle işler.

RenderFact türü üç ABI paketinde yayımlanır ve her dilin plugin geliştirme kiti tarafından yeniden dışa aktarılır; kitlerin render örnekleri dosyalarının yanında iki olgu bildirir. Go’da değer, guest’inizin yazdığı JSON’dur; eşlemeler yerine struct’lardan oluşan bir dilimi marshal etmek, her girdinin anahtarlarını bildirdiğiniz sırada tutan şeydir:

type stackFact struct {
Name string `json:"name"`
Resources int `json:"resources"`
}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})
if err != nil {
pdk.SetError(err)
return 1
}
out := aggrega.RenderNodeOutput{
Files: files,
RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},
}

İşlenen birimleri dışarıda bırakma

Bir kaynak işlemesi, provider’ın işlediği çıktının dışında bırakması gereken birimleri adlandırabilir; örneğin getirilen bir chart’ın her işlemede yeniden ürettiği bir Secret. Bir girdinin hangi işlenmiş birimi adlandırdığını yalnızca sizin provider’ınız bilir. Bu yüzden girdiler guest’inize iletilir ve dışarıda bırakma işini guest’iniz yapar. Girdiler, render_node girdisinde source_listing’in yanında isteğe bağlı bir omits listesi olarak gelir:

{
"node": { "id": "payments-api" },
"context": { },
"source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] },
"omits": [
{ "kind": "Secret", "name": "payments-api-token", "namespace": "payments" },
{ "kind": "ConfigMap", "name": "payments-api-dashboards" }
]
}

Her girdi bir kind, bir name ve isteğe bağlı bir namespace’ten oluşur. Bunlar düz dizelere çözümlenmiş olarak, yazarın bildirdiği sırayla listelenir. Derlemeye uygulanmayan bir girdi iletilmez. Üç alanın neyi seçtiği sizin provider’ınızın kendi sözleşmesidir: hedefinizin biçimindeki bir kaynağın türü, adı ve ad alanı. Bu nedenle bunu, girdileri yazan yazarlar için belgeleyin.

Bir yazar, bir girdinin alanlarını hassas olarak bildirdiği bir değerden oluşturabilir; örneğin adını hassas bir ayardan alan bir kaynak. Böyle bir girdi "sensitive": true ile gelir ve guest’iniz onu, işleme girdisinin taşıdığı diğer tüm işaretli değerler gibi ele alır (bkz. Bir girdinin hassas olarak işaretlediği değerler). Girdiyi yine alanlarına göre eşleştirir ve sayar, çünkü girdi bunun için vardır. Ancak girdinin hiçbir alanını bir retteye, uyarıya ya da günlük satırına koymaz. İşaret girdinin tamamını kapsar, çünkü derleyici değerin hangi alanı ürettiğini söylemez. Hiçbir alan böyle bir değerden oluşturulmadığında işaret bulunmaz.

Girdileri dikkate alan bir guest üç şey yapar:

  • Her girdiyi işlediği çıktıyla karşılaştırarak eşleştirir; bunu sizin biçiminizin terimleriyle yapar.
  • Eşleşen her birimi döndürdüğü her şeyin dışında bırakır: files içeriğinin, derived_keys içinde bildirdiği adların ve render_facts içinde raporladığı olguların dışında. Böylece derleyicinin aldığı hiçbir şey o birimi artık tanımlamaz.
  • Her girdi için bir sayı raporlar: çıktısındaki isteğe bağlı bir omitted listesinde, girdilerin geldiği sırayla. Her sayı, o girdinin eşleştiği birimlerin sayısıdır ve bu birimleri başka bir girdinin de eşleştirip eşleştirmediğine bakılmadan sayılır:
{
"files": [ { "path": "templates/deployment.yaml", "content": "..." } ],
"omitted": [1, 0]
}

Sıfır eksiksiz bir yanıttır: o girdi, guest’inizin işlediği hiçbir şeyle eşleşmemiştir. Dışarıda bırakılanlar hakkında geri dönen tek bilgi sayılardır; birimlerin kendisi, guest’inizin döndürdüğü çıktıda yer almaz.

Bu üçünü de yapan bir provider, bunu sözleşmesinde omits: true ile bildirir. Plugin varlığı aynı iddiayı spec.provider.contract.omits olarak kaydeder. Varlık bir işleme davranışı sözleşmesi taşıyorsa yükleme, describe() çağrısı farklı bir değer raporlayan guest’i reddeder. Girdiler yalnızca bir kaynak listesine eşlik eder: sentezlenmiş bir workload’un ya da bir yapıt kümesinin işlenmesi bunları hiçbir zaman taşımaz.

Hiç girdi taşımayan bir işleme bu alanlardan etkilenmez. İki alan da isteğe bağlıdır ve boş olduklarında bulunmazlar. Bu nedenle hiç girdi taşımayan bir işleme, soketten alanlar hiç yokmuş gibi bayt bayt aynı biçimde geçer ve bu alanları hiç okumayan bir guest onlardan etkilenmez. OmitEntry türü üç ABI paketinde yayımlanır ve her dilin plugin geliştirme kiti tarafından yeniden dışa aktarılır.

Derleyicinin yanıtınızla yaptığı. Girdiler, bir yazarın bir Recipe ya da FeatureRecipe üzerine yazdığı omits: anahtarından gelir (Recipe → omits: alanı). Derleyici her girdinin şablonlarını değerlendirir ve uygulanan girdileri guest’inize verir. Ardından sayılarınızı okur, yalnızca sayılarınızı: bunları denetlemek için döndürülen bir dosyanın içine hiçbir zaman bakmaz:

Bugünkü durum: kullanılabilir. Derleyiciyle dağıtılan helm, compose ve cloudformation guest’leri bu iddiayı bildirir ve girdileri dikkate alır. Helm guest’i, döndürdüğü hiçbir metne herhangi bir girdinin hiçbir alanını yazmaz. Compose ve cloudformation guest’leri bir girdiyi reddettiklerinde girdinin türünü, adını ve ad alanını belirtir. Bir girdinin dışarıda bıraktığı birimleri hâlâ adlandıran bir dosyayı ya da şablonu reddettiklerinde ise o birimleri belirtir. Bu durumlarda işaretli bir girdinin her alanını <redacted> olarak gösterirler. Helm-chart ve terraform guest’leri bu iddiayı bildirmez. Bu nedenle bunlardan birinin işlediği ve omits: bildiren bir belge reddedilir.

Bir Recipe’in sınıra kattığı dosyaları kabul etme

Bazı dosyalar, sınırın bileşenlerinden birine değil, sınırın bütününe aittir; örneğin bir hedefin, sınırın dağıttığı her şey için bir kez okuduğu bir provider yapılandırması. Bir Recipe bu dosyaları spec.boundary.artifacts altında yazar ve işi guest’iniz değil derleyici yapar. Derleyici her dosyayı, bir artifacts: girdisinin değerlendirildiği bağlama göre değerlendirir. Gönderim grubuna katkıda bulunan her katılımcının bildirdiği dosyaları ada göre birleştirir. Her dosyayı, grubun birleştirilmiş çıktısını tutan dizine, assemble_boundary çağrınızın döndürdüklerinin yanına bir kez yazar. Bu dosyaların hiçbiri herhangi bir dışa aktarımda guest’inize verilmez ve guest’inize bunlardan biri hakkında hiçbir zaman soru sorulmaz. Bu nedenle uygulanacak bir şey yoktur; yalnızca hedefiniz hakkında bir beyanda bulunmanız gerekir:

"contract": {
"input_kinds": { "sourced": true, "artifacts_standalone": true },
"boundary_assembly": "nest",
"boundary_artifacts": true
}

boundary_artifacts: true bildirimini yalnızca hedefiniz, o dizine yerleştirilen bir dosyayı sınırın çıktısının parçası olarak okuyorsa yapın. Plugin varlığı aynı iddiayı spec.provider.contract.boundaryArtifacts olarak kaydeder. Varlık bir işleme davranışı sözleşmesi taşıyorsa yükleme, describe() çağrısı farklı bir değer raporlayan guest’i reddeder. Bloğu bildiren ve provider’ı bunu iddia etmeyen bir Recipe, herhangi bir şey işlenmeden önce reddedilir. Ret, provider’ı ve bileşeni belirtir; bkz. The provider does not support boundary artifacts (Provider sınır yapıtlarını desteklemiyor). Bu birleştirmelerden birinin, birleştirmenizin de yazdığı bir ada yerleştirdiği dosya, derlemeyi iki katılımcının aynı çıktı yoluna yazması durumu olarak durdurur. Bu nedenle birleştirmenizin yazdığı adlar, yazarlar için belgelediklerinizin bir parçasıdır.

Bugünkü durum: kullanılabilir. Derleyiciyle dağıtılan terraform guest’i bu iddiayı bildirir ve Terraform her dosyayı sınırın kök yapılandırmasının yanında okur. Helm, compose, helm-chart ve cloudformation guest’leri bu iddiayı bildirmez.

Bir kaynağın ekosisteminin hiçbir zaman dağıtmadığı şeyleri bildirme

Bir Recipe’in yerel kaynak dizini — aynı yerde tutulan bir chart, bir modül — Recipe ile birlikte yayımlanır ve içindeki her dosya ona ait değildir. Bir provider guest’i, kendi ekosisteminin hiçbir zaman dağıtmadığı şeyleri sözleşmesindeki source_ignore aracılığıyla, .gitignore’un kullandığı söz diziminde yok sayma kuralları olarak bildirir:

"contract": {
"input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false },
"boundary_assembly": "none",
"source_ignore": {
"patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"],
"files": [".helmignore"]
}
}
  • patterns, kaynak dizininin kökünden okunan, sırayla uygulanan kurallardır; sonraki bir eşleşme öncekini geçersiz kılar.
  • files, ekosisteminizin bir kaynağın içinde dikkate aldığı yok sayma dosyalarını adlandırır. Bir kaynağın taranması sırasında bunlardan biriyle karşılaşıldığında, satırları, sizin kalıplarınızdan sonra, onu barındıran dizin için ek kurallar olarak okunur.

Bildirim, bir varlık işlendiğinde değil, sabitlendiğinde okunur. Yazarın sabitleme adımı, çalışma alanında varlığın yeteneğine hizmet eden plugin’i çözümler, sizin kurallarınızı yazarın kendi .aggregaignore dosyasıyla birleştirir — bu dosyanın satırları en son gelir ve bu nedenle adlandırdıkları her yolda üstün gelir — ve plugin’inizin adını, sürüm olmadan, birleştirilmiş kuralların tam haliyle birlikte varlığın entity.lock dosyasına kaydeder. O varlığın sonraki her yayımlanması, karşılaştırılması ve işlenmesi kaydedilmiş kuralları uygular; ana makine bunları eşleştirir ve herhangi bir ekosistem hakkında kendine ait bir görüş taşımaz. Böylece guest’inize işleme sırasında verilen dosyalar — listeleme ve ana makineden paketlemesini veya okumasını istediği her dosya — tam olarak varlığın bir yayımının taşıdığı dosyalardır ve kuralların dışarıda bıraktığı bir dosya, adı belirtilerek, yokmuş gibi yanıtlanır. Bir kaynak altındaki sembolik bağlantı, guest’iniz çağrılmadan önce reddedilir.

Uyumluluk, kaydedilmiş olandan çıkar. Bir guest, aynı ABI sürümünü konuşuyorsa, sözleşmesi varlığının beyanıyla eşleşiyorsa ve yayımlanmış kümenin dışında hiçbir dosyaya ihtiyaç duymuyorsa, kendi yeteneği için yayımlanmış bir Recipe’i işleyebilir. Kümenin dışarıda bıraktığı bir dosyaya ihtiyaç duyan bir guest, derlemesini açıkça başarısız kılmalı ve dosyayı adlandırmalıdır — ana makinenin bir paketleme ya da okuma isteğini reddi dosyayı adlandırır ve guest bunu kendi hatasına taşır. Bir tüketicinin çalışma alanının bir yetenek için bağladığı plugin, bir varlığın kilidinin kaydettiklerinden farklı kurallar bildirdiğinde, tüketicinin çekme işlemi her iki plugin’i ve farkı adlandıran bir uyarı yazdırır; bu nedenle hiçbir zaman durmaz.

source_ignore’un atlanması hiçbir kural bildirmez ve işlediğiniz bir kaynak bu durumda yazarın kendi kurallarının tuttuğu her dosyayı tutar. Alan isteğe bağlıdır ve kendine ait bir ABI sürümü gerektirmez: onu atlayan bir guest, hiçbir şey bildirmeyen bir guest olarak yüklenir. Plugin varlığı aynı bildirimi spec.provider.contract.sourceIgnore olarak kaydeder; kaydettiği durumda yükleme, describe() çağrısı farklı bir şey bildiren bir guest’i reddeder.

Belirlenimcilik ve örneğin yeniden kullanımı

Ana makine bir guest’in çıktı baytlarını olduğu gibi tüketir; bu nedenle bir guest aynı girdiden aynı çıktıyı üretmelidir. Varsayılan olarak bir guest her düğüm için yeniden yüklenir — yapısı gereği düğümler arasında hiçbir durum taşınmaz. Kendini reusable_instance olarak bildiren bir guest ise derleme başına bir kez yüklenir ve tek örneği her geçişe hizmet eder; bu, baskın olan düğüm başına örnekleme maliyetini geri kazandırır. Yeniden kullanım yalnızca durumsuz bir guest için güvenli olduğundan, aggrega build --verify-determinism her düğümü aynı örnek üzerinden iki kez işler ve herhangi bir düğümün iki işlemesi farklıysa derlemeyi durdurur; varsayılan derleme bir kez işler ve bildirime güvenir. Wasm derleme önbelleği diskte tutulur ve süreç genelindedir; böylece bir guest bir kez derlenir ve sıcak derlemeler yeniden derlemeyi atlar.

Linter soketi — yayımlama linter’ı

Linter soketi, derleme zamanında değil aggrega lint aracılığıyla çalışan, bant dışı bir kapı olan standart publishing-linter olarak dağıtılır. Bir katalog varlığını (ve --pre-publish modunda, varlığın şu anda yayımlanmış sürümünü) tüketir ve her biri bir önem derecesi ve bir ileti taşıyan bulguların listesini döndürür; --pre-publish modunda ayrıca bir sürüm artışı sınıflandırması döndürür. Ana makine onu, diğer her soketle aynı AOT saflık güvenlik duvarının arkasında, gömülü Wasm çalışma zamanı üzerinden çalıştırır. Kural kümesinin tamamı, önem dereceleri ve kural başına devre dışı bırakma seçenekleri cli/aggrega-lint.md belgesinde açıklanmıştır.

Linter, isteğe bağlı bir katalog disiplinidir: derleyici onu aggrega build sırasında çalıştırmaz (derleme sırasında warn önem derecesinde ve aggrega lint --pre-publish altında halt önem derecesinde ortaya çıkan x-aggrega-* caydırma uyarısı tek istisnadır). Kurallar bir plugin içinde yaşadığından, bir kuruluş kendi disiplinini uygulamak için aggrega lint’i farklı bir linter plugin’ine yönlendirebilir.

aggrega lint’in çalıştığı hiçbir kapsamda bir linter plugin’ine hiçbir parametre değeri ulaşmaz. Herhangi bir belge teslim edilmeden önce ana makine, bir Aggregate’in parametre varsayılanlarını, içe aktardığı her modüle geçirdiği değerleri ve bir Release’in parametrelerini saklar; her parametre bildiriminin sözleşmesini — yalnızca bir bildirimin, iç içe geçtiği her düzeyde, yazıldığı anahtarları — ve bir parametreyi okuyan her şablon metnini korur: bir parametrenin değeri bizzat bir kimlik bilgisi olabilir ve buraya bağlanan plugin, çalışma alanının yazmadığı bir kod olabilir. Her belgenin ne taşıdığı Bir linter plugin’ine ne verilir başlığı altında açıklanmıştır.

Kablo kodlaması. Girdi ve çıktı her ikisi de kanonik CBOR olarak taşınır (RFC 8949 §4.2.1). Bir guest girdisini çözer ve çıktısını, kitinin LinterInput ve LinterOutput türlerinin zaten taşıdığı giriş noktaları üzerinden kodlar — Go’da DecodeCBOR ve EncodeCBOR, Rust’ta decode_cbor ve encode_cbor, TypeScript’te decodeCBORLinterInput ve encodeCBORLinterOutput — baytları okuyup yazarak (Rust’ta Vec<u8>, TypeScript’te Host.inputBytes() ve Host.outputBytes(...)). Hiçbir CBOR kütüphanesi gerekmez ve hiçbir şey baytları elle ayrıştırmaz. Varlık belgeleri — proposed, previous, implemented_component ve release — ve components’in her değeri JSON belgelerinin baytları olarak geçer; bu nedenle bir guest içlerine bakmak için onları JSON olarak ayrıştırır. components, şemanın sırayı koruyan olarak işaretlediği bir eşlemedir; bu nedenle bir Release’in tamamını okuyan bir kuralın girdisinde, Aggregate’in bileşen örneklerini bildirdiği sırada bir sıralı girdi listesi olarak geçer ve bir guest onu kitinin sırayı koruyan kapsayıcısı aracılığıyla okur. policies, yalnızca ayarlanmış bayrakları tutan bir eşleme olarak geçer; bu nedenle taşımadığı bir bayrak false olarak okunur ve her bulgu ortak Diagnostic biçiminde geçer. Bu kodlamada bir LinterOutput olmayan bir yanıt — JSON olarak yazılmış ya da biçimin bildirmediği bir üst düzey alan taşıyan bir yanıt — hiçbir şey bulmayan bir çalıştırma olarak okunmak yerine, çağırdığı export’u adlandırarak lint işlemini başarısız kılar. aggrega plugin run-local --export lint_rules ile doğrudan çağrıldığında bir linter’a, bu kodlamaya dönüştürülmüş yazılı JSON yükü verilir ve yanıtı export’un çıktı biçimi olarak okunup JSON olarak yazdırılır — bu biçimde olmayan bir yanıt, bir derlemenin reddettiği gibi, export’u adlandırarak reddedilir.

Bugünkü durum: kullanılabilir. publishing-linter dağıtılır ve aggrega lint aracılığıyla ana makine üzerinden çalışır.

Ayrıştırıcı soketi — kanonik ağaç çıktısı

Bir ayrıştırıcı, derleyicinin yerel olarak okumadığı bir biçimde yazılmış bir kaynağı kanonik, yapılandırılmış bir ağaca dönüştürür; böylece bir tüketici kendi ayrıştırıcısını taşımak yerine ağacı okur. Ana makine, istenen biçimi parse:<format> olarak duyuran ayrıştırıcıyı çözümler ve onun parse dışa aktarımını üç yerde çağırır: bir render-verdict ilkesine yerel olarak okumadığı bir biçimde render edilmiş bir yapıt verildiğinde, bir içe aktarıcı ana makineden aggrega_parse_source aracılığıyla bir ağaç istediğinde ve hiçbir biçim adlandırmayan bir içe aktarma tanındığında (aşağıdaki içe aktarıcı soketine bakın). Bir konuk hiçbir zaman bir ayrıştırıcıyı kendisi çağırmaz.

Girdi biçimi (ana makine → konuk). Şunları taşıyan bir ParseInput belgesi:

  • format — istenen biçim; ayrıştırıcının parse:<format> yeteneklerinden biri, öneki olmadan.
  • bytes — kaynak baytları.
  • options — tüketicinin ayrıştırıcıya özgü davranış için sağladığı, olduğu gibi iletilen bir seçenekler belgesi. Tüketici hiçbirini sağlamadığında bulunmaz.

Çıktı biçimi (konuk → ana makine). Şunları taşıyan bir ParseOutput belgesi: tree — üst düzeyi bir nesne, bir dizi veya bir skaler olabilen, JSON belgesi olarak ayrıştırılmış kaynak —, ortak Diagnostic biçimindeki tanılamalar, ağaç düğümlerini özgün baytlarda konumlandıran isteğe bağlı kaynak aralıkları ve ayrıştırma tamamlanamadığında bir hata error alanı. Her alan ve kısıtlamaları, oluşturulan ayrıştırıcı soketi şema başvurusunda yer alır.

Kablo kodlaması. Girdi ve çıktı, bir konuğun aynı ParseInput belgesini aggrega_parse_source çağrısına verirken kullanılan kodlama olan kanonik CBOR (RFC 8949 §4.2.1) olarak iletilir. Bir konuk, girdisinin kodunu çözer ve çıktısını, kitinin ParseInput ve ParseOutput türlerinin zaten taşıdığı giriş noktalarıyla kodlar — Go’da DecodeCBOR ve EncodeCBOR, Rust’ta decode_cbor ve encode_cbor, TypeScript’te decodeCBORParseInput ve encodeCBORParseOutput — ve bayt okuyup yazar (Rust’ta Vec<u8>, TypeScript’te Host.inputBytes() ve Host.outputBytes(...)). Hiçbir CBOR kitaplığı gerekmez ve hiçbir şey baytları elle ayrıştırmaz. Kaynak baytları ham bir bayt dizisi olarak iletilir ve oluşturulan kod çözücü bunları kitin kendi alan türüne yerleştirir: Go’da bir bayt dilimi, Rust ve TypeScript’te bir base64 dizesi. options ve tree, JSON belgelerinin baytları olarak iletilir; böylece bir ayrıştırıcının yazdığı ağaç tüketicisine olduğu gibi ulaşır. Tamamlanamayan bir ayrıştırıcı nedenini çıktının error alanında söyler ve ayrıştırma, ayrıştırıcıyı ve o iletiyi adlandırarak başarısız olur; bu kodlamada bir ParseOutput olmayan bir yanıt — JSON olarak yazılmış ya da biçimin bildirmediği bir üst düzey alan taşıyan bir yanıt — da ayrıştırıcıyı ve onun parse dışa aktarımını adlandırarak ayrıştırmayı başarısız kılar. Başarısız bir ayrıştırma, render-verdict rolünde bir derlemeyi durdurur ve bir içe aktarıcıya aggrega_parse_source çağrısının yanıt olarak verdiği hata olarak ulaşır. Ayrıştırıcının reddettiği bir kaynak da — ağacının yanında bir halt tanılamasıyla yanıtladığı bir kaynak — aynı şekildedir: içe aktarıcının çağrısı, bu tür her tanılamanın iletisiyle, ayrıştırıcının sırasıyla başarısız olur ve ağaç ona hiçbir zaman verilmez. aggrega plugin run-local --export parse ile doğrudan çağrıldığında, bir ayrıştırıcıya bu kodlamaya dönüştürülmüş, yazılmış JSON yükü verilir — JSON’un her bayt alanını yazdığı gibi, o yükte base64 olarak yazılmış kaynakla — ve yanıtı dışa aktarımın çıktı biçimi olarak okunup JSON olarak yazdırılır — bu biçimde olmayan bir yanıt, bir derlemenin reddettiği gibi, dışa aktarımı adlandırarak reddedilir.

Tür tanımları. Ayrıştırıcı kablo türleri — ParseInput, ParseOutput, NodeSpan ve SourceSpan — üç ABI paketinin tümünde yayımlanır ve her dilin eklenti geliştirme kiti tarafından yeniden dışa aktarılır; üçünün uyum içinde kalması için tek bir kodekten oluşturulur. Her kitin parse örneği girdisini bu şekilde okur ve çıktısını bu şekilde yazar; ikili dosyanın içinde gelen HCL, TOML, YAML, JSON ve yorumlu JSON ayrıştırıcıları da öyle.

Bugünkü durum: kullanılabilir — ilkenin yerel olarak okumadığı bir biçimdeki bir yapıt için render-verdict rolünde, bir içe aktarıcı için aggrega_parse_source aracılığıyla ve hiçbir biçim adlandırmayan bir içe aktarmanın biçimini tanımak için çağrılır.

İçe aktarıcı soketi — taslak yazım çıktısı

Bir içe aktarıcı, başka bir araç için yazılmış bir kaynağı — örneğin bir ajan oluşturucudan dışa aktarılmış bir akışı — taslak Aggrega yazım dosyalarına dönüştürür. Derleme dışında çalışır: aggrega import, düzenleyici oturumunun aggrega/import yöntemi ve asistana yönelik import aracı, istenen biçimi import:<format> olarak bildiren içe aktarıcıyı çözümler ve her içe aktarma için onun import dışa aktarımını bir kez çağırır. Bir derleme onu hiçbir zaman çağırmaz. Hangi içe aktarıcının çalıştığı ve bir operatörün ona ne verdiği Bir kaynağı hangi içe aktarıcı taslaklara dönüştürür altında açıklanır. Derleyicinin okuduğu her biçim için bir tane olmak üzere kendi içe aktarıcıları Çekirdek içe aktarıcılar sayfasında açıklanır: bunların hangi biçimler olduğu, her birinin neyi okuduğu, neyin taslağını çıkardığı, aldığı ayarlar, her derleyici sürümüyle yayımlanmaları ve bir içe aktarmanın makinede henüz bulunmayan birini nasıl getirip doğruladığı.

Girdi biçimi (ana makine → konuk). Şunları taşıyan bir ImportInput belgesi:

  • format — içe aktarmanın istediği biçim; içe aktarıcının import:<format> yeteneklerinden biri, öneki olmadan.
  • bytes — kaynak baytları: bir dosyanın içe aktarılmasında dosyanın tamamı, bir dizinin içe aktarılmasında ise boş; dizinin dosyaları sources altında gelir.
  • name — önünde dizin olmadan kaynağın adı; böylece içe aktarıcı bildirdiklerinde ve taslağını oluşturduklarında kaynağı adlandırabilir: bir dosyanın içe aktarılmasında, bytes değerinin okunduğu dosyanın temel adı; bir dizinin içe aktarılmasında, dizinin tam yolundan okunan kendi temel adı; dolayısıyla aggrega import . içinde çalıştığı dizinin adını iletir, dizinin dosyalarının her biri ise yine kendi adıyla gelir. Kaynağın verecek bir adı olmadığında bulunmaz.
  • sources — adlandırılmış kaynaklar; her biri adını ve baytlarını taşır ve tümü ada göre sıralanmış tek bir listededir: bir dizinin içe aktarılmasında, dizinin içe aktarıcının bildirdiği dosya kalıplarının seçtiği her dosyası, çalışma alanının derleme çıktı klasörü hariç, dizin içindeki eğik çizgiyle ayrılmış yoluyla adlandırılmış olarak; ve bu içe aktarıcıyı bağlayan plugins.importer girdisinin with.sources altında bildirdiği dosyalar, her biri temel adıyla. Aynı ada sahip bir dizin dosyası ile bir with.sources dosyası, biri diğerini gizlemek yerine içe aktarmanın reddedilmesine yol açar. Hiç yoksa bulunmaz.
  • settings — o girdinin with.settings altında bildirdiği ayarlar nesnesi; anahtarları sıralanmış bir JSON belgesi olarak, olduğu gibi aktarılır. Hiçbir girdi içe aktarıcıyı bağlamıyorsa ya da girdi hiç ayar bildirmiyorsa bulunmaz.
  • catalog — çalışma alanının kendi kataloğunun barındırdığı Components’in bir görünümü: içe aktarıcının kendisinin seçildiği katalog — çalışma alanının katalog klasörleri ya da çalışma alanı hiçbirini belirtmiyorsa varsayılan kayıt defterinin yayımladığı ve bu makinede tutulan katalog anlık görüntüsü — ve görünümün kendisi için hiçbir şey getirilmeden. components listesi her Component adı için bir girdi barındırır ve ada göre sıralıdır; katalog bir Component’in birden çok sürümünü barındırıyorsa girdi, onu sürüm belirtmeden adlandıran bir referansın çözümlendiği sürümü açıklar. Her girdi Component’in name ve version alanlarını, labels alanını, values ve provides bölümlerinin bildirdiği üst düzey anahtar adlarını (values ve provides, her biri sıralı) ve sockets alanını — her biri soketin name alanı ile o soket üzerinden bağlanan bir bağımlılığın karşılaması gereken etiket selector alanı — Component’in bunları bildirdiği sırayla taşır. Başka birini genişleten bir Component, bildirdiklerinin yanı sıra miras aldıklarını da taşır ve miras aldığı soketler önce gelir. Görünüm yalnızca adları, sürümleri, etiketleri ve seçicileri barındırır — hiçbir zaman bir değer, bir varsayılan ya da bir gizli bilgi barındırmaz — ve sırası sabittir, böylece bir katalog tek bir bayt dizisi üretir. Katalog hiç Component barındırmıyorsa bulunmaz.

Çıktı biçimi (konuk → ana makine). İçe aktarmanın ürettiği varlıkları — her biri var olan bir katalog varlığına referans ya da taslağı çıkarılmış bir gövde —, bunların ardındaki eşleme kararlarını, paylaşılan Diagnostic biçimindeki tanılamaları, yazılacak iskele dosyalarını ve içe aktarma tamamlanamadığında bir hata error alanını taşıyan bir ImportOutput belgesi. Her alan ve kısıtları, üretilmiş içe aktarıcı soketi şema referansında yer alır.

Aktarım kodlaması. Girdi ve çıktının ikisi de kanonik CBOR (RFC 8949 §4.2.1) olarak taşınır. Bir konuk girdisinin kodunu çözer ve çıktısını, kitinin ImportInput ve ImportOutput türlerinin zaten taşıdığı giriş noktalarıyla kodlar — Go’da DecodeCBOR ve EncodeCBOR, Rust’ta decode_cbor ve encode_cbor, TypeScript’te decodeCBORImportInput ve encodeCBORImportOutput — baytları okuyup yazarak (Rust’ta Vec<u8>, TypeScript’te Host.inputBytes() ve Host.outputBytes(...)). Hiçbir CBOR kütüphanesi gerekmez ve hiçbir şey baytları elle ayrıştırmaz. settings, ikili belgenin içinde JSON belgesinin baytları olarak taşınır; bu nedenle bir konuk, diğer her sokette olduğu gibi içine bakmak için onu JSON olarak ayrıştırır. Tamamlayamayan bir içe aktarıcı nedenini çıktının error alanında belirtir ve içe aktarma, içe aktarıcıyı ve o iletiyi adlandırarak durur; bu kodlamada bir ImportOutput olmayan bir yanıt — JSON olarak yazılmış ya da biçimin bildirmediği bir üst düzey alan taşıyan bir yanıt — da içe aktarıcıyı ve onun import dışa aktarımını adlandırarak içe aktarmayı durdurur. aggrega plugin run-local --export import ile doğrudan çağrıldığında, içe aktarıcıya yazılmış JSON yükü bu kodlamaya dönüştürülerek verilir ve yanıtı dışa aktarımın çıktı biçimi olarak okunup JSON olarak yazdırılır — bu biçimde olmayan bir yanıt, bir derlemenin reddettiği gibi, dışa aktarımı adlandırarak reddedilir.

Biçiminizdeki bir kaynak nasıl tanınır. Bir içe aktarma hiçbir biçim belirtmeyebilir; bu durumda ana makine, kendisi hiçbir biçim bilmeden, içe aktarıcıların bildirdiklerinden bir biçim tanır. Bir içe aktarıcı, describe() öz raporunda, importer (bir ImporterContract) altında, biçimlerindeki bir kaynağın tanındığı imzaların bir detect listesini bildirir. Her DetectSignature şunları belirtir:

  • syntax — kaynağın ayrıştırıldığı sözdizimsel biçim; bir ayrıştırıcı eklentisinin parse:<syntax> olarak bildirdiği bir biçim, örneğin json ya da yaml;
  • files — kaynağın adının sonuyla eşleştirilen isteğe bağlı dosya adı kalıpları: tek bir bölüm dosyanın kendi adıyla, eğik çizgiyle ayrılmış birkaç bölüm ise yolunun o sayıdaki son bölümleriyle eşleştirilir; *, ? ve [...] bir bölüm içinde eşleşir. Hiç kalıp bildirmeyen bir imza, adı ne olursa olsun tek dosyadan oluşan bir kaynağa uygulanır ve bir dizinin hiçbir dosyasına uygulanmaz;
  • match — ayrıştırılmış ağacın tümünü karşılaması gereken yüklemler; her biri, ağacın tepesinden itibaren noktalarla birleştirilmiş anahtarlardan oluşan bir path (tam sayı olan bir bölüm bir dizi konumunu seçer), present, absent, object, array, string, number ya da boolean değerlerinden birini alan bir is ve isteğe bağlı olarak bir equals dizesi ya da bir prefix dizesi — ikisinden en fazla biri — taşıyan bir PathMatch.

Bir içe aktarma hiçbir biçim belirtmediğinde ana makine, içe aktarmanın arasından seçim yaptığı her içe aktarıcının — çalışma alanının kataloğundakiler ve derleyicinin çekirdek içe aktarıcıları — imzalarını kimliklerine ve sürümlerine göre sırayla eşleştirir: kaynağı, kataloğun bir sözdizimi için sunduğu ayrıştırıcıyla — ya da kataloğun ayrıştırıcı sunmadığı bir sözdizimi için derleyicinin kendisinin taşıdığı ayrıştırıcıyla — sözdizimi başına en fazla bir kez ayrıştırır, yüklemleri ağaç üzerinde değerlendirir ve kaynağı, imzası eşleşen tek içe aktarıcının biçimi olarak okur. Bir içe aktarıcının aggrega_parse_source çağrısı da bu ayrıştırıcı üzerinden yanıtlanır; böylece bir içe aktarıcı kaynağını, tanındığı ayrıştırıcı üzerinden okur. Bir sözdiziminde ayrıştırılamayan bir kaynak, o sözdizimini belirten hiçbir imzayla eşleşmez; ne kataloğun ne de derleyicinin ayrıştırıcı sunduğu bir sözdizimi, ayrıştırıcının yokluğunu belirterek tanımayı durdurur. Hiçbir imzanın eşleşmediği bir kaynak, biçim istenerek reddedilir; birden fazla biçim olarak tanınan bir kaynak ise bu biçimler belirtilerek reddedilir. Bir imza bir kaynağı, içe aktarıcısının bildirdiği her biçim olarak tanır; bu nedenle kaynaklarının tanınması istenen bir içe aktarıcı tek bir biçim sunar ve hiç imza bildirmeyen bir içe aktarıcıya yalnızca biçimi belirtilerek ulaşılır.

Importer’ın Plugin varlığı aynı listeyi spec.importer.detect olarak kaydeder; varlık guest’ten üretildiğinde bu liste describe() çıktısından türetilir. Tanıma bu kaydı okur, dolayısıyla guest, biçimi belirlenene kadar yüklenmez. Guest’in yüklenmesi ve yayımlanması, raporu varlığının kaydından farklı olan bir guest’i importer.detect adını vererek reddeder; hiçbir şey kaydetmeyen bir varlık ise herhangi bir iddiada bulunmaz. Tanımlayıcı şu durumlarda yükleme sırasında reddedilir: sözleşme importer olmayan bir plugin üzerinde bildirilmişse, bir imza hiçbir sözdizimi belirtmiyorsa ya da hatalı biçimlendirilmiş bir dosya deseni belirtiyorsa ve bir yüklem hiçbir yol belirtmiyorsa, yedi değerin dışında bir is belirtiyorsa ya da hem equals hem prefix belirtiyorsa.

Derleyicinin çekirdek importer’ları ve Go kitinin import örneği imzalarını bu şekilde bildirir. Langflow importer’ı kaynağı JSON olarak okur ve data.nodes konumunda bir dizi ister; Flowise importer’ı nodes ve edges konumlarında diziler ve data.nodes konumunda hiçbir şey olmamasını ister; n8n importer’ı nodes konumunda bir dizi, connections konumunda bir nesne ve edges ya da data.nodes konumlarında hiçbir şey olmamasını ister; MCP importer’ı her istemci yapılandırması için dosyasını adlandıran bir imza bildirir — .mcp.json, claude_desktop_config.json ve .cursor/mcp.json, mcpServers konumunda bir nesneyle JSON olarak okunur; .vscode/mcp.json ise Visual Studio Code’un okuduğu gibi yorumlu JSON olarak, servers konumunda bir nesneyle okunur — ve hiçbir dosya adlandırmayan, https://static.modelcontextprotocol.io/schemas/ ile başlayan bir $schema dizesi isteyen bir imza daha bildirir; Compose importer’ı kaynağı YAML olarak okur, Compose’un varsayılan olarak okuduğu dosyaları — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml ve bunların dört geçersiz kılma dosyasını — adlandırır ve services konumunda bir nesne ister; Dify importer’ı kaynağı YAML olarak okur, hiçbir dosya adlandırmaz ve kind konumunda app dizesini, app.mode ve version konumlarında da bir şey olmasını ister; CrewAI importer’ı config/agents.yaml ve config/tasks.yaml dosyalarını adlandırır (ağaçtan hiçbir şey istenmeden YAML olarak okunur), crew.jsonc ve crew.json dosyalarını (agents konumunda bir listeyle yorumlu JSON olarak okunur) ve agents/*.jsonc ile agents/*.json dosyalarını (role konumunda bir şeyle yorumlu JSON olarak okunur) adlandırır; böylece bunlardan hiçbir ikisi aynı kaynakla eşleşmez ve biçim belirtilmeden tek başına içe aktarılan bir dosya hem YAML hem JSON olarak okunur; LangGraph importer’ı graphs konumunda bir nesneyle JSON olarak okunan langgraph.json dosyasını adlandırır, hiçbir dosya adlandırmayan ve graphs konumunda bir nesne ile $schema konumunda https://langgra.ph/schema.json dizesini isteyen bir imza bildirir ve hiçbir ortam dosyası adlandırmaz; çünkü tanıma, herhangi bir importer’ın desenlerinin seçtiği her dosyayı okur, dolayısıyla ortam dosyası adlandıran bir desen, biçim belirtilmeden içe aktarılan her dizinin ortam dosyalarını açardı; Google ADK importer’ı root_agent.yaml dosyasını adlandırır (name ve instruction konumlarında bir şeyle ya da agent_class konumunda bir dize ve name konumunda bir şeyle YAML olarak okunur) ve başka hiçbir dosya adlandırmaz; çünkü bir alt ajanın yapılandırmasının adı herhangi bir şey olabilir ve her YAML dosyasını adlandıran bir desen, biçim belirtilmeden içe aktarılan her dizinin her birini açardı; Agent Framework importer’ı kaynağı YAML olarak okur, hiçbir dosya adlandırmaz ve kind konumunda Prompt dizesini ve model konumunda bir nesne ister; Go kitinin import örneği kaynağı YAML olarak okur ve kind konumunda DemoSource dizesini ister. Go’da:

Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{
Syntax: "json",
Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},
}}},

Bir dizinin içe aktarılması neleri okur. Kaynak bir dizin olabilir ve neyin okunacağına importer’ın bildirdiği dosya desenleri karar verir: host, dizindeki dosyalardan, herhangi bir derinlikte, importer’ın imzalarındaki files desenlerinden birinin seçtiği dosyaları tam olarak okur — her biri, dosyanın dizin içindeki eğik çizgiyle ayrılmış yolunun sonuyla eşleştirilir — ve bunları ad sırasıyla sources olarak, bytes boş bırakılarak ve dizinin kendi adı name olarak verilerek iletir. Dizindeki başka hiçbir dosya açılmaz. Çalışma alanının bir derlemesinin işlenmiş dosyalarını yazdığı klasör — çalışma alanı kökünün altındaki dist/ — onu içeren bir dizinin parçası olarak okunmaz: dosyalarının hiçbiri iletilmez ya da tanınmaz ve ona giden bir bağlantı atlanır; dolayısıyla derlenmiş bir dizin içerdiği proje olarak okunurken, o klasörün kendisi olan ya da onun içinde bulunan bir dizin belirtildiği gibi okunur. Hiçbir files deseni bildirmeyen bir imza dizinden hiçbir dosya seçmez; dolayısıyla hiç desen bildirmeyen bir importer tek bir dosya okur ve dizini reddeder; desenlerinin seçtiği hiçbir dosyayı içermeyen bir dizin de reddedilir. Dizin kendi sınırları içinde tutulur: okunacak dosyalar arasında ya da bir dizine giden ve dizinin dışına çıkan bir bağlantı, herhangi bir şey okunmadan önce reddedilir; bir dizine giden bağlantıya hiçbir zaman girilmez ve hiçbir desenin seçmediği bir dosyaya giden bağlantı okunmadan atlanır. Bir dizinin biçiminin tanınması da aynı kuralı izler — her imza, desenlerinin seçtiği dosyalara karşı ad sırasıyla denenir; her dosya sözdizimi başına en fazla bir kez okunup ayrıştırılır ve hiçbir desen bildirmeyen bir imza bunların hiçbirine uygulanmaz. Host hiçbir sınır koymaz: importer için fazla büyük bir dizin, importer’ın kendi çalışma zamanı sınırlarınca reddedilir. Derleyicinin Langflow, Flowise, n8n, Dify ve Agent Framework importer’larının hiçbiri files deseni bildirmez, dolayısıyla her biri tek bir dosya okur; MCP importer’ı dört istemci yapılandırmasının adlarını bildirir, dolayısıyla bir dizinin içerdiği bu dosyaların her birini okur; Compose importer’ı sekiz Compose dosya adını bildirir, dolayısıyla bir dizinin içerdiği her Compose dosyası kendisine iletilir ve Compose’un okuyacaklarını birleştirir; CrewAI importer’ı bir CrewAI projesinin bildirimlerinin yazıldığı altı adı bildirir, dolayısıyla kendisine projenin bildirimleri iletilir, programından hiçbir şey iletilmez; LangGraph importer’ı langgraph.json dosyasını bildirir, dolayısıyla kendisine bir uygulamanın yapılandırması iletilir, kodundan ya da ortam dosyalarından hiçbiri iletilmez; bir ortam dosyası ona yalnızca eklenmesinin with.sources alanı altında ulaşır; Google ADK importer’ı root_agent.yaml dosyasını bildirir, dolayısıyla kendisine bir uygulamanın kök ajan yapılandırması iletilir, kodundan ya da ortam dosyasından hiçbiri iletilmez; alt ajanlarının adlandırdığı yapılandırmalar ona yalnızca eklenmesinin with.sources alanı altında ulaşır.

Tür tanımları. Importer kablo türleri — ImportInput, ImportSource, CatalogProjection, CatalogComponent, CatalogSocket, ImportOutput ve bunun taşıdığı varlık, karar ve iskelet biçimleri — üç ABI paketinin hepsinde yayımlanır ve her dilin plugin geliştirme kitince yeniden dışa aktarılır; üçü birbirine uyumlu kalsın diye tek bir codec’ten üretilir; describe öz raporunun taşıdığı ImporterContract, DetectSignature ve PathMatch tanıma türleri de öyledir. Go kitinin importer paketi github.com/aggrega-ai/aggrega-pdk/go/pkg/importer, biçimi ne olursa olsun bir importer’ın yaptığı her şeyi taşır; derleyicinin her biri bunun üzerine kurulu çekirdek importer’ları da girdilerini bu şekilde okur ve çıktılarını bu şekilde yazar.

Go kiti üzerine kurulu bir importer neye karşı puanlar. Kitin puanlayıcısı her kaynak düğümünü yalnızca catalog görünümündeki Components’e karşı tartar: adaylar çalışma alanının kendi kataloğudur — bir kurumsal kataloğun Components’i de standart kütüphaneninkiler gibi — ve kit kendine ait hiçbir aday taşımaz. Her Component’in adını, component.aggrega.ai/category etiketinin taşıdığı kategoriyi, etiketlerini ve değerlerinin bildirdiği anahtar adlarını okur; provides anahtarları ve soketleri tartılmaz. Kataloğa eklenen bir Component, hiçbir importer yeniden derlenmeden bir sonraki içe aktarmada adaydır. Katalog hiçbir Component içermediği için görünüm yoksa hiçbir düğümün adayı olmaz: hiçbiri başvurulmaz ya da ipucu olarak verilmez ve taslağın kendine ait bir Component verdiği her düğüm taslak olarak oluşturulur. Kit aracılığıyla puanlayan her importer bu şekilde puanlar — derleyicinin Langflow, Flowise, n8n ve Compose importer’ları da bunlar arasındadır; MCP importer’ı ise hiçbir aday tartmaz. Kiti kullanmayan bir importer görünümü dilediği gibi okur.

Go kit üzerine kurulu bir importer’ın bir platformun socket’lerini ne için okuduğu. Socket’lerin bir puanda hiçbir ağırlığı yoktur, ancak kit bir taslağı düzenlemek için onları okur. Akışlarını bir platformun yazıldıkları gibi çalıştırdığı bir format — Langflow, Flowise ve n8n akışlarında olduğu gibi — varsayılan olarak o platformun akışı taşıyan Component’inin tek bir örneği olarak taslağa dökülür ve akışın her parçası, platformun catalog girdisinin sockets öğelerini listelediği sırayla, selector değerini parçanın Component’inin etiketlerinin (görünümün bu etiketleri taşıdığı biçimiyle) karşıladığı ilk socket’e bağlanır. Yalnızca seçici ve etiketler okunur; kit kendine ait bir seçici dilbilgisi taşımadığından seçici, importer’ın sağladığı bir fonksiyonla eşleştirilir. Görünümde platformun adını taşıyan bir Component bulunmadığında hiçbir parça bağlanmaz. Çekirdek importer’lar, derleyicinin Langflow, Flowise ve n8n importer’larının bu şekilde oluşturduğu taslağı ve bunun yerine her düğümü kendine ait bir Component olarak taslağa döken layout ayarını açıklar.

Bugünkü durum: kullanılabilir — aggrega import tarafından ve düzenleyici oturumundaki ile asistana yönelik araçtaki aynı işlem tarafından çalıştırılır.

Yerleştirme ölçütü: linter soketi ile yönetişim karar rolleri

Belgelenen soketlerden ikisi benzer bir yüzeyi paylaşır (her ikisi de kural başına sonuç üretir), ancak işlem hattındaki yerleri ve geçit semantikleri farklıdır. Belirli bir denetimi hangi soketin taşıyacağına karar verme ölçütü:

  • Yönetişim karar rolleri (bant içi, derlemeyi durduran). Derlemeyi durduran politikalar için ayrılmıştır: bir halt kararı derleme işlem hattını durdurur ve derleme hiçbir yapıt üretmez. Kullanım alanları, ihlali çıktıyı uygulamak için güvensiz kılan politikalardır: uyumluluk geçitleri (PCI / SOC2 sınır yerleşimi), topoloji değişmezleri (sıfır güven girişi, sınırlar arası kimlik doğrulama), kimlik bilgisi akışının biçimi (IR’de düz metin gizli bilgi bulunmaması) vb. Bir politika IR grafiği (ir-verdict, render öncesinde) ya da render edilmiş yapıtlar (render-verdict, render sonrasında) üzerinde akıl yürütür.
  • Linter soketi (bant dışı, CI / IDE, tavsiye niteliğinde). En iyi uygulama ve keşfedilebilirlik denetimleri için ayrılmıştır: ihlali şüpheli olan ancak güvensiz olmayan kurallar; sahipsiz gizli bilgiler, kullanılmayan parametreler, kullanımdan kaldırılmış etiket sözcükleri, maliyet ataması için etiket eksiksizliği, adlandırma uzlaşımından sapma. Başarısızlık tavsiye niteliğinde çıktı üretir; derleme yine de yapıt üretir.

Tek bir kural olarak ifade edilen yerleştirme ölçütü: denetim derlemeyi durdurmalıysa bir yönetişim karar rolüne aittir; denetim işlem hattını engellemeden bir yazarı ya da gözden geçireni uyarmalıysa linter soketine aittir.

Her ikisi de bugün kullanılabilir. Linter soketi, yayımlama linter’ını aggrega lint aracılığıyla çalıştırır; yönetişim karar rolleri ise bir çalışma alanı bir karar rolü eklentisi eklediğinde aggrega build sırasında bant içinde çağrılır. Bir karar rolünün kendi önem düzeylerini taşıdığını unutmayın: bir politika durdurmadan tavsiyede bulunan warn ve info kararları da üretebilir. Dolayısıyla yukarıdaki durdurma ile tavsiye arasındaki çizgi, bütün denetimler için yerleştirme yönergesidir; bir politikanın yalnızca durdurabileceği iddiası değildir. Önem düzeyi modeli için yönetişim soketi sayfasına bakın.

Çapraz başvurular

  • policy-socket.md — governance soketinin kapsamlı ele alınışı: dört rol, karar önem dereceleri, operatör girdi kanalı, derleyiciyle birlikte gelen iki motordan herhangi biri için politika yazma, harici bir politika motorunu sarmalama ve referans konuklar.
  • core-importers.md — derleyicinin okuduğu her biçim için bir tane olmak üzere kendi içe aktarıcıları: her birinin ne okuduğu, ayarları ve her derleyici sürümüyle birlikte yayımlanmaları.
  • 10-status.md#compilation-pipeline-phases — Durum sayfasındaki plugin işlem hattı sınıflandırması (Wasm plugin işlem hattı çalışma zamanı hazırlık durumu).
  • architecture/04-entity-taxonomy.md §“Domain 3: Infrastructure Base” — kimlik bilgisi FeatureRecipes için İki Parçalı Plugin İlkesi (Fetcher + Injector deseni).
  • architecture/13-catalog-and-registry.md — provider segmentiyle başlayan OCI taksonomisi.
  • entities/featurerecipe.md — FeatureRecipe pipeline: yazım yüzeyi.
  • when-to-use-a-pipeline-step.md — karar kılavuzu: işlem hattı adımı mı, şablonlu bir FeatureRecipe mi.
  • templates/expansion-matrix.md — plugin işlem hattının pipeline: with: bloğu şablon değerlendirme kuralları ve .steps erişim semantiği.
  • examples/04-secrets.md — kimlik bilgileri için bir FeatureRecipe’nin alabileceği Fetcher + Injector işlem hattı biçimi.
  • errors/error-translation.md — plugin konuklarının katıldığı hata çevirisi disiplini.