Kontrakt wtyczek Wasm
Potok kompilacji Aggrega zawiera wyznaczone punkty gniazd, w których wtyczki WebAssembly (Wasm) rozszerzają działanie kompilatora: cztery role gniazda zarządzania, w tym bramkę mutacji (Mutation Gate) przy budowie topologii i bramkę walidacji (Validation Gate) przy analizie statycznej; potok wtyczek po renderowaniu dla kroków encji FeatureRecipe i Recipe; gniazdo renderowania przez dostawcę; gniazdo parsera; gniazdo importera; oraz gniazdo lintowania działające poza głównym przebiegiem. Ta strona dokumentuje publiczny kontrakt wtyczek Wasm: jakie gniazda istnieją, co każde gniazdo przyjmuje i zwraca, gdzie każde gniazdo znajduje się w potoku kompilacji oraz w jakiej piaskownicy wykonuje się każda wtyczka.
Ta strona opisuje gniazda — punkty potoku i kształty ich wejść i wyjść. Informacje o wtyczce — encji Plugin, deklaracjach uprawnień dla poszczególnych eksportów, limitach środowiska uruchomieniowego oraz cyklu życia publikacja→pobranie→budowanie — zawiera przewodnik dla twórców wtyczek Wasm.
Aggrega osadza środowisko uruchomieniowe hosta Wasm — Extism działające na silniku Wazero — które ładuje i wykonuje wtyczki za zaporą czystości AOT: host nie przyznaje gościowi żadnych uprawnień otoczenia — brak sieci, brak systemu plików, brak zmiennych środowiskowych, odrzucane stdio, obserwowalny zegar ścienny zamrożony w chwili niezmiennej względem kompilacji — dzięki czemu wtyczka nie może naruszyć gwarancji kompilacji z wyprzedzeniem (ahead-of-time) zapewnianych przez kompilator. Pełny zakres uprawnień — regułę modułów importu przy ładowaniu, odmowy w momencie instancjonowania oraz wyselekcjonowane funkcje hosta — opisuje kontrakt piaskownicy poniżej. Autorzy encji Plugin piszą kod pod hosta za pomocą PDK w trzech językach (Go, Rust, TypeScript). aggrega lint wywołuje przez hosta gniazdo lintera — standardowy linter publikacji. aggrega build wywołuje role gniazda zarządzania działające w czasie kompilacji, gdy obszar roboczy je konfiguruje: rolę transformacji adnotacji podczas rozwiązywania i rolę transformacji etykiet przy budowie topologii (obie kształtują wynik), a także werdykt IR podczas analizy statycznej i werdykt renderowania dotyczący wyrenderowanych artefaktów. Każda z nich nic nie robi, gdy do danej roli nie jest podłączona żadna wtyczka, więc kompilacja bez konfiguracji zarządzania pozostaje niezmieniona. aggrega build wywołuje też pipeline: encji FeatureRecipe i Recipe w potoku wtyczek zamykającym renderowanie — każdy zadeklarowany krok jest wykonywany przez hosta na zbiorze wyrenderowanych dokumentów, stosując łatki RFC 6902 danego kroku i emitując jego efekty uboczne. Zob. Stan języka → Fazy potoku kompilacji.
Kontrakt piaskownicy
Każde gniazdo uruchamia swój plugin w tej samej piaskownicy hosta. Piaskownica ma dwie niezależne warstwy — kontrolę strukturalną przy ładowaniu i odmowę uprawnień przy instancjonowaniu — i razem określają one, do czego plugin ma dostęp, do czego nie ma, oraz za co odpowiada.
Reguła modułów importu (czas ładowania). Loader przegląda sekcję importów binarium pluginu i dopuszcza importy funkcji tylko w trzech przestrzeniach nazw modułów: wasi_snapshot_preview1 (środowisko uruchomieniowe WASI preview-1, z którym linkuje się środowisko uruchomieniowe języka gościa), extism:host/env (ABI środowiska uruchomieniowego Extism — własne intrinsics pamięci i IO PDK) oraz extism:host/user (wyselekcjonowane funkcje hosta Aggrega). Gość może importować dowolną nazwę funkcji w dozwolonym module; import w jakimkolwiek innym module wskazuje powierzchnię, której host nie udostępnia, i plugin zostaje odrzucony przy ładowaniu z diagnostyką wskazującą moduł i import. Reguła celowo nie cenzuruje poszczególnych nazw funkcji WASI: statycznie linkowane środowisko uruchomieniowe języka importuje funkcje systemu plików i gniazd, których jego aktywne ścieżki kodu nigdy nie wywołują — wciągnięte przechodnio przez zależności — a samo nazwanie importu niczego nie przyznaje. To odmowa uprawnień przy instancjonowaniu, a nie cenzura importów, gwarantuje brak operacji I/O.
Zero uprawnień otoczenia (instancjonowanie). Host instancjonuje gościa z rzeczywistym zachowaniem WASI i zerowymi uprawnieniami otoczenia:
- brak systemu plików — brak wstępnie otwartych katalogów, więc wywołanie systemu plików kończy się błędem na granicy wywołania;
- brak gniazd sieciowych;
- puste środowisko;
- odrzucane stdio — nic, co gość zapisze na stdout lub stderr, nie trafia do strumieni hosta;
- zamrożony obserwowalny zegar czasu rzeczywistego, przypięty do chwili niezmiennej dla budowania, więc gość odczytujący czas nie może przemycić czasu budowania do swojego wyjścia;
- rzeczywisty, postępujący zegar monotoniczny — środowisko uruchomieniowe języka gościa potrzebuje go do uruchomienia, a czas monotoniczny mierzy upływ czasu, a nie chwilę zegara rzeczywistego;
- rzeczywista entropia hosta — przypięta entropia ustabilizowałaby wewnętrzne ziarno haszowania środowiska uruchomieniowego języka i maskowała niedeterminizm gościa, zamiast pozwolić mu ujawnić się jako różniące się wyjście;
- jedna syntetyczna nazwa programu jako argv.
Wywołanie I/O, które gość faktycznie wykona — otwarcie pliku, nawiązanie połączenia przez gniazdo — kończy się błędem na granicy wywołania. To własny model bezpieczeństwa WASI oparty na uprawnieniach: piaskownica odmawia uprawnienia, zamiast pilnować kodu.
Dane wejściowe docierają wyłącznie przez ładunek i wyselekcjonowane funkcje hosta. Plugin otrzymuje wszystko, co renderuje lub ocenia, w ładunku przenoszonym przez jego gniazdo — projekcje grafu i węzłów, wartości oraz kontekst renderowania. Kodowanie, w jakim dociera ładunek, jest ustalone dla każdego gniazda i podane w sekcji danego gniazda poniżej; każdy opublikowany typ ładunku zawiera punkt wejścia kodowania i dekodowania dla kodowania swojego gniazda, więc gość wywołuje jedną funkcję, zamiast wybierać parser. W przypadku renderowania encji Provider ze źródłem ładunek zawiera listing źródła zamiast bajtów źródła: posortowany zbiór wpisów {path, is_dir} pod katalogiem głównym źródła węzła, bez jakiejkolwiek interpretacji układu dostawcy przez hosta. Gość stosuje własną logikę układu — wybiera pojedynczy plik compose, schodzi do katalogu głównego chartu, wymaga Chart.yaml, rekurencyjnie dołącza moduł — i odczytuje dokładnie wybrany fragment przez wywołanie zwrotne hosta. Poza ładunkiem host wiąże wyselekcjonowany zbiór funkcji hosta zgodny z zasadą najmniejszych uprawnień i przyznaje pluginowi dokładnie te, które importuje jego binarium:
aggrega_log— wiersz logu w miejscu docelowym logów hosta.aggrega_emit_warning— ustrukturyzowane ostrzeżenie, które host zgłasza po wywołaniu.aggrega_fetch_external_input— kanał pobierania zewnętrznych danych wejściowych (poniżej).aggrega_pack_source— wywołanie zwrotne wyboru źródła: gość wskazuje wybór{file | dir | tree, path}pod katalogiem głównym źródła, a host odczytuje i pakuje dokładnie to w piaskownicy, która rozwiązuje ścieżki pod katalogiem głównym i odrzuca...aggrega_read_source_file— odczyt zawartości pojedynczego pliku w tej samej piaskownicy, do wyboru źródła zależnego od zawartości.aggrega_parse_source— wywołanie zwrotne konsumpcji producenta: gość wskazuje format składniowy i przekazuje bajty źródła, a host znajduje parser dla tego formatu, uruchamia go i zwraca wytworzone przez niego drzewo kanoniczne. W ten sposób konsument uzyskuje wynik producenta przez hosta, zamiast samodzielnie wywoływać gościa-producenta, a host ogranicza to do jednego poziomu — producent osiągnięty w ten sposób, który wywoła je ponownie, otrzymuje odmowę — więc konsument wywołuje je raz na źródło i może kolejno konsumować wiele źródeł.
Host wyznacza zbiór importowany przez plugin z jego binarium .wasm, weryfikuje go względem wyselekcjonowanej listy dozwolonych i porównuje z funkcjami hosta deklarowanymi przez describe() gościa. aggrega plugin sync zapisuje ten zbiór w spec.runtime.hostFunctions encji, a publikacja odrzuca encję, której zapis różni się od binarium, dzięki czemu powierzchnia hosta każdego pluginu jest widoczna w katalogu i nie może rozejść się z binarium.
Błędy wywołań zwrotnych niosą kod możliwy do dopasowania maszynowo, pod hostfunc_error_code. Wywołania zwrotne hosta zwracające odpowiedź — aggrega_fetch_external_input, aggrega_pack_source, aggrega_read_source_file oraz wywołanie zwrotne konsumpcji producenta aggrega_parse_source — przekazują błąd w paśmie: koperta odpowiedzi zawiera komunikat czytelny dla człowieka, a obok niego opcjonalny kod możliwy do dopasowania maszynowo pod hostfunc_error_code, pochodzący z zamkniętego słownika. Komunikat to swobodny tekst dla człowieka; kod to stabilny identyfikator, według którego gość rozgałęzia logikę bez parsowania komunikatu. Przy powodzeniu kodu brak; przy błędzie host ustawia oba. PDK udostępnia tę parę jako typowany błąd, którego tekstem jest komunikat, a którego pole kodu gość porównuje z reeksportowanymi stałymi kodów danego języka. Gość toleruje brak kodu i kod, którego nie rozpoznaje, wracając do komunikatu — dopasowanie kodu jest więc doprecyzowaniem w miarę możliwości, nałożonym na zawsze obecny komunikat, a nigdy jego zastępstwem. Zamknięty zbiór wartości to schemat kodów błędów funkcji hosta.
🔴 Błąd na tej granicy nazywają dwa różne słowniki, a odczytywany klucz mówi, z którym z nich ma się do czynienia. Pomylenie ich to jedyny błąd, który warto tu wyróżnić, ponieważ wartość z każdego z nich jest zwykłym ciągiem znaków, a ani host, ani gość nie sprawdza, z którego zbioru pochodzi.
hostfunc_error_codew odpowiedzi wysyłanej przez hosta do gościa. Jego wartość należy do zamkniętego katalogu podlinkowanego powyżej — stałej, wolno zmieniającej się listy nazywającej sposoby, w jakie wywołanie zwrotne hosta może zakończyć się błędem. Ponieważ zbiór jest zamknięty, gość może porównać wartość z nazwaną stałą reeksportowaną przez jego zestaw i rozgałęzić logikę według wyniku.condition_codeobokcondition_short_codew wyjściu gniazda zwracanym przez gościa do hosta. Są to dwa identyfikatory warunku zatrzymującego zgłoszonego przez samego gościa i pochodzą one z otwartego, rosnącego zbioru warunków rejestrowanych przez kompilator, a nie z katalogu.condition_codeto opisowy kod, pod którym warunek jest zarejestrowany;condition_short_codeto forma zwarta — literaEi cztery cyfry — którą czytelnik cytuje, wyszukuje i wkleja do zgłoszenia. Host wypisuje krótki kod w nagłówku w nawiasach kwadratowych renderowanej diagnostyki, dzięki czemu warunek zgłoszony przez gościa można cytować dokładnie tak jak warunek zgłoszony przez kompilator. Host nie wyznacza żadnej z tych wartości, ale je sprawdza: krótki kod, który nie odpowiada żadnemu warunkowi zadeklarowanemu przez ten kompilator albo odpowiada warunkowi o wycofanym numerze, zatrzymuje budowanie, zamiast dotrzeć do czytelnika jako identyfikator, który do niczego nie prowadzi.
Dwa identyfikatory po stronie gościa są zgłaszane razem: gość, który ustawia jeden, a nie ustawia drugiego, wskazał warunek, którego host nie może rozwiązać, i host zgłasza wtedy zamiast niego własny ogólny warunek awarii pluginu, a komunikat nadal niesie całą awarię. Ponadto condition_code nigdy nie należy do katalogu funkcji hosta, więc porównanie go z ponownie eksportowaną stałą nigdy nie daje dopasowania — dlatego każdy klucz wskazuje własny słownik, a nie awarię w ogóle.
Sloty każdego wywołania zwrotnego mają określone kodowanie, a każdy slot przechowujący dokument ładunku przechowuje go binarnie. Każdy argument przyjmowany przez wywołanie zwrotne hosta jest wskaźnikiem do pamięci gościa, z wyjątkiem numerycznego poziomu aggrega_log; wywołanie zwrotne zwracające odpowiedź odpowiada również wskaźnikiem. Zawartość każdego z tych slotów jest ustalona dla danego wywołania zwrotnego:
| Wywołanie zwrotne | Sloty argumentów | Slot odpowiedzi |
|---|---|---|
aggrega_log, aggrega_emit_warning | tekst UTF-8 — brak dokumentu ładunku | brak odpowiedzi |
aggrega_fetch_external_input | sam URL w UTF-8 — brak dokumentu ładunku | kanoniczny CBOR |
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_source | kanoniczny CBOR (RFC 8949 §4.2.1) | kanoniczny CBOR |
Tabela dzieli się według tego, co przechowuje każdy slot, a nie według tożsamości wywołania zwrotnego: slot przechowujący dokument ładunku niesie kanoniczny CBOR, a slot przechowujący sam ciąg znaków — wiersz logu, pole diagnostyki, URL — niesie tekst UTF-8. aggrega_fetch_external_input jest jedynym, którego dwa sloty się różnią: jego argument to sam URL, odczytywany jako tekst UTF-8, a odpowiedź to dokument ładunku w kanonicznym CBOR.
Co gość robi w slocie niosącym ładunek, a czego robić nie może. 🔴 Slot przechowujący dokument ładunku przechowuje nieprzezroczysty ciąg bajtów, a nie tekst UTF-8 — jest to więc kształt, który gość deklaruje, a nie tylko bajty, które tam umieszcza. Gość, który alokuje takie żądanie jako ciąg znaków lub odczytuje taką odpowiedź jako ciąg znaków, nie współpracuje z hostem: konwersja tekstowa w dowolnym kierunku psuje bajty binarne. Awaria jest głośna, a nie częściowa — żądanie, którego host nie potrafi zdekodować, wraca jako koperta odpowiedzi z kodem request_undecodable, w tym samym kształcie wewnątrzpasmowym co każda inna awaria wywołania zwrotnego, więc gość ją zgłasza, zamiast kontynuować na w połowie odczytanym ładunku. Typy ładunku to SourcePackRequest i SourcePackResponse dla aggrega_pack_source, SourceFileRequest i SourceFileResponse dla aggrega_read_source_file, ParseInput i ParseSourceResponse dla aggrega_parse_source oraz sam typ odpowiedzi FetchExternalInputResponse dla aggrega_fetch_external_input, którego URL jest alokowany jako tekst. Konkretnie, dla każdego zestawu:
- Go — żądanie należy zbudować za pomocą
EncodeCBOR()typu żądania, zaalokować za pomocąpdk.AllocateBytes(niepdk.AllocateString), a odpowiedź odczytać za pomocąReadBytes()z pamięci, na którą wskazuje wskaźnik odpowiedzi, doDecodeCBORtypu odpowiedzi. Wyjątkiem po stronie żądania jest URL pobierania, alokowany za pomocąpdk.AllocateString; jego odpowiedź odczytuje się jak każdą inną. Deklaracja//go:wasmimportjest w obu przypadkach wskaźnikiem, więc nic w sygnaturze nie pokazuje kształtu — kształt określają alokacja i odczyt. - Rust — deklaracja
#[host_fn]wprost określa kształt: każde z trzech wywołań zwrotnych z ładunkiem ma postaćfn <callback>(request: Vec<u8>) -> Vec<u8>;, a wywołanie zwrotne pobierania ma postaćfn aggrega_fetch_external_input(url: String) -> Vec<u8>;. Żądanie należy zbudować za pomocąencode_cbor()typu żądania, a odpowiedź odczytać za pomocądecode_cbor(&raw)typu odpowiedzi. - TypeScript — żądanie należy zbudować za pomocą funkcji
encodeCBOR…typu żądania, zaalokować za pomocąMemory.fromBuffer(nieMemory.fromString), a odpowiedź odczytać za pomocąreadBytes()do funkcjidecodeCBOR…typu odpowiedzi. URL pobierania alokuje się za pomocąMemory.fromString; jego odpowiedź odczytuje się za pomocąreadBytes()jak pozostałe. Podobnie jak w Go, wpisdeclare modulejest w obu przypadkach wskaźnikiem.
Gość, który wywołuje opakowanie PDK, nie potrzebuje niczego z powyższych. Opakowania — FetchExternalInput, PackSource, ReadSourceFile i ParseSource, w zapisie właściwym dla każdego języka — wykonują alokację i kodowanie, a żadna z ich sygnatur nie wymienia typu przesyłanego, więc gość, który korzysta z tych wywołań zwrotnych przez swój zestaw, sam niczego nie alokuje ani nie dekoduje; gość, który sam deklaruje i wywołuje funkcje hosta, alokuje i odczytuje swoją pamięć w sposób opisany powyżej. Żądanie zaalokowane jako tekst jest odrzucane, a nie obsługiwane połowicznie, a odpowiedzi odczytanej jako tekst nie da się zdekodować, więc niezgodność obu stron ujawnia się wyraźnie, a nie po cichu.
Dwie właściwości, na których można polegać. Odpowiedź ma to samo kodowanie niezależnie od tego, czy wywołanie się powiedzie, czy nie: gość odczytuje jeden slot i przed zdekodowaniem nie może wiedzieć, który z dwóch wariantów zawiera, więc jeden punkt wejścia dekodowania odczytuje oba, a opisane powyżej kod błędu i komunikat docierają przez niego. Ponadto gość wypełnia pole bajtowe w typie pola właściwym dla swojego zestawu — wycinku bajtów w Go, ciągu base64 w Rust i TypeScript — ponieważ konwersja na surowy ciąg bajtów niesiony przez kodowanie binarne jest zadaniem wygenerowanego kodera, wykonywanym na wyjściu i odwracanym na wejściu. Dotyczy to bajtów źródłowych ParseInput, zawartości pliku zwracanej przez aggrega_read_source_file, zawartości pobranej przez aggrega_fetch_external_input oraz zawartości każdego spakowanego pliku w odpowiedzi pakowania źródła: te bajty przekraczają granicę raz, a nie podwójnie zakodowane, i żaden gość nie koduje w base64 niczego, co koder zaraz zdekoduje z base64. Pole content odpowiedzi odczytu pliku źródłowego i pobierania jest pomijane, gdy jest puste, więc odpowiedź dla pustego pliku lub pobranego ładunku o zerowej długości nie niesie żadnej zawartości; taka odpowiedź jest nadal sukcesem, ponieważ awaria zawsze niesie swój komunikat i kod, a opakowanie każdego zestawu zwraca dla niej puste bajty. Drzewo zwracane przez aggrega_parse_source jest przesyłane jako ciąg bajtów zawierający dosłownie jego własny dokument JSON; host go ani nie odczytuje, ani nie przekształca. Parser odczytuje ten sam ParseInput, w tym samym kodowaniu, w swoim eksporcie parse — zob. gniazdo parsera.
Kanoniczność oznacza, że identyczne wejście daje identyczne bajty po każdej stronie, co pozwala porównywać ładunek między trzema zestawami pluginów, a nie tylko przesyłać go w obie strony, i dlatego wynik kompilacji pozostaje identyczny co do bajtu. Gość nie potrzebuje biblioteki CBOR i nic nie parsuje bajtów ręcznie: każdy opublikowany typ ładunku dostarcza punkty wejścia kodowania i dekodowania, których wymaga kodowanie jego slotu.
Za determinizm odpowiada autor pluginu. Host przyjmuje bajty wyjściowe gościa dosłownie i nie przepuszcza ich przez żaden serializator, więc kontrakt, którego musi przestrzegać każdy plugin, brzmi: identyczne wejście daje identyczne bajty wyjściowe. Piaskownica usuwa otoczeniowe źródła niedeterminizmu — czas zegarowy, środowisko, stan systemu plików — ale celowo nie maskuje pozostałych: gość, który koduje entropię lub upływ czasu monotonicznego w swoim wyniku, daje widocznie różne bajty między uruchomieniami, a nie stabilnie ukrytą wadę.
Kanał pobierania danych zewnętrznych. aggrega_fetch_external_input jest jedynym dozwolonym kanałem dla zdalnej treści i jest pośredniczony przez hosta, a nie jest dostępem gościa do sieci: gość wskazuje URL, a host serwuje bajty zgodnie z dyscypliną przypinania danych zewnętrznych. URL przypięty w pliku blokady encji Release jest serwowany z lokalnego magazynu adresowanego treścią i weryfikowany względem zapisanego skrótu; nieprzypięty URL jest odrzucany z diagnostyką wskazującą URL i krok, który go przypina, ponieważ renderowanie korzysta z domknięcia zapisanego w pliku blokady i nigdy go nie poszerza. Przypięcia są zapisywane podczas rozwiązywania zależności encji Release, co jest jedynym momentem, w którym cokolwiek jest przypinane. Przewodnik dla programistów zawiera pełny opis tworzenia oraz dyscypliny przypinania.
Mapy zachowujące kolejność
Niektóre mapy przenoszone przez ładunek są w schemacie swojego gniazda oznaczone jako zachowujące kolejność, ponieważ kolejność ich wpisów należy do tego, co przenoszą: węzły kompilacji, etykiety węzła, załączniki węzła, wejścia i wyjścia kroku potoku, przestrzenie kluczy deklarowane przez dostawcę. Opublikowane typy ładunków przechowują każdą taką mapę w kontenerze, który utrzymuje wpisy w kolejności, w jakiej zostały ustawione:
| Zestaw | Kontener |
|---|---|
| Go | aggrega.OrderedMap[V] — nazwa, pod którą zestaw udostępnia abi.OrderedMap[V] z pakietu ABI |
| Rust | OrderedMap<V> z crate’a aggrega-abi, reeksportowany przez zestaw |
| TypeScript | własny typ języka Map<string, V> |
Kontenery Go i Rust udostępniają operacje mapy — wyszukanie klucza, ustawienie go, usunięcie, odczyt kluczy, przejście po wpisach w kolejności, ich zliczenie. Ustawienie klucza, który kontener już zawiera, zastępuje jego wartość i zachowuje jego miejsce; nowy klucz trafia za wszystkie istniejące.
Kolejność przetrwa oba kodowania. W kodowaniu binarnym oznaczona mapa jest zapisywana jako uporządkowana lista wpisów — każdy wpis to lista dwuelementowa: klucz, a potem wartość — w kolejności kontenera, podczas gdy kodowanie kanoniczne zapisałoby w przeciwnym razie mapę z posortowanymi kluczami. W kodowaniu tekstowym jest to obiekt JSON, którego składowe są zapisane w kolejności kontenera. Dekoder w każdym z kodowań odrzuca mapę, w której klucz się powtarza, podając ten klucz. Mapa nieoznaczona w schemacie zachowuje w kodowaniu binarnym postać posortowanej mapy, a w opublikowanych typach — zwykły typ mapy danego języka.
Trzy konsekwencje dla gościa:
- Kolejność jest częścią wyjścia. Ponieważ oznaczona mapa jest zapisywana w kolejności wypełniania, gość, który wypełnia ją ze źródła bez ustalonej kolejności — na przykład iterując po wbudowanej mapie Go — zapisuje bajty różniące się między uruchomieniami dla identycznego wejścia. Należy wypełniać ją w ustalonej kolejności.
- Kolejność utrzymuje się tylko, dopóki mapa pozostaje w swoim kontenerze. Gość, który przekształca ładunek w ogólny typ wartości własnego języka, otrzymuje zamiast tego kolejność tego typu:
map[string]anyw Go nie ma żadnej, aserde_json::Valuew Rust utrzymuje klucze obiektów posortowane, chyba że crate zostanie zbudowany z funkcjąpreserve_order. - W TypeScript należy czytać i zapisywać za pomocą wygenerowanych funkcji. Typ zawierający oznaczoną mapę dekoduje swój JSON składowa po składowej, więc klucz odczytywany jako indeks tablicy, taki jak
"8080", zachowuje swoje miejsce tam, gdzieJSON.parseprzeniósłby go na początek obiektu; a jego koder zapisuje każdyMapjako obiekt, podczas gdyJSON.stringifyzapisujeMapjako{}.Object.keysdlaMaptakże jest puste: kluczeMapnależy odczytywać jego własną metodąkeys().
Wartości oznaczone przez dane wejściowe jako wrażliwe
Plugin nigdy nie cytuje w zwracanej odmowie ani ostrzeżeniu wartości, którą jego dane wejściowe oznaczają jako wrażliwą — przez jej klucz lub jako część ładunku oznaczonego w całości. Odmowa to error przenoszony przez wynik; ostrzeżenie to Diagnostic przenoszony przez wynik, niezależnie od jego poziomu, lub zgłoszone przez aggrega_emit_warning. Host przekazuje ten tekst bez zmian wszędzie, gdzie go raportuje — w wierszu poleceń, w serwerze języka i na liście problemów edytora, w narzędziach asystenta — i nie odczytuje z niego żadnej wartości, więc plugin jest jedyną stroną, która może tę wartość pominąć. Zamiast niej należy podać klucz, ustawienie lub pozycję: czytelnik znajdzie wartość na tej podstawie.
Zasada obejmuje tekst, który biblioteka pisze w imieniu pluginu, w tym samym stopniu co tekst pisany przez sam plugin. Silnik szablonów raportuje dane, które przetwarzał, walidator schematu cytuje wartość niespełniającą pattern, parser cytuje token, którego nie mógł odczytać. Gdy taki błąd dotyczył wartości oznaczonej przez dane wejściowe, należy go zgłosić bez tej wartości — na przykład uruchomić ten sam krok ponownie, zastępując każdą oznaczoną wartość symbolem zastępczym, zgłosić błąd tego przebiegu, jeśli wystąpi w tym samym miejscu, a w przeciwnym razie poinformować, że treść błędu została wstrzymana. W ładunku oznaczonym w całości każda wartość jest wartością oznaczoną, natomiast jego klucze — struktura dokumentu — pozostają czytelne.
Miejsca, w których dane wejściowe oznaczają klucz lub ładunek jako wrażliwy, w zapisie używanym w protokole:
| Gniazdo i eksport | Gdzie odczytywane jest oznaczenie |
|---|---|
provider render_node i validate_node_input (RenderNodeInput) | node.sensitive_rendered_keys: każdy klucz wskazuje wpis node.values, gdy są to własne wartości encji Component, kluczowane deklarowanymi przez nią liśćmi — valuesMapping encji Recipe zapisuje klucze, których nie nazywa żadna deklaracja, więc żaden z nich nie jest tu oznaczony — albo wpis mapy attachments kontenera workloadu, który odczytuje slot zadeklarowany jako wrażliwy. node.sensitive_values oznacza node.values w całości: ma wartość true, gdy te wartości wytworzył valuesMapping — encji Recipe lub encji FeatureRecipe danego załącznika — i odczytuje on wartość zadeklarowaną przez autora jako wrażliwą. workload_projection.sensitive_workload oznacza w ten sam sposób każdą wartość workloadu, gdy jego szablon odczytuje taką wartość, a każdy wpis artifacts_projection.entries niesie sensitive_content dla własnej treści, łącznie z komunikatem parsera dotyczącym tej treści. Każdy wpis omits niesie sensitive, gdy szablon wytwarzający jego rodzaj, nazwę lub przestrzeń nazw odczytuje taką wartość, i wtedy każde pole tego wpisu jest wartością oznaczoną. Każdy wpis node.features niesie oznaczenie własnego załącznika: sensitive_payload_leaves (liście values.<path> i infra.<path>, które jego encja Feature deklaruje jako wrażliwe), sensitive_inject (klucze dostarczania inject odczytujące klucz provides, który jego encja Feature deklaruje jako wrażliwy) oraz sensitive (czy załącznik w ogóle obsługuje materiał zadeklarowany jako wrażliwy). |
governance ir-verdict (PolicyInput) | graph: sensitive_payload_leaves każdego węzła oraz sensitive_payload_leaves, sensitive_inject i sensitive każdego załącznika. Każda wartość wskazana przez te oznaczenia dociera już jako znacznik wstrzymania {"aggrega_withheld": "declared"}, więc sama wartość nigdy nie trafia do pluginu. |
Żadne inne dane wejściowe gniazda ani dane wejściowe żadnego innego eksportu providera nie niosą oznaczenia. Oznaczenie klucza wskazuje tylko to, co dokładnie łączy z deklaracją, więc brak klucza nigdy nie oznacza, że wartość można bezpiecznie cytować: oznacza, że z tym kluczem nie dało się połączyć żadnej deklaracji. Oznaczenie ładunku jest odczytywane z odwołań szablonu, który wytworzył ładunek — odwołania sięgającego zadeklarowanej wartości, szablonu przekazującego całość swoich danych lub szablonu, którego nie da się sparsować — a nigdy z wartości, więc jego brak oznacza, że szablon nie odczytał żadnej zadeklarowanej wartości, na ile wskazują jego odwołania, albo że żaden szablon nie wytworzył ładunku; nie jest to stwierdzenie, że ładunek nie zawiera niczego wrażliwego.
Umiejscowienie gniazd Wasm w potoku
Potok kompilacji rezerwuje następujące punkty gniazd. Etykiety kształtu stosują czteroetykietową taksonomię ze strony Status.
| Gniazdo | Umiejscowienie w potoku | Status obecnie |
|---|---|---|
Gniazdo governance, rola annotation-transform | Rozwiązywanie (przed rozwinięciem adnotacji) | dostępne — wywoływane, gdy przestrzeń robocza dołącza plugin annotation-transform; wstrzykuje adnotacje, które rozwinięcie zamienia w dołączenia encji Feature |
Gniazdo governance, rola label-transform | Budowa topologii (Topology Builder) | dostępne — wywoływane, gdy przestrzeń robocza dołącza plugin label-transform; automatycznie oznacza etykiety węzłów za pomocą JSON Patch |
Gniazdo governance, rola ir-verdict | Analiza statyczna (Static Analyzer, na grafie IR) | dostępne — wywoływane, gdy przestrzeń robocza dołącza plugin ir-verdict; werdykt halt zatrzymuje kompilację |
Gniazdo governance, rola render-verdict | Renderowanie (na wyrenderowanych artefaktach) | dostępne — wywoływane, gdy przestrzeń robocza dołącza plugin render-verdict; werdykt halt zatrzymuje kompilację |
Pluginy pipeline: encji FeatureRecipe i Recipe | Potok pluginów (modyfikacja po renderowaniu) | dostępne — każdy zadeklarowany krok działa na zbiorze wyrenderowanych dokumentów, stosując poprawki RFC 6902 i emitując efekty uboczne |
| Plugins renderujące Provider (helm, helm-chart, compose, terraform, cloudformation) | Renderowanie bazowe (dostawcy) | dostępne — każdy dostawca renderuje przez swojego gościa Wasm; renderowanie odbywa się wyłącznie w Wasm, bez zapasowego renderera po stronie hosta |
Wtyczki parserów (parse:<format>) | Renderowanie — dla polityki render-verdict; oraz poza głównym przebiegiem — dla importu | dostępne — wywoływane dla artefaktu w formacie, którego polityka render-verdict nie odczytuje natywnie, dla importera przez aggrega_parse_source oraz w celu rozpoznania formatu importu, który go nie podaje |
Wtyczki importerów (import:<format>) | Poza głównym przebiegiem (aggrega import) | dostępne — wywoływane przez aggrega import, sesję edytora i narzędzie przeznaczone dla asystenta |
Wtyczki linterów (linter/publishing) | Poza potokiem (aggrega lint) | dostępne — publishing-linter jest dostarczany i uruchamiany przez hosta za pomocą aggrega lint |
Podfaza rozwijania encji Feature sterowana adnotacjami, będąca częścią rozwiązywania, jest natywnym przebiegiem potoku w Go, a nie gniazdem Wasm. Waliduje wartości adnotacji względem spec.schema docelowej encji Feature i wstrzykuje syntetyczne dołączenia encji Feature w czasie budowy IR. Zobacz vocabulary/labels-and-annotations.md, aby poznać sześć powierzchni przenoszących adnotacje i etykiety, oraz providers/well-known-annotations.md, aby poznać kształt powiązań i wskazówki dotyczące tworzenia.
Kontrakt kształtu wyjścia — co istnieje obecnie
Socket governance udostępnia typowaną powierzchnię kontraktu w każdej ze swoich czterech ról, a to rola określa, którą z nich. Autorzy rozszerzeń typu Plugin implementują po stronie gościa kod, który generuje udokumentowane kształty; host odczytuje je w czasie budowania, raz dla każdej skonfigurowanej wtyczki, gdy przestrzeń robocza dołącza wtyczkę w tej roli. Poniższe podsekcje są ułożone w kolejności, w jakiej potok je wywołuje.
Rola annotation-transform — wyjście wstrzykiwania adnotacji
Umiejscowienie w potoku. Rozwiązywanie, po rozwiązaniu komponentów i przed uruchomieniem rozwijania encji Feature sterowanego adnotacjami.
Kształt wejścia (host → gość). Dokument AnnotationTransformInput zawierający:
targets— cele wstrzykiwania: rozwiązane komponenty, które gość może opatrzyć adnotacjami — te, które granica wskazuje bezpośrednio, oraz każdy komponent, który wprowadza wpis routingu waggregates:granicy, niezależnie od tego, czy wpis go wskazuje — każdy z własnymiboundary_path,component_name(dla komponentu wprowadzonego przez routing jest to jego identyfikator z kropkami w grafie buildu, np.metrics.query) iannotations, które zapisuje na nim encja Release, dzięki czemu gość może zdecydować, co dodać, nie wypierając wartości nadanej przez autora. Każda wartość adnotacji dociera w postaci, w jakiej ją zapisano — jako tekst, obiekt podkluczy lubnull, gdy komponent rezygnuje z adnotacji, którą by odziedziczył — a każdy klucz, który ma komponent, jest obecny niezależnie od wartości. Uporządkowane deterministycznie przez hosta.binding_keys— klucze adnotacji, dla których encja Manifest rejestruje powiązanie, w kolejności autora. Wstrzyknięcie pod zarejestrowanym kluczem zostaje następnie rozwinięte w dołączenie encji Feature, więc gość odczytuje tę listę, aby wstrzykiwać klucze, które zadziałają. Host nie wymaga, aby wstrzyknięcie wskazywało zarejestrowany klucz: niezarejestrowana wstrzyknięta adnotacja zachowuje się dokładnie tak jak niepowiązana adnotacja nadana przez autora.sources— pliki definicji zadeklarowane przez dołączenie wwith.sources, każdy z własną ścieżką nazwy bazowej i treścią, posortowane według ścieżki.settings— obiekt ustawień o dowolnej postaci zadeklarowany przez dołączenie wwith.settings, przekazywany gościowi dosłownie.
settings i sources to ten sam niezależny od silnika kanał with, który odczytuje każda inna rola, i oba są nieobecne, gdy dołączenie ich nie deklaruje. Ponieważ wyjście tej roli kształtuje budowanie, ustawienia i treść źródeł dołączenia są przypinane w pliku blokady wydania podczas pobierania i odtwarzane z niego podczas budowania.
Kształt wyjścia (gość → host). Dokument AnnotationTransformOutput zawierający:
injections— adnotacje do dodania, w kolejności. Każda wskazuje istniejącą współrzędną celu (boundary_pathicomponent_name) orazannotation_keyi jegoannotation_value: tekst lub obiekt podkluczy, który zasila powiązanie kierujące kilka podkluczy naraz.
Host stosuje wyłącznie dodania adnotacji, tylko do dostarczonych przez siebie współrzędnych i każde z wartością, jaką autor mógłby zapisać w tej adnotacji. Wstrzykniętą wartość odczytuje dokładnie tak, jak tę samą wartość zapisaną w encji Release — podklucze obiektu w kolejności, w jakiej zapisał je gość — więc rozwijanie traktuje ją tak samo jak adnotację napisaną przez autora. Wstrzyknięcie wskazujące współrzędną, której ładunek nie zawiera, albo niosące null, listę, liczbę, wartość logiczną lub obiekt bez podkluczy, zatrzymuje budowanie z komunikatem wskazującym współrzędną i adnotację, zamiast zostać po cichu pominięte lub zastosowane; cały wynik jest sprawdzany, zanim jakakolwiek jego część zostanie zastosowana. To ograniczenie wyznacza granice roli: operator dołączający tu wtyczkę zadeklarował wstrzykiwanie adnotacji i nic więcej. Gdy budowanie później odrzuca wstrzykniętą adnotację z powodu sposobu jej kierowania, wartości podklucza, której nie dopuszcza schemat powiązanej encji Feature, lub filaru, którego adnotacja po stronie encji Release nie może używać, jego komunikat wskazuje wtyczkę, która ją wstrzyknęła, i rolę, w której jest dołączona.
Kodowanie przesyłu. Ładunek i wynik tej roli są przesyłane jako kanoniczny CBOR (RFC 8949 §4.2.1), w obu kierunkach. Gość odczytuje go i zapisuje przez punkty wejścia, które mają typy ładunku — DecodeCBOR i EncodeCBOR w Go, decode_cbor i encode_cbor w Rust, decodeCBORAnnotationTransformInput i encodeCBORAnnotationTransformOutput w TypeScript — więc biblioteka CBOR nie jest potrzebna i nic nie parsuje bajtów ręcznie. W Rust eksport przyjmuje i zwraca Vec<u8>; w TypeScript odczytuje Host.inputBytes() i zapisuje Host.outputBytes(...). annotations każdego celu to mapa, którą schemat oznacza jako zachowującą kolejność, więc jest przesyłana jako uporządkowana lista wpisów w kolejności, w jakiej przechowuje ją cel, a gość odczytuje ją przez zachowujący kolejność kontener swojego zestawu; każda wartość jest przesyłana jako bajty swojego JSON, tak jak annotation_value wstrzyknięcia w przeciwnym kierunku. settings jest przesyłane jako bajty swojego dokumentu JSON, które gość parsuje jako JSON, aby zajrzeć do środka. Odpowiedź, która nie jest dokumentem AnnotationTransformOutput w tym kodowaniu — zapisana jako JSON lub zawierająca pole najwyższego poziomu, którego kształt nie deklaruje — zatrzymuje budowanie, podając plugin i jego eksport, zamiast zostać odczytana jako pusta lista wstrzyknięć. Wywołany bezpośrednio przez aggrega plugin run-local --export transform_annotations gość otrzymuje ładunek JSON nadany przez autora, przekonwertowany na to kodowanie, a jego odpowiedź jest odczytywana jako kształt wyjściowy eksportu i wypisywana jako JSON — odpowiedź, która nie ma tego kształtu, jest odrzucana z podaniem eksportu, tak jak odrzuca ją budowanie.
Definicje typów. Typy przesyłu annotation-transform — AnnotationTransformInput, AnnotationTransformOutput, AnnotationTarget, AnnotationInjection, AnnotationSource — są publikowane we wszystkich trzech pakietach ABI, generowane z jednego kodeka, dzięki czemu wszystkie trzy pozostają zsynchronizowane.
Rola label-transform — wynik w postaci JSONPatch
Miejsce w potoku. Budowa topologii, po spłaszczeniu grafu i przed zbudowaniem grafu IR, dzięki czemu selektory gniazd i encji Feature oceniane przez analizator odczytują etykiety, które pozostawia ta rola.
Kształt wejścia (host → gość). Dokument MutatorInput zawierający:
compilation_context— tożsamość wydania (release_name,environment).graph— projekcjęMutatorGraphwęzłów topologii: encję Component każdego węzła, rozwiązaną wersję, etykiety orazvaluesdeklarowane przez jego instancję.settings— obiekt ustawień o dowolnej postaci zadeklarowany przez dołączenie wwith.settings, przekazywany gościowi dosłownie.sources— pliki definicji zadeklarowane przez dołączenie wwith.sources, każdy ze ścieżką w postaci nazwy bazowej i treścią, dzięki czemu mutatorem może sterować zapisany w repozytorium plik reguł lub mapowania zamiast ustawień podanych bezpośrednio.
Graf jest projekcją, a nie grafem IR: każdy węzeł niesie swój rozwiązany zbiór etykiet i wartości, które jego instancja deklaruje w encji Aggregate, natomiast krawędzie i ładunki feature pozostają wewnątrz kompilatora. Wartości są własnymi wartościami encji Aggregate, z szablonami już obliczonymi względem jej parametrów, więc wartość przeniesiona do parametru dociera jako wartość dostarczona przez encję Release; wartość domyślna zadeklarowana przez schemat encji Component ani nic, co wnosi encja Recipe lub Feature, nie należą do nich, a węzeł, który nie deklaruje wartości, nie ma klucza values. Wartość, którą encja Component węzła deklaruje jako wrażliwą, jest zatajana dokładnie tak, jak zataja ją werdykt nad grafem — odczytuje się ją jako {"aggrega_withheld": "declared"} — natomiast każda wartość sąsiednia, do której nie sięga żadna deklaracja, dociera w postaci, w jakiej ją zapisano. To właśnie pozwala, by konfiguracja zadeklarowana przez programistę decydowała o etykiecie — na przykład baza danych, której wartości włączają rozszerzenie wektorowe, zostaje awansowana do datastore.aggrega.ai/engine: vector. settings i sources to ten sam niezależny od silnika kanał with, który odczytują role werdyktów; host przekazuje je dalej i nigdy nie interpretuje ich treści. Ponieważ wynik mutatora kształtuje budowanie, ustawienia i treść źródeł dołączenia są przypinane w pliku blokady wydania podczas pobierania i odtwarzane z niego podczas budowania, więc wejście mutatora nie zmienia się po zmianie któregokolwiek z nich po pobraniu, aż do następnego pobrania.
Kształt wyjścia (gość → host). Dokument MutatorOutput zawierający:
patches— tablicę nieprzezroczystych dokumentów JSONPatch (RFC 6902), które host stosuje wyłącznie do etykiet węzłów; wartości, które niosło wejście, są tylko do odczytu.
Każda łatka adresuje etykiety konkretnego węzła za pomocą JSON Pointer (RFC 6901); host stosuje łatki w kolejności tablicy i ponownie wczytuje zmodyfikowany zbiór etykiet do grafu IR. Zadaniem roli label-transform jest automatyczne tagowanie w przedsiębiorstwie — dodawanie etykiet zgodności, obserwowalności i przypisania kosztów, deklarowanych przez politykę przedsiębiorstwa, bez modyfikowania treści katalogu. Powierzchnia etykiet jest jedynym dozwolonym celem tej roli: łatka, która dotyka pola węzła innego niż jego etykiety, dodaje lub usuwa węzeł albo ustawia wartość etykiety niebędącą ciągiem znaków, zatrzymuje budowanie, zamiast zostać po cichu przyjęta. RFC 6901 jest bazową gramatyką ścieżek dla każdej powierzchni ścieżek dokumentów w Aggrega — opisanego tu kontraktu wtyczek Wasm, a także eksportów .locals *_path oraz pól schematu *Path w innych miejscach dokumentacji. Kanoniczną deklarację bazy oraz dyscyplinę sufiksów *Path / *_path, która rozróżnia obie strony tworzenia, opisuje sekcja „Document-path naming-suffix discipline” w 02-naming-conventions.md.
Kodowanie przesyłu. Ładunek i wynik tej roli są przesyłane w obu kierunkach jako kanoniczny CBOR (RFC 8949 §4.2.1). Kanoniczność oznacza, że identyczne wejście daje identyczne bajty po każdej stronie, co pozwala porównywać ładunek między trzema zestawami wtyczek, a nie tylko przesyłać go tam i z powrotem, i dlatego wynik budowania pozostaje identyczny co do bajtu. Gość odczytuje i zapisuje go przez punkty wejścia, które typ ładunku jego zestawu już udostępnia — DecodeCBOR i EncodeCBOR w Go, decode_cbor i encode_cbor w Rust, decodeCBORMutatorInput i encodeCBORMutatorOutput w TypeScript — więc biblioteka CBOR nie jest potrzebna i nic nie parsuje bajtów ręcznie. W Rust eksport przyjmuje i zwraca Vec<u8>; w TypeScript odczytuje Host.inputBytes() i zapisuje Host.outputBytes(...). Pole nodes grafu, pole labels każdego węzła i pole values każdego węzła to mapy, które schemat oznacza jako zachowujące kolejność, więc są przesyłane jako uporządkowane listy wpisów — węzły w kolejności, w jakiej przechowuje je budowanie, czyli w kolejności autora, etykiety każdego węzła w kolejności, w jakiej węzeł je niesie, a wartości każdego węzła w kolejności, w jakiej zapisuje je encja Aggregate — a gość odczytuje wszystkie trzy przez kontener zachowujący kolejność ze swojego zestawu. Każda wartość jest przesyłana jako bajty swojego dokumentu JSON: zestawy Go i Rust przekazują ją gościowi jako ten JSON, do sparsowania w takim zakresie, jakiego potrzebuje reguła, a zestaw TypeScript jako sparsowaną wartość.
Dwóch rzeczy to nie zmienia. Tablica patches pozostaje w JSON: gniazdo przenosi każdy dokument łatki dosłownie jako nieprzezroczystą treść i żadna ze stron nie zagląda do jego wnętrza, więc kształt samego dokumentu łatki nie zależy od kodowania, które przenosi jego gniazdo. Ponadto settings i sources nadal są przekazywane dosłownie — settings dociera jako bajty zapisane przez autora dołączenia, które gość parsuje jako JSON, jeśli musi zajrzeć do środka.
Każda inna rola zarządzania używa tego samego kodowania — rola annotation-transform i obie role werdyktów mówią o tym we własnych sekcjach — więc gość obsługujący więcej niż jedną rolę posługuje się kanonicznym CBOR w każdej obsługiwanej roli, odczytując każdy ładunek przez punkt wejścia dekodowania jego własnego typu.
Definicje typów. Typy przesyłu mutatora — MutatorInput, MutatorOutput, CompilationContext, MutatorGraph, MutatorNode — są publikowane we wszystkich trzech pakietach ABI (github.com/aggrega-ai/aggrega-abi/go, crate aggrega-abi oraz @aggrega-ai/aggrega-abi), generowanych z jednego kodeka, dzięki czemu wszystkie trzy pozostają ze sobą zsynchronizowane. Host składa wejście i stosuje łatki zwrócone przez gościa.
Role werdyktów — wynik w postaci tablicy werdyktów
Gość polityki analizuje kompilację i zwraca listę werdyktów; host działa na podstawie poziomu ważności każdego werdyktu i nigdy nie interpretuje samej polityki. Pełne omówienie — cztery role, poziomy ważności, kanał wejściowy dostarczany przez operatora, pisanie polityki dla jednego z dwóch silników wbudowanych w kompilator, opakowywanie zewnętrznego silnika polityk, gości referencyjnych oraz sposób, w jaki operator dołącza politykę — znajduje się na stronie gniazda zarządzania. Ta sekcja opisuje umiejscowienie w potoku i typowane kształty danych przesyłanych.
Umiejscowienie w potoku. Polityka jest dołączana do dokładnie jednej roli werdyktu, która określa, gdzie jest ewaluowana:
ir-verdict— ewaluowana podczas analizy statycznej, przed renderowaniem bazowym. Analizator składa ładunek przy każdej kompilacji.render-verdict— ewaluowana po renderowaniu, na wyemitowanych artefaktach.
Gdy przestrzeń robocza dołącza plugin roli werdyktu, potok serializuje ładunek tej roli do pluginu i odczytuje zwrócone werdykty.
Kształt wejścia (host → gość). Rola wybiera ładunek:
PolicyInputroliir-verdictzawieragraph— pełny, niezależny od możliwości graf IR (o tym samym kształcie, który emituje Topology Builder), z każdym węzłem, krawędzią i szczegółem dołączenia, jakie posiada kompilator, z tą różnicą, że wartość zadeklarowana przez autora jako wrażliwa dociera zatajona (zob. Wartości, które wejście oznacza jako wrażliwe) — orazprecalculated_paths, ścieżki routingu wyliczane równolegle przez analizator, dzięki czemu polityka może wnioskować o osiągalności bez ponownego przechodzenia grafu. Graf jest wersjonowanym grafem IR, pochodzącym z jednego źródła — schematuir-v1beta1; kształt IR nie jest tajny (to ten sam graf, który emitujeaggrega inspect), a sekrety w nim są wskaźnikami, nigdy tekstem jawnym.RenderPolicyInputrolirender-verdictzawieraartifacts— wyrenderowane pliki wyjściowe posortowane według ścieżki, dzięki czemu dane przesyłane są identyczne bajt w bajt między uruchomieniami dla identycznego wejścia. Każdy wpis zawiera wyjściową ścieżkę artefaktupathi jego wyrenderowaną treśćcontent; zawiera teżformat, w którym go wyrenderowano, jeśli dostawca, który go wytworzył, go zadeklarował, oraztree, sparsowany kanoniczny widok formatu, którego gość nie czyta natywnie, parsowany przez hosta za pomocą rozwiązanego parsera i przekazywany bez interpretacji. Oba są nieobecne, gdy nie mają zastosowania — format, który gość czyta natywnie (JSON, YAML), pozostaje niesparsowany, aby gość odczytał go zcontent.
Obie role zawierają dodatkowo sources dołączenia (pliki definicji polityk, które host odczytuje w czasie kompilacji i przekazuje gościowi dosłownie; ścieżki jako nazwy bazowe, treść nieprzezroczysta) oraz settings (obiekt o dowolnej postaci przekazywany bez zmian). Oba są nieobecne, gdy dołączenie żadnych nie deklaruje.
Kształt wyjścia (gość → host). Dokument PolicyOutput zawierający:
results— tablicę wpisówDiagnostic, każdy zseverity(halt,warnlubinfo) i ciągiemmessage. Werdykt może też ustawić w tym samym wpisiecode,rule_id,classification,source_ref,locationisuggest; host dołącza te z nich, które werdykt zawierał, do wyrenderowanego werdyktu, na każdej ścieżce poziomu ważności.
Pojawiają się tylko werdykty, które zostały wyzwolone; ewaluacja zezwalająca zwraca pustą tablicę. Host przechodzi przez werdykty i mapuje każdy poziom ważności na działanie: halt zatrzymuje kompilację (pokazując każdy komunikat halt), warn oznacza werdykt i pozwala kontynuować kompilację, info rejestruje go bez wpływu na wynik. halt zatrzymuje kompilację przez tę samą bramkę, której używa naruszenie selektora lub appliesTo.
Kodowanie przesyłanych danych. Ładunki obu ról oraz PolicyOutput, który gość zwraca w każdej z nich, są przesyłane jako kanoniczny CBOR (RFC 8949 §4.2.1). Gość odczytuje je i zapisuje przez punkty wejścia, które mają typy ładunków — DecodeCBOR i EncodeCBOR w Go, decode_cbor i encode_cbor w Rust, decodeCBORPolicyInput, decodeCBORRenderPolicyInput i encodeCBORPolicyOutput w TypeScript — więc żadna biblioteka CBOR nie jest potrzebna i nic nie parsuje bajtów ręcznie. W Rust każdy eksport przyjmuje i zwraca Vec<u8>; w TypeScript odczytuje Host.inputBytes() i zapisuje Host.outputBytes(...). Mapy grafu zachowujące kolejność, w tym jego nodes i labels każdego węzła, są przesyłane jako uporządkowane listy wpisów w kolejności, w jakiej przechowuje je kompilacja, a gość odczytuje je przez kontener zachowujący kolejność ze swojego zestawu; w jakiej kolejności polityka je otrzymuje w każdym silniku polityk, opisano na stronie gniazda zarządzania. settings oraz sparsowane tree artefaktu są przesyłane jako bajty ich dokumentów JSON, które gość parsuje jako JSON, aby zajrzeć do środka. Odpowiedź, która nie jest PolicyOutput w tym kodowaniu — zapisana jako JSON lub zawierająca pole najwyższego poziomu, którego kształt nie deklaruje — zatrzymuje kompilację ze wskazaniem pluginu i jego eksportu, zamiast zostać odczytana jako pusta lista werdyktów. Gość wywołany bezpośrednio przez aggrega plugin run-local --export verdict_ir lub --export verdict_render otrzymuje napisany przez autora ładunek JSON przekonwertowany na to kodowanie, a jego odpowiedź jest odczytywana jako kształt wyjściowy eksportu i wypisywana jako JSON — odpowiedź, która nie ma tego kształtu, jest odrzucana z podaniem eksportu, tak jak odrzuca ją kompilacja.
Definicje typów. Typy przesyłanych danych polityk są publikowane w tych samych trzech pakietach ABI: PolicyInput (rola ir-verdict), RenderPolicyInput (rola render-verdict), współdzielony PolicySource oraz PolicyOutput, którego wpisy results są wartościami Diagnostic. Poziom ważności diagnostyki to jedna z trzech wartości wspólnych dla wszystkich gniazd — halt, warn lub info — a te trzy są publikowane jako stałe obok typów przesyłanych danych w każdym z trzech pakietów, dzięki czemu gość raportuje z tego samego zamkniętego zbioru, według którego host kieruje. Gość, który zwróci jakąkolwiek inną wartość, zatrzymuje kompilację z komunikatem wskazującym plugin i zwróconą wartość: poziom ważności, którego nie da się skierować, jest defektem pluginu zgłaszanym przez hosta, a nie diagnostyką, którą host pomija.
Kontrakt kształtu wyjścia — potok FeatureRecipe i gniazda dostawców
Poniższe gniazda przenoszą typowane powierzchnie kontraktu, które kompilator wywołuje podczas budowania. Kroki pipeline: encji FeatureRecipe i Recipe działają w potoku pluginów na zbiorze wyrenderowanych dokumentów; gniazdo renderowania przez dostawcę działa na etapie renderowania bazowego; linter publikacji działa poza głównym przebiegiem.
Łatki RFC 6902 (potok pluginów)
Kroki pipeline: encji FeatureRecipe i Recipe działające w potoku pluginów emitują operacje RFC 6902 JSON Patch na zbiorze wyrenderowanych dokumentów. Host przekazuje każdemu krokowi cały zbiór dokumentów z kluczami; krok wybiera docelowe dokumenty według treści i zwraca łatki adresowane kluczami, które silnik stosowania nakłada na wskazane dokumenty — zwykle dopisując kontener sidecar, montując wolumen z sekretem lub przepisując zmienną środowiskową. Krok zwraca też side_effects (poniżej), diagnostics — każdy wpis w tym samym wspólnym kształcie Diagnostic, w którym każde gniazdo zgłasza problemy — oraz outputs (poniżej). Opisano w examples/04-secrets.md.
Stan obecny: dostępne. Każdy zadeklarowany krok działa podczas aggrega build.
Kodowanie przesyłu. Wejście kroku (FRPStepInput) i jego odpowiedź (FRPStepOutput) są przesyłane jako kanoniczny CBOR (RFC 8949 §4.2.1), w obu kierunkach. Gość dekoduje wejście i koduje odpowiedź przez punkty wejścia, które mają typy ładunku — DecodeCBOR i EncodeCBOR w Go, decode_cbor i encode_cbor w Rust (na typach publikowanych przez crate aggrega-abi), decodeCBORFRPStepInput i encodeCBORFRPStepOutput w TypeScript — czytając i zapisując bajty (Vec<u8> w Rust, Host.inputBytes() i Host.outputBytes(...) w TypeScript). Biblioteka CBOR nie jest potrzebna i nic nie parsuje bajtów ręcznie. Wejście with kroku (step_input), zwracane przez niego outputs oraz zbiory dokumentów own i host to mapy, które schemat oznacza jako zachowujące kolejność, więc są przesyłane jako uporządkowane listy wpisów w kolejności, w jakiej trzyma je potok, a gość czyta je i zapisuje przez kontener zachowujący kolejność ze swojego zestawu — dzięki temu wyjścia kroku trafiają do .steps.<id>.outputs w kolejności, w jakiej krok je zwrócił. tree każdej jednostki, każda wartość step_input i outputs, value łatki, crd efektu ubocznego oraz context renderowania są przesyłane jako bajty swoich dokumentów JSON, które gość parsuje jako JSON, by zajrzeć do środka; bytes jednostki są przesyłane jako surowy ciąg bajtów, który wygenerowany dekoder wpisuje do typu pola właściwego dla zestawu — wycinka bajtów w Go, łańcucha base64 w Rust i TypeScript. Każda diagnostyka jest przesyłana we wspólnym kształcie Diagnostic. Odpowiedź, która nie jest FRPStepOutput w tym kodowaniu — zapisana jako JSON albo zawierająca pole najwyższego poziomu, którego kształt nie deklaruje — kończy krok niepowodzeniem z podaniem uruchamianej funkcji, co zatrzymuje budowanie, chyba że krok jest optional. Wywołany bezpośrednio przez aggrega plugin run-local --export step krok otrzymuje napisany ładunek JSON przekonwertowany do tego kodowania, a jego odpowiedź jest odczytywana jako kształt wyjściowy eksportu i wypisywana jako JSON — odpowiedź, która nie ma tego kształtu, jest odrzucana z podaniem eksportu, tak jak odrzuca ją budowanie.
Efekty uboczne — emitowanie zasobów (pluginy poświadczeń w potoku pluginów)
Potoki FeatureRecipe dla poświadczeń (Two-Part Plugin Principle: Fetcher + Injector) emitują pełne zasoby obok poprawki poprzez side_effects kroku, z których każdy deklaruje jeden z dwóch rodzajów zdefiniowanych przez kontrakt: emit_crd, dokument zasobu niestandardowego, taki jak CRD ExternalSecret lub VaultSecret, który klaster pobiera w czasie działania, albo emit_file, zapisany plik. Krok zwracający jakikolwiek inny rodzaj zatrzymuje budowanie, podając węzeł, indeks efektu ubocznego i zadeklarowany rodzaj. Krok Fetchera emituje kompletny zasób; krok Injectora zwraca poprawkę, która montuje wynikowy Secret Kubernetes. Opisano w examples/04-secrets.md.
Stan obecny: dostępne.
Wyjście kroku (mapa outputs kroku pipeline:)
Krok potoku pluginów publikuje nazwane wyjścia, które kolejne kroki odczytują przez {{ .steps.<id>.outputs.<key> }}. Kształt wyjścia definiuje dostawca osobno dla każdego pluginu; wyjścia kroków są ograniczone do tego samego potoku i widoczne tylko dla kolejnych kroków w kolejności deklaracji. Opisane w templates/expansion-matrix.md, wiersz 10.
Stan obecny: dostępne.
Renderowanie Provider — gniazdo sterowane przez gościa
Dostawca jest gościem Wasm. Renderowanie odbywa się wyłącznie w Wasm: nazwa capability: encji Recipe wskazuje encję Plugin renderującą dla dostawcy (pluginType: provider), która wymienia tę nazwę w swoim spec.provider.capabilities i ogłasza eksport render_node, a gość tego pluginu renderuje węzeł. Nie ma renderera w hoście, do którego można by się cofnąć; nazwa dostawcy, której nie obsługuje żaden Plugin, zatrzymuje budowanie na etapie routingu. Dodanie standardowego dostawcy to dostarczenie gościa .wasm i encji Plugin w katalogu — host nie zawiera kodu specyficznego dla dostawców.
Możliwość obsługiwana przez dostawcę nie zawiera dwukropka, podobnie jak możliwość, z którą krok potoku deklaruje zgodność. capability: encji Recipe jest odczytywane jako możliwość do ostatniego dwukropka i przypięta wersja po nim — helm:1.0.0 żąda helm w wersji 1.0.0 — więc nazwy zawierającej dwukropek nie może zażądać żadna encja Recipe. Host odrzuca taką nazwę w capabilities z describe() dla gościa provider lub pipeline-step przy ładowaniu gościa i przy generowaniu jego encji do publikacji, podając gościa i nazwę. parse:<format> parsera i import:<format> importera zachowują dwukropek: są wyszukiwane według formatu, nigdy przez capability: encji Recipe.
Host jest generycznym routerem. Odczytuje samoopis gościa z describe() — w tym jego kontrakt zachowania renderowania — i wywołuje eksporty gościa, nie rozumiejąc żadnego formatu dostawcy. Ten kontrakt steruje wywoływaniem jako dane:
input_kinds(sourced,synthesized,artifacts_standalone) — które rodzaje wejścia encji Recipe gość renderuje; host sprawdza rodzaj wejścia węzła względem tego zbioru.boundary_assembly(none|merge|nest) — jak gość łączy wyjście grupy wywołań:mergeklasyfikuje wyjście poszczególnych węzłów jako fragmenty, które asembler scala w jeden artefakt,nestzagnieżdża pliki poszczególnych węzłów w złożonym opakowaniu,nonezapisuje wyjście każdego węzła bezpośrednio.nest_segment(opcjonalne) — dla składanianestkatalog, pod którym umieszczany jest własny podkatalog każdego współtwórcy, zapisany jako jedna nazwa katalogu; gdy go brak, podkatalog każdego współtwórcy znajduje się bezpośrednio w pozycji rozsyłania.assembly_name_annotation(opcjonalne) — adnotacja granicy, której rozwiązana wartość nadaje nazwę artefaktowi składanemu przez gościa z grupy rozsyłania; gdy jej brak, gość nadaje nazwę swojemu złożeniu wyłącznie na podstawie ścieżki rozsyłania.cross_boundary_linking(opcjonalne) — czy gość łączy krawędźusesprzekraczającą granicę przez swoje eksportylink_publishilink_resolve; gość deklaruje wartość true dokładnie wtedy, gdy eksportuje oba, a ładowanie odrzuca gościa, którego flaga i eksporty są niezgodne.artifact_delimiters(opcjonalne) — para ograniczników szablonów Go, którą gość stosuje do treści artefaktów.reusable_instance(opcjonalne) — czy jedna załadowana instancja może obsłużyć każde przejście w budowaniu (zob. Determinizm i ponowne użycie instancji poniżej).omits(opcjonalne) — czy gość respektuje wpisy pominięć, które niesie renderowanie źródła (zob. Pomijanie wyrenderowanych jednostek poniżej).boundary_artifacts(opcjonalne) — czy cel gościa przyjmuje pliki, które encja Recipe wnosi do wspólnego wyjścia swojej granicy (zob. Przyjmowanie plików, które encja Recipe wnosi do granicy poniżej).source_ignore(opcjonalne) — pliki, których ekosystem gościa nigdy nie dostarcza obok renderowanego źródła (zob. Deklarowanie, czego ekosystem źródła nigdy nie dostarcza poniżej).
Gniazdo to stały zestaw eksportów — jeden obowiązkowy, pozostałe opcjonalne i ogłaszane w describe():
render_node(obowiązkowy) — renderuje jeden węzeł IR do natywnych plików dostawcy.assemble_boundary(opcjonalny) — scala wyjście poszczególnych węzłów grupy wywołań w jeden artefakt na ścieżkę (obecny, gdyboundary_assemblyma wartośćmergelubnest).validate_node_input(opcjonalny) — strukturalna walidacja wejścia węzła przed renderowaniem; diagnostykahaltzatrzymuje budowanie, awarntrafia do wyniku budowania.carve/reassemble(opcjonalne, w parze) — własny, wierny bajtowo kodek łatek gościa dla kroków potoku po renderowaniu, używany tylko wtedy, gdy oba są ogłoszone.name_bound(opcjonalny) — gość ocenia, czy nazwa proponowana przez hosta jako tożsamość komponentu daje nazwy akceptowane przez jego cel, odpowiadając ograniczeniem, a nie własną nazwą.rendered_name(opcjonalny) — gość zgłasza nazwę, jaką jego cel nadaje zasobom renderowanym dla węzła.link_publish/link_resolve(opcjonalne, w parze) — gość łączy krawędźusesprzekraczającą granicę: konsumowany punkt końcowy publikuje uchwyt, a konsumujący punkt końcowy rozwiązuje go we własnym złożonym wyniku.
Pole artifacts: encji Recipe trafia do render_node przez projekcję artefaktów w danych wejściowych: host wykonuje odczyt $import, ewaluację szablonów Go oraz obliczenie klucza/wartości pochodzenia i przekazuje gościowi każdy wpis już odczytany i obliczony; gość odpowiada za rozmieszczenie i emisję w formacie, który zna tylko on. Opisano to w architecture/13-catalog-and-registry.md.
Dane wejściowe renderowania źródła niosą wartości węzła w node.values, a node.values_mapped mówi, skąd pochodzą: ma wartość true, gdy są wynikiem valuesMapping encji Recipe — lub, w przypadku własnego renderowania załącznika, jego encji FeatureRecipe — i jest nieobecne, gdy są to własne wartości komponentu przekazane w postaci, w jakiej je zapisano. To, czy gość je odczytuje, jest kwestią jego własnego kontraktu. Provider cloudformation wiąże Parameters szablonu ze źródła wyłącznie z wartościami wytworzonymi przez mapowanie, ponieważ własne wartości komponentu mogły zostać zapisane dla innych wejść encji Recipe; provider terraform zapisuje argumenty modułu ze źródła z wartości, które otrzymuje jego złożenie, i nie odczytuje tej flagi. Wartości te są przekazywane w każdym wyrenderowanym węźle danych wejściowych assemble_boundary dla węzła renderowanego ze źródła — w przypadku komponentu niezależnie od tego, czy wytworzyło je mapowanie, a w przypadku dołączonej encji Feature tylko wtedy, gdy wytworzyło je valuesMapping jej encji FeatureRecipe — a ta sama flaga jest przekazywana obok nich i tylko tam, gdzie one, dzięki czemu asembler odczytuje tę samą odpowiedź, co własne renderowanie węzła; provider cloudformation odczytuje ją tam, aby ustalić, które parametry wypełniło wiązanie węzła, i odrzuca odwołanie do takiego parametru z dowolnego innego miejsca stosu, łącznie z hostem dołączonej encji Feature. Flaga rejestruje sposób wytworzenia wartości i nigdy nie jest wyprowadzana z klucza ani wartości.
Kodowanie przesyłu. Każdy eksport tego gniazda przyjmuje dane wejściowe i zwraca wynik jako kanoniczny CBOR (RFC 8949 §4.2.1), w obu kierunkach. Gość dekoduje dane wejściowe i koduje wynik przez punkty wejścia, które typy ładunku już udostępniają — DecodeCBOR i EncodeCBOR w Go, decode_cbor i encode_cbor w Rust, a w TypeScript funkcje decodeCBOR i encodeCBOR każdego typu, takie jak decodeCBORRenderNodeInput i encodeCBORRenderNodeOutput — odczytując i zapisując bajty (Vec<u8> w Rust, Host.inputBytes() i Host.outputBytes(...) w TypeScript). Biblioteka CBOR nie jest potrzebna i nic nie parsuje bajtów ręcznie. Pole content wyrenderowanego pliku oraz każde inne pole bajtowe przechodzi jako surowy ciąg bajtów, który wygenerowany dekoder wpisuje do własnego typu pola zestawu: wycinka bajtów w Go, ciągu base64 w Rust i TypeScript. Mapy, które schemat oznacza jako zachowujące kolejność — m.in. values, features i uses węzła, derived_keys odpowiedzi oraz values kontrybutora złożenia — przechodzą jako uporządkowane listy wpisów w kolejności, w jakiej przechowuje je kompilacja, a gość odczytuje je przez kontener zestawu zachowujący kolejność. Każda wartość values węzła przechodzi jako bajty własnego dokumentu JSON, dzięki czemu klucze wewnątrz wartości zachowują kolejność, w jakiej je zapisano; tak samo każdy wpis załącznika w features, kontekst renderowania, sparsowany workload, każda wzbogacona krawędź, każda wycięta jednostka i każda operacja poprawki, a gość parsuje je jako JSON, aby zajrzeć do środka. Każda diagnostyka przechodzi we wspólnym kształcie Diagnostic. Odpowiedź, która nie jest kształtem wyniku danego eksportu w tym kodowaniu — zapisana jako JSON lub zawierająca pole najwyższego poziomu, którego kształt nie deklaruje — zatrzymuje kompilację, wskazując wywołany eksport. Przykłady ładunków na tej stronie zapisano jako JSON dla czytelności. Wywołany bezpośrednio przez aggrega plugin run-local --export render_node lub dowolny inny eksport gniazda gość otrzymuje utworzony ładunek JSON przekonwertowany do tego kodowania, a jego odpowiedź jest odczytywana jako kształt wyniku eksportu i wypisywana jako JSON — odpowiedź, która nie ma tego kształtu, jest odrzucana ze wskazaniem eksportu, tak jak odrzuca ją kompilacja.
Stan obecny: dostępne dla wszystkich pięciu providerów. Gość helm renderuje charty ze źródła (rozwiązując katalog główny chartu), syntetyzowane workloady i samodzielne artefakty jako płaskie manifesty Kubernetes. Gość helm-chart składa chart nadrzędny, zagnieżdżając chart ze źródła każdego węzła jako sub-chart, i zawiera wierny bajtowo kodek poprawek oraz nawiasowe ([[ ]]) ograniczniki artefaktów. Gość compose renderuje pliki compose ze źródła i syntetyzowane workloady, scala grupę dyspozycji w jeden docker-compose.yaml i dołącza usługę do sieci komponentów wskazanych w jej x-aggrega-networks-of. Gość terraform emituje konfigurację Terraform dosłownie (HCL lub JSON) albo dołącza moduł ze źródła i dostarcza jego wejścia jako argumenty bloku module danego komponentu, przed renderowaniem strukturalnie waliduje HCL modułu ze źródła i składa granicę w jedną konfigurację główną, deklarującą każdy komponent jako blok module pobierający własny podkatalog tego komponentu. Gość cloudformation renderuje szablony ze źródła i samodzielne fragmenty stosu, scala grupę dyspozycji w jeden szablon stosu i łączy krawędź uses przekraczającą granicę przez link_publish i link_resolve. Każdy renderuje offline i deterministycznie.
Deklarowanie nazw wyprowadzanych przez gościa
Gość dostawcy zwykle wyprowadza nazwy, których potrzebuje jego wynik, a których nikt nie napisał — identyfikator, pod którym cel adresuje jeden zasób, nazwę, pod którą jeden wynik jest publikowany, aby inny mógł się do niego odwołać — z tożsamości węzła i emitowanego zasobu. Dwa węzły mogą dojść do jednej nazwy zawsze, gdy części, z których są wyprowadzane, się zgadzają, a ponieważ nazwa znajduje się w bajtach pliku zapisywanych przez hosta dosłownie, host nie widzi tego konfliktu: musiałby parsować format dostawcy, aby go znaleźć, a to jest dokładnie ta wiedza, która pozostaje w gościu.
Dlatego render_node zwraca w swoim wyniku opcjonalne derived_keys, a kierunek jest odwrócony — zamiast hosta sprawdzającego wynik gość deklaruje, a host sprawdza:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "derived_keys": { "logical-ids": ["paymentsapiQueue", "paymentsapiTopic"], "export-names": ["aggrega--prod--api--orders-db--host"] }}Każdy klucz derived_keys to przestrzeń kluczy nazwana przez gościa, a każda przestrzeń zawiera nazwy wyprowadzone do niej przez gościa, w kolejności wyprowadzania. Zarówno nazwy przestrzeni, jak i nazwy w nich należą do własnego słownictwa autora: host odczytuje je wyłącznie jako ciągi znaków do porównania pod kątem równości w obrębie jednej przestrzeni. Nie parsuje nazwy, nie dowiaduje się, co oznacza przestrzeń ani nazwa, i nigdy sam żadnej nie wyprowadza — dzięki temu jedno sprawdzenie obejmuje każdy rodzaj nazwy wyprowadzanej przez każdego dostawcę, a nowy dostawca nie wymaga nowego kodu hosta. W opublikowanych typach derived_keys jest mapą zachowującą kolejność, więc przestrzenie przechodzą w kolejności, w jakiej ustawia je gość.
To, co host z nimi robi, sprowadza się do jednego pytania: czy w obrębie jednej przestrzeni każda zadeklarowana nazwa jest unikalna wśród współtwórców, których wyniki łączą się w jeden złożony wynik? Dwóch współtwórców deklarujących jedną nazwę w jednej przestrzeni zatrzymuje kompilację, a komunikat zatrzymania wskazuje przestrzeń, nazwę i obu współtwórców, dzięki czemu autor może działać bez czytania kodu dostawcy. Nazwy unikalne oraz nazwy, które przypadkiem się pokrywają w dwóch różnych przestrzeniach, przechodzą.
Przy decydowaniu, co deklarować, warto znać trzy właściwości:
- Zakresem jest jeden złożony wynik — zbiór współtwórców, których pliki są łączone. Gość, który potrzebuje unikalności w węższym lub szerszym zakresie, wyraża ten zakres w deklarowanej nazwie przestrzeni, dzięki czemu wybór należy do autora, a nie do hosta.
- Jeden współtwórca może dowolnie powtarzać nazwę. Węzeł może być renderowany w kilku przejściach — renderowaniu źródła, syntezie obciążenia, umieszczaniu artefaktów — a deklaracje są łączone. Ta sama nazwa zadeklarowana dwukrotnie przez jednego współtwórcę oznacza, że opisuje on jeden zasób dwa razy, a nie konflikt.
- Deklarowanie nie zmienia żadnych bajtów. Pole jest stwierdzeniem o tym, co gość wyprowadził, a nigdy zmianą tego, co wyemitował, więc wyrenderowany wynik gościa jest identyczny niezależnie od tego, czy deklaruje, czy nie. Pominięcie
derived_keysjest prawidłowe i wyłącza sprawdzenie dla tego gościa.
Raportowanie faktów o tym, co wyemitował gość
Niektóre informacje o renderowaniu węzła są widoczne tylko dla dostawcy, który je wykonał — co zawierają zapisane przez niego dokumenty, jakie nazwy definiują, ile czegoś wyemitował — ponieważ odczytanie ich z bajtów pliku wymaga zrozumienia formatu dostawcy. render_node może sam raportować takie informacje na opcjonalnej liście render_facts obok swoich plików:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "render_facts": [ { "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] }, { "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] } ]}Każdy fakt to name i value, a oba należą do danego dostawcy: jakie fakty raportuje, co oznacza każda nazwa i co zawiera każdy wpis, jest częścią własnego, udokumentowanego kontraktu dostawcy, więc należy to udokumentować dla autorów, którzy będą je czytać.
Wartość każdego faktu należy raportować jako listę — tablicę JSON — nawet gdy zawiera jeden wpis. Jedna nazwa może być raportowana przez więcej niż jedno renderowanie komponentu: jego własne renderowanie może obejmować kilka wywołań — na przykład renderowanie chartu i umieszczanie artefaktów — a każda encja Feature dołączona do komponentu jest renderowana własnym wywołaniem dostawcy. Żaden dostawca nie może wiedzieć w chwili renderowania, czy jego raport będzie jedynym pod daną nazwą, dlatego każdy raport jest listą, a kompilator łączy listy otrzymane dla jednej nazwy w jedną listę. Fakt, którego wartość jest czymkolwiek innym — obiektem, ciągiem znaków, liczbą, wartością logiczną, null — jest odrzucany, gdy gość go zwróci: kompilacja zatrzymuje się z krótkim kodem E0325, wskazując fakt, węzeł i gościa oraz podając, jaka była wartość. Wpisy w liście mogą być dowolnymi wartościami JSON w udokumentowanym kształcie.
To, że wartość jest listą, jest jedyną rzeczą, jaką kompilator o niej wie. Indeksuje fakty według nazwy i przekazuje każdą listę szablonom, które ją odczytują — fakty komponentu-hosta każdej dołączonej do niego encji Feature, fakty każdego wywołującego encji Feature, która deklaruje, że odczytuje fakty renderowania swoich wywołujących, a fakty każdego celu encji Feature, która deklaruje, że odczytuje fakty renderowania komponentów, z którymi połączony jest jej host, jak opisuje kontekst szablonu — dekodując każdą listę na wartość, po której szablon może iterować. Nigdy nie dowiaduje się, co oznacza nazwa lub wpis, i nigdy sam nie wyprowadza faktu, więc nowy dostawca może raportować nowe fakty bez żadnych zmian po stronie kompilatora. Fakty raportowane przez encję Feature dołączoną do węzła z jej własnego renderowania są przechowywane oddzielnie od faktów zaraportowanych przez własne renderowanie węzła.
Przy decydowaniu, co raportować, warto znać cztery właściwości:
- Kolejność należy do autora. Fakty zachowują kolejność, w jakiej wymienia je gość, a każda wartość zachowuje własne bajty — kolejność wpisów listy i kluczy każdego obiektu jest taka, jaką zapisał gość. Fakty należy wymieniać w stałej kolejności, a każdy wpis zapisywać ze stałą kolejnością kluczy, aby identyczne dane wejściowe dawały identyczne bajty; lista faktów zamiast mapy istnieje właśnie po to, aby kolejność przetrwała w natywnym typie sekwencji każdego zestawu bez żadnego oznaczania, podczas gdy mapa zachowuje kolejność zapisaną przez gościa tylko wtedy, gdy jej schemat oznacza ją jako zachowującą kolejność, a gość wypełnia kontener zachowujący kolejność swojego zestawu.
- Raportowanie nie zmienia żadnych bajtów. Pliki zapisywane przez kompilator są plikami zwróconymi przez gościa, niezależnie od tego, czy towarzyszą im fakty.
- Węzeł może raportować w kilku przejściach. Węzeł może być renderowany jako renderowanie źródła, synteza obciążenia i umieszczanie artefaktów; fakty raportowane przez każde z nich są przechowywane w kolejności wykonania przejść, a nazwa raportowana przez więcej niż jedno z nich odczytywana jest jako jedna lista łącząca je w tej kolejności.
- Niezaraportowanie niczego jest kompletną odpowiedzią. Pominięcie
render_factsjest prawidłowe, a dostawca, który nic nie raportuje, renderuje dokładnie tak, jak bez tego pola.
Typ RenderFact jest publikowany w trzech pakietach ABI i reeksportowany przez zestaw do tworzenia pluginów każdego języka, a przykłady renderowania w zestawach raportują dwa fakty obok swoich plików. W Go wartością jest JSON zapisany przez gościa; serializowanie wycinka struktur zamiast map zapewnia, że klucze każdego wpisu zachowują zadeklarowaną kolejność:
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}},}Pomijanie wyrenderowanych jednostek
Renderowanie źródła może wskazać jednostki, które dostawca musi pominąć w tym, co renderuje — na przykład Secret generowany od nowa przez pobrany chart przy każdym renderowaniu. To, którą wyrenderowaną jednostkę wskazuje dany wpis, wie tylko dostawca, dlatego wpisy trafiają do gościa, a pomija je sam gość. Przychodzą na wejściu render_node jako opcjonalna lista omits obok source_listing:
{ "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" } ]}Każdy wpis to kind, name i opcjonalne namespace, już rozwiązane do zwykłych ciągów znaków i wymienione w kolejności, w jakiej zadeklarował je autor; wpis, który nie dotyczy danej kompilacji, nie jest przekazywany. To, co wybierają te trzy pola, jest własnym kontraktem dostawcy — rodzaj, nazwa i przestrzeń nazw zasobu w formacie danego celu — dlatego należy go udokumentować dla autorów piszących wpisy.
Autor może zbudować pola wpisu z wartości, którą zadeklarował jako wrażliwą — na przykład zasobu nazwanego od wrażliwego ustawienia. Taki wpis przychodzi z "sensitive": true, a gość traktuje go tak jak każdą inną oznaczoną wartość, którą niesie wejście renderowania (zob. Wartości oznaczone przez wejście jako wrażliwe): nadal dopasowuje i zlicza wpis według jego pól, bo do tego wpis służy, i nie umieszcza żadnego z jego pól w odmowie, ostrzeżeniu ani wierszu logu. Oznaczenie obejmuje cały wpis, ponieważ kompilator nie mówi, które pole powstało z tej wartości. Nie występuje, gdy żadne pole nie zostało zbudowane z takiej wartości.
Gość, który respektuje wpisy, robi trzy rzeczy:
- Dopasowuje każdy wpis do tego, co wyrenderował, w kategoriach swojego formatu.
- Pomija każdą dopasowaną jednostkę we wszystkim, co zwraca — w
files, w nazwach deklarowanych wderived_keysi w faktach zgłaszanych wrender_facts— tak by nic, co otrzymuje kompilator, już jej nie opisywało. - Zgłasza jedną liczbę na wpis w opcjonalnej liście
omittedna wyjściu, w kolejności, w jakiej przyszły wpisy; każda to liczba jednostek dopasowanych przez dany wpis, liczona niezależnie od tego, czy dopasował je też inny wpis:
{ "files": [ { "path": "templates/deployment.yaml", "content": "..." } ], "omitted": [1, 0]}Zero jest pełną odpowiedzią: dany wpis nie dopasował niczego, co wyrenderował gość. Liczby to wszystko, co wraca na temat pominiętych elementów; same jednostki po prostu nie występują w tym, co zwrócił gość.
Dostawca, który robi wszystkie trzy rzeczy, deklaruje to przez omits: true w swoim kontrakcie. Encja Plugin zapisuje tę samą deklarację jako spec.provider.contract.omits; jeśli encja zawiera kontrakt zachowania renderowania, ładowanie odrzuca gościa, którego describe() zgłasza inną wartość. Wpisy towarzyszą wyłącznie listingowi źródła: renderowanie syntetyzowanego workloadu ani zestawu artefaktów nigdy ich nie niesie.
Renderowanie bez wpisów nie zmienia się przez te pola. Oba pola są opcjonalne i nieobecne, gdy są puste, więc renderowanie bez wpisów przechodzi przez gniazdo bajt w bajt tak, jakby te pola nie istniały, a gość, który ich nigdy nie czyta, nie jest przez nie dotknięty. Typ OmitEntry jest publikowany w trzech pakietach ABI i reeksportowany przez zestaw do tworzenia pluginów każdego języka.
Co kompilator robi z odpowiedzią. Wpisy pochodzą z klucza omits:, który autor zapisuje w encji Recipe lub FeatureRecipe (Recipe → Pole omits:); kompilator ewaluuje szablony każdego wpisu i przekazuje gościowi te, które mają zastosowanie. Następnie odczytuje liczby i tylko liczby — nigdy nie zagląda do zwróconego pliku, by je sprawdzić:
- Lista liczb, która nie zawiera jednej nieujemnej liczby na każdy przekazany wpis, zatrzymuje kompilację — gdy jej brak, jest za krótka, za długa lub zawiera liczbę mniejszą od zera — z podaniem węzła, dostawcy, liczby przekazanych wpisów i liczby zwróconych wartości. Raport, który się nie zgadza, nie pozwala ustalić, który wpis co pominął. Zob. A provider’s omitted counts do not match the omits entries it was handed (Liczby pominięć dostawcy nie odpowiadają przekazanym mu wpisom omits).
- Zero zatrzymuje kompilację, z podaniem pierwszego w kolejności autora wpisu o liczbie zero: węzła, dostawcy, pozycji wpisu na liście deklarowanej przez jego dokument oraz rodzaju, nazwy i przestrzeni nazw, do których został rozwiązany. Zero zgłasza gość; zatrzymanie należy do kompilatora. Zob. An omits entry left out nothing the source rendered (Wpis omits nie pominął niczego, co wyrenderowało źródło).
- Dokument deklarujący
omits:, którego dostawca nie deklarujeomits: true, jest odrzucany, zanim cokolwiek zostanie wyrenderowane, dzięki czemu autor od razu dowiaduje się, że klucz nie miałby żadnego skutku, zamiast znaleźć dokument na wyjściu. Kompilator odczytuje deklarację zdescribe(), gdy każda encja Recipe i FeatureRecipe w kompilacji jest już powiązana, i odrzuca przed wyrenderowaniem pierwszego komponentu — więc gość, który nie deklaruje klucza, nigdy nie otrzymuje wpisu. Odmowa podaje dostawcę i komponent, dla którego renderowany jest dokument, albo — w przypadku encji FeatureRecipe generowanej raz dla granicy — granicę i dołączenie. Zob. The provider does not support omits (Dostawca nie obsługuje omits).
Stan obecny: dostępne. Goście helm, compose i cloudformation dystrybuowani z kompilatorem deklarują tę możliwość i respektują wpisy. Gość helm nie zapisuje żadnego pola żadnego wpisu w zwracanym tekście. Goście compose i cloudformation podają rodzaj, nazwę i przestrzeń nazw wpisu, gdy go odrzucają, oraz jednostki pominięte przez wpis, gdy odrzucają plik lub szablon, który nadal je wskazuje, i wyświetlają tam każde pole oznaczonego wpisu jako <redacted>. Goście helm-chart i terraform nie deklarują tej możliwości, więc dokument deklarujący omits: renderowany przez któregoś z nich jest odrzucany.
Przyjmowanie plików, które Recipe wnosi do granicy
Niektóre pliki należą do granicy jako całości, a nie do jednego z jej komponentów — na przykład konfiguracja dostawcy, którą cel odczytuje raz dla wszystkiego, co granica wdraża. Recipe zapisuje je w spec.boundary.artifacts, a pracę wykonuje kompilator, nie gość: ewaluuje każdy plik względem kontekstu, względem którego ewaluowany jest wpis artifacts:, scala według nazwy pliki zadeklarowane przez wszystkich uczestników grupy dyspozycji i zapisuje każdy raz w katalogu zawierającym złożone wyjście grupy, obok tego, co zwraca assemble_boundary. Gość nie otrzymuje żadnego z tych plików w żadnym eksporcie i nigdy nie jest o nie pytany, więc nie ma nic do zaimplementowania — trzeba jedynie złożyć deklarację dotyczącą celu:
"contract": { "input_kinds": { "sourced": true, "artifacts_standalone": true }, "boundary_assembly": "nest", "boundary_artifacts": true}Należy deklarować boundary_artifacts: true tylko wtedy, gdy cel odczytuje plik umieszczony w tym katalogu jako część wyjścia granicy. Encja Plugin zapisuje tę samą deklarację jako spec.provider.contract.boundaryArtifacts; jeśli encja zawiera kontrakt zachowania renderowania, ładowanie odrzuca gościa, którego describe() zgłasza inną wartość. Recipe deklarujący ten blok, którego dostawca go nie deklaruje, jest odrzucany, zanim cokolwiek zostanie wyrenderowane, z podaniem dostawcy i komponentu; zob. The provider does not support boundary artifacts (Dostawca nie obsługuje artefaktów granicy). Plik, który jedno z tych scaleń umieszcza pod nazwą zapisywaną także przez złożenie, zatrzymuje kompilację jako two contributors writing one output path (dwóch uczestników zapisujących tę samą ścieżkę wyjściową), dlatego nazwy zapisywane przez złożenie należą do tego, co dokumentuje się dla autorów.
Stan obecny: dostępne. Gość terraform dystrybuowany z kompilatorem deklaruje tę możliwość, a Terraform odczytuje każdy plik obok głównej konfiguracji granicy; goście helm, compose, helm-chart i cloudformation jej nie deklarują.
Deklarowanie tego, czego ekosystem źródła nigdy nie dostarcza
Lokalny katalog źródłowy encji Recipe — współlokowany chart, moduł — jest publikowany razem z encją Recipe, a nie każdy plik w nim do niej należy. Gość dostawcy określa, czego jego własny ekosystem nigdy nie dostarcza, za pomocą source_ignore w swoim kontrakcie, jako reguły ignorowania w składni, której używa .gitignore:
"contract": { "input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false }, "boundary_assembly": "none", "source_ignore": { "patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"], "files": [".helmignore"] }}patternsto reguły odczytywane od katalogu głównego źródła, stosowane po kolei, przy czym późniejsze dopasowanie nadpisuje wcześniejsze.fileswskazuje pliki ignorowania, które dany ekosystem respektuje wewnątrz źródła. Gdziekolwiek przechodzenie źródła napotka taki plik, jego wiersze są odczytywane jako dodatkowe reguły dla katalogu, który go zawiera, po wzorcach gościa.
Deklaracja jest odczytywana, gdy encja jest przypinana, a nie gdy jest renderowana. Krok przypinania autora ustala plugin obsługujący zdolność encji w jego przestrzeni roboczej, składa reguły gościa z własnym .aggregaignore autora — którego wiersze są ostatnie, a więc wygrywają dla każdej ścieżki, którą wskazują — i zapisuje nazwę pluginu, bez wersji, wraz z dokładnymi złożonymi regułami, w pliku entity.lock encji. Każda późniejsza publikacja, porównanie i renderowanie tej encji stosuje zapisane reguły; host je dopasowuje i nie ma własnego zdania o żadnym ekosystemie. Zatem pliki przekazywane gościowi przy renderowaniu — listing oraz każdy plik, o którego spakowanie lub odczyt prosi hosta — to dokładnie te pliki, które zawiera publikacja encji, a na plik pominięty przez reguły pada odpowiedź, że go nie ma, z jego nazwą. Dowiązanie symboliczne w źródle jest odrzucane przed wywołaniem gościa.
Zgodność wynika z tego, co zostało zapisane. Gość może renderować encję Recipe opublikowaną dla jego zdolności, gdy posługuje się tą samą wersją ABI, jego kontrakt odpowiada deklaracji jego encji i nie potrzebuje żadnego pliku spoza opublikowanego zbioru. Gość, który potrzebuje pliku pominiętego w zbiorze, musi głośno zakończyć swoją kompilację błędem i wskazać ten plik — odmowa spakowania lub odczytu przez hosta podaje jego nazwę, a gość przenosi ją do własnego błędu. Gdy plugin, który przestrzeń robocza konsumenta wiąże dla danej zdolności, deklaruje reguły inne niż zapisane w pliku blokady encji, operacja pull konsumenta wypisuje ostrzeżenie wskazujące oba pluginy i różnicę; nigdy nie zatrzymuje się z tego powodu.
Pominięcie source_ignore nie deklaruje żadnych reguł, a renderowane źródło zachowuje wtedy każdy plik, który zachowują własne reguły autora. Pole jest opcjonalne i nie wymaga własnej wersji ABI: gość, który je pomija, ładuje się jak gość nic niedeklarujący. Encja Plugin zapisuje tę samą deklarację jako spec.provider.contract.sourceIgnore; jeśli to robi, ładowanie odrzuca gościa, którego describe() zgłasza coś innego.
Determinizm i ponowne użycie instancji
Host przyjmuje bajty wyjściowe gościa dosłownie, więc gość musi dawać identyczne wyjście z identycznego wejścia. Domyślnie gość jest ładowany od nowa dla każdego węzła — z założenia żaden stan nie przechodzi między węzłami. Gość, który sam deklaruje reusable_instance, jest natomiast ładowany raz na kompilację, a jego jedyna instancja obsługuje każde przejście, co eliminuje dominujący koszt instancjonowania na węzeł. Ponieważ ponowne użycie jest bezpieczne tylko dla gościa bezstanowego, aggrega build --verify-determinism renderuje każdy węzeł dwukrotnie przez tę samą instancję i zatrzymuje kompilację, jeśli dwa renderowania któregokolwiek węzła się różnią; domyślna kompilacja renderuje raz i ufa deklaracji. Pamięć podręczna kompilacji Wasm jest zapisywana na dysku i współdzielona w całym procesie, więc gość kompiluje się raz, a kolejne kompilacje pomijają ponowną kompilację.
Gniazdo lintera — linter publikacji
Gniazdo lintera jest dostarczane jako standardowy publishing-linter, bramka działająca poza głównym przebiegiem, uruchamiana przez aggrega lint, a nie w czasie kompilacji. Przyjmuje encję katalogu (a w trybie --pre-publish także aktualnie opublikowaną wersję encji) i zwraca listę ustaleń, każde z poziomem ważności i komunikatem; w trybie --pre-publish zwraca też klasyfikację podbicia wersji. Host wywołuje go przez wbudowane środowisko uruchomieniowe Wasm, za tą samą zaporą czystości AOT co każde inne gniazdo. Pełny zestaw reguł, poziomy ważności i wyłączenia poszczególnych reguł opisano w cli/aggrega-lint.md.
Linter to opcjonalna dyscyplina katalogu: kompilator nie uruchamia go podczas aggrega build (z jedynym wyjątkiem ostrzeżenia zniechęcającego do x-aggrega-*, które pojawia się z ważnością warn podczas kompilacji i z ważnością halt w aggrega lint --pre-publish). Ponieważ reguły znajdują się w pluginie, przedsiębiorstwo może skierować aggrega lint na inny plugin lintera, aby egzekwować własną dyscyplinę.
Żadna wartość parametru nie trafia do pluginu lintera, w żadnym zakresie, w którym działa aggrega lint. Zanim jakikolwiek dokument zostanie przekazany, host wstrzymuje wartości domyślne parametrów encji Aggregate, wartości, które przekazuje ona każdemu importowanemu modułowi, oraz parametry encji Release, zachowując kontrakt każdej deklaracji parametru — tylko klucze, którymi deklaracja jest zapisana, na każdym poziomie zagnieżdżenia — oraz każdy tekst szablonu, który odczytuje parametr: wartość parametru może sama być poświadczeniem, a dołączony tu plugin może być kodem, którego przestrzeń robocza nie napisała. To, co zawiera każdy dokument, opisano w What a linter plugin is handed (Co jest przekazywane pluginowi lintera).
Kodowanie przesyłu. Wejście i wyjście są przesyłane jako kanoniczny CBOR (RFC 8949 §4.2.1). Gość dekoduje wejście i koduje wyjście przez punkty wejścia, które już mają LinterInput i LinterOutput z jego zestawu — DecodeCBOR i EncodeCBOR w Go, decode_cbor i encode_cbor w Rust, decodeCBORLinterInput i encodeCBORLinterOutput w TypeScript — odczytując i zapisując bajty (Vec<u8> w Rust, Host.inputBytes() i Host.outputBytes(...) w TypeScript). Nie jest potrzebna żadna biblioteka CBOR i nic nie parsuje bajtów ręcznie. Dokumenty encji — proposed, previous, implemented_component i release — oraz każda wartość components są przesyłane jako bajty swoich dokumentów JSON, więc gość parsuje je jako JSON, aby zajrzeć do środka. components to mapa, którą schemat oznacza jako zachowującą kolejność, więc na wejściu reguły odczytującej całą encję Release jest przesyłana jako uporządkowana lista wpisów w kolejności, w jakiej encja Aggregate deklaruje swoje instancje komponentów, a gość odczytuje ją przez kontener zachowujący kolejność ze swojego zestawu. policies jest przesyłana jako mapa zawierająca tylko ustawione flagi, więc flaga, której nie zawiera, jest odczytywana jako fałsz, a każde ustalenie jest przesyłane we wspólnym kształcie Diagnostic. Odpowiedź, która nie jest LinterOutput w tym kodowaniu — zapisana jako JSON lub zawierająca pole najwyższego poziomu, którego kształt nie deklaruje — powoduje niepowodzenie lintowania ze wskazaniem wywołanego eksportu, zamiast zostać odczytana jako przebieg, który niczego nie znalazł. Przy bezpośrednim wywołaniu przez aggrega plugin run-local --export lint_rules linter otrzymuje autorski ładunek JSON przekonwertowany do tego kodowania, a jego odpowiedź jest odczytywana jako kształt wyniku eksportu i wypisywana jako JSON — odpowiedź, która nie ma tego kształtu, jest odrzucana ze wskazaniem eksportu, tak jak odrzuca ją kompilacja.
Stan obecny: dostępne. Publishing-linter jest dostarczany i uruchamiany przez hosta za pomocą aggrega lint.
Gniazdo parsera — wyjście w postaci drzewa kanonicznego
Parser przekształca źródło zapisane w formacie, którego kompilator nie odczytuje natywnie, w kanoniczne drzewo strukturalne, dzięki czemu konsument odczytuje drzewo zamiast utrzymywać własny parser. Host wyszukuje parser, który ogłasza żądany format jako parse:<format>, i wywołuje jego eksport parse w trzech miejscach: gdy polityka werdyktu renderowania otrzymuje wyrenderowany artefakt w formacie, którego nie odczytuje natywnie, gdy importer prosi hosta o drzewo przez aggrega_parse_source, oraz gdy rozpoznawany jest import, który nie wskazuje formatu (zob. gniazdo importera poniżej). Gość nigdy sam nie wywołuje parsera.
Kształt wejścia (host → gość). Dokument ParseInput zawierający:
format— żądany format, jedna z możliwościparse:<format>parsera bez prefiksu.bytes— bajty źródła.options— dokument opcji dostarczany przez konsumenta na potrzeby zachowania specyficznego dla parsera, przekazywany bez zmian. Nieobecny, gdy konsument żadnego nie dostarcza.
Kształt wyjścia (gość → host). Dokument ParseOutput zawierający tree — sparsowane źródło jako dokument JSON, którego najwyższy poziom może być obiektem, tablicą lub wartością skalarną — ewentualne diagnostyki we wspólnym kształcie Diagnostic, opcjonalne zakresy źródła lokalizujące węzły drzewa w oryginalnych bajtach oraz error opisujący niepowodzenie, gdy parsowanie nie mogło się zakończyć. Wszystkie pola i ich ograniczenia opisuje wygenerowana dokumentacja schematu gniazda parsera.
Kodowanie przesyłu. Wejście i wyjście są przesyłane jako kanoniczny CBOR (RFC 8949 §4.2.1), czyli w tym samym kodowaniu, w którym przesyłany jest ParseInput, gdy gość przekazuje go do aggrega_parse_source. Gość dekoduje wejście i koduje wyjście przez punkty wejścia, które ParseInput i ParseOutput jego zestawu już zapewniają — DecodeCBOR i EncodeCBOR w Go, decode_cbor i encode_cbor w Rust, decodeCBORParseInput i encodeCBORParseOutput w TypeScript — odczytując i zapisując bajty (Vec<u8> w Rust, Host.inputBytes() i Host.outputBytes(...) w TypeScript). Nie jest potrzebna żadna biblioteka CBOR i nic nie parsuje bajtów ręcznie. Bajty źródła są przesyłane jako surowy ciąg bajtów, a wygenerowany dekoder umieszcza je we własnym typie pola zestawu: wycinku bajtów w Go, łańcuchu base64 w Rust i TypeScript. options i tree są przesyłane jako bajty swoich dokumentów JSON, więc drzewo zapisane przez parser dociera do konsumenta bez zmian. Parser, który nie może zakończyć pracy, podaje przyczynę w polu error wyjścia, a parsowanie kończy się niepowodzeniem z podaniem nazwy parsera i tego komunikatu; odpowiedź, która nie jest ParseOutput w tym kodowaniu — zapisana jako JSON lub zawierająca pole najwyższego poziomu, którego kształt nie deklaruje — również powoduje niepowodzenie parsowania z podaniem nazwy parsera i jego eksportu parse. Nieudane parsowanie zatrzymuje budowanie w roli werdyktu renderowania, a do importera dociera jako niepowodzenie, którym odpowiada aggrega_parse_source. Tak samo jest ze źródłem odrzuconym przez parser — takim, na które odpowiada diagnostyką halt obok drzewa: wywołanie importera kończy się niepowodzeniem z komunikatem każdej takiej diagnostyki, w kolejności parsera, i nigdy nie otrzymuje drzewa. Wywołany bezpośrednio przez aggrega plugin run-local --export parse parser otrzymuje napisany ładunek JSON przekonwertowany do tego kodowania — ze źródłem zapisanym w tym ładunku jako base64, tak jak JSON zapisuje każde pole bajtowe — a jego odpowiedź jest odczytywana jako kształt wyniku eksportu i wypisywana jako JSON — odpowiedź, która nie ma tego kształtu, jest odrzucana ze wskazaniem eksportu, tak jak odrzuca ją kompilacja.
Definicje typów. Typy przesyłu parsera — ParseInput, ParseOutput, NodeSpan i SourceSpan — są publikowane we wszystkich trzech pakietach ABI i ponownie eksportowane przez zestaw do tworzenia wtyczek każdego języka, generowane z jednego kodeka, dzięki czemu wszystkie trzy pozostają zsynchronizowane. Przykład parse każdego zestawu odczytuje wejście i zapisuje wyjście w ten sposób, podobnie jak parsery HCL, TOML, YAML, JSON oraz JSON z komentarzami dostarczane w pliku binarnym.
Stan obecny: dostępne — wywoływane w roli werdyktu renderowania dla artefaktu w formacie, którego polityka nie odczytuje natywnie, przez aggrega_parse_source dla importera oraz do rozpoznawania formatu importu, który nie wskazuje żadnego.
Gniazdo importera — szkicowe pliki autorskie
Importer przekształca źródło napisane dla innego narzędzia — na przykład przepływ wyeksportowany z kreatora agentów — w szkicowe pliki autorskie Aggrega. Działa poza głównym procesem: aggrega import, metoda aggrega/import sesji edytora oraz narzędzie import przeznaczone dla asystenta wyszukują importer, który ogłasza żądany format jako import:<format>, i wywołują jego eksport import raz na import. Kompilacja nigdy go nie wywołuje. To, który importer zostaje uruchomiony i co przekazuje mu operator, opisano w sekcji Który importer przekształca źródło w szkice. Własne importery kompilatora, po jednym dla każdego odczytywanego formatu, opisano na stronie Importery podstawowe: jakie to formaty, co każdy z nich odczytuje, co szkicuje, jakie przyjmuje ustawienia, jak są publikowane z każdym wydaniem kompilatora oraz jak import pobiera i weryfikuje importer, którego maszyna jeszcze nie posiada.
Kształt wejścia (host → gość). Dokument ImportInput zawierający:
format— format, o który poprosił import, jedna z możliwościimport:<format>importera bez prefiksu.bytes— bajty źródła: cały plik w przypadku importu pliku i pusta wartość w przypadku importu katalogu, którego pliki trafiają dosources.name— nazwa źródła, bez poprzedzającego ją katalogu, aby importer mógł wskazać źródło w tym, co zgłasza, i w tym, co tworzy jako szkic: przy imporcie pliku nazwa bazowa pliku, z którego odczytanobytes; przy imporcie katalogu własna nazwa bazowa katalogu, odczytana z jego pełnej ścieżki, więcaggrega import .przekazuje nazwę katalogu, w którym jest uruchamiane, a pliki katalogu nadal przychodzą każdy pod własną nazwą. Nieobecne, gdy źródło nie ma nazwy do przekazania.sources— nazwane źródła, każde z nazwą i bajtami, na jednej liście posortowanej według nazwy: w przypadku importu katalogu każdy jego plik wybrany przez zadeklarowane wzorce plików importera, z pominięciem folderu wyników budowania obszaru roboczego, nazwany ścieżką rozdzielaną ukośnikami wewnątrz katalogu; oraz pliki, które wpisplugins.importerdołączający ten importer deklaruje wwith.sources, każdy pod swoją nazwą bazową. Plik katalogu i plik zwith.sourceso tej samej nazwie powodują odrzucenie importu, zamiast by jeden przesłaniał drugi. Pole nieobecne, gdy źródeł nie ma.settings— obiekt ustawień, który ten wpis deklaruje wwith.settings, jako dokument JSON z posortowanymi kluczami, przekazywany bez zmian. Pole nieobecne, gdy żaden wpis nie dołącza importera lub wpis ich nie deklaruje.catalog— widok encji Components przechowywanych we własnym katalogu obszaru roboczego: katalogu, z którego wybrano sam importer — folderów katalogu obszaru roboczego lub, jeśli obszar roboczy żadnego nie wskazuje, migawki katalogu publikowanej przez jego domyślny rejestr i przechowywanej na tej maszynie — bez pobierania czegokolwiek na potrzeby samego widoku. Jego listacomponentszawiera jeden wpis na nazwę encji Component, posortowany według nazwy; gdy katalog zawiera kilka wersji encji Component, wpis opisuje wersję, do której rozwiązuje się odwołanie podające jej nazwę bez wersji. Każdy wpis zawieranameiversionencji Component, jejlabels, nazwy kluczy najwyższego poziomu deklarowane przez jej values i provides (valuesiprovides, każde posortowane) oraz jejsockets— każde znamegniazda i selektorem etykietselector, który musi spełniać zależność podłączona przez to gniazdo — w kolejności, w jakiej deklaruje je encja Component. Encja Component rozszerzająca inną zawiera to, co dziedziczy, oraz to, co deklaruje, a dziedziczone gniazda występują jako pierwsze. Widok zawiera wyłącznie nazwy, wersje, etykiety i selektory — nigdy wartość, wartość domyślną ani sekret — a jego kolejność jest stała, więc jeden katalog daje jedną sekwencję bajtów. Pole nieobecne, gdy katalog nie zawiera żadnej encji Component.
Kształt wyjścia (gość → host). Dokument ImportOutput zawierający encje utworzone przez import — każda jest odwołaniem do istniejącej encji katalogu albo szkicową treścią — decyzje mapowania, które za nimi stoją, ewentualne diagnostyki we wspólnym kształcie Diagnostic, pliki szkieletu do zapisania oraz błąd error, gdy importu nie udało się ukończyć. Wszystkie pola i ich ograniczenia opisuje wygenerowana dokumentacja schematu gniazda importera.
Kodowanie przesyłowe. Zarówno wejście, jak i wyjście są przesyłane jako kanoniczny CBOR (RFC 8949 §4.2.1). Gość dekoduje wejście i koduje wyjście przez punkty wejścia, które mają już ImportInput i ImportOutput jego zestawu — DecodeCBOR i EncodeCBOR w Go, decode_cbor i encode_cbor w Rust, decodeCBORImportInput i encodeCBORImportOutput w TypeScript — odczytując i zapisując bajty (Vec<u8> w Rust, Host.inputBytes() i Host.outputBytes(...) w TypeScript). Nie jest potrzebna żadna biblioteka CBOR i nic nie parsuje bajtów ręcznie. settings przechodzi wewnątrz dokumentu binarnego jako bajty swojego dokumentu JSON, więc aby zajrzeć do środka, gość parsuje go jako JSON, jak w każdym innym gnieździe. Importer, który nie może ukończyć pracy, podaje przyczynę w error wyjścia, a import zostaje zatrzymany z nazwą importera i tym komunikatem; odpowiedź, która nie jest dokumentem ImportOutput w tym kodowaniu — zapisana jako JSON albo zawierająca pole najwyższego poziomu, którego kształt nie deklaruje — również zatrzymuje import, z nazwą importera i jego eksportu import. Importer wywołany bezpośrednio przez aggrega plugin run-local --export import otrzymuje napisany ładunek JSON przekonwertowany na to kodowanie, a jego odpowiedź jest odczytywana jako kształt wyniku eksportu i wypisywana jako JSON — odpowiedź, która nie ma tego kształtu, jest odrzucana ze wskazaniem eksportu, tak jak odrzuca ją kompilacja.
Jak rozpoznawane jest źródło w danym formacie. Import może nie podawać formatu; host rozpoznaje go wtedy na podstawie deklaracji importerów, sam nie znając żadnego formatu. Importer deklaruje w swoim raporcie describe(), w importer (ImporterContract), listę detect sygnatur, po których rozpoznaje się źródło w jego formatach. Każda sygnatura DetectSignature podaje:
syntax— format składniowy, w jakim parsowane jest źródło, czyli format ogłaszany przez plugin parsera jakoparse:<syntax>, np.jsonlubyaml;files— opcjonalne wzorce nazw plików dopasowywane do końca nazwy źródła: jeden segment do samej nazwy pliku, kilka segmentów rozdzielonych ukośnikami do tylu samo końcowych segmentów jego ścieżki, przy czym*,?i[...]dopasowują w obrębie segmentu. Sygnatura, która ich nie deklaruje, ma zastosowanie do źródła będącego jednym plikiem niezależnie od jego nazwy i do żadnego pliku katalogu;match— predykaty, które musi spełniać sparsowane drzewo, każdy jakoPathMatchze ścieżkąpathkluczy połączonych kropkami od wierzchołka drzewa (segment będący liczbą całkowitą wybiera pozycję w tablicy), polemiso wartościpresent,absent,object,array,string,numberlubbooleanoraz opcjonalnie ciągiemequalsalbo ciągiemprefix— co najwyżej jednym z nich.
Gdy import nie podaje formatu, host dopasowuje sygnatury każdego importera, spośród których import wybiera — tych z katalogu obszaru roboczego i importerów podstawowych kompilatora — w kolejności ich tożsamości i wersji: parsuje źródło parserem, który katalog udostępnia dla danej składni — lub, dla składni, dla której katalog nie udostępnia parsera, parserem wbudowanym w kompilator — co najwyżej raz na składnię, sprawdza predykaty na drzewie i odczytuje źródło jako format jedynego importera, którego sygnatura pasuje. Przez ten sam parser odpowiadane jest również wywołanie aggrega_parse_source importera, więc importer odczytuje źródło przez parser, za pomocą którego zostało rozpoznane. Źródło, które nie daje się sparsować w danej składni, nie pasuje do żadnej sygnatury ją podającej; składnia, dla której ani katalog, ani kompilator nie udostępnia parsera, przerywa rozpoznawanie ze wskazaniem braku parsera. Źródło, do którego nie pasuje żadna sygnatura, jest odrzucane z prośbą o podanie formatu, a źródło rozpoznane jako więcej niż jeden format jest odrzucane z wymienieniem tych formatów. Sygnatura rozpoznaje źródło jako każdy format ogłaszany przez jej importer, więc importer, którego źródła mają być rozpoznawane, obsługuje jeden format, a importer niedeklarujący żadnej sygnatury jest osiągalny tylko przez podanie jego formatu.
Encja Plugin importera zapisuje tę samą listę jako spec.importer.detect, wyprowadzoną z describe(), gdy encja jest generowana z gościa; rozpoznawanie odczytuje ten zapis, więc gość nie jest ładowany, dopóki jego format nie zostanie ustalony. Ładowanie i publikowanie gościa odrzuca takiego, którego raport różni się od zapisu w jego encji, wskazując importer.detect, a encja, która nie zapisuje żadnej listy, niczego nie deklaruje. Deskryptor jest odrzucany przy ładowaniu, gdy kontrakt jest zadeklarowany we wtyczce, która nie jest importerem, gdy sygnatura nie wskazuje składni lub wskazuje błędny wzorzec pliku oraz gdy predykat nie wskazuje ścieżki, wskazuje is spoza siedmiu wartości albo jednocześnie equals i prefix.
Importery podstawowe kompilatora oraz przykład import z zestawu dla Go deklarują swoje sygnatury w ten sposób. Importer Langflow odczytuje źródło jako JSON i wymaga tablicy w data.nodes; importer Flowise wymaga tablic w nodes i edges oraz braku czegokolwiek w data.nodes; importer n8n wymaga tablicy w nodes, obiektu w connections i braku czegokolwiek w edges oraz data.nodes; importer MCP deklaruje po jednej sygnaturze na konfigurację klienta, wskazując jej plik — .mcp.json, claude_desktop_config.json i .cursor/mcp.json, odczytywane jako JSON z obiektem w mcpServers, oraz .vscode/mcp.json, odczytywany jako JSON z komentarzami, tak jak odczytuje go Visual Studio Code, z obiektem w servers — oraz jedną niewskazującą pliku, która wymaga ciągu $schema zaczynającego się od https://static.modelcontextprotocol.io/schemas/; importer Compose odczytuje źródło jako YAML, wskazuje pliki, które Compose odczytuje domyślnie — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml i ich cztery pliki nadpisań — i wymaga obiektu w services; importer Dify odczytuje źródło jako YAML, nie wskazuje pliku i wymaga ciągu app w kind oraz czegokolwiek w app.mode i w version; importer CrewAI wskazuje config/agents.yaml i config/tasks.yaml, odczytywane jako YAML bez wymagań wobec drzewa, crew.jsonc i crew.json, odczytywane jako JSON z komentarzami z listą w agents, oraz agents/*.jsonc i agents/*.json, odczytywane jako JSON z komentarzami z czymkolwiek w role, tak że żadne dwie z nich nie pasują do jednego źródła, a plik importowany samodzielnie bez wskazania formatu jest odczytywany zarówno jako YAML, jak i jako JSON; importer LangGraph wskazuje langgraph.json, odczytywany jako JSON z obiektem w graphs, deklaruje jedną sygnaturę niewskazującą pliku, która wymaga obiektu w graphs i ciągu https://langgra.ph/schema.json w $schema, i nie wskazuje żadnego pliku środowiskowego, ponieważ rozpoznawanie odczytuje każdy plik wybrany przez wzorce dowolnego importera, więc wzorzec wskazujący taki plik otwierałby pliki środowiskowe każdego katalogu importowanego bez wskazania formatu; importer Google ADK wskazuje root_agent.yaml, odczytywany jako YAML z czymkolwiek w name i w instruction albo z ciągiem w agent_class i czymkolwiek w name, i nie wskazuje żadnego innego pliku, ponieważ konfiguracja podagenta może mieć dowolną nazwę, a wzorzec wskazujący każdy plik YAML otwierałby każdy taki plik w każdym katalogu importowanym bez wskazania formatu; importer Agent Framework odczytuje źródło jako YAML, nie wskazuje pliku i wymaga ciągu Prompt w kind oraz obiektu w model; przykład import z zestawu dla Go odczytuje źródło jako YAML i wymaga ciągu DemoSource w kind. W Go:
Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{ Syntax: "json", Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},}}},Co odczytuje import katalogu. Źródłem może być katalog, a o tym, co zostanie odczytane, decydują zadeklarowane wzorce plików importera: host odczytuje dokładnie te pliki katalogu, na dowolnej głębokości, które wybiera jeden ze wzorców files sygnatur importera — każdy dopasowywany do końca ścieżki pliku w katalogu, rozdzielanej ukośnikami — i przekazuje je jako sources w kolejności nazw, z pustym bytes i własną nazwą katalogu jako name. Żaden inny plik katalogu nie jest otwierany. Folder, do którego build obszaru roboczego zapisuje wyrenderowane pliki — dist/ pod katalogiem głównym obszaru roboczego — nie jest odczytywany jako część zawierającego go katalogu: żaden z jego plików nie jest przekazywany ani rozpoznawany, a dowiązanie prowadzące do niego jest pomijane, więc katalog, który został zbudowany, jest odczytywany jako projekt, który zawiera, natomiast katalog będący tym folderem lub leżący w nim jest odczytywany tak, jak go wskazano. Sygnatura bez wzorców files nie wybiera żadnego pliku katalogu, więc importer, który nie deklaruje żadnego wzorca, odczytuje jeden plik i odrzuca katalog; odrzucany jest też katalog, w którym nie ma pliku wybieranego przez wzorce. Import nie wychodzi poza katalog: dowiązanie wśród plików, które miałyby zostać odczytane, lub dowiązanie do katalogu, prowadzące poza katalog, jest odrzucane, zanim cokolwiek zostanie odczytane, do dowiązania do katalogu nigdy się nie wchodzi, a dowiązanie do pliku niewybieranego przez żaden wzorzec jest pomijane bez odczytu. Rozpoznawanie formatu katalogu podlega tej samej zasadzie — każda sygnatura jest sprawdzana względem plików wybieranych przez jej wzorce, w kolejności nazw, każdy plik jest odczytywany i parsowany najwyżej raz na składnię, a sygnatura bez wzorców nie dotyczy żadnego z nich. Host niczego nie ogranicza: katalog zbyt duży dla importera odrzucają własne limity środowiska wykonawczego importera. Żaden z importerów kompilatora Langflow, Flowise, n8n, Dify i Agent Framework nie deklaruje wzorców files, więc każdy odczytuje jeden plik; jego importer MCP deklaruje nazwy czterech konfiguracji klientów, więc odczytuje każdą z nich, która znajduje się w katalogu, jego importer Compose deklaruje osiem nazw plików Compose, więc otrzymuje każdy plik Compose z katalogu i scala te, które odczytałby Compose; jego importer CrewAI deklaruje sześć nazw, pod którymi zapisywane są deklaracje projektu CrewAI, więc otrzymuje deklaracje projektu, a nic z jego programu; jego importer LangGraph deklaruje langgraph.json, więc otrzymuje konfigurację aplikacji, a nic z jej kodu ani plików środowiskowych — plik środowiskowy trafia do niego tylko przez with.sources jego dołączenia; a jego importer Google ADK deklaruje root_agent.yaml, więc otrzymuje konfigurację głównego agenta aplikacji, a nic z jej kodu ani pliku środowiskowego — konfiguracje wskazywane przez jej podagentów trafiają do niego tylko przez with.sources jego dołączenia.
Definicje typów. Typy przesyłane przez importer — ImportInput, ImportSource, CatalogProjection, CatalogComponent, CatalogSocket, ImportOutput oraz przenoszone przez niego kształty encji, decyzji i szkieletów — są publikowane we wszystkich trzech pakietach ABI i ponownie eksportowane przez zestaw do tworzenia wtyczek każdego języka, generowane z jednego kodeka, dzięki czemu te trzy pozostają ze sobą zgodne; to samo dotyczy typów rozpoznawania ImporterContract, DetectSignature i PathMatch, przenoszonych przez raport describe. Pakiet importera zestawu dla Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer, zawiera wszystko, co robi importer niezależnie od formatu, a importery podstawowe kompilatora, wszystkie na nim zbudowane, w ten sposób odczytują wejście i zapisują wyjście.
Względem czego ocenia importer zbudowany na zestawie dla Go. Mechanizm oceny zestawu porównuje każdy węzeł źródła z encjami Components z widoku catalog i z niczym więcej: kandydatami jest własny katalog przestrzeni roboczej — encje Components katalogu przedsiębiorstwa na równi z tymi z biblioteki standardowej — a zestaw nie zawiera żadnego własnego kandydata. Z każdej encji Component odczytuje nazwę, kategorię zapisaną w jej etykiecie component.aggrega.ai/category, jej etykiety oraz nazwy kluczy deklarowanych przez jej values; jej klucze provides i gniazda nie są brane pod uwagę. Encja Component dodana do katalogu jest kandydatem przy następnym imporcie, bez przebudowywania importera. Gdy widoku brak, ponieważ katalog nie zawiera żadnej encji Component, żaden węzeł nie ma kandydata: żaden nie jest wskazywany ani podpowiadany, a każdy węzeł, któremu szkic nadaje własną encję Component, jest szkicowany. Tak ocenia każdy importer korzystający z zestawu — w tym importery kompilatora Langflow, Flowise, n8n i Compose, podczas gdy jego importer MCP nie bierze pod uwagę żadnego kandydata; importer, który nie korzysta z zestawu, odczytuje widok w dowolny wybrany przez siebie sposób.
Do czego importer zbudowany na zestawie Go odczytuje sockety platformy. Sockety nie mają żadnej wagi w ocenie, ale zestaw odczytuje je, aby rozplanować szkic. Format, którego przepływy platforma uruchamia w postaci, w jakiej zostały zapisane — jak w przypadku Langflow, Flowise i n8n — jest domyślnie szkicowany jako jedna instancja encji Component tej platformy niosąca przepływ, a każda część przepływu jest podłączana do pierwszego socketu, w kolejności, w jakiej wpis catalog platformy wymienia swoje sockets, którego selector jest spełniany przez etykiety encji Component tej części, w postaci, w jakiej widok niesie te etykiety. Odczytywane są tylko selektor i etykiety, a selektor jest dopasowywany przez funkcję dostarczaną przez importer, ponieważ zestaw nie ma własnej gramatyki selektorów; jeśli widok nie zawiera encji Component o nazwie platformy, żadna część nie zostaje podłączona. Importery podstawowe opisują szkic, który w ten sposób tworzą importery Langflow, Flowise i n8n kompilatora, oraz ustawienie layout, które zamiast tego szkicuje każdy węzeł jako osobną encję Component.
Stan obecny: dostępne — wywoływane przez aggrega import oraz przez tę samą operację w sesji edytora i w narzędziu przeznaczonym dla asystenta.
Kryterium umiejscowienia: gniazdo lintera a role werdyktu zarządzania
Dwa z udokumentowanych gniazd mają podobny interfejs — oba emitują wyniki dla poszczególnych reguł — ale różnią się umiejscowieniem w potoku i semantyką blokowania. Kryterium decydujące, które gniazdo obsługuje daną kontrolę:
- Role werdyktu zarządzania (w paśmie, zatrzymujące kompilację). Zarezerwowane dla polityk zatrzymujących kompilację: werdykt
haltzatrzymuje potok kompilacji, a kompilacja nie generuje żadnych artefaktów. Przypadki użycia to polityki, których naruszenie sprawia, że zastosowanie wyniku jest niebezpieczne: bramki zgodności (umiejscowienie granic PCI / SOC2), niezmienniki topologii (ruch przychodzący zero-trust, uwierzytelnianie między granicami), kształt przepływu poświadczeń (brak sekretów w postaci jawnego tekstu w IR) itd. Polityka analizuje graf IR (ir-verdict, przed renderowaniem) lub wyrenderowane artefakty (render-verdict, po renderowaniu). - Gniazdo lintera (poza pasmem, CI / IDE, doradczo). Zarezerwowane dla kontroli dobrych praktyk i wykrywalności: reguł, których naruszenie jest podejrzane, ale nie niebezpieczne — osierocone sekrety, nieużywane parametry, przestarzałe słownictwo etykiet, kompletność tagów na potrzeby przypisywania kosztów, odchylenia od konwencji nazewnictwa. Niepowodzenie generuje wynik doradczy; kompilacja nadal generuje artefakty.
Kryterium umiejscowienia ujęte w jednej regule: jeśli kontrola ma zatrzymać kompilację, należy ją umieścić w roli werdyktu zarządzania; jeśli kontrola ma ostrzec autora lub recenzenta bez blokowania potoku, należy ją umieścić w gnieździe lintera.
Oba są dziś dostępne. Gniazdo lintera uruchamia linter publikacji za pomocą aggrega lint; role werdyktu zarządzania są wywoływane w paśmie podczas aggrega build, gdy obszar roboczy dołącza wtyczkę roli werdyktu. Należy pamiętać, że rola werdyktu ma własne poziomy ważności — polityka może sama emitować werdykty warn i info, które doradzają bez zatrzymywania — więc powyższa granica między zatrzymaniem a doradzaniem jest wskazówką dotyczącą umiejscowienia całych kontroli, a nie twierdzeniem, że polityka może jedynie zatrzymywać. Model poziomów ważności opisuje strona gniazda zarządzania.
Odsyłacze
policy-socket.md— wyczerpujące omówienie gniazda zarządzania: cztery role, poziomy ważności werdyktów, kanał wejściowy operatora, pisanie polityki dla jednego z dwóch silników dostarczanych wewnątrz kompilatora, opakowywanie zewnętrznego silnika polityk oraz referencyjni goście.core-importers.md— własne importery kompilatora, po jednym dla każdego odczytywanego przez niego formatu: co każdy z nich odczytuje, ich ustawienia oraz ich publikacja z każdym wydaniem kompilatora.10-status.md#compilation-pipeline-phases— klasyfikacja potoku wtyczek na stronie statusu (gotowość środowiska uruchomieniowego potoku wtyczek Wasm).architecture/04-entity-taxonomy.md§„Domain 3: Infrastructure Base” — zasada Two-Part Plugin Principle dla encji FeatureRecipes poświadczeń (wzorzec Fetcher + Injector).architecture/13-catalog-and-registry.md— taksonomia OCI, która zaczyna się od segmentu dostawcy.entities/featurerecipe.md— powierzchnia tworzeniapipeline:w encji FeatureRecipe.when-to-use-a-pipeline-step.md— przewodnik decyzyjny: krok potoku a szablonowa encja FeatureRecipe.templates/expansion-matrix.md— reguły ewaluacji szablonów w blokupipeline:with:potoku wtyczek oraz semantyka dostępu.steps.examples/04-secrets.md— kształt potoku Fetcher + Injector, jaki może przyjąć encja FeatureRecipe poświadczeń.errors/error-translation.md— dyscyplina tłumaczenia błędów, w której uczestniczą goście wtyczek.