Przewodnik dla twórców wtyczek Wasm
To jest kanoniczny przewodnik po tworzeniu wtyczki WebAssembly (Wasm) dla Aggrega i publikowaniu jej jako encji katalogu. Przedstawia od początku do końca kontrakt autora wtyczki: czym jest wtyczka, jak wtyczka opisuje się hostowi, jak tworzyć jej eksporty i deklaracje możliwości, jakie limity środowiska uruchomieniowego i funkcje hosta stosuje host, czym jest encja Plugin, która wprowadza wtyczkę do katalogu, jak encja Recipe lub FeatureRecipe odwołuje się do wtyczki, oraz cykl życia publikacja→pobranie→budowanie, który prowadzi wtyczkę od pliku .wasm na dysku do zweryfikowanego, przypiętego skrótem artefaktu, z którego korzysta budowanie.
Strona towarzysząca plugin-contract.md dokumentuje gniazda — punkty potoku, do których podłączają się wtyczki, oraz kształty wejścia i wyjścia, które każde gniazdo przyjmuje i zwraca. Ten przewodnik dokumentuje wtyczkę — encję, zakres możliwości i cykl życia. Ze strony kontraktu można się dowiedzieć, do którego gniazda jest kierowana wtyczka; z tej strony — jak ją stworzyć i dostarczyć.
Jeśli zamiast opisu referencyjnego potrzebna jest przećwiczona ścieżka przez całe zadanie, strona tworzenie dostawcy buduje od początku do końca jednego małego gościa dostawcy — deskryptor, kompilację, encję, podłączenie i renderowanie, którego wynik można przeczytać — łącznie z odmową, na którą zwykle trafia pierwsza wersja, i sposobem jej odczytania.
1. Czym jest plugin Wasm
Plugin Wasm to moduł WebAssembly, który rozszerza kompilator w wyznaczonym gnieździe. Binarny plik hosta w Go nie zawiera żadnej logiki specyficznej dla chmury ani infrastruktury; cała wiedza dziedzinowa — renderowanie szablonów, translacja formatów, ewaluacja polityk, linting — znajduje się w pluginach. Host orkiestruje potok i przekazuje ładunek każdego gniazda przez granicę ABI do gościa; gość wykonuje pracę dziedzinową i zwraca wynik o kształcie właściwym dla danego gniazda. Ładunek i wynik każdego gniazda są przesyłane jako kanoniczny CBOR, z dwoma wyjątkami: plugin CLI otrzymuje wektor argumentów jako tekst JSON i odpowiada kodem wyjścia oraz strumieniowanym tekstem, a samoopis describe jest tekstem JSON. Sekcja każdego gniazda w kontrakcie pluginów podaje jego kodowanie, a gość odczytuje je i zapisuje przez punkty wejścia, które typ ładunku jego zestawu już udostępnia, więc żaden gość nie parsuje bajtów ręcznie.
Plugin działa za zaporą czystości AOT (ahead-of-time). Host ładuje i wykonuje moduł przez wbudowane środowisko uruchomieniowe Wasm w konfiguracji odbierającej uprawnienia: bez gniazd sieciowych, bez systemu plików, bez zmiennych środowiskowych, z odrzucanym stdio i z obserwowalnym zegarem zamrożonym w chwili niezmiennej dla kompilacji. Każde wywołanie wejścia/wyjścia, którego spróbuje gość, kończy się niepowodzeniem na granicy wywołania, więc plugin nie może sięgać po stan czasu wykonania. Pluginy należy tworzyć z myślą o tej zaporze: plugin przekształca przekazany mu ładunek i zwraca wynik, który host przyjmuje dosłownie, a za determinizm odpowiada autor — identyczne wejście musi dawać identyczne bajty wyjściowe. Jedynym dopuszczonym kanałem dla treści zdalnych jest pośredniczone przez hosta pobieranie danych zewnętrznych (sekcja 4), które dostarcza bajty w trybie przypięcia do skrótu, zamiast dawać gościowi bezpośredni dostęp do sieci.
Gniazda, do których może być skierowany plugin — wśród nich bramka mutacji przy budowie topologii, bramka walidacji przy analizie statycznej, potok FeatureRecipe, linter działający poza głównym przebiegiem oraz gniazdo renderowania dostawcy — oraz kształty wejścia/wyjścia każdego gniazda są opisane w plugin-contract.md. Gniazdo, które obsługuje plugin, to jedyna wartość deklarowana przez niego w metadata.pluginType, a pełny zbiór wartości akceptowanych przez to pole podaje dotyczący go wpis referencyjny w entities/plugin.md §„metadata.pluginType”. Przykłady w tym przewodniku używają provider (renderuje węzły IR do artefaktów natywnych dla dostawcy), linter (analizuje utworzoną treść i zgłasza diagnostyki) oraz pipeline-step (krok w pipeline: encji FeatureRecipe lub Recipe, który nakłada poprawki na wyrenderowany zbiór dokumentów).
Gościa tworzy się względem hosta za pomocą trójjęzycznego zestawu do tworzenia pluginów (PDK) — w Go, Rust lub TypeScript. PDK opakowuje bazowy łańcuch narzędzi Wasm builderami z typami Aggrega dla kształtów wejścia i wyjścia, które przenosi każde gniazdo.
2. Samoopis describe()
Każda wtyczka eksportuje funkcję describe(), która zwraca samoopis wtyczki: implementowane typy gniazd, docelową wersję ABI, deklarowane możliwości — odczytywane zgodnie z typem gniazda, czyli nazwy możliwości w przypadku providera lub kroku potoku oraz formaty źródłowe z prefiksem w przypadku parsera lub importera — importowane funkcje hosta oraz możliwość każdego oferowanego punktu wejścia, określaną osobno dla każdego eksportu. describe() to własny opis wtyczki: czym jest i co robi.
Samoopis jest punktem zaczepienia modelu zaufania. Encja Plugin, która wprowadza wtyczkę do katalogu (sekcja 5), powtarza te same fakty jako deklaracje autora, a host porównuje deklaracje encji z wynikiem describe() wtyczki w dwóch momentach — przy publikacji, zanim jakiekolwiek bajty trafią do rejestru, oraz przy ładowaniu, zanim wtyczka zostanie uruchomiona. Niezgodność powoduje głośne zatrzymanie. Encja jest czytelną dla człowieka powierzchnią widoczną w katalogu; describe() jest wiążącym źródłem maszynowym, względem którego host ją weryfikuje. Należy przygotować obie tak, aby były zgodne; porównanie istnieje właśnie po to, aby wychwycić przypadek, w którym się rozejdą. Sprawdza ono to, co encja deklaruje, a nie to, co pomija: encja deklarująca mniej, niż zgłasza plik binarny — na przykład pozostawiona po przebudowie, która dodała eksport — nadal się ładuje, choć nie opisuje już wszystkiego, co robi plik binarny.
3. Tworzenie eksportów i deklarowanie ich możliwości
Plugin udostępnia jeden lub więcej eksportów — nazwanych punktów wejścia, do których host kieruje wywołania (na przykład render_node, lint_naming, step). Każdy eksport zawiera blok możliwości: deklarację autora, co dany eksport robi. Możliwość eksportu ma cztery pola:
name— nazwa eksportu w ABI, czyli nazwa, do której host kieruje wywołania. Wymagane.operates— operacja potoku wykonywana przez eksport:patch(modyfikacja istniejącego wyrenderowanego dokumentu) lubemit(dodanie nowego dokumentu). Jest to zadeklarowana możliwość. Host porównuje ją z raportemdescribe()pluginu podczas publikacji i podczas ładowania, więc deklaracja zapisana w encji i opis podany przez sam plugin muszą być zgodne. Jest to weryfikowana deklaracja dotycząca eksportu, a nie przełącznik wywołań: w czasie renderowania operację, którą krok faktycznie wykonuje, określa wynik zwrócony przez gościa, a nie wartość tego pola. Brak pola oznacza brak deklaracji operacji.scope— korzeń dokumentów, na którym działa eksport:own(własne wyrenderowane dokumenty węzła) lubhost(dokumenty komponentu, do którego dołączona jest encja FeatureRecipe o zakresie komponentu). Przed uruchomieniem pluginu kroku potoku host odczytuje zadeklarowany zakres eksportu kroku i wymusza, aby provider renderujący dokumenty tego zakresu występował wspec.pipelineStep.capabilitiespluginu (sekcja 5) — eksport o zakresieownjest sprawdzany względem providera renderującego własne dokumenty węzła, eksport o zakresiehostwzględem providera komponentu hosta, a pusty zakres na potrzeby tego sprawdzenia przyjmuje domyślnieown. Jest to bramka zgodności providera, uruchamiana przed krokiem; dokument, którego faktycznie dotyczy operacja gościa, jest wskazywany dla każdej operacji w wyniku zwróconym przez gościa, a nie wybierany na podstawie tego zadeklarowanego pola. Brak pola oznacza domyślnieown.selector— dowolny, czytelny dla człowieka opis tego, na czym działa eksport (na przykładworkloads carrying a pod template). Służy jako dokumentacja dla czytelników katalogu i waggrega inspect; kompilator go nie interpretuje.
Eksporty należy zapisywać w kolejności, w jakiej mają być czytane; wpisy zachowują kolejność autora w encji i w inspect. Plugin bez zapisanych eksportów nie deklaruje żadnej powierzchni eksportów — jest to poprawne dla pluginu, którego gniazdo nie wymaga deklaracji możliwości dla poszczególnych eksportów.
4. Limity środowiska uruchomieniowego i funkcje hosta
Encja wtyczki może zawierać opcjonalny blok runtime, który ogranicza sposób, w jaki host ładuje i uruchamia wtyczkę.
Limity pamięci i czasu. maxMemoryPages ogranicza pamięć liniową wtyczki w stronach Wasm (64 KiB na stronę); timeoutMs ogranicza, jak długo własny kod wtyczki może działać podczas jednego wywołania, w milisekundach. Czas spędzony w funkcjach hosta wywoływanych przez wtyczkę nie wlicza się do tego limitu. W systemie Linux miarą jest czas procesora wątku wykonującego kod gościa, więc czas, w którym gość czeka na procesor na obciążonej maszynie, również się nie wlicza; w innych systemach jest to czas rzeczywisty. Pierwsze wywołanie świeżo załadowanej wtyczki obejmuje także jednorazową inicjalizację środowiska uruchomieniowego języka gościa, która odbywa się w ramach tego wywołania. Oba limity są opcjonalne i mają wartości domyślne: zero lub brak wartości oznacza domyślny limit platformy. Program ładujący ogranicza każdą wtyczkę domyślnym limitem platformy, gdy encja nie deklaruje żadnego, więc ładowanie nigdy nie jest nieograniczone, a wywołania zawsze można przerwać. Limit w encji należy podnieść, gdy dołączenie rzeczywiście potrzebuje więcej pamięci lub czasu, niż pozwala wartość domyślna.
Funkcje hosta. hostFunctions rejestruje nazwy funkcji hosta importowanych przez wtyczkę. Jest to pole wyprowadzane maszynowo — nie należy go tworzyć ręcznie. aggrega plugin sync odczytuje funkcje hosta bezpośrednio z sekcji importów pliku .wasm i automatycznie zapisuje to pole w pliku encji, a publikacja ponownie wyprowadza je z pliku binarnego i odrzuca encję, której zapis się różni; dzięki temu wtyczka otrzymuje dokładnie te funkcje hosta, które jej plik binarny faktycznie importuje, sprawdzone względem starannie dobranej listy dozwolonych (import spoza tej listy jest jawnie odrzucany). Zapis jest migawką opublikowanego pliku binarnego, tak samo jak adresowane treścią odwołanie plugin: jest migawką opublikowanych bajtów: odzwierciedla plik binarny w chwili publikacji i jest ponownie wyprowadzany oraz weryfikowany przy pobieraniu wtyczki. Aby przed publikacją zobaczyć funkcje hosta importowane przez lokalny plik .wasm — wartość, którą zapisuje aggrega plugin sync — należy uruchomić aggrega inspect --plugin <file.wasm>.
Starannie dobrany zestaw funkcji hosta. Trzy funkcje hosta mają charakter ogólny: aggrega_log (poziom i komunikat, emitowane jako jeden wiersz dziennika w miejscu docelowym dziennika hosta), aggrega_emit_warning (kod, komunikat i ścieżka, gromadzone jako ustrukturyzowane ostrzeżenie, które host udostępnia po wywołaniu) oraz aggrega_fetch_external_input (adres URL, na który odpowiedzią są bajty wejścia zgodnie z opisaną niżej dyscypliną przypinania). PDK opakowuje wszystkie trzy w każdym języku — Go: aggrega.Log, aggrega.EmitWarning, aggrega.FetchExternalInput; Rust: log, emit_warning, fetch_external_input; TypeScript: log, emitWarning, fetchExternalInput — dzięki czemu gość wywołuje typowaną funkcję zamiast surowego ABI. Wywołania zwrotne źródła i parsowania — dla gościa, który odczytuje fragmenty pozyskanego źródła lub uzyskuje sparsowane drzewo za pośrednictwem hosta — oraz kodowanie przenoszone przez sloty każdego wywołania zwrotnego są opisane w plugin-contract.md.
Lokalna treść źródłowa przychodzi przez hosta — nigdy z systemu plików. Wtyczka renderująca dostawcy nigdy nie odczytuje źródła z dysku; wywołanie systemu plików kończy się błędem na granicy wywołania. Host przekazuje gościowi w ładunku renderowania listing źródła — ścieżkę każdego wpisu względem katalogu głównego źródła oraz informację, czy jest katalogiem, w posortowanej kolejności, bez treści plików — a gość stosuje do niego własną logikę układu, a następnie odczytuje dokładnie wybrane przez siebie pliki przez wywołania zwrotne źródła, które zwracają bajty odczytane przez hosta spod katalogu głównego źródła. Kształty ładunków dla poszczególnych gniazd oraz wywołania zwrotne są opisane w plugin-contract.md.
Zdalna treść przychodzi przez pobieranie wejścia zewnętrznego. Wtyczka, która potrzebuje zdalnej treści — archiwum chartu, zdalnego dokumentu schematu — wywołuje opakowanie pobierania z PDK. Na poziomie protokołu gość przekazuje adres URL do aggrega_fetch_external_input jako tekst UTF-8 i otrzymuje jedną odpowiedź w kanonicznym CBOR, zawierającą albo pobrane bajty w surowej postaci, albo komunikat o błędzie wraz z kodem nadającym się do dopasowania maszynowego; opakowanie dekoduje odpowiedź do postaci bajty-lub-błąd. Bajty docierają dokładnie w takiej postaci, w jakiej zostały pobrane, łącznie z ładunkiem, który nie jest poprawnym UTF-8, a ładunek o zerowej długości wraca jako puste bajty, a nie błąd. Host obsługuje adres URL zgodnie z dyscypliną przypinania wejść zewnętrznych:
- Adres URL już przypięty w pliku blokady encji Release jest obsługiwany z lokalnego magazynu adresowanego treścią i przy każdym odczycie weryfikowany względem zapisanego skrótu. Brakujący obiekt w magazynie jest uzupełniany z sieci na podstawie zapisanego skrótu — uzupełnienie zweryfikowane skrótem nie może zmienić wyniku.
- Nieprzypięty adres URL jest odrzucany z błędem, który podaje adres URL i sposób naprawy. Kompilacja renderuje domknięcie zapisane w jej pliku blokady, więc żadna kompilacja nie pobiera nieprzypiętego odwołania i nie istnieje ustawienie, które by to umożliwiało.
- Przypinanie następuje podczas rozwiązywania zależności encji Release:
aggrega pullrenderuje Release, aby ustalić, jakich wejść zewnętrznych żąda jego renderowanie, pobiera każde z nich i zapisuje je w pliku blokady obok przypięć zależności. Cykl pracy autora wtyczki wygląda więc tak: jednorazowe rozwiązanie, a potem dowolnie częste kompilacje offline.
Dozwolone schematy to https, http wyłącznie do hostów pętli zwrotnej oraz oci (przypinany skrótem manifestu). Plik blokady zapisuje każde przypięte wejście — jego adres URL, skrót sha256, rozmiar oraz wtyczki, które go wymagały — więc ponowna kompilacja obsługuje te same bajty z lokalnego magazynu: powtarzalnie i offline po przypięciu.
Z PDK dla Go:
import "github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega"
chart, err := aggrega.FetchExternalInput("https://charts.example.com/postgresql-16.3.2.tgz")if err != nil { // The error names the URL and the remedy — an unpinned URL reports exactly // what to pin and how. Surface it as a render failure; do not mask it. return fmt.Errorf("fetching chart archive: %w", err)}Co kończy się błędem i dlaczego.
- Wywołanie systemu plików lub sieci kończy się błędem na granicy wywołania: gość nie ma żadnych wstępnie otwartych katalogów ani gniazd. Dotyczy to każdej ścieżki kodu, łącznie z zależnością biblioteczną, która próbuje odczytać plik — zamiast tego należy odczytywać źródło przez wywołania zwrotne źródła.
- Import z modułu spoza
wasi_snapshot_preview1,extism:host/enviextism:host/userkończy się błędem przy ładowaniu, z diagnostyką podającą moduł i import. Poszczególne nazwy funkcji WASI w dozwolonym module nigdy nie są cenzurowane — nieużywane importy systemu plików i gniazd statycznie linkowanego środowiska uruchomieniowego języka są w porządku, ponieważ samo nazwanie importu niczego nie przyznaje. - Pobranie adresu URL, którego plik blokady nie przypina, kończy się błędem podającym ten adres URL; rozwiązaniem jest uruchomienie
aggrega pull --release <release>, które przypina każde wejście zewnętrzne zużywane przez renderowanie encji Release, a następnie kompilacja.
Nie istnieje pole listy dozwolonych hostów dla wychodzącego dostępu do sieci. Wtyczka nigdy nie sięga do sieci w czasie kompilacji — to jest granica kompilacji z wyprzedzeniem — więc takiego pola nie ma do wypełnienia. Zdalna treść przychodzi przez opisany wyżej kanał wejść zewnętrznych, pośredniczony przez hosta i przypięty skrótami, nigdy przez bezpośredni dostęp do sieci.
Konfiguracja. configKV to mapa ciągów na ciągi, którą środowisko uruchomieniowe przekazuje wtyczce przy starcie. Wpisy zachowują kolejność nadaną przez autora, dzięki czemu emitowany rekord jest identyczny bajt po bajcie między uruchomieniami. Brak wartości pozostawia w mocy domyślną pustą konfigurację środowiska uruchomieniowego.
5. Encja Plugin
Plugin trafia do katalogu jako encja Plugin — powierzchnia tworzenia i metadanych pluginu. Encja deklaruje, czym jest plugin, i wskazuje artefakt .wasm; kompilator nie interpretuje zachowania pluginu i przekazuje dalej przypiętą referencję, a bajty wykonuje środowisko uruchomieniowe Wasm.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: aws-secrets-manager version: 1.2.0 pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: capabilities: - helm - compose signature: type: sigstore-cosign runtime: maxMemoryPages: 256 timeoutMs: 5000 # hostFunctions is recorded by `aggrega plugin sync` from the .wasm — do not author it. exports: - name: fetch operates: emit scope: own selector: external-secret resources for the bound credentialPola:
- Celowo brak pola lokalizacji artefaktu. Encja nie zawiera wskaźnika do pliku
.wasm, a schemat go nie przyjmuje. Lokalizacja artefaktu pluginu jest wyprowadzana z jego tożsamości — współrzędnejmetadata.pluginType/metadata.name, która tworzy ścieżkę repozytoriumplugin/<pluginType>/<name>— oraz z rejestru, względem którego skonfigurowano przestrzeń roboczą, więc nie ma lokalizacji do zapisania ani do pomylenia. Rozwiązany skrót treści jest zapisywany dla każdej encji Release w jej pliku blokady, a kompilacja weryfikuje względem niego pobrane bajty: tożsamość w encji, zweryfikowane bajty w pliku blokady. metadata.version— wydanie, które publikuje encja; musi być równe wersji pochodzenia kompilacji samego gościa, zgłaszanej wdescribe(). Autor pluginu nadaje wersję plikowi.wasmw czasie kompilacji — kompilacja wpisuje wersję do gościa, a kompilacja, która pobiera ją z tagu wydania, wpisuje wersję wydania tylko w commicie wskazanym przez ten tag — ametadata.versionencji wskazuje to samo wydanie. Etap publikacji porównuje obie wartości i zatrzymuje się przy rozbieżności, więc encja zawsze wskazuje dokładną wersję dostarczanego pliku binarnego.aggrega plugin gen-catalog --plugin(poniżej) kopiuje wersję zgłaszaną przez gościa do generowanej encji; jest to wersja wydania, gdy gościa zbudowano z otagowanego commita. Wymagane.metadata.pluginType— typ gniazda implementowany przez plugin, jeden z:provider,linter,pipeline-step,governance,cli,parseriimporter. Plugin implementuje dokładnie jeden. Znajduje się w bloku adresowania oboknameiversioni dostarcza segment<pluginType>wyprowadzonej współrzędnej. Wymagane.spec.abiVersion— wersja ABI host/gość, na którą celuje plugin. Akceptowaną wartością jestv1beta1; przyszła rewizja ABI doda kolejną akceptowaną wartość. Wymagane.- Blok dla danego typu gniazda, zawierający
capabilities— plugin deklaruje, co obsługuje, wewnątrz bloku należącego do jegometadata.pluginType, i to blok ustala znaczenie wpisu.spec.provider.capabilitieswymienia możliwości obsługiwane przez dostawcę (nazwy możliwości, takie jakhelmlubcompose).spec.pipelineStep.capabilitieswymienia dostawców, z których wyrenderowanymi danymi wyjściowymi zgodny jest dany krok.spec.parser.capabilitieswymienia formaty źródłowe odczytywane przez parser, każdy zapisany jakoparse:<format>.spec.importer.capabilitieswymienia obce formaty, z których importer tworzy szkice encji, każdy zapisany jakoimport:<format>. Importer napisany w Go może przejąć wszystko, co nie zależy od jego formatu — ocenianie, decyzję o referencji lub szkicu, szkice i ich renderowanie oraz swoje ustawienia — z pakietu importera zestawu Go,github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Plugin typulinter,governancelubclinie obsługuje żadnej możliwości i nie zawiera żadnego z czterech bloków. Wpisy zachowują kolejność autora, a każda lista jest jawną, przetestowaną deklaracją: należy deklarować to, względem czego plugin faktycznie zbudowano i przetestowano, ponieważ konsument rozwiązuje dokładnie względem tego, co wymieniono. W przypadku kroku potoku ta deklaracja jest egzekwowana podczas renderowania — gdy krok dotyka zakresu, kompilacja zatrzymuje się, chyba że dostawca renderujący dokumenty tego zakresu należy do deklarowanych przez plugin — więc pusta lista nie pasuje do żadnego dostawcy i nigdzie nie dopuszcza kroku. spec.signature— opcjonalny opisowy wskaźnik do dołączonego podpisu pluginu (sekcja 8). Ten blok służy wyłącznie dokumentacji: zapisuje dla czytelników katalogu, gdzie znajduje się podpis i jak go utworzono; sam nie dopuszcza pluginu. Kontrolą egzekwującą jest polityka zaufania danego rejestru stosowana przy pobieraniu.spec.runtime— opcjonalny blok ograniczeń wykonania z sekcji 4. Autor zapisujemaxMemoryPages,timeoutMsiconfigKV;hostFunctionsjest wyprowadzane maszynowo i zapisywane przezaggrega plugin sync, a publikacja je weryfikuje — nie pisze go autor.spec.exports— deklaracje możliwości poszczególnych eksportów z sekcji 3 (name,operates,scope,selector).
Generowanie encji z pliku .wasm. Nie trzeba ręcznie pisać części encji należących do maszyny. aggrega plugin gen-catalog --plugin <file.wasm> odczytuje samoopis gościa describe() i na jego podstawie tworzy gotową do publikacji encję Plugin oraz niewielką, dostarczoną przez autora nakładkę (tożsamość, limity wykonania i ewentualny blok dostawcy). Generator wpisuje pola, dla których źródłem prawdy jest plik binarny — deklaracje eksportów, kontrakt możliwości, odwzorowanie poleceń i rekord funkcji hosta — i kopiuje metadata.version z wersji pochodzenia kompilacji zgłaszanej przez describe() gościa, a nakładka dostarcza tylko to, czego plik binarny nie zgłasza. Jest to wspierana ścieżka dla zewnętrznego autora pluginu: zbudować plik .wasm i nadać mu wersję, a następnie ponownie wygenerować encję, aby jej pola należące do maszyny pozostawały zgodne z plikiem binarnym. Wersja jest jedynym kopiowanym polem, które wskazuje wydanie, a nie fakt dotyczący bajtów, dlatego należy generować z kompilacji commita wskazanego przez tag wydania — lub, wychodząc od kompilacji deweloperskiej, ustawić metadata.version na wydanie w wygenerowanej encji przed otagowaniem commita, który ją zawiera. Z gościa bez wersji pochodzenia kompilacji nie można wygenerować encji z wersją — najpierw należy nadać gościowi wersję w czasie kompilacji.
Plik .wasm obok swojej encji. Podczas pisania pluginu nie ma jeszcze nic opublikowanego, co kompilacja mogłaby pobrać, więc kompilacja czyta plik .wasm pluginu obok jego encji Plugin w folderze katalogu, pod nazwą wyprowadzoną z typu pluginu i nazwy encji: dla pipeline-step/patch jest to pipeline-step--patch.wasm. Małe litery, cyfry i większość łączników są zapisywane w tej nazwie bez zmian; każdy inny znak jest zapisywany w postaci zakodowanej, podobnie jak łącznik na kilku pozycjach — dlatego tam, gdzie ma to znaczenie, odmowa z powodu brakującego pliku .wasm, A plugin’s .wasm is not on this machine (Moduł pluginu nie znajduje się na tej maszynie), podaje pełną nazwę. aggrega lint <plugin.yaml> czyta plik .wasm z tego samego miejsca — obok przekazanego pliku encji, w jakimkolwiek folderze ten plik się znajduje — chyba że plik binarny sam zawiera plugin, i wypisuje uwagę dla każdego eksportu, możliwości lub kontraktu, który plik .wasm zgłasza, a który encja pomija. Jeśli nie ma tam pliku .wasm, lint informuje, że pominął ten raport, podając plik, którego szukał, i folder, a jego wynik się nie zmienia.
Opis poszczególnych pól zawiera strona encji ../entities/plugin.md.
6. Odwoływanie się do pluginu
Krok potoku lub gniazdo pluginu odwołuje się do pluginu przez jego URI encji Plugin — tożsamość encji, a nie bezpośrednio artefakt .wasm. Encja jest warstwą, która niesie przypięty skrót, deklaracje możliwości, limity wykonania i podpis; odwołanie się do encji to sposób, w jaki konsument otrzymuje to wszystko.
Sama ścieżka .wasm lub surowe odwołanie do artefaktu pozostawione w polu plugin jest odrzucane przy ładowaniu: nie pasuje do niego żadna encja Plugin, więc rozwiązywanie pluginu kończy się wyraźnym błędem. URI encji jest obowiązkowe — pośrednictwo przez encję jest kontraktem, a nie opcjonalnym udogodnieniem. Krok potoku encji FeatureRecipe wskazuje encję w pipeline[].plugin; opis sposobu definiowania potoku zawiera ../entities/featurerecipe.md.
Gdy dwa lub więcej pluginów jest ze sobą sprzężonych — muszą uzgodnić wspólny kontrakt przekazania danych, jak w parze Fetcher i Injector, w której wyjście jednego pluginu jest wejściem drugiego (zasada Two-Part Plugin Principle opisana w plugin-contract.md) — należy zdefiniować ten kontrakt raz i sprawić, by każdy plugin zależał od tej jednej definicji, zamiast niezależnie powtarzać kształt przekazywanego JSON w każdym pluginie. Wspólny kształt to struktura JSON wymieniana przez pluginy, która może znajdować się w jednym wpisie SchemaLibrary, do którego odwołują się oba pluginy. Jedno źródło kontraktu utrzymuje sprzężone pluginy w zgodzie w miarę jego ewolucji; niezależne powtórzenia rozjeżdżają się, a rozbieżność ujawnia się dopiero wtedy, gdy oba pluginy przestają być ze sobą zgodne w czasie wykonania. Zaleca się współdzielenie kontraktu, a nie kodu Wasm — każdy plugin pozostaje osobnym artefaktem.
7. Cykl życia publish → pull → build
Plugin przechodzi od pliku .wasm na dysku do zweryfikowanego artefaktu gotowego do użycia w buildzie przez trzy etapy.
Publikacja. aggrega push publikuje encję Plugin i jej .wasm razem jako pojedynczy manifest OCI, oznaczony tagiem według metadata.version: YAML encji jest blobem konfiguracji manifestu, a .wasm stanowi warstwę tego samego manifestu. To publikacja pary jako jednego otagowanego manifestu sprawia, że push jest atomowy — nie istnieje okno, w którym jedna połowa jest opublikowana, a druga nie — i dlatego jeden podpis tego manifestu obejmuje obie połowy. Obie połowy są nazwane w manifeście, więc ogólny klient OCI pobierający tag wersji zapisuje encję do entity.yaml, a plik wykonywalny do entity.wasm.
Zanim jakiekolwiek bajty trafią do rejestru, publikacja przeprowadza swoje kontrole. Encja jest najpierw odczytywana względem schematu Plugin, tak jak odczytuje ją ładowanie katalogu, więc metadata.version, który nie jest wersją semantyczną — lub jakiekolwiek inne odstępstwo od schematu — zostaje odrzucony, zanim .wasm zostanie odczytany. Następnie .wasm jest ładowany, a jego samoopis describe() jest porównywany z zadeklarowanymi w encji deklaracjami możliwości — niezgodność głośno przerywa działanie, więc opublikowana encja nigdy nie deklaruje niczego, czego nie zgłasza dostarczany przez nią plugin. Gość, którego wersja pochodzenia buildu w describe() zawiera znacznik -dirty, nadawany buildowi z drzewa roboczego z niezatwierdzonymi zmianami, zostaje odrzucony: ta wersja wskazuje commit, który nie zawiera tego, co zostało zbudowane. Wersja deweloperska zbudowana z commita (1.0.0-3-g1a2b3c4) i wersja przedpremierowa (1.0.0-rc.1) są publikowane. Zapisany metadata.version jest porównywany z wersją pochodzenia buildu w describe() gościa, a rozbieżność przerywa publikację, więc obie muszą być zgodne. Obie odmowy usuwa się w ten sam sposób: należy zbudować plugin z czystego checkoutu commita wskazanego przez tag wydania, tak aby zgłaszał samą wersję wydania — w przypadku nowego wydania należy najpierw zatwierdzić encję wraz z wydawanym kodem źródłowym i otagować ten commit. Skopiowanie do encji wersji zgłaszanej przez build deweloperski nie jest naprawą: publikuje ono ten build pod wersją, której nie wskazuje żaden tag wydania. Funkcje hosta importowane przez .wasm są wyprowadzane z pliku binarnego i porównywane z zapisem zatwierdzonym w spec.runtime.hostFunctions; rozbieżność przerywa publikację i wskazuje aggrega plugin sync, które ponownie zapisuje to pole, ponieważ pole jest zarządzane maszynowo, a publikacja nigdy nie nadpisuje zatwierdzonego pliku encji. Opublikowana encja zawiera ostemplowany zapis funkcji hosta; skrót treści .wasm jest właściwością manifestu, jako który para jest publikowana, i jest zapisywany dla konsumenta w pliku blokady encji Release, a nie w encji.
Pobranie. aggrega pull rozwiązuje wszystkie zależności encji Release i zapisuje plik blokady dla każdej encji Release, przypinający każdą encję katalogu i każdy zdalny artefakt do wersji i skrótu treści. Opublikowana encja Plugin jest rozwiązywana w ramach tego rozwiązywania zależności; jej .wasm jest pobierany wraz z manifestem, który go zawiera, a bajty są weryfikowane względem skrótu treści zapisanego w pliku blokady. Pobranie ponownie wyprowadza też funkcje hosta ze zweryfikowanego .wasm i sprawdza je względem ostemplowanego zapisu hostFunctions, przerywając działanie, jeśli są niezgodne — to dodatkowa warstwa ochrony ponad przypięciem skrótu, wychwytująca plik binarny, którego stempel nie powstał z jego własnych importów. Jeśli polityka zaufania rejestru wymaga podpisów, podpis encji jest na tym etapie pobierany, weryfikowany i zapisywany w pliku blokady jako zweryfikowany fakt (sekcja 8). Weryfikacja odbywa się przy pobraniu, nigdy przy buildzie — build pozostaje czysto ahead-of-time.
Build. aggrega build używa przypiętego, zweryfikowanego pluginu z rozwiązanych zależności. Kompilator przekazuje referencję przypiętą skrótem, a środowisko uruchomieniowe Wasm wykonuje bajty; bramka ładowania ponownie przeprowadza porównanie describe() oraz egzekwowanie funkcji hosta i limitów uruchomieniowych, zanim plugin zostanie uruchomiony.
8. Podpisywanie i zaufanie
Encja Plugin jest podpisywana dokładnie tak samo jak każda inna encja katalogu: podpisywany jest skrót (digest) manifestu, a podpis jest dołączany jako OCI referrer. Artefakt .wasm nie jest podpisywany osobno i nie potrzebuje osobnego podpisu — jest warstwą tego samego manifestu, którego skrót jest podpisany, więc podpis obejmuje go bezpośrednio: ingerencja w .wasm zmienia skrót manifestu i unieważnia podpis.
Podpisywanie przy publikacji jest opcjonalne; weryfikację przy pobieraniu (pull) wymusza polityka zaufania danego rejestru. Rejestr skonfigurowany tak, by wymagał podpisów, przerywa pobieranie, gdy wymaganego podpisu brakuje, jest on niezaufany lub nieprawidłowy. Blok spec.signature w encji jest wskaźnikiem dokumentacyjnym, który mówi, gdzie znajduje się podpis i jak został wytworzony; zapisuje fakty dla czytelników katalogu i sam nie decyduje o dopuszczeniu. Bramką jest polityka stosowana w chwili pobierania.
Polecenia i ich flagi są opisane razem z interfejsami publikowania i pobierania — zob. ../cli/aggrega-sign.md, ../cli/aggrega-push.md oraz ../cli/aggrega-pull.md. Ten przewodnik nie powtarza tabel flag; te strony są jedynym miejscem opisu interfejsu poleceń.
9. Wersjonowanie encji
Encja Plugin ma w metadata.version ścisłą wersję semantyczną (Semantic Version). Opublikowana wersja jest niezmienna: ponowna publikacja wersji, która już istnieje w rejestrze, z inną zawartością jest odrzucana na etapie kontroli publikacji.
Po zmianie encji pluginu i ponownej publikacji dyscyplina publikowania klasyfikuje zmianę względem poprzednio opublikowanej wersji i wymaga, aby podbicie wersji jej odpowiadało. Klasyfikację określa rubryka podbijania wersji: zmiana dotycząca wyłącznie dokumentacji lub komentarzy to PATCH; zmiana ściśle addytywna (nowe pole opcjonalne, nowy wpis) to MINOR; usunięcie, zawężenie typu lub przekształcenie wcześniej opcjonalnego pola w wymagane to MAJOR. Podbicie wersji ponad wymagany poziom jest zawsze dozwolone; zbyt małe podbicie kończy się zatrzymaniem z diagnostyką wskazującą wymagane podbicie. Pierwsza publikacja encji pomija sprawdzenie podbicia i zgłasza ostrzeżenie, że nie przeprowadzono weryfikacji. Sprawdzenie można uruchomić przed publikacją poleceniem aggrega lint --pre-publish; pełną rubrykę i ustawienia poszczególnych reguł opisuje ../cli/aggrega-lint.md.
Encja Plugin nie ma mechanizmu extends, więc reguły dziedziczenia obowiązujące encje Components i Features w katalogu jej nie dotyczą. Dyscypliną wersjonowania obowiązującą encję pluginu są rubryka podbijania wersji i niezmienność.
10. Odsyłacze
authoring-a-provider-walkthrough.md— jeden gość dostawcy zbudowany od początku do końca, od pustego katalogu do wyrenderowanego wyniku.plugin-contract.md— punkty gniazd, na które celuje wtyczka, oraz kształty wejścia/wyjścia dla poszczególnych gniazd.policy-socket.md— szczegółowy opis gniazda zarządzania: jego 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 oraz referencyjni goście polityk.core-importers.md— własne importery kompilatora, po jednym dla każdego odczytywanego przez niego formatu, zbudowane na pakiecie importera z zestawu Go: co każdy z nich odczytuje, ich ustawienia oraz ich publikacja z każdym wydaniem kompilatora.../compatibility.md— jak wersjonowane są zestawy do tworzenia pluginów i co sprawia, że plugin zbudowany dla jednego wydania nadal ładuje się w następnym.../entities/plugin.md— dokumentacja encjiPluginpole po polu.../entities/featurerecipe.md— powierzchnia tworzeniapipeline:encji FeatureRecipe, która odwołuje się do wtyczki przez URI encji.../cli/aggrega-lint.md— linter publikacji, rubryka podbijania wersji oraz egzekwowanie niezmienności.../cli/aggrega-inspect.md— sprawdzanie możliwości, limitów środowiska uruchomieniowego i podpisu encjiPlugin.../cli/aggrega-push.md,../cli/aggrega-pull.md,../cli/aggrega-sign.md— polecenia do publikowania, pobierania i podpisywania.