Entwicklerleitfaden für Wasm-Plugins
Dies ist der maßgebliche Leitfaden für das Erstellen eines WebAssembly-Plugins (Wasm) für Aggrega und seine Veröffentlichung als Katalogentität. Er vermittelt den Vertrag des Plugin-Autors von Anfang bis Ende: was ein Plugin ist, wie sich ein Plugin gegenüber dem Host beschreibt, wie man seine Exporte und Fähigkeitsansprüche erstellt, die Laufzeitgrenzen und Host-Funktionen, die der Host anwendet, die Entität Plugin, die ein Plugin in den Katalog bringt, wie ein Recipe oder FeatureRecipe auf ein Plugin verweist, und den Lebenszyklus publish→pull→build, der ein Plugin von einer Datei .wasm auf der Festplatte zu einem verifizierten, per Digest fixierten Artefakt bringt, das ein Build konsumiert.
Die Begleitseite plugin-contract.md dokumentiert die Sockets — die Punkte der Pipeline, an denen Plugins angebunden werden, und die Ein-/Ausgabeformen, die jeder Socket konsumiert und erzeugt. Dieser Leitfaden dokumentiert das Plugin — die Entität, die Fähigkeitsoberfläche und den Lebenszyklus. Lesen Sie die Vertragsseite, um zu erfahren, auf welchen Socket Ihr Plugin abzielt; lesen Sie diese Seite, um zu erfahren, wie Sie es erstellen und ausliefern.
Für einen durchgehenden Weg durch die gesamte Aufgabe statt einer Referenz dazu baut die Anleitung einen Provider erstellen einen kleinen Provider-Guest von Anfang bis Ende — Deskriptor, Build, Entität, Anbindung und ein Rendering, dessen Ausgabe Sie lesen können —, einschließlich der Ablehnung, auf die ein erster Entwurf meist stößt, und wie man sie liest.
1. Was ein Wasm-Plugin ist
Ein Wasm-Plugin ist ein WebAssembly-Modul, das den Compiler an einem festgelegten Socket erweitert. Die Go-Host-Binärdatei enthält keine cloudspezifische oder Infrastrukturlogik; die gesamte domänenspezifische Intelligenz — Template-Rendering, Formatübersetzung, Richtlinienauswertung, Linting — liegt in Plugins. Der Host orchestriert die Pipeline und übergibt die Payload jedes Sockets über die ABI-Grenze an den Guest; der Guest erledigt die Domänenarbeit und gibt die Ergebnisform dieses Sockets zurück. Payload und Ergebnis jedes Sockets werden als kanonisches CBOR übertragen, mit zwei Ausnahmen: Ein CLI-Plugin erhält seinen Argumentvektor als JSON-Text und antwortet mit einem Exit-Code und dem Text, den es streamt, und die Selbstauskunft describe ist JSON-Text. Der Abschnitt jedes Sockets im Plugin-Vertrag nennt seine Kodierung, und ein Guest liest und schreibt sie über die Einstiegspunkte, die der Payload-Typ seines Kits bereits mitbringt, sodass kein Guest Bytes von Hand parst.
Ein Plugin läuft hinter einer Ahead-of-Time-Reinheits-Firewall. Der Host lädt und führt das Modul über eine eingebettete Wasm-Laufzeit in einer Konfiguration mit verweigerten Fähigkeiten aus: keine Netzwerk-Sockets, kein Dateisystem, keine Umgebung, verworfenes stdio und eine beobachtbare Wanduhr, eingefroren auf einen Build-invarianten Zeitpunkt. Jeder I/O-Aufruf, den ein Guest versucht, schlägt an der Aufrufgrenze fehl, sodass ein Plugin nicht auf Laufzeitzustand zugreifen kann. Erstellen Sie Plugins mit Blick auf diese Firewall: Ein Plugin transformiert die Payload, die es erhält, und gibt ein Ergebnis zurück, das der Host unverändert übernimmt, und Determinismus liegt in Ihrer Verantwortung — identische Eingaben müssen identische Ausgabebytes erzeugen. Der eine sanktionierte Kanal für entfernte Inhalte ist der vom Host vermittelte Abruf externer Eingaben (Abschnitt 4), der Bytes nach einer per Digest fixierten Disziplin liefert, statt dem Guest direkten Netzwerkzugriff zu geben.
Die Sockets, auf die ein Plugin abzielen kann — darunter der Mutations-Prüfpunkt bei der Topologiekonstruktion, der Validierungs-Prüfpunkt bei der statischen Analyse, die FeatureRecipe-Pipeline, der Out-of-Band-Linter und der Provider-Rendering-Socket —, und ihre Ein-/Ausgabeformen pro Socket sind in plugin-contract.md dokumentiert. Welchen Socket ein Plugin bedient, ist der eine Wert, den es in metadata.pluginType deklariert, und die gesamte Menge der Werte, die dieses Feld akzeptiert, ist dessen Referenzeintrag in entities/plugin.md §„metadata.pluginType“. Die Beispiele in diesem Leitfaden verwenden provider (rendert IR-Knoten in Provider-native Artefakte), linter (prüft erstellte Inhalte und meldet Diagnosen) und pipeline-step (ein Schritt in der pipeline: eines FeatureRecipe oder eines Recipe, der die Menge der gerenderten Dokumente patcht).
Sie erstellen den Guest gegenüber dem Host mit dem Plugin-Entwicklungskit (PDK) in drei Sprachen — Go, Rust oder TypeScript. Das PDK kapselt die zugrunde liegende Wasm-Toolchain mit Aggrega-typisierten Buildern für die Ein- und Ausgabeformen, die jeder Socket transportiert.
2. Die Selbstauskunft describe()
Jedes Plugin exportiert eine Funktion describe(), die die Selbstauskunft des Plugins zurückgibt: den oder die Socket-Typen, die es implementiert, die ABI-Version, auf die es abzielt, die Fähigkeiten, die es beansprucht — gelesen gemäß dem Socket-Typ, also Fähigkeitsnamen für einen Provider oder einen Pipeline-Schritt und präfixierte Quellformate für einen Parser oder einen Importer —, die Host-Funktionen, die es importiert, und die Fähigkeit pro Export jedes Einstiegspunkts, den es anbietet. describe() ist die eigene Darstellung des Plugins davon, was es ist und was es tut.
Die Selbstauskunft ist der Anker des Vertrauensmodells. Die Entität Plugin, die das Plugin in den Katalog bringt (Abschnitt 5), gibt dieselben Fakten als erstellte Ansprüche wieder, und der Host gleicht die Ansprüche der Entität zu zwei Zeitpunkten mit der Ausgabe von describe() des Plugins ab — bei der Veröffentlichung, bevor Bytes in der Registry landen, und beim Laden, bevor das Plugin läuft. Eine Abweichung führt zu einem lauten Abbruch. Die Entität ist die für Menschen lesbare, im Katalog sichtbare Oberfläche; describe() ist die maschinelle Referenz, gegen die der Host sie prüft. Erstellen Sie beide so, dass sie übereinstimmen; der Abgleich existiert genau dafür, den Fall abzufangen, in dem sie auseinanderlaufen. Er prüft, was die Entität beansprucht, und nicht, was sie auslässt: Eine Entität, die weniger beansprucht, als die Binärdatei meldet — etwa eine, die nach einem Neubau mit einem zusätzlichen Export zurückgeblieben ist —, lädt trotzdem, beschreibt aber nicht mehr alles, was die Binärdatei tut.
3. Exporte und ihre Fähigkeitsansprüche erstellen
Ein Plugin bietet einen oder mehrere Exporte an — benannte Einstiegspunkte, an die der Host Aufrufe verteilt (zum Beispiel render_node, lint_naming, step). Jeder Export trägt einen Fähigkeitsblock: den Anspruch des Autors, was dieser Export tut. Die Fähigkeit eines Exports hat vier Felder:
name— der ABI-Name des Exports, der Name, an den der Host Aufrufe verteilt. Erforderlich.operates— die Pipeline-Operation, die der Export ausführt:patch(ein vorhandenes gerendertes Dokument ändern) oderemit(ein neues Dokument hinzufügen). Dies ist ein deklarierter Fähigkeitsanspruch. Der Host gleicht ihn bei der Veröffentlichung und beim Laden mit der Selbstauskunftdescribe()des Plugins ab, sodass der erstellte Anspruch der Entität und die eigene Darstellung des Plugins übereinstimmen müssen. Er ist ein validierter Anspruch über den Export, kein Verteilungsschalter: Zur Render-Zeit wird die Operation, die ein Schritt tatsächlich ausführt, vom zurückgegebenen Ergebnis des Guests getragen und nicht aus diesem Feld ausgewählt. Fehlt das Feld, trägt es keinen Operationsanspruch.scope— die Dokumentwurzel, auf die der Export wirkt:own(die eigenen gerenderten Dokumente des Knotens) oderhost(die Dokumente der Komponente, an die ein FeatureRecipe mit Komponentenbereich angebunden ist). Bevor das Plugin eines Pipeline-Schritts läuft, liest der Host den deklarierten Export-Bereich des Schritts und erzwingt, dass der Provider, der die Dokumente dieses Bereichs rendert, inspec.pipelineStep.capabilitiesdes Plugins (Abschnitt 5) erscheint — ein Export mit Bereichownwird gegen den Provider geprüft, der die eigenen Dokumente des Knotens rendert, ein Export mit Bereichhostgegen den Provider der Host-Komponente, und ein leerer Bereich gilt für diese Prüfung alsown. Das ist der Prüfpunkt für Provider-Kompatibilität, der vor dem Schritt läuft; das Dokument, das eine Guest-Operation tatsächlich berührt, wird pro Operation im zurückgegebenen Ergebnis des Guests benannt und nicht aus diesem deklarierten Feld ausgewählt. Fehlt das Feld, giltown.selector— eine frei formulierte, für Menschen lesbare Beschreibung dessen, worauf der Export wirkt (zum Beispielworkloads carrying a pod template). Dokumentation für Leser des Katalogs und die Oberflächeaggrega inspect; der Compiler interpretiert sie nicht.
Erstellen Sie Exporte in der Reihenfolge, in der sie gelesen werden sollen; die Einträge behalten die Reihenfolge des Autors in der Entität und in inspect bei. Ein Plugin ohne erstellte Exporte deklariert keine Export-Oberfläche — gültig für ein Plugin, dessen Socket keinen Fähigkeitsanspruch pro Export braucht.
4. Laufzeitgrenzen und Host-Funktionen
Eine Plugin-Entität kann einen optionalen Block runtime tragen, der einschränkt, wie der Host das Plugin lädt und ausführt.
Speicher- und Zeitgrenzen. maxMemoryPages begrenzt den linearen Speicher des Plugins in Wasm-Seiten (64 KiB pro Seite); timeoutMs begrenzt, wie lange der eigene Code des Plugins während eines Aufrufs laufen darf, in Millisekunden. Zeit, die in den vom Plugin aufgerufenen Host-Funktionen verbracht wird, zählt nicht dazu. Unter Linux ist das Maß die Prozessorzeit des Threads, der den Guest ausführt, sodass auch Zeit, in der der Guest auf einer ausgelasteten Maschine auf einen Prozessor wartet, nicht zählt; auf anderen Systemen ist es die verstrichene Zeit. Der erste Aufruf eines frisch geladenen Plugins zählt außerdem die einmalige Initialisierung der Laufzeit der Guest-Sprache mit, die innerhalb dieses Aufrufs läuft. Beide Grenzen sind optional mit Standardwerten: Null oder ein fehlender Wert wendet die Standardobergrenze der Plattform an. Der Loader begrenzt jedes Plugin auf den Plattformstandard, wenn die Entität keine Grenze deklariert, sodass ein Laden nie unbegrenzt und ein Aufruf nie unabbrechbar ist. Erhöhen Sie eine Grenze an der Entität, wenn eine Anbindung tatsächlich mehr Speicher oder mehr Zeit braucht, als der Standard erlaubt.
Host-Funktionen. hostFunctions hält die Namen der Host-Funktionen fest, die das Plugin importiert. Es ist ein maschinell abgeleitetes Feld — erstellen Sie es nicht selbst. aggrega plugin sync liest die Host-Funktionen direkt aus dem Importabschnitt der Datei .wasm und hält das Feld für Sie in der Entitätsdatei fest, und die Veröffentlichung leitet sie erneut aus der Binärdatei ab und weist eine Entität zurück, deren Eintrag abweicht; so erhält ein Plugin genau die Host-Funktionen, die seine Binärdatei tatsächlich importiert, validiert gegen eine kuratierte Allowlist (ein Import außerhalb der Allowlist wird laut abgelehnt). Der Eintrag ist eine Momentaufnahme der veröffentlichten Binärdatei, so wie die inhaltsadressierte Referenz plugin: eine Momentaufnahme der veröffentlichten Bytes ist: Er spiegelt die Binärdatei zum Zeitpunkt der Veröffentlichung wider und wird beim Pull des Plugins erneut abgeleitet und geprüft. Um vor der Veröffentlichung zu sehen, welche Host-Funktionen eine lokale Datei .wasm importiert — den Wert, den aggrega plugin sync festhält —, führen Sie aggrega inspect --plugin <file.wasm> aus.
Die kuratierte Host-Oberfläche. Drei der Host-Funktionen sind allgemein verwendbar: aggrega_log (eine Stufe und eine Meldung, ausgegeben als eine Logzeile am Log-Ziel des Hosts), aggrega_emit_warning (ein Code, eine Meldung und ein Pfad, gesammelt als strukturierte Warnung, die der Host nach dem Aufruf ausgibt) und aggrega_fetch_external_input (eine URL, beantwortet mit den Bytes der Eingabe gemäß der unten beschriebenen Fixierungsdisziplin). Das PDK kapselt alle drei in jeder Sprache — Go: aggrega.Log, aggrega.EmitWarning, aggrega.FetchExternalInput; Rust: log, emit_warning, fetch_external_input; TypeScript: log, emitWarning, fetchExternalInput —, sodass ein Guest eine typisierte Funktion statt der rohen ABI aufruft. Die Quell- und Parse-Callbacks — für einen Guest, der Ausschnitte einer beschafften Quelle liest oder über den Host einen geparsten Baum erhält — und die Kodierung, die die Slots jedes Callbacks tragen, sind in plugin-contract.md aufgeführt.
Lokale Quellinhalte kommen über den Host — nie aus dem Dateisystem. Ein Provider-Render-Plugin liest seine Quelle nie von der Festplatte; ein Dateisystemaufruf schlägt an der Aufrufgrenze fehl. Der Host übergibt dem Guest eine Quellauflistung in der Render-Payload — für jeden Eintrag den Pfad relativ zur Quellwurzel und ob er ein Verzeichnis ist, sortiert, ohne Dateiinhalt —, und der Guest wendet seine eigene Layout-Logik darauf an und liest dann genau die Dateien, die er auswählt, über die Quell-Callbacks zurück, die die Bytes zurückgeben, die der Host unter der Quellwurzel liest. Die Payload-Formen pro Socket und die Callbacks sind in plugin-contract.md dokumentiert.
Entfernte Inhalte kommen über den Abruf externer Eingaben. Ein Plugin, das entfernte Inhalte braucht — ein Chart-Archiv, ein entferntes Schemadokument —, ruft den Abruf-Wrapper des PDK auf. Bei der Übertragung übergibt der Guest die URL als UTF-8-Text an aggrega_fetch_external_input und erhält eine einzige Antwort in kanonischem CBOR, die entweder die abgerufenen Bytes, roh, oder eine Fehlermeldung neben ihrem maschinell abgleichbaren Code trägt; der Wrapper dekodiert die Antwort in Bytes oder einen Fehler. Die Bytes kommen genau so an, wie sie abgerufen wurden, einschließlich einer Payload, die kein gültiges UTF-8 ist, und eine Payload der Länge null kommt als leere Bytes statt als Fehler zurück. Der Host liefert die URL gemäß der Fixierungsdisziplin für externe Eingaben:
- Eine bereits in der Lockfile des Release fixierte URL wird aus dem lokalen inhaltsadressierten Speicher geliefert und bei jedem Lesen gegen ihren aufgezeichneten Digest geprüft. Ein fehlender Blob im Speicher wird anhand des aufgezeichneten Digests aus dem Netz nachgeladen — ein per Digest geprüftes Nachladen kann die Ausgabe nicht verändern.
- Eine nicht fixierte URL wird abgelehnt, mit einem Fehler, der die URL und die Abhilfe nennt. Ein Build rendert die Hülle, die seine Lockfile aufzeichnet, sodass kein Build eine nicht fixierte Referenz abruft und es keine Einstellung gibt, die das bewirkt.
- Die Fixierung erfolgt, wenn die Abhängigkeiten des Release aufgelöst werden:
aggrega pullrendert das Release, um herauszufinden, welche externen Eingaben sein Rendering anfordert, ruft jede davon ab und hält sie in der Lockfile neben den Abhängigkeitsfixierungen fest. Die Arbeitsschleife eines Plugin-Autors lautet also: einmal auflösen, dann so oft offline bauen, wie Sie möchten.
Zulässige Schemata sind https, http nur zu Loopback-Hosts und oci (über den Manifestdigest fixiert). Die Lockfile hält jede fixierte Eingabe fest — ihre URL, den Digest sha256, die Größe und die Plugins, die sie angefordert haben —, sodass ein erneuter Build dieselben Bytes aus dem lokalen Speicher liefert: reproduzierbar und, einmal fixiert, offline.
Mit dem Go-PDK:
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)}Was fehlschlägt und warum.
- Ein Dateisystem- oder Netzwerkaufruf schlägt an der Aufrufgrenze fehl: Der Guest hat keine vorab geöffneten Verzeichnisse und keine Sockets. Das gilt für jeden Codepfad, auch für eine Bibliotheksabhängigkeit, die versucht, eine Datei zu lesen — lesen Sie die Quelle stattdessen über die Quell-Callbacks.
- Ein Import unter einem anderen Modul als
wasi_snapshot_preview1,extism:host/envundextism:host/userschlägt beim Laden fehl, mit einer Diagnose, die das Modul und den Import nennt. Einzelne WASI-Funktionsnamen innerhalb eines zugelassenen Moduls werden nie zensiert — die ungenutzten Dateisystem- und Socket-Importe einer statisch gelinkten Sprachlaufzeit sind unproblematisch, denn das Benennen eines Imports gewährt nichts. - Der Abruf einer URL, die die Lockfile nicht fixiert, schlägt mit einem Fehler fehl, der die URL nennt; die Abhilfe ist,
aggrega pull --release <release>auszuführen, das jede externe Eingabe fixiert, die das Rendering des Release konsumiert, und dann zu bauen.
Es gibt kein Feld mit einer Host-Allowlist für ausgehenden Netzwerkzugriff. Ein Plugin erreicht zur Build-Zeit nie das Netzwerk — das ist die Ahead-of-Time-Grenze —, also gibt es kein solches Feld zu erstellen. Entfernte Inhalte kommen über den oben beschriebenen, vom Host vermittelten, per Digest fixierten Kanal für externe Eingaben, nie über ambienten Netzwerkzugriff.
Konfiguration. configKV ist eine String-zu-String-Map, die die Laufzeit dem Plugin beim Start übergibt. Die Einträge behalten die Reihenfolge des Autors bei, sodass der ausgegebene Eintrag über Läufe hinweg byteidentisch ist. Fehlt sie, bleibt die leere Standardkonfiguration der Laufzeit in Kraft.
5. Die Entität Plugin
Ein Plugin gelangt als Entität Plugin in den Katalog — die Authoring- und Metadatenoberfläche des Plugins. Die Entität deklariert, was das Plugin ist, und verweist auf das Artefakt .wasm; der Compiler interpretiert das Verhalten des Plugins nicht und leitet die fixierte Referenz weiter, während die Wasm-Laufzeit die Bytes ausführt.
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 credentialDie Felder:
- Bewusst kein Feld für den Artefaktort. Die Entität trägt keinen Verweis auf die Datei
.wasm, und das Schema akzeptiert keinen. Der Artefaktort eines Plugins wird aus seiner Identität abgeleitet — der Koordinatemetadata.pluginType/metadata.name, die den Repository-Pfadplugin/<pluginType>/<name>bildet — plus der Registry, für die der Workspace konfiguriert ist, sodass es keinen Ort zu erstellen und keinen falsch anzugeben gibt. Der aufgelöste Inhaltsdigest wird pro Release in der Lockfile dieses Release festgehalten, und der Build prüft die abgerufenen Bytes dagegen: Identität in der Entität, geprüfte Bytes in der Lockfile. metadata.version— das Release, das die Entität veröffentlicht und das der eigenen Build-Provenienz-Version des Guests entsprechen muss, wie sie indescribe()gemeldet wird. Ein Plugin-Autor versioniert die Datei.wasmzur Build-Zeit — der Build prägt die Version in den Guest ein, und ein Build, der sie aus einem Release-Tag übernimmt, prägt die Release-Version nur auf dem Commit ein, den dieser Tag nennt —, undmetadata.versionder Entität nennt dasselbe Release. Die Veröffentlichungsprüfung gleicht beide ab und bricht bei einer Abweichung ab, sodass die Entität immer die genaue Version der Binärdatei nennt, die sie ausliefert.aggrega plugin gen-catalog --plugin(siehe unten) kopiert die Version, die der Guest meldet, in die Entität, die es erzeugt; das ist die Release-Version, wenn der Guest aus dem getaggten Commit gebaut wurde. Erforderlich.metadata.pluginType— der Socket-Typ, den dieses Plugin implementiert, ausprovider,linter,pipeline-step,governance,cli,parserundimporter. Ein Plugin implementiert genau einen. Er steht im Adressierungsblock nebennameundversionund liefert das Segment<pluginType>der abgeleiteten Koordinate. Erforderlich.spec.abiVersion— die Host/Guest-ABI-Version, auf die das Plugin abzielt.v1beta1ist der akzeptierte Wert; eine künftige ABI-Revision fügt einen akzeptierten Wert hinzu. Erforderlich.- Der Block für Ihren Socket-Typ, der
capabilitiesträgt — ein Plugin deklariert, was es bedient, innerhalb des Blocks, der zu seinemmetadata.pluginTypegehört, und der Block legt fest, was ein Eintrag bedeutet.spec.provider.capabilitiesnennt die Fähigkeiten, die ein Provider bedient (Fähigkeitsnamen wiehelmodercompose).spec.pipelineStep.capabilitiesnennt die Provider, mit deren gerenderter Ausgabe Ihr Schritt kompatibel ist.spec.parser.capabilitiesnennt die Quellformate, die ein Parser liest, jeweils alsparse:<format>geschrieben.spec.importer.capabilitiesnennt die fremden Formate, aus denen ein Importer Entitätsentwürfe erstellt, jeweils alsimport:<format>geschrieben. Ein in Go geschriebener Importer kann alles, was nicht von seinem Format abhängt — die Bewertung, die Entscheidung zwischen Verweis und Entwurf, die Entwürfe und ihr Rendering sowie seine Einstellungen —, aus dem Importer-Paket des Go-Kits übernehmen,github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Ein Plugin vom Typlinter,governanceoderclibedient keine Fähigkeit und trägt keinen der vier Blöcke. Die Einträge behalten die Reihenfolge des Autors bei, und jede Liste ist ein expliziter, getesteter Anspruch: Deklarieren Sie, wogegen Sie das Plugin tatsächlich gebaut und getestet haben, denn ein Konsument löst genau gegen das auf, was aufgeführt ist. Für einen Pipeline-Schritt wird dieser Anspruch beim Rendern durchgesetzt — wenn ein Schritt einen Bereich berührt, bricht der Build ab, sofern der Provider, der die Dokumente dieses Bereichs rendert, nicht zu denen gehört, die Ihr Plugin beansprucht —, sodass eine leere Liste keinem Provider entspricht und den Schritt nirgends zulässt. spec.signature— ein optionaler beschreibender Verweis auf die angehängte Signatur des Plugins (Abschnitt 8). Dieser Block ist reine Dokumentation: Er hält für Leser des Katalogs fest, wo die Signatur liegt und wie sie erzeugt wurde; er lässt das Plugin nicht selbst zu. Die durchsetzende Prüfung ist die Vertrauensrichtlinie pro Registry, die beim Pull angewendet wird.spec.runtime— der optionale Block der Ausführungsbeschränkungen aus Abschnitt 4. Der Autor schreibtmaxMemoryPages,timeoutMsundconfigKV;hostFunctionswird maschinell abgeleitet und vonaggrega plugin syncfestgehalten, was die Veröffentlichung prüft, und nicht vom Autor erstellt.spec.exports— die Fähigkeitsansprüche pro Export aus Abschnitt 3 (name,operates,scope,selector).
Die Entität aus Ihrer Datei .wasm erzeugen. Sie müssen die maschinell verwalteten Teile der Entität nicht von Hand schreiben. aggrega plugin gen-catalog --plugin <file.wasm> liest die Selbstauskunft describe() des Guests und erzeugt daraus eine veröffentlichungsbereite Entität Plugin, ergänzt um ein kleines, von Ihnen erstelltes Overlay (die Identität, die Laufzeitgrenzen und einen etwaigen Provider-Block). Der Generator prägt die Felder ein, für die die Binärdatei die maßgebliche Quelle ist — die Export-Ansprüche, den Fähigkeitsvertrag, den Befehlsspiegel und den Eintrag der Host-Funktionen —, und kopiert metadata.version aus der Build-Provenienz-Version in describe() des Guests, während das Overlay nur liefert, was die Binärdatei nicht meldet. Das ist der unterstützte Weg für den Autor eines Drittanbieter-Plugins: Bauen und versionieren Sie Ihre Datei .wasm, und erzeugen Sie dann die Entität neu, damit ihre maschinell verwalteten Felder im Gleichschritt mit der Binärdatei bleiben. Die Version ist das einzige kopierte Feld, das ein Release statt einer Tatsache über die Bytes nennt; erzeugen Sie daher aus einem Build des Commits, den der Tag des Release nennt — oder setzen Sie, ausgehend von einem Entwicklungs-Build, metadata.version in der erzeugten Entität auf das Release, bevor Sie den Commit taggen, der sie enthält. Ein Guest, der keine Build-Provenienz-Version trägt, kann nicht zu einer versionierten Entität erzeugt werden — versionieren Sie den Guest zuerst zur Build-Zeit.
Die .wasm neben ihrer Entität. Während Sie ein Plugin schreiben, ist nichts veröffentlicht, das ein Build abrufen könnte, daher liest ein Build die .wasm des Plugins neben seiner Plugin-Entität in einem Katalogverzeichnis, unter einem Namen, der aus Plugin-Typ und Name der Entität abgeleitet ist: Für pipeline-step/patch ist es pipeline-step--patch.wasm. Kleinbuchstaben, Ziffern und die meisten Bindestriche werden so in diesen Namen geschrieben, wie sie sind; jedes andere Zeichen wird in maskierter Form geschrieben, ebenso ein Bindestrich an einigen Positionen — wo es darauf ankommt, nennt daher die Ablehnung einer fehlenden .wasm, A plugin’s .wasm is not on this machine (Das Modul eines Plugins ist nicht auf diesem Rechner), den Namen vollständig. aggrega lint <plugin.yaml> liest die .wasm von derselben Stelle — neben der Entitätsdatei, die es erhält, in welchem Verzeichnis diese Datei auch liegt —, es sei denn, das Binary enthält das Plugin selbst, und gibt für jeden Export, jede Fähigkeit oder jeden Vertrag, den die .wasm meldet und den die Entität auslässt, einen Hinweis aus. Wo dort keine .wasm liegt, meldet der Lint, dass er diesen Bericht übersprungen hat, und nennt die Datei, nach der er gesucht hat, und das Verzeichnis; sein Ergebnis ändert sich nicht.
Die Referenz Feld für Feld finden Sie auf der Entitätsseite ../entities/plugin.md.
6. Auf ein Plugin verweisen
Ein Pipeline-Schritt oder ein Plugin-Socket verweist auf ein Plugin über seine URI der Entität Plugin — die Identität der Entität, nicht direkt das Artefakt .wasm. Die Entität ist die Schicht, die die Digest-Fixierung, die Fähigkeitsansprüche, die Laufzeitgrenzen und die Signatur trägt; über den Verweis auf die Entität erhält ein Konsument all das.
Ein bloßer Pfad .wasm oder eine rohe Artefaktreferenz in einem Feld plugin wird beim Laden abgelehnt: Keine Entität Plugin passt dazu, sodass die Plugin-Auflösung laut fehlschlägt. Die Entitäts-URI ist zwingend — die Indirektion über die Entität ist der Vertrag, keine optionale Bequemlichkeit. Ein Pipeline-Schritt eines FeatureRecipe nennt die Entität in pipeline[].plugin; die Authoring-Oberfläche der Pipeline beschreibt ../entities/featurerecipe.md.
Wenn zwei oder mehr Plugins gekoppelt sind — sie müssen sich auf einen gemeinsamen Übergabevertrag einigen, wie bei einem Paar aus Fetcher und Injector, bei dem die Ausgabe des einen Plugins die Eingabe des anderen ist (das in plugin-contract.md beschriebene Prinzip des zweiteiligen Plugin) —, erstellen Sie diesen Vertrag einmal und lassen Sie jedes Plugin von der einen Definition abhängen, statt die JSON-Übergabeform in jedem Plugin unabhängig neu zu formulieren. Die gemeinsame Form ist die JSON-Struktur, die die Plugins austauschen, und sie kann in einem einzigen SchemaLibrary-Eintrag liegen, auf den beide Plugins verweisen. Eine einzige Quelle für den Vertrag hält gekoppelte Plugins synchron, während er sich weiterentwickelt; unabhängige Neuformulierungen driften auseinander, und die Abweichung zeigt sich erst, wenn die beiden zur Laufzeit nicht mehr übereinstimmen. Die Empfehlung lautet, den Vertrag zu teilen, nicht den Wasm-Code — jedes Plugin bleibt ein eigenes Artefakt.
7. Der Lebenszyklus publish → pull → build
Ein Plugin gelangt in drei Stufen von einer Datei .wasm auf der Festplatte zu einem verifizierten Artefakt, das ein Build konsumieren kann.
Publish. aggrega push veröffentlicht eine Entität Plugin und ihre Datei .wasm zusammen als ein einziges OCI-Manifest, getaggt mit metadata.version: Das YAML der Entität ist der Konfigurations-Blob im Manifest, und die Datei .wasm wird als Layer im selben Manifest mitgeführt. Das Paar als ein getaggtes Manifest zu veröffentlichen, macht den Push atomar — es gibt kein Zeitfenster, in dem eine Hälfte veröffentlicht ist und die andere nicht —, und deshalb deckt eine Signatur über dieses Manifest beide Hälften ab. Beide Hälften sind im Manifest benannt, sodass ein generischer OCI-Client, der das Versions-Tag abruft, die Entität nach entity.yaml und die ausführbare Datei nach entity.wasm schreibt.
Bevor Bytes landen, führt die Veröffentlichung ihre Prüfungen aus. Die Entität wird zuerst gegen das Schema Plugin gelesen, so wie ein Katalog-Ladevorgang sie liest, sodass ein metadata.version, das keine semantische Version ist — oder jede andere Abweichung vom Schema —, abgelehnt wird, bevor die Datei .wasm gelesen wird. Die Datei .wasm wird dann geladen, und ihre Selbstauskunft describe() wird mit den erstellten Fähigkeitsansprüchen der Entität abgeglichen — eine Abweichung führt zu einem lauten Abbruch, sodass eine veröffentlichte Entität nie beansprucht, was das mitgelieferte Plugin nicht meldet. Ein Guest, dessen Build-Provenienz-Version in describe() die Markierung -dirty trägt, mit der ein Build aus einem Arbeitsverzeichnis mit nicht committeten Änderungen versehen wird, wird abgelehnt: Diese Version nennt einen Commit, der nicht enthält, was gebaut wurde. Eine aus einem Commit gebaute Entwicklungsversion (1.0.0-3-g1a2b3c4) und eine Vorabversion (1.0.0-rc.1) werden veröffentlicht. Das festgehaltene metadata.version wird mit der Build-Provenienz-Version in describe() des Guests abgeglichen, und eine Abweichung bricht die Veröffentlichung ab, sodass beide übereinstimmen müssen. Beide Ablehnungen werden auf dieselbe Weise behoben: Bauen Sie das Plugin aus einem sauberen Checkout des Commits, den der Tag des Release nennt, sodass es selbst die Release-Version meldet — committen Sie für ein neues Release die Entität zusammen mit der Quelle, die es veröffentlicht, und taggen Sie zuerst diesen Commit. Die Version, die ein Entwicklungs-Build meldet, in die Entität zu kopieren, ist keine Reparatur: Damit wird dieser Build unter einer Version veröffentlicht, die kein Release-Tag nennt. Die Host-Funktionen, die die Datei .wasm importiert, werden aus der Binärdatei abgeleitet und mit dem in spec.runtime.hostFunctions committeten Eintrag verglichen; eine Abweichung bricht die Veröffentlichung ab und nennt aggrega plugin sync, das das Feld neu festhält, denn das Feld wird maschinell verwaltet, und eine Veröffentlichung schreibt die committete Entitätsdatei nie um. Die veröffentlichte Entität trägt den eingeprägten Eintrag der Host-Funktionen; der Inhaltsdigest der Datei .wasm gehört zu dem Manifest, als das das Paar veröffentlicht wird, und wird für einen Konsumenten in der Lockfile des Release festgehalten, statt in die Entität geschrieben zu werden.
Pull. aggrega pull löst alle Abhängigkeiten eines Release auf und schreibt eine Lockfile pro Release, die jede Katalogentität und jedes entfernte Artefakt auf eine Version und einen Inhaltsdigest fixiert. Ein veröffentlichtes Plugin wird über diese Abhängigkeitsauflösung aufgelöst; seine Datei .wasm wird mit dem Manifest abgerufen, das sie trägt, und die Bytes werden gegen den Inhaltsdigest geprüft, den die Lockfile festhält. Pull leitet außerdem die Host-Funktionen erneut aus der verifizierten Datei .wasm ab und prüft sie gegen den eingeprägten Eintrag hostFunctions, wobei es abbricht, wenn beide nicht übereinstimmen — eine Defense-in-Depth-Prüfung über der Digest-Fixierung, die eine Binärdatei erkennt, deren eingeprägter Eintrag nicht aus ihren eigenen Importen erzeugt wurde. Wenn die Vertrauensrichtlinie der Registry Signaturen verlangt, wird die Signatur der Entität in dieser Stufe abgerufen und geprüft und als verifizierte Tatsache in der Lockfile festgehalten (Abschnitt 8). Die Verifikation erfolgt beim Pull, nie beim Build — der Build bleibt ahead-of-time-rein.
Build. aggrega build konsumiert das fixierte, verifizierte Plugin aus den aufgelösten Abhängigkeiten. Der Compiler leitet die per Digest fixierte Referenz weiter, und die Wasm-Laufzeit führt die Bytes aus; die Ladeprüfung führt den Abgleich mit describe() sowie die Durchsetzung der Host-Funktionen und Laufzeitgrenzen erneut aus, bevor das Plugin läuft.
8. Signieren und Vertrauen
Eine Entität Plugin wird genau wie jede andere Katalogentität signiert: Der Manifestdigest wird signiert und als OCI-Referrer angehängt. Das Artefakt .wasm wird nicht separat signiert, und es braucht keine separate Signatur — es ist ein Layer in genau dem Manifest, dessen Digest signiert wird, sodass die Signatur es direkt abdeckt: Eine Manipulation an der Datei .wasm ändert den Manifestdigest und macht die Signatur ungültig.
Signieren erfolgt bei der Veröffentlichung auf Opt-in-Basis; die Verifikation wird von der Vertrauensrichtlinie pro Registry beim Pull durchgesetzt. Eine Registry, die so konfiguriert ist, dass sie Signaturen verlangt, bricht den Pull ab, wenn eine erforderliche Signatur fehlt, nicht vertrauenswürdig oder ungültig ist. Der Block spec.signature an der Entität ist ein Dokumentationsverweis darauf, wo die Signatur liegt und wie sie erzeugt wurde; er hält Fakten für Leser des Katalogs fest und regelt die Zulassung nicht selbst. Der Prüfpunkt ist die Richtlinie zur Pull-Zeit.
Die Befehle und ihre Flags sind bei den Oberflächen für Veröffentlichung und Konsum dokumentiert — siehe ../cli/aggrega-sign.md, ../cli/aggrega-push.md und ../cli/aggrega-pull.md. Dieser Leitfaden wiederholt die Flag-Tabellen nicht; diese Seiten sind der einzige Ort für die Befehlsoberfläche.
9. Die Entität versionieren
Eine Entität Plugin trägt in metadata.version eine strikte Semantic Version. Eine veröffentlichte Version ist unveränderlich: Eine Version, die in der Registry bereits existiert, mit anderem Inhalt erneut zu veröffentlichen, wird an der Veröffentlichungsprüfung abgelehnt.
Wenn Sie eine Plugin-Entität ändern und erneut veröffentlichen, klassifiziert die Veröffentlichungsdisziplin die Änderung gegenüber der zuvor veröffentlichten Version und verlangt, dass die Versionserhöhung dazu passt. Die Klassifizierung folgt der Rubrik für Versionserhöhungen: Eine Änderung nur an Dokumentation oder Kommentaren ist PATCH; eine rein additive Änderung (ein neues optionales Feld, ein neuer Eintrag) ist MINOR; eine Entfernung, eine Typeinschränkung oder ein zuvor optionales Feld, das erforderlich wird, ist MAJOR. Eine zu große Erhöhung ist immer erlaubt; eine zu kleine Erhöhung bricht mit einer Diagnose ab, die die erforderliche Erhöhung nennt. Die erste Veröffentlichung einer Entität überspringt die Prüfung der Erhöhung und gibt eine Warnung aus, dass keine Verifikation durchgeführt wurde. Führen Sie die Prüfung vor der Veröffentlichung mit aggrega lint --pre-publish aus; die vollständige Rubrik und die Einstellungen pro Regel beschreibt ../cli/aggrega-lint.md.
Ein Plugin hat keine Oberfläche extends, sodass die Vererbungsregeln, die die Components und Features des Katalogs bestimmen, es nicht erreichen. Die Rubrik für Versionserhöhungen und die Unveränderlichkeit sind die Versionierungsdisziplin, die eine Plugin-Entität bestimmt.
10. Querverweise
authoring-a-provider-walkthrough.md— ein Provider-Guest, durchgehend gebaut, von einem leeren Verzeichnis bis zur gerenderten Ausgabe.plugin-contract.md— die Socket-Punkte, auf die ein Plugin abzielt, und die Ein-/Ausgabeformen pro Socket.policy-socket.md— der Governance-Socket im Detail: seine vier Rollen, die Schweregrade von Verdikten, der Eingabekanal des Betreibers, das Schreiben einer Richtlinie für eine der beiden im Compiler mitgelieferten Engines und die Referenz-Guests für Richtlinien.core-importers.md— die eigenen Importer des Compilers, einer für jedes Format, das er liest, aufgebaut auf dem Importer-Paket des Go-Kits: was jeder liest, ihre Einstellungen und ihre Veröffentlichung mit jeder Compiler-Version.../compatibility.md— wie die Plugin-Kits versioniert werden und was dafür sorgt, dass ein Plugin, das gegen eine Version gebaut wurde, auch in der nächsten geladen wird.../entities/plugin.md— die Referenz der EntitätPluginFeld für Feld.../entities/featurerecipe.md— die Authoring-Oberflächepipeline:des FeatureRecipe, die per Entitäts-URI auf ein Plugin verweist.../cli/aggrega-lint.md— der publishing-linter, die Rubrik für Versionserhöhungen und die Durchsetzung der Unveränderlichkeit.../cli/aggrega-inspect.md— das Prüfen der Fähigkeiten, Laufzeitgrenzen und Signatur einer EntitätPlugin.../cli/aggrega-push.md,../cli/aggrega-pull.md,../cli/aggrega-sign.md— die Befehlsoberflächen für Veröffentlichung, Konsum und Signieren.