Plugin
Plugin to adresowany treścią plugin WebAssembly: artefakt .wasm hostowany w OCI, przypięty skrótem sha256, deklarujący implementowany typ gniazda, docelową wersję ABI, opcjonalny wskaźnik podpisu oraz opcjonalny blok środowiska uruchomieniowego. Encja jest powierzchnią autorską i metadanych pluginu; rozwiązywanie zależności przypina artefakt skrótem, a polityka zaufania danego rejestru weryfikuje jego podpis przy pobieraniu. Kompilator nie interpretuje zachowania pluginu — przekazuje przypiętą referencję; środowisko uruchomieniowe WebAssembly wykonuje bajty.
Ta strona omawia powierzchnię autorską katalogu Plugin pole po polu. Pełny przepływ pracy autora — czym jest plugin, samoopis describe(), cykl życia publikacja→pobranie→budowanie, podpisywanie i wersjonowanie — opisano w przewodniku dla twórców pluginów Wasm. Punkty gniazd, do których dołącza się plugin, oraz kształty ich wejść i wyjść opisano w kontrakcie pluginów Wasm.
Rola encji Plugin
Encja Plugin wiąże logiczną tożsamość pluginu z konkretnym artefaktem .wasm oraz z metadanymi możliwości i środowiska uruchomieniowego, których host potrzebuje, aby bezpiecznie go załadować i uruchomić. Krok potoku lub gniazdo pluginu odwołuje się do encji przez jej URI; encja przechowuje zadeklarowane możliwości, limity środowiska uruchomieniowego i wskaźnik podpisu, natomiast rozwiązany skrót zawartości znajduje się w pliku blokady wydania. Lokalizacja .wasm jest wyprowadzana z tożsamości pluginu — adresowalnej współrzędnej plugin/<pluginType>/<name>, złożonej z metadata.pluginType i samej metadata.name, oraz ze skonfigurowanego rejestru — i nie jest polem definiowanym przez autora. Pośrednictwo encji jest obowiązkowe — samo odwołanie do .wasm lub do artefaktu jest odrzucane przy ładowaniu, ponieważ nie pasuje do niego żadna encja.
Deklaracje encji Plugin są pogrupowane według typu gniazda i od tego pogrupowania zaczyna się czytanie encji:
- Jeden blok na typ gniazda —
spec.provider,spec.pipelineStep,spec.parser,spec.importer. Plugin zawiera ten jeden blok, który wskazuje jegometadata.pluginType, a każdy blok zawiera listęcapabilities:— zapisaną przezaggrega plugin gen-catalogna podstawie własnegodescribe()pluginu — której znaczenie należy wyłącznie do tego bloku: lista providera wymienia możliwości, które obsługuje, lista kroku potoku wymienia możliwości providera, z którymi jego krok jest zgodny, a listy parsera i importera wymieniają formaty źródłowe, zapisywane jakoparse:<format>iimport:<format>. Znaczenie niesie zawieranie — do wpisu możliwości nie można dotrzeć bez uprzedniego odczytania bloku, który mówi, jakiego rodzaju jest to deklaracja. - Blok providera zawiera więcej niż listę —
spec.providerdeklaruje też, jak plugin tłumaczy rodzaj Workload, które natywne adnotacje platformy odczytuje oraz swój kontrakt zachowania renderowania (spec.provider.contract: rodzaje wejścia, składanie granic, ograniczniki artefaktów, ponowne użycie instancji). Opisują one zachowanie renderowania, a nie obsługiwany wymiar, dlatego znajdują się obok listy możliwości providera, a nie w niej. - Gniazdo przekrojowe nie deklaruje możliwości — plugin typu
linter,governancelubclinie zawiera żadnego z czterech bloków, ponieważ nie obsługuje żadnego wymiaru renderowania ani formatu źródłowego.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: aws-secrets-manager version: 1.2.0 pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: # capabilities is recorded by `aggrega plugin gen-catalog` from the plugin's describe(); an author may narrow it. 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 credentialmetadata
Standardowe metadane katalogu. Pola name, version i pluginType są wymagane; version to ścisła wersja semantyczna (np. 1.2.0). Pola opcjonalne — description, maintainers, license, repository, home, keywords — mają ten sam kształt, jaki ma każda encja katalogu, a metadata nie przyjmuje żadnego innego klucza. Opublikowana wersja jest niezmienna: ponowna publikacja istniejącej wersji jest odrzucana na etapie publikacji.
metadata.name jest samą nazwą — nie zawiera prefiksu gniazda. Adresowalna współrzędna pluginu plugin/<pluginType>/<name> jest wyprowadzana z metadata.pluginType i samej nazwy z metadata.name; nie wpisuje się jej do nazwy.
metadata.pluginType
Typ gniazda, który implementuje ten plugin. Znajduje się w bloku adresowania obok name i version, ponieważ stanowi część tożsamości pluginu: dostarcza segment <pluginType> wyprowadzanej współrzędnej plugin/<pluginType>/<name>. Plugin implementuje dokładnie jeden typ gniazda, wybrany z taksonomii typów pluginów rozpoznawanej przez środowisko uruchomieniowe:
provider— renderuje węzły IR do artefaktów natywnych dla dostawcy.linter— analizuje utworzoną treść i zgłasza diagnostyki.pipeline-step— krok wpipeline:encji FeatureRecipe lub Recipe, który nakłada poprawki na zbiór wyrenderowanych dokumentów.governance— pełni role nadzoru w potoku budowania. Podczas konstruowania topologii automatycznie nadaje etykiety węzłom grafu topologii, zwracając dokumenty JSON Patch, które host stosuje do projekcji grafu zawierającej wyłącznie etykiety. Na etapie analizy statycznej lub renderowania ocenia graf IR lub wyrenderowane artefakty i zwraca werdykt akceptacji lub odrzucenia; niespełniona reguła zatrzymuje budowanie. To, co może emitować, określa rola, do której jest dołączony, a nie jego rodzaj.parser— parsuje obcy format źródłowy (HCL, TOML, YAML, JSON, …) do ustrukturyzowanego drzewa JSON, dzięki czemu konsument, który musi odczytać format nieparsowany natywnie przez kompilator, pracuje na sparsowanym drzewie zamiast na surowym tekście.importer— przekształca obce źródło definicji infrastruktury lub agentów w robocze pliki autorskie Aggrega, ogłaszając obsługiwane formaty jako możliwościimport:<format>.cli— dodaje uruchomieniowe podpolecenieaggrega <cmd>, które operator wywołuje z wiersza poleceń. Jest to gniazdo czasu uruchomienia, odrębne od gniazd renderowania i potoku działających w czasie kompilacji.
Wymagane.
spec.abiVersion
Wersja ABI host/guest, na którą jest przeznaczony plugin. Akceptowaną wartością jest v1beta1; nowa rewizja ABI dodaje kolejną. Wymagane.
Deklarowanie możliwości: jeden blok na typ gniazda
Możliwość (capability) to to, o co konsument prosi plugin — możliwość renderowania, której żąda encja Recipe, lub format źródłowy, który kompilacja musi odczytać. Możliwości pluginu są zapisywane w bloku należącym do jego typu gniazda, więc to, w którym bloku znajduje się lista, określa znaczenie jej wpisów:
metadata.pluginType | Gdzie deklarowane są jego możliwości | Co nazywa wpis |
|---|---|---|
provider | spec.provider.capabilities | Możliwość renderowania obsługiwana przez ten plugin, np. helm lub compose. |
pipeline-step | spec.pipelineStep.capabilities | Provider, z którego renderowanym wynikiem zgodny jest krok tego pluginu. |
parser | spec.parser.capabilities | Format źródłowy odczytywany przez ten plugin, zapisywany jako parse:<format>. |
importer | spec.importer.capabilities | Obcy format źródłowy, z którego ten plugin tworzy szkice encji, zapisywany jako import:<format>. |
linter, governance, cli | — | Nic. Te gniazda nie obsługują żadnej możliwości, więc nie zawierają żadnego z czterech bloków. |
Plugin implementuje dokładnie jeden typ gniazda, więc jego encja zawiera jeden blok. Lista jest własnym raportem pluginu: aggrega plugin gen-catalog odczytuje describe() pluginu i zapisuje w bloku każdą zgłoszoną przez niego możliwość. Autor może przed publikacją zawęzić listę, pomijając możliwość zgłaszaną przez plugin, której opublikowana encja nie powinna oferować; aggrega validate <entity> --plugin <file.wasm> i aggrega push akceptują zawężoną listę i wypisują komunikat wskazujący każdą możliwość zgłaszaną przez plugin, którą lista pomija. Żadne z nich nie akceptuje listy wskazującej możliwość, której plugin nie zgłasza: oba ją odrzucają, wskazując każdą taką możliwość oraz możliwości, które plugin faktycznie zgłasza, więc opublikowana lista nigdy nie oferuje więcej, niż zapewnia plugin. Encja pipeline-step, której plugin zgłasza helm i helm-chart, a która wymienia także compose, jest odrzucana w ten sposób:
[E0080] entity "probe-step:1.0.0-rc.1" lists capabilities ["compose"], which the plugin's describe() does not report (it reports ["helm" "helm-chart"]); remove them from the list, which may name only capabilities the plugin reports: wasm: entity contract claim does not match plugin describe()Konsument rozwiązuje dokładnie względem tego, co jest wymienione.
spec.provider
Blok gniazda dostawcy dla wtyczki pluginType: provider: obsługiwane przez nią możliwości, sposób, w jaki tłumaczy należący do platformy rodzaj Workload aggrega.ai/v1beta1, które natywne adnotacje platformy odczytuje oraz jej kontrakt zachowania renderowania. Blok występuje w każdej wtyczce renderującej jako dostawca i nie występuje w żadnym innym typie wtyczki. Dostawca, który renderuje wyłącznie treść pozyskaną ze źródła lub treść artefaktów, bez syntezy encji Workload, również zawiera ten blok — deklaruje w nim swoje możliwości i swój kontrakt, a po prostu pomija workloadSchema.
spec.provider.capabilities
Możliwości obsługiwane przez tego dostawcę — nazwy możliwości, takie jak helm lub compose — których kształt wyjścia renderuje. Dostawca jest uniwersalny w obrębie artefaktów współdzielących kształt wyjścia danej możliwości, a nie w obrębie wszystkich możliwości, dlatego lista wymienia możliwości zgłaszane przez sam plugin: aggrega plugin gen-catalog zapisuje ją na podstawie describe() pluginu, a autor może ją zawęzić przed publikacją. Wpisy zachowują kolejność, w jakiej zostały zapisane.
Żądany przez encję Recipe cel dostawcy (spec.capability: helm) jest rozwiązywany do wtyczki dostawcy, której lista zawiera ten cel. Gdy ten sam cel wymienia więcej niż jedna wtyczka dostawcy, wybiera przestrzeń robocza: wybór plugins.providers w konfiguracji przestrzeni roboczej wskazuje, której wtyczki użyć; jest on rozwiązywany podczas aggrega pull i zapisywany w pliku blokady. Przy braku wyboru i dokładnie jednym kandydacie używany jest ten kandydat; przy braku wyboru i więcej niż jednym kandydacie kompilacja zostaje zatrzymana i wymienia wszystkich kandydatów. Niejednoznaczność jest rozstrzygana w każdej przestrzeni roboczej w miejscu użycia, a nie przez regułę unikalności obejmującą cały katalog. Pusta lub nieobecna lista nie deklaruje żadnej możliwości, więc wtyczka nie obsługuje żadnego celu.
Nazwa możliwości nie zawiera tu dwukropka. Wartość spec.capability encji Recipe jest odczytywana jako możliwość do ostatniego dwukropka i przypięta wersja po nim, więc o nazwę zawierającą dwukropek nigdy nie dałoby się poprosić; wtyczka, której describe() zgłasza taką nazwę, jest odrzucana przy ładowaniu i nie jest z niej generowana żadna encja do publikacji. To samo dotyczy możliwości dostawców wymienianych przez wtyczkę pipeline-step. Dwukropek w parse:<format> parsera i import:<format> importera jest częścią tych nazw i pozostaje.
spec.provider.workloadSchema
Deklaracja JSON Schema 2020-12 dokumentująca, jak ten dostawca tłumaczy rodzaj Workload aggrega.ai/v1beta1 na natywne manifesty dostawcy. Zgodnie z konwencją deklaruje ją dostawca, który wykonuje syntezę: taki dostawca deklaruje workloadSchema jako udokumentowany kontrakt tłumaczenia, opisujący, które pola encji Workload dostawca wykorzystuje, jakie zamknięte zbiory akceptuje każde pole o kształcie wyliczenia i jakie ograniczenia zakresu obowiązują.
Treść jest kompilowana do JSON Schema 2020-12 przy ładowaniu encji Plugin — jest to strukturalne zabezpieczenie, które odrzuca błędnie sformułowany schemat przy ładowaniu, a nie przy renderowaniu. O tym, czy encja Recipe workload: jest obsługiwana, decyduje zdolność syntezy powiązanego dostawcy, a nie obecność tego pola: encja Recipe w trybie syntezy powiązana z dostawcą, który nie potrafi syntezować, zatrzymuje się z wyraźnym błędem w czasie renderowania. Katalog biblioteki standardowej utrzymuje workloadSchema w zgodności z możliwościami dostawcy. Pole jest udokumentowanym kontraktem; nic innego go nie odczytuje. Same treści encji Workload są walidowane względem należącego do platformy wbudowanego schematu Workload, a nie względem tego pola specyficznego dla dostawcy.
spec.provider.wellKnownAnnotations
Uporządkowana tablica wyliczająca natywne dla platformy klucze dobrze znanych adnotacji — należące do zarezerwowanej przestrzeni nazw aggrega.ai/ — które ten dostawca odczytuje, wraz z zachowaniem stosowanym, gdy danej adnotacji brak. Każdy wpis zawiera key (adnotację odczytywaną przez dostawcę, np. aggrega.ai/namespace), purpose (co adnotacja kontroluje, gdy jest obecna), opcjonalne defaultBehavior (co robi dostawca, gdy adnotacji brak) oraz opcjonalne scope wymieniające, gdzie dostawca odczytuje klucz — sourced, synthesized lub artifactsStandalone, czyli rodzaje wejścia encji Recipe, albo boundary dla klucza odczytywanego raz na granicę. key i purpose są wymagane; wpisy zachowują kolejność nadaną przez autora.
Pole jest deklaracją wsparcia dostawcy, a kompilator odczytuje je na dwa sposoby. Wpis, którego scope wskazuje rodzaj wejścia nieobjęty deklaracją własnego contract.inputKinds bloku, przeczy tej deklaracji, więc encja Plugin jest odrzucana ze wskazaniem klucza i zakresu. Ponadto gdy kompilacja renderuje przez tego dostawcę, adnotacja aggrega.ai/, której żaden wpis nie obejmuje dla żadnego rodzaju wejścia deklarowanego przez renderowanie, powoduje ostrzeżenie wskazujące klucz, dostawcę i te rodzaje wejścia; wartość nadal przechodzi bez zmian, a kompilacja się nie zatrzymuje. Gdy pola brak, nie stanowi ono żadnej deklaracji i dla tego dostawcy nie jest zgłaszane żadne takie ostrzeżenie. Walidacja schematu sprawdza jedynie kształt każdego wpisu (klucz należy do przestrzeni nazw aggrega.ai/, purpose jest obecne); jest ona odrębna od sprawdzenia w czasie wykonania, które reguluje wiązanie wartości w zarezerwowanej przestrzeni nazw.
metadata: pluginType: providerspec: abiVersion: v1beta1 provider: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm workloadSchema: | # how the Workload kind translates to this provider's native output ... wellKnownAnnotations: - key: aggrega.ai/namespace purpose: Overrides the target namespace the provider renders into. defaultBehavior: Renders into the boundary's default namespace.Zestawy adnotacji poszczególnych dostawców oraz treść workloadSchema dostarczane przez dostawców biblioteki standardowej są udokumentowane w ../providers/well-known-annotations.md, ../providers/helm.md, ../providers/helm-chart.md i ../providers/compose.md.
spec.provider.readsNoWellKnownAnnotations
Deklaruje, że ten dostawca nie odczytuje żadnego z natywnych dla platformy, dobrze znanych kluczy adnotacji. Jest to deklaracja wsparcia nieobejmująca żadnego klucza i mówi coś, czego nie mówi pominięcie zarówno jej, jak i wellKnownAnnotations: brak deklaracji jest milczeniem, a ta deklaracja jest własnym stwierdzeniem dostawcy, że nie odczytuje niczego w zarezerwowanej przestrzeni nazw aggrega.ai/. Kompilacja renderująca przez takiego dostawcę ostrzega o każdej adnotacji aggrega.ai/, która dociera do renderowania, wskazując klucz, dostawcę i rodzaje wejścia deklarowane przez renderowanie; wartość nadal przechodzi bez zmian, a kompilacja się nie zatrzymuje.
Można zapisać wyłącznie true, więc pominięcie pola pozostaje jedynym sposobem, by niczego nie deklarować. Nie można go zapisać razem z wellKnownAnnotations: dostawca, który odczytuje niektóre klucze, wymienia je zamiast tego tam. Obie odmowy są na poziomie schematu, więc encja Plugin jest odrzucana przy odczycie.
spec: provider: capabilities: - terraform readsNoWellKnownAnnotations: trueDeklaruje go dostawca terraform z biblioteki standardowej; ../providers/terraform.md wyjaśnia, co to oznacza dla encji Release renderowanej przez niego.
spec.provider.contract
Samodzielnie zadeklarowany przez plugin renderujący dostawcy kontrakt zachowania renderowania w czasie kompilacji: rodzaje wejścia, które renderuje, sposób składania wyniku poszczególnych węzłów grupy dyspozycji, para ograniczników szablonu stosowana do importowanych plików artefaktów, informacja, czy jedna załadowana instancja może obsłużyć każde przejście, czy respektuje wpisy pominięć oraz czy przyjmuje pliki, które encja Recipe wnosi do współdzielonego wyniku swojej granicy. Znajduje się obok capabilities w tym samym bloku, ale odpowiada na inne pytanie: lista możliwości mówi, które możliwości ten plugin obsługuje, a kontrakt mówi, jak je renderuje. aggrega plugin gen-catalog zapisuje go na podstawie własnego raportu pluginu z describe(), a host porównuje go z tym raportem przy publikacji i przy ładowaniu; niezgodność zatrzymuje proces. Brak bloku oznacza brak kontraktu zachowania renderowania, a porównanie obejmuje wtedy tylko deklaracje poszczególnych eksportów. Wszystkie pola są opcjonalne.
| Pole | Skutek |
|---|---|
inputKinds | Które z trzech rodzajów wejścia encji Recipe plugin renderuje, każdy jako niezależna deklaracja logiczna: sourced (zestaw plików źródłowych — chart, moduł, plik compose), synthesized (syntetyzowana encja Workload) oraz artifactsStandalone (samodzielny węzeł zawierający importowane dokumenty artefaktów, bez źródła i bez workloadu). Host weryfikuje rodzaj wejścia węzła względem tego zbioru. |
boundaryAssembly | Sposób, w jaki plugin łączy wynik renderowania poszczególnych węzłów grupy dyspozycji: none zapisuje wynik każdego węzła bezpośrednio w ścieżce dyspozycji; merge scala fragmenty poszczególnych węzłów w jeden dokument; nest umieszcza wynik każdego węzła na jego własnej pozycji w nadrzędnej strukturze. Brak pola oznacza brak deklaracji składania. |
artifactDelimiters | Para ograniczników szablonów Go, którą plugin stosuje do importowanych plików artefaktów, jako left i right. Brak pola oznacza domyślną parę {{/}}; plugin, którego składnia docelowa koliduje z tą parą, deklaruje parę alternatywną (na przykład [[/]]). |
reusableInstance | Czy jedna załadowana instancja pluginu może obsłużyć każde przejście renderowania, składania i walidacji w kompilacji zamiast nowej instancji dla każdego przejścia. Deklarowane jako true tylko wtedy, gdy plugin nie przechowuje stanu między przejściami, tak aby pojedyncza instancja dawała bajtowo identyczny wynik niezależnie od tego, czy jest użyta ponownie, czy załadowana od nowa. Brak pola (false) ładuje nową instancję dla każdego przejścia, izolując plugin, który z założenia przechowuje stan. aggrega build --verify-determinism dowodzi stabilności wyniku pluginu wielokrotnego użytku, renderując każdy węzeł dwukrotnie i zatrzymując się przy jakiejkolwiek różnicy. |
omits | Czy plugin respektuje wpisy pominięć — wpisy wskazujące renderowane jednostki, które należy pominąć w wyniku węzła: pomija w renderowanym wyniku każdą jednostkę dopasowaną przez wpis i raportuje, ile jednostek dopasował każdy wpis. Wartość zapisuje deklarację raportowaną przez describe() pluginu, więc true jest poprawne tylko dla pluginu, który to raportuje, a wartość różna od raportu zatrzymuje proces. Brak pola (false) oznacza brak takiej obsługi. |
boundaryArtifacts | Czy cel pluginu przyjmuje pliki, które encja Recipe wnosi do współdzielonego wyniku granicy, w której renderuje, zgodnie z spec.boundary.artifacts tej encji: kompilator zapisuje każdy taki plik jeden raz, obok tego, co plugin składa dla granicy, a cel odczytuje go jako część tego wyniku. Wartość zapisuje deklarację raportowaną przez describe() pluginu, a wartość różna od raportu zatrzymuje proces. Brak pola (false) oznacza brak takiej obsługi, a encja Recipe deklarująca ten blok dla tego pluginu zostaje odrzucona, zanim cokolwiek zostanie wyrenderowane. |
metadata: pluginType: providerspec: provider: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm-chart contract: inputKinds: sourced: true synthesized: false artifactsStandalone: false boundaryAssembly: nest artifactDelimiters: left: "[[" right: "]]" reusableInstance: truespec.pipelineStep
Blok kroku potoku dla pluginu pluginType: pipeline-step. Jego jedyne pole, capabilities, wskazuje dostawców, których wyrenderowane wyjście krok pluginu potrafi przekształcać — nazwy możliwości, takie jak helm lub compose. Krok jest pisany pod kształt wyjścia jednego dostawcy naraz, więc lista wymienia dostawców zgłaszanych przez sam plugin; wpisy zachowują kolejność, w jakiej zostały zapisane. Blok występuje tylko w pluginach kroków potoku.
Blok jest czytelnym dla katalogu zapisem tej deklaracji: aggrega plugin gen-catalog zapisuje go na podstawie samoopisu describe() zwracanego przez sam plugin, a autor może go zawęzić przed publikacją. Egzekwowanie odczytuje tę samą deklarację z pluginu: gdy krok dotyka zakresu, kompilacja zostaje zatrzymana, chyba że dostawca renderujący dokumenty tego zakresu należy do tych, które plugin deklaruje. Pusta lub nieobecna lista nie deklaruje żadnej zgodności, więc żaden zakres nie dopuszcza kroku.
metadata: pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm - composespec.parser
Blok parsera dla wtyczki pluginType: parser. Jego jedyne pole, capabilities, wymienia formaty źródłowe, które wtyczka przekształca w kanoniczne drzewo strukturalne, każdy zapisany jako parse:<format>. Prefiks jest częścią wpisu, więc wtyczka odczytująca kilka formatów wymienia po jednym wpisie na format. aggrega plugin gen-catalog zapisuje listę na podstawie własnego describe() wtyczki, autor może ją zawęzić przed publikacją, a wpisy zachowują kolejność, w jakiej zostały zapisane. Blok występuje tylko we wtyczkach parserów.
Żądany format jest rozwiązywany do parsera, którego lista zawiera pasujący wpis. Format, którego nie ogłasza żaden parser, zatrzymuje kompilację, a format ogłaszany przez więcej niż jedną wtyczkę parsera zatrzymuje ją jako niejednoznaczny, wskazując kandydatów — nie ma wariantu zapasowego, ponieważ parser nie ma domyślnego ustawienia niewymagającego konfiguracji, do którego można by się odwołać. Pusta lub nieobecna lista nie deklaruje żadnego formatu, więc wtyczka niczego nie parsuje.
metadata: pluginType: parserspec: abiVersion: v1beta1 parser: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - parse:hcl - parse:tomlspec.importer
Blok importera dla pluginu pluginType: importer. Jego pole capabilities wymienia obce formaty źródłowe, które plugin przekształca w robocze pliki autorskie Aggrega, każdy zapisany jako import:<format>. Prefiks jest częścią wpisu, więc plugin obsługujący kilka formatów wymienia po jednym wpisie na format. aggrega plugin gen-catalog zapisuje listę na podstawie własnego describe() pluginu, autor może ją zawęzić przed publikacją, a wpisy zachowują kolejność, w jakiej zostały zapisane. Blok występuje tylko w pluginach importera.
Żądany format importu jest rozwiązywany do importera, którego lista zawiera pasujący wpis. Format, którego nie ogłasza żaden importer, zatrzymuje import, a format ogłaszany przez więcej niż jeden plugin importera zatrzymuje go jako niejednoznaczny, z wymienieniem kandydatów, chyba że wpis plugins.importer w konfiguracji obszaru roboczego dołącza jednego z nich — wtedy uruchamiany jest właśnie on. Pusta lub nieobecna lista nie zgłasza żadnego formatu, więc plugin niczego nie importuje.
Jego pole detect zapisuje sygnatury, po których rozpoznawane jest źródło w tych formatach, gdy import nie wskazuje formatu. Jest zarządzane maszynowo, podobnie jak zapisy funkcji hosta i poleceń: wynika z tego, co zgłasza describe() pluginu, gdy encja jest generowana z pluginu, w kolejności, w jakiej plugin deklaruje sygnatury, i autor go nie pisze. Każda sygnatura określa:
syntax— format składniowy, w którym źródło jest parsowane, czyli format ogłaszany przez plugin parsera jakoparse:<syntax>, na przykładjsonlubyaml.files— opcjonalne wzorce nazw plików, dopasowywane do końca nazwy źródła: wzorzec z jednym segmentem do samej nazwy pliku, wzorzec z kilkoma segmentami rozdzielonymi ukośnikami do tylu samo końcowych segmentów jego ścieżki, więc.vscode/mcp.jsonpasuje do pliku o nazwiemcp.jsonw katalogu o nazwie.vscode.*,?i[...]dopasowują w obrębie segmentu. Gdy pole jest nieobecne, sygnatura dotyczy źródła będącego jednym plikiem, niezależnie od jego nazwy, i żadnego pliku katalogu. Wzorce sygnatur importera decydują też o tym, które pliki katalogu przekazuje muaggrega import.match— predykaty, które sparsowane drzewo musi spełnić, wszystkie. Każdy mapath, czyli klucze połączone kropkami od wierzchołka drzewa, przy czym segment będący liczbą całkowitą wybiera pozycję w tablicy;is, jedno zpresent,absent,object,array,string,numberiboolean; oraz opcjonalnieequals, ciąg, którym wartość musi być, lubprefix, ciąg, od którego musi się zaczynać — co najwyżej jedno z tych dwóch.
Gdy import nie wskazuje formatu, do źródła dopasowywane są sygnatury każdego importera z katalogu obszaru roboczego — wliczając każdą wersję — oraz importerów wbudowanych kompilatora. Źródło jest parsowane raz dla każdej składni, w której odczytuje je sygnatura dotycząca jego nazwy, za pomocą parsera udostępnianego dla tej składni przez katalog obszaru roboczego — lub, dla składni, dla której katalog nie udostępnia parsera, tego, który ma sam kompilator — a źródło, które nie parsuje się w danej składni, nie pasuje do żadnej sygnatury ją wskazującej. Katalog jest dopasowywany poprzez swoje pliki: każda sygnatura jest sprawdzana względem plików katalogu wybranych przez jej wzorce, w kolejności nazw, a sygnatura bez wzorca nie dotyczy żadnego z nich. Źródło, do którego pasuje sygnatura, jest rozpoznawane jako każdy format ogłaszany przez jej importer. Jeśli rozpoznano dokładnie jeden format, źródło jest odczytywane w tym formacie. Źródło, do którego nie pasuje żadna sygnatura, jest odrzucane z prośbą o podanie formatu i wymienieniem formatów ogłaszanych przez importery — albo, w przypadku katalogu, z prośbą o podanie jednego z jego plików osobno lub formatu, którego importer deklaruje wzorce plików, z wymienieniem tylko tych formatów; źródło rozpoznane jako więcej niż jeden format jest odrzucane z ich wymienieniem, z warunkiem More than one importer recognises the source (Więcej niż jeden importer rozpoznaje źródło). Zatem importer ogłaszający więcej niż jeden format ma każde źródło pasujące do jego sygnatur odrzucane jako niejednoznaczne, a importer, którego źródła mają być rozpoznawane, obsługuje jeden format.
Jeśli encja zapisuje detect, musi ono być równe temu, co zgłasza describe() wtyczki, sygnatura po sygnaturze i w tej samej kolejności: wczytanie importera odrzuca wtyczkę, której raport się różni, wskazując importer.detect, i tak samo jej publikacja. Encja, która nie zapisuje detect, niczego nie deklaruje i nie jest porównywana, więc wczytuje dowolne sygnatury zgłaszane przez describe() jej wtyczki, a formaty jej importera są wtedy osiągalne tylko przez jawne ich podanie.
metadata: pluginType: importerspec: abiVersion: v1beta1 importer: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - import:langflow detect: - syntax: json match: - path: data.nodes is: arrayspec.signature
Opcjonalny, opisowy wskaźnik do podpisu dołączonego do pluginu. Blok ma wyłącznie charakter dokumentacyjny — zapisuje dla czytelników katalogu, gdzie znajduje się podpis i jak został wytworzony; sam nie dopuszcza pluginu. Wiążącym sprawdzeniem jest polityka zaufania danego rejestru, stosowana przy pobieraniu: podpis jest pobierany jako OCI referrer, weryfikowany względem zaufanych tożsamości rejestru lub przypiętego klucza i zapisywany w pliku blokady jako zweryfikowany fakt. Rejestr wymagający podpisów przerywa pobieranie, gdy wymaganego podpisu brakuje, nie jest zaufany lub jest nieprawidłowy.
type— schemat podpisu. Obsługiwanym schematem jestsigstore-cosign. Wymagane, gdy blok jest obecny.signatureRef— referencja OCI referrer dołączonego pakietu podpisu, służąca dokumentacji i wykrywaniu. Nieobecne, gdy podpis jest wykrywany przez wyliczenie referrerów przy pobieraniu, a nie przypięty tutaj.publicKeyRef— wskaźnik do klucza publicznego, którym wytworzono podpis, w przypadku podpisu z kluczem. Brak oznacza podpis bezkluczowy (oparty na tożsamości OIDC), weryfikowany względem zaufanych tożsamości rejestru.
spec.runtime
Opcjonalne ograniczenia wykonania, które host stosuje podczas ładowania i uruchamiania pluginu. Wychodzący dostęp do sieci nie jest polem do wypełnienia przez autora: plugin nigdy nie łączy się z siecią w czasie budowania — to granica kompilacji ahead-of-time — dlatego nie ma tu pola z listą dozwolonych hostów. Zdalna treść potrzebna pluginowi trafia do niego przez pośredniczony przez hosta, przypięty skrótem kanał danych zewnętrznych, zapisany w pliku blokady encji Release, a nigdy przez swobodny dostęp do sieci; przewodnik dla deweloperów opisuje opakowanie pobierania i zasady przypinania.
| Pole | Skutek |
|---|---|
maxMemoryPages | Ogranicza pamięć liniową pluginu w stronach Wasm (64 KiB na stronę). Zero lub brak wartości oznacza domyślny limit platformy, więc ładowanie nigdy nie jest nieograniczone; dołączenie, które potrzebuje więcej, zwiększa tę wartość. |
timeoutMs | Ogranicza, jak długo własny kod pluginu może działać podczas jednego wywołania, w milisekundach, bez wliczania czasu spędzonego w wywoływanych przez niego funkcjach hosta. W systemie Linux mierzony jest czas procesora, więc czas oczekiwania na procesor na obciążonej maszynie się nie liczy; w innych systemach jest to czas rzeczywisty. Pierwsze wywołanie świeżo załadowanego pluginu obejmuje także jego własne uruchomienie. Zero lub brak wartości oznacza domyślny limit platformy, więc wywołania nigdy nie da się nie przerwać; dołączenie, które działa dłużej, zwiększa tę wartość. |
hostFunctions | Nazwy funkcji hosta importowanych przez plugin. Wyznaczane maszynowo i tylko do odczytu — nie należy ich wpisywać: aggrega plugin sync odczytuje funkcje hosta z sekcji importów pliku .wasm i zapisuje to pole, publikacja odrzuca zapis różniący się od pliku binarnego, a wartość odzwierciedla opublikowany plik binarny i jest walidowana względem utrzymywanej listy dozwolonych funkcji. Host rejestruje dokładnie ten zbiór, dając każdemu pluginowi najmniej uprzywilejowany interfejs hosta, jakiego potrzebuje jego plik binarny; pobranie ponownie wyznacza tę wartość i weryfikuje ją względem pliku binarnego. Aby podejrzeć wartość przed publikacją, należy uruchomić aggrega inspect --plugin <file.wasm>. |
configKV | Plugin-specific konfiguracja, którą środowisko uruchomieniowe przekazuje pluginowi przy starcie, w postaci par klucz/wartość typu string-string. Wpisy zachowują kolejność autora, dzięki czemu emitowany rekord jest identyczny bajt po bajcie między uruchomieniami. Brak pola pozostawia w mocy domyślną, pustą konfigurację środowiska uruchomieniowego. |
spec.exports
Eksporty oferowane przez plugin, każdy z zadeklarowaną zdolnością, w postaci uporządkowanej listy zachowującej kolejność nadaną przez autora. Eksport to jeden nazwany punkt wejścia, do którego host kieruje wywołania (na przykład render_node, lint_naming, step); blok zdolności danego eksportu określa, co ten eksport robi, tak jak aggrega plugin gen-catalog zapisuje to na podstawie samoopisu pluginu describe(), a host porównuje go z tym samoopisem przy publikacji i przy ładowaniu. Brak pola oznacza brak zadeklarowanej powierzchni eksportów.
| Pole | Skutek |
|---|---|
name | Nazwa ABI eksportu — nazwa, do której host kieruje wywołania. Wymagana dla każdego wpisu. |
operates | Operacja potoku wykonywana przez eksport: patch (modyfikacja istniejącego wyrenderowanego dokumentu) lub emit (dodanie nowego dokumentu). Host porównuje wartość z samoopisem pluginu; jest to weryfikowana deklaracja zdolności, a nie przełącznik wywołań — operację wykonywaną przez krok niesie wynik zwrócony przez gościa. Brak pola oznacza brak deklaracji operacji. |
scope | Korzeń dokumentów, na którym działa eksport: own (własne wyrenderowane dokumenty węzła) lub host (dokumenty komponentu, do którego dołączona jest encja FeatureRecipe o zakresie komponentu). Host odczytuje zadeklarowany zakres przed krokiem, aby wymusić zgodność z providerem renderującym ten zakres. Brak pola oznacza wartość domyślną own. |
selector | Dowolny, czytelny dla człowieka opis tego, na czym działa eksport (na przykład workloads carrying a pod template). Dokumentacja dla czytelników katalogu i powierzchni inspekcji; kompilator jej nie interpretuje. |
spec.commands
Czasowniki najwyższego poziomu aggrega <command>, które wnosi wtyczka cli, w postaci uporządkowanej listy zachowującej kolejność deklarowaną w samoopisie describe() wtyczki. Pole zarządzane maszynowo i tylko do odczytu — nie należy go tworzyć ręcznie. aggrega plugin sync odczytuje zestaw poleceń z samoopisu describe() wtyczki i zapisuje go tutaj, dzięki czemu polecenia instalowane przez wtyczkę CLI można odczytać z encji bez ładowania pliku .wasm. Wtyczka inna niż cli nie wnosi żadnych poleceń i zapisuje pustą listę. Host instaluje dokładnie ten zestaw; zapisany zestaw, który odbiega od samoopisu describe() wtyczki, powoduje zatrzymanie przy ładowaniu, a publikacja odrzuca zestaw niezsynchronizowany z plikiem binarnym i kieruje autora do ponownego jego zapisania. Aby ponownie zsynchronizować zapis po zmianie wtyczki, należy uruchomić aggrega plugin sync.
Każdy wpis polecenia zawiera:
| Pole | Skutek |
|---|---|
name | Czasownik polecenia rejestrowany przez host — token aggrega <name> wywoływany przez operatora oraz dyskryminator przekazywany przez host pluginowi przy wywołaniu, dzięki któremu pojedynczy plugin obsługujący kilka poleceń rozpoznaje, które polecenie zostało wywołane. Wymagany dla każdego wpisu. |
description | Jednowierszowy krótki tekst pomocy polecenia, wyświetlany na liście poleceń i w wyniku pomocy. Wyłącznie dokumentacja; host nie podejmuje na jego podstawie żadnych działań. |
flags | Flagi polecenia w zadeklarowanej kolejności. Każdy wpis rejestruje jedną flagę polecenia, dzięki czemu aggrega help <command> wyświetla ją tak jak flagę polecenia wbudowanego. Polecenie bez flag pozostawia to pole puste. |
Każdy wpis flags deklaruje jedną flagę:
| Pole | Skutek |
|---|---|
name | Długa nazwa flagi — token --name przekazywany przez operatora w wierszu poleceń. Wymagana dla każdego wpisu. |
shorthand | Opcjonalny krótki alias flagi — forma -x, którą operator może przekazać zamiast długiej nazwy — w postaci pojedynczej litery lub cyfry ASCII. Brak pola oznacza, że flaga nie ma krótkiego aliasu. |
description | Jednowierszowy tekst pomocy flagi, wyświetlany w wyniku pomocy polecenia. Opcjonalna dokumentacja; host ani jej nie weryfikuje, ani nie podejmuje na jej podstawie działań. |
type | Typ wartości flagi — string, bool lub int — oraz rodzaj flagi, jako który wyświetla ją pomoc. Brak pola oznacza wyświetlanie jako flagi tekstowej. |
default | Wartość domyślna flagi, gdy operator jej nie przekaże, wyrażona jako ciąg znaków. Dla flagi bool lub int jest to wartość tego typu. Brak pola oznacza, że flaga nie deklaruje wartości domyślnej. |
Plugin CLI deklaruje swoje polecenia i ich flagi w describe(); host rejestruje dokładnie tę powierzchnię i wyświetla flagi każdego polecenia w aggrega help <command> tak samo jak flagi polecenia wbudowanego.
Host sprawdza każdą flagę zadeklarowaną przez plugin podczas dodawania jego poleceń, a plugin, którego deklaracje nie przejdą sprawdzenia, jest pomijany, a nie dodawany: żadne z jego poleceń nie zostaje zarejestrowane, ostrzeżenie wskazuje plugin, polecenie, flagę i problem z nią, a wszystkie pozostałe polecenia — wbudowane lub z innego pluginu — działają dalej. Deklaracja nie przechodzi sprawdzenia, gdy:
- flaga nie ma nazwy lub polecenie deklaruje tę samą nazwę dwukrotnie;
- skrót jest czymś innym niż pojedyncza litera lub cyfra ASCII albo polecenie deklaruje ten sam skrót dla dwóch flag;
- nazwa lub skrót powiela flagę, którą ma już każde polecenie
aggrega—--help, jej-horaz flagi globalne, takie jak--offlinei--config; - typ jest czymś innym niż
string,boollubint; - wartości domyślnej nie da się sparsować jako typu flagi —
maybedlabool,threedlaint.
Jednoznakowa postać shorthand i trzy wartości type są także częścią schematu tej encji, więc encja Plugin zapisująca inną wartość jest odrzucana przy ładowaniu katalogu. To, że nazwa lub skrót występuje raz na polecenie, że żadne z nich nie powiela flagi wspólnej dla wszystkich poleceń i że wartość domyślna parsuje się jako jej typ, sprawdza wyłącznie host. Sprawdzenie obejmuje to, czy host może zadeklarować flagę na potrzeby pomocy w zapisanej postaci; nie widzi ono, czy plugin odczytuje deklarowane flagi, ponieważ plugin sam parsuje swoje argumenty.
metadata: pluginType: clispec: abiVersion: v1beta1 # commands is recorded by `aggrega plugin sync` from the plugin's describe() — do not author it. commands: - name: greet description: Print a friendly greeting flags: - name: name shorthand: n description: Who to greet type: string default: worldInspekcja encji Plugin
aggrega inspect <path-to-Plugin.yaml> wyświetla plik Plugin: jego tożsamość i typ gniazda, możliwości deklarowane przez jego blok, tabelę możliwości poszczególnych eksportów w kolejności nadanej przez autora, ograniczenia środowiska uruchomieniowego oraz — przy --detail — wskaźnik podpisu i klucze konfiguracji środowiska uruchomieniowego. Do encji Plugin można się odwołać przez ścieżkę pliku albo przez jej współrzędną <pluginType>/<name> w katalogu. Zobacz ../cli/aggrega-inspect.md.
Odsyłacze
- Przewodnik dla twórców wtyczek Wasm — pełny proces pracy autora:
describe(), deklaracje możliwości, limity środowiska uruchomieniowego, cykl życia, podpisywanie, wersjonowanie. - Kontrakt wtyczek Wasm — punkty gniazd, do których podłącza się wtyczka, oraz kształty ich danych wejściowych i wyjściowych.
entities/featurerecipe.md— powierzchniapipeline:encji FeatureRecipe, która odwołuje się do wtyczki przez URI encji.cli/aggrega-lint.md— linter publikacji, zasady podbijania wersji oraz egzekwowanie niezmienności, które regulują publikowanie encjiPlugin.