Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Plugin

Ein Plugin ist ein inhaltsadressiertes WebAssembly-Plugin: ein in OCI gehostetes .wasm-Artefakt, gepinnt über den sha256-Digest, das den Socket-Typ deklariert, den es implementiert, die ABI-Version, auf die es abzielt, einen optionalen Signaturzeiger und einen optionalen Runtime-Block. Die Entität ist die Authoring- und Metadatenoberfläche eines Plugins; die Abhängigkeitsauflösung pinnt das Artefakt über den Digest, und die Vertrauensrichtlinie pro Registry prüft seine Signatur beim Pull. Der Compiler interpretiert das Verhalten des Plugins nicht — er leitet die gepinnte Referenz weiter; die WebAssembly-Runtime führt die Bytes aus.

Diese Seite behandelt die Authoring-Oberfläche des Katalogs für Plugin Feld für Feld. Für den vollständigen Arbeitsablauf des Autors — was ein Plugin ist, die Selbstauskunft describe(), der Lebenszyklus publish→pull→build, Signierung und Versionierung — siehe den Entwicklerleitfaden für Wasm-Plugins. Für die Socket-Punkte, an die sich ein Plugin anbindet, und ihre Ein- und Ausgabeformen siehe den Wasm-Plugin-Vertrag.

Die Rolle des Plugin

Ein Plugin verknüpft eine logische Plugin-Identität mit einem konkreten .wasm-Artefakt und mit den Fähigkeits- und Runtime-Metadaten, die der Host benötigt, um es sicher zu laden und auszuführen. Ein Pipeline-Schritt oder ein Plugin-Socket referenziert die Entität über ihre URI; die Entität trägt die deklarierten Fähigkeiten, die Runtime-Limits und den Signaturzeiger, während der aufgelöste Inhalts-Digest in der Lockdatei des Release liegt. Der Ort der .wasm-Datei leitet sich aus der Identität des Plugins ab — der adressierbaren Koordinate plugin/<pluginType>/<name>, die sich ihrerseits aus metadata.pluginType und dem bloßen metadata.name zusammensetzt, plus der konfigurierten Registry — und ist kein geschriebenes Feld. Die Indirektion über die Entität ist zwingend — ein bloßer Verweis auf eine .wasm-Datei oder ein Artefakt wird beim Laden abgelehnt, weil keine Entität dazu passt.

Die Deklarationen eines Plugin sind nach Socket-Typ gruppiert, und mit dieser Gruppierung beginnt das Lesen der Entität:

  • Ein Block pro Socket-Typ — spec.provider, spec.pipelineStep, spec.parser, spec.importer. Ein Plugin trägt den einen Block, den sein metadata.pluginType nennt, und jeder Block enthält eine Liste capabilities: — von aggrega plugin gen-catalog aus dem eigenen describe() des Plugins erfasst —, deren Bedeutung allein diesem Block gehört: Bei einem Provider nennt die Liste die Fähigkeiten, die er bedient, bei einem Pipeline-Schritt die Provider-Fähigkeiten, mit denen sein Schritt kompatibel ist, und bei einem Parser und einem Importer nennt sie Quellformate, geschrieben parse:<format> und import:<format>. Die Einbettung trägt die Bedeutung — ein Fähigkeitseintrag ist nicht erreichbar, ohne zuerst den Block zu lesen, der sagt, um welche Art von Anspruch es sich handelt.
  • Ein Provider-Block enthält mehr als seine Liste — spec.provider deklariert außerdem, wie das Plugin die Workload-Art übersetzt, welche plattformnativen Annotationen es liest, und seinen Vertrag zum Render-Verhalten (spec.provider.contract: Eingabearten, Boundary-Zusammenstellung, Artefakt-Trennzeichen, Wiederverwendung von Instanzen). Diese beschreiben Render-Verhalten statt einer bedienten Dimension, weshalb sie neben der Fähigkeitsliste des Providers stehen und nicht darin.
  • Ein querschnittlicher Socket deklariert keine Fähigkeiten — ein linter-, governance- oder cli-Plugin trägt keinen der vier Blöcke, weil es keine Render-Dimension und kein Quellformat bedient.
apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
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 credential

metadata

Standard-Katalogmetadaten. name, version und pluginType sind erforderlich; version ist eine strikte Semantic Version (z. B. 1.2.0). Die optionalen Felder — description, maintainers, license, repository, home, keywords — folgen derselben Form, die jede Katalogentität trägt, und metadata akzeptiert keinen anderen Schlüssel. Eine veröffentlichte Version ist unveränderlich: Das erneute Veröffentlichen einer vorhandenen Version wird an der Veröffentlichungsprüfung abgelehnt.

metadata.name ist bloß — es trägt kein Socket-Präfix. Die adressierbare Koordinate des Plugins, plugin/<pluginType>/<name>, wird aus metadata.pluginType und dem bloßen metadata.name abgeleitet; sie wird nicht in den Namen geschrieben.

metadata.pluginType

Der Socket-Typ, den dieses Plugin implementiert. Er steht im Adressierungsblock neben name und version, weil er Teil der Identität des Plugins ist: Er liefert das Segment <pluginType> der abgeleiteten Koordinate plugin/<pluginType>/<name>. Ein Plugin implementiert genau einen Socket-Typ aus der Taxonomie der Plugin-Typen, die die Runtime erkennt:

  • provider — rendert IR-Knoten in providernative Artefakte.
  • linter — prüft geschriebene Inhalte und gibt Diagnosen aus.
  • pipeline-step — ein Schritt in der pipeline: eines FeatureRecipe oder eines Recipe, der die gerenderte Dokumentmenge patcht.
  • governance — erfüllt die Governance-Rollen der Build-Pipeline. Beim Topologieaufbau versieht es die Knoten des Topologiegraphen automatisch mit Labels und gibt JSON-Patch-Dokumente zurück, die der Host auf eine nur aus Labels bestehende Projektion des Graphen anwendet. Bei der statischen Analyse oder in der Render-Phase bewertet es den IR-Graphen oder die gerenderten Artefakte und gibt ein Urteil über Annahme oder Ablehnung zurück; eine nicht erfüllte Regel hält den Build an. Die Rolle, an die es angebunden ist, nicht sein Typ, legt fest, was es ausgeben darf.
  • parser — parst ein fremdes Quellformat (HCL, TOML, YAML, JSON, …) in einen strukturierten JSON-Baum, sodass ein Verbraucher, der ein Format lesen muss, das der Compiler nicht nativ parst, mit einem geparsten Baum statt mit dem Rohtext arbeitet.
  • importer — wandelt eine fremde Infrastruktur- oder Agentendefinitionsquelle in Entwürfe von Aggrega-Authoring-Dateien um und gibt die Formate, die es verarbeitet, als Fähigkeiten import:<format> bekannt.
  • cli — steuert einen Laufzeit-Unterbefehl aggrega <cmd> bei, den ein Betreiber auf der Kommandozeile aufruft. Ein Laufzeit-Socket, getrennt von den Render- und Pipeline-Sockets zur Kompilierzeit.

Erforderlich.

spec.abiVersion

Die Host/Guest-ABI-Version, auf die das Plugin abzielt. v1beta1 ist der akzeptierte Wert; eine neue ABI-Revision fügt einen hinzu. Erforderlich.

Fähigkeiten deklarieren: ein Block pro Socket-Typ

Eine Fähigkeit ist das, was ein Verbraucher von einem Plugin verlangt — eine Render-Fähigkeit, die ein Recipe anfordert, oder ein Quellformat, das ein Build lesen muss. Die Fähigkeiten eines Plugins werden in dem Block erfasst, der zu seinem Socket-Typ gehört, sodass der Block, in dem die Liste steht, festlegt, was ihre Einträge bedeuten:

metadata.pluginTypeWo seine Fähigkeiten deklariert werdenWas ein Eintrag nennt
providerspec.provider.capabilitiesEine Render-Fähigkeit, die dieses Plugin bedient, etwa helm oder compose.
pipeline-stepspec.pipelineStep.capabilitiesEin Provider, mit dessen gerenderter Ausgabe der Schritt dieses Plugins kompatibel ist.
parserspec.parser.capabilitiesEin Quellformat, das dieses Plugin liest, geschrieben parse:<format>.
importerspec.importer.capabilitiesEin fremdes Quellformat, aus dem dieses Plugin Entitäten entwirft, geschrieben import:<format>.
linter, governance, cli—Nichts. Diese Sockets bedienen keine Fähigkeit und tragen daher keinen der vier Blöcke.

Ein Plugin implementiert genau einen Socket-Typ, daher trägt seine Entität einen Block. Die Liste ist die eigene Auskunft des Plugins: aggrega plugin gen-catalog liest das describe() des Plugins und schreibt jede Fähigkeit, die es meldet, in den Block. Ein Autor kann die Liste vor dem Veröffentlichen einschränken und dabei eine Fähigkeit weglassen, die das Plugin meldet, die die veröffentlichte Entität aber nicht anbieten soll; aggrega validate <entity> --plugin <file.wasm> und aggrega push akzeptieren eine eingeschränkte Liste und geben einen Hinweis aus, der jede vom Plugin gemeldete Fähigkeit nennt, die die Liste weglässt. Keiner von beiden akzeptiert eine Liste, die eine Fähigkeit nennt, die das Plugin nicht meldet: Beide lehnen sie ab und nennen jede solche Fähigkeit sowie die Fähigkeiten, die das Plugin tatsächlich meldet, sodass eine veröffentlichte Liste nie mehr anbietet, als das Plugin bereitstellt. Eine pipeline-step-Entität, deren Plugin helm und helm-chart meldet und die zusätzlich compose auflistet, wird so abgelehnt:

[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()

Ein Verbraucher löst genau gegen das auf, was aufgelistet ist.

spec.provider

Der Provider-Socket-Block für ein Plugin mit pluginType: provider: die Fähigkeiten, die es bedient, wie es die plattformeigene Workload-Art aggrega.ai/v1beta1 übersetzt, welche plattformnativen Annotationen es liest, und sein Render-Verhaltensvertrag. Der Block ist bei jedem Provider-rendernden Plugin vorhanden und fehlt bei jedem anderen Plugin-Typ. Ein Provider, der nur Sourced- oder Artefaktinhalte ohne Workload-Synthese rendert, trägt den Block trotzdem — er deklariert dort seine Fähigkeiten und seinen Vertrag und lässt workloadSchema einfach weg.

spec.provider.capabilities

Die Fähigkeiten, die dieser Provider bedient — Fähigkeitsnamen wie helm oder compose —, deren Ausgabeform er rendert. Ein Provider ist generisch über Artefakte hinweg, die die Ausgabeform einer Fähigkeit teilen, nicht über alle Fähigkeiten hinweg, daher nennt die Liste die Fähigkeiten, die das Plugin selbst meldet: aggrega plugin gen-catalog erfasst sie aus dem describe() des Plugins, und ein Autor kann sie vor der Veröffentlichung einschränken. Einträge behalten die Reihenfolge, in der sie erfasst werden.

Das von einem Recipe angeforderte Provider-Ziel (spec.capability: helm) wird zu dem Provider-Plugin aufgelöst, dessen Liste dieses Ziel enthält. Wenn mehr als ein Provider-Plugin dasselbe Ziel listet, entscheidet der Workspace: Die Auswahl plugins.providers in der Workspace-Konfiguration nennt das zu verwendende Plugin, wird bei aggrega pull aufgelöst und in der Lockfile festgehalten. Ohne Auswahl und mit genau einem Kandidaten wird dieser Kandidat verwendet; ohne Auswahl und mit mehr als einem Kandidaten bricht der Build ab und nennt jeden Kandidaten. Mehrdeutigkeit wird pro Workspace an der Stelle der Verwendung aufgelöst statt durch eine katalogweite Eindeutigkeitsregel. Eine leere oder fehlende Liste deklariert keinen Fähigkeitsanspruch, sodass das Plugin kein Ziel bedient.

Ein Fähigkeitsname enthält hier keinen Doppelpunkt. Das spec.capability eines Recipe wird bis zu seinem letzten Doppelpunkt als Fähigkeit und danach als Versions-Pin gelesen, daher könnte ein Name, der einen Doppelpunkt enthält, niemals angefordert werden; ein Plugin, dessen describe() einen solchen Namen meldet, wird beim Laden abgelehnt, und aus ihm wird keine Entität zur Veröffentlichung erzeugt. Dasselbe gilt für die Provider-Fähigkeiten, die ein pipeline-step-Plugin listet. Der Doppelpunkt in parse:<format> eines Parsers und in import:<format> eines Importers ist Teil dieser Namen und bleibt erhalten.

spec.provider.workloadSchema

Eine Deklaration in JSON Schema 2020-12, die dokumentiert, wie dieser Provider die Workload-Art aggrega.ai/v1beta1 in native Manifeste des Providers übersetzt. Sie wird per Konvention bei einem Provider deklariert, der synthetisiert: Ein solcher Provider deklariert workloadSchema als dokumentierten Übersetzungsvertrag und beschreibt, welche Workload-Felder der Provider verarbeitet, welche geschlossenen Mengen jedes Enum-förmige Feld akzeptiert und welche Bereichsbeschränkungen gelten.

Der Body wird zu JSON Schema 2020-12 kompiliert, wenn das Plugin geladen wird — eine strukturelle Leitplanke, die ein fehlerhaftes Schema beim Laden statt beim Rendern ablehnt. Ob ein workload:-Recipe unterstützt wird, bestimmt die Synthesefähigkeit des gebundenen Providers, nicht das Vorhandensein dieses Feldes: Ein Recipe im synthetisierten Modus, das an einen Provider gebunden ist, der nicht synthetisieren kann, bricht zur Renderzeit mit einer deutlichen Meldung ab. Der Standardbibliothekskatalog hält workloadSchema mit der Fähigkeit des Providers synchron. Das Feld ist der dokumentierte Vertrag; nichts anderes liest es. Workload-Bodies selbst werden gegen das plattformeigene eingebettete Workload-Schema validiert, nicht gegen dieses providerspezifische Feld.

spec.provider.wellKnownAnnotations

Ein geordnetes Array, das die plattformnativen Well-known-Annotationsschlüssel aufzählt — jene unter dem reservierten Namespace aggrega.ai/ —, die dieser Provider liest, zusammen mit dem Verhalten, das angewendet wird, wenn einer davon fehlt. Jeder Eintrag trägt einen key (die vom Provider gelesene Annotation, z. B. aggrega.ai/namespace), einen purpose (was die Annotation steuert, wenn sie vorhanden ist), ein optionales defaultBehavior (was der Provider tut, wenn die Annotation fehlt) und ein optionales scope, das auflistet, wo der Provider den Schlüssel liest — sourced, synthesized oder artifactsStandalone, die Recipe-Eingabearten, oder boundary für einen Schlüssel, der einmal pro Grenze gelesen wird. key und purpose sind erforderlich; Einträge behalten die Reihenfolge des Autors.

Das Feld ist der Unterstützungsanspruch des Providers, und der Compiler liest es auf zwei Arten. Ein Eintrag, dessen scope eine Eingabeart nennt, die das contract.inputKinds desselben Blocks nicht beansprucht, widerspricht diesem Anspruch, und das Plugin wird unter Nennung des Schlüssels und des Scopes abgelehnt. Und wenn ein Build über diesen Provider rendert, erzeugt eine aggrega.ai/-Annotation, die kein Eintrag für irgendeine vom Rendern deklarierte Eingabeart abdeckt, eine Warnung, die den Schlüssel, den Provider und diese Eingabearten nennt; der Wert wird dennoch unverändert durchgereicht, und der Build bricht nicht ab. Fehlt das Feld, erhebt es keinerlei Anspruch, und für diesen Provider wird keine solche Warnung ausgegeben. Die Schemavalidierung prüft nur die Form jedes Eintrags (der Schlüssel liegt unter dem Namespace aggrega.ai/, purpose ist vorhanden); sie ist getrennt von der Laufzeitprüfung, die das Binden eines Werts in den reservierten Namespace regelt.

metadata:
pluginType: provider
spec:
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.

Die providerspezifischen Annotationsmengen und der workloadSchema-Inhalt, die die Provider der Standardbibliothek mitliefern, sind unter ../providers/well-known-annotations.md, ../providers/helm.md, ../providers/helm-chart.md und ../providers/compose.md dokumentiert.

spec.provider.readsNoWellKnownAnnotations

Deklariert, dass dieser Provider keinen der plattformnativen Well-known-Annotationsschlüssel liest. Es ist ein Unterstützungsanspruch, der keinen Schlüssel abdeckt, und er sagt etwas aus, was das Weglassen sowohl dieses Feldes als auch von wellKnownAnnotations nicht aussagt: Ein fehlender Anspruch ist Schweigen, während dieser die eigene Aussage des Providers ist, dass er nichts unter dem reservierten Namespace aggrega.ai/ liest. Ein Build, der über einen solchen Provider rendert, warnt vor jeder aggrega.ai/-Annotation, die das Rendern erreicht, und nennt den Schlüssel, den Provider und die vom Rendern deklarierten Eingabearten; der Wert wird dennoch unverändert durchgereicht, und der Build bricht nicht ab.

Nur true darf geschrieben werden, sodass das Weglassen des Feldes die einzige Möglichkeit bleibt, nichts auszusagen. Es kann nicht zusammen mit wellKnownAnnotations geschrieben werden: Ein Provider, der einige der Schlüssel liest, listet diese stattdessen dort. Beide Ablehnungen erfolgen auf Schemaebene, sodass das Plugin abgelehnt wird, wenn es gelesen wird.

spec:
provider:
capabilities:
- terraform
readsNoWellKnownAnnotations: true

Der Provider terraform der Standardbibliothek deklariert es; ../providers/terraform.md erläutert, was das für ein über ihn gerendertes Release bedeutet.

spec.provider.contract

Der selbstdeklarierte Render-Verhaltensvertrag eines Provider-rendernden Plugins zur Kompilierzeit: die Eingabearten, die es rendert, wie es die knotenweise Ausgabe einer Dispatch-Gruppe zusammensetzt, das Template-Begrenzerpaar, das es auf importierte Artefaktdateien anwendet, ob eine einzige geladene Instanz jeden Übergang bedienen darf, ob es Omit-Einträge berücksichtigt und ob es die Dateien akzeptiert, die ein Recipe zur gemeinsamen Ausgabe seiner Grenze beiträgt. Er steht neben capabilities im selben Block, beantwortet aber eine andere Frage: Die Fähigkeitsliste sagt, welche Fähigkeiten dieses Plugin bedient, während der Vertrag sagt, wie es sie rendert. aggrega plugin gen-catalog erfasst ihn aus der eigenen describe()-Selbstauskunft des Plugins, und der Host gleicht ihn bei der Veröffentlichung und beim Laden mit dieser Selbstauskunft ab; eine Abweichung führt zum Abbruch. Fehlt er, wird kein Render-Verhaltensvertrag deklariert, und der Abgleich vergleicht nur die exportbezogenen Ansprüche. Alle Felder sind optional.

FeldWirkung
inputKindsWelche der drei Recipe-Eingabearten das Plugin rendert, jeweils ein unabhängiger boolescher Anspruch: sourced (eine Menge von Quelldateien — ein Chart, ein Modul, eine Compose-Datei), synthesized (eine synthetisierte Workload) und artifactsStandalone (ein eigenständiger Knoten, der importierte Artefaktdokumente und weder eine Quelle noch eine Workload trägt). Der Host prüft die Eingabeart eines Knotens gegen diese Menge.
boundaryAssemblyWie das Plugin die knotenweise Render-Ausgabe einer Dispatch-Gruppe kombiniert: none schreibt die Ausgabe jedes Knotens direkt in den Dispatch-Pfad; merge führt die knotenweisen Fragmente zu einem Dokument zusammen; nest legt die Ausgabe jedes Knotens an ihrer eigenen Position in einer Umbrella-Struktur ab. Fehlt es, wird kein Zusammensetzungsanspruch erhoben.
artifactDelimitersDas Go-Template-Begrenzerpaar, das das Plugin auf importierte Artefaktdateien anwendet, als left und right. Fehlt es, gilt das Standardpaar {{/}}; ein Plugin, dessen Zielsyntax mit diesem Paar kollidiert, deklariert ein alternatives Paar (zum Beispiel [[/]]).
reusableInstanceOb eine einzige geladene Plugin-Instanz jeden Render-, Zusammensetzungs- und Validierungsübergang eines Builds bedienen darf statt einer frischen Instanz pro Übergang. Wird nur dann als true deklariert, wenn das Plugin keinen Zustand über Übergänge hinweg hält, sodass eine einzige Instanz byteidentische Ausgabe erzeugt, ob wiederverwendet oder frisch geladen. Fehlt es (false), wird pro Übergang eine frische Instanz geladen, was ein Plugin isoliert, das konstruktionsbedingt Zustand trägt. aggrega build --verify-determinism weist nach, dass die Ausgabe eines wiederverwendbaren Plugins stabil ist, indem jeder Knoten zweimal gerendert und bei jeder Abweichung abgebrochen wird.
omitsOb das Plugin Omit-Einträge berücksichtigt — Einträge, die gerenderte Einheiten nennen, die aus der Ausgabe eines Knotens wegzulassen sind: Es lässt jede Einheit, auf die ein Eintrag passt, aus dem Gerenderten weg und meldet, wie viele Einheiten jeder Eintrag getroffen hat. Der Wert hält den Anspruch fest, den das describe() des Plugins meldet, daher ist true nur für ein Plugin richtig, das ihn meldet, und ein Wert, der von der Meldung abweicht, führt zum Abbruch. Fehlt es (false), wird keine solche Unterstützung deklariert.
boundaryArtifactsOb das Ziel des Plugins die Dateien akzeptiert, die ein Recipe zur gemeinsamen Ausgabe der Grenze beiträgt, in der es rendert, unter spec.boundary.artifacts des Recipe: Der Compiler schreibt jede solche Datei einmal, neben das, was das Plugin für die Grenze zusammensetzt, und das Ziel liest sie als Teil dieser Ausgabe. Der Wert hält den Anspruch fest, den das describe() des Plugins meldet, und ein Wert, der von der Meldung abweicht, führt zum Abbruch. Fehlt es (false), wird keine solche Unterstützung deklariert, und ein Recipe, das den Block für dieses Plugin deklariert, wird abgelehnt, bevor irgendetwas gerendert wird.
metadata:
pluginType: provider
spec:
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: true

spec.pipelineStep

Der Pipeline-Step-Block für ein Plugin mit pluginType: pipeline-step. Sein einziges Feld, capabilities, nennt die Provider, deren gerenderte Ausgabe der Step des Plugins zu transformieren weiß — Fähigkeitsnamen wie helm oder compose. Ein Step wird jeweils gegen die Ausgabeform eines einzigen Providers geschrieben, daher nennt die Liste die Provider, die das Plugin selbst meldet; Einträge behalten die Reihenfolge, in der sie erfasst werden. Der Block ist nur bei Pipeline-Step-Plugins vorhanden.

Der Block ist die im Katalog lesbare Aufzeichnung dieses Anspruchs: aggrega plugin gen-catalog erfasst ihn aus der eigenen describe()-Selbstauskunft des Plugins, und ein Autor kann ihn vor der Veröffentlichung einschränken. Die Durchsetzung liest denselben Anspruch aus dem Plugin: Wenn ein Step einen Scope berührt, bricht der Build ab, sofern der Provider, der die Dokumente dieses Scopes rendert, nicht zu denen gehört, die das Plugin beansprucht. Eine leere oder fehlende Liste deklariert keinen Kompatibilitätsanspruch, sodass kein Scope den Step zulässt.

metadata:
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- helm
- compose

spec.parser

Der Parser-Block für ein Plugin mit pluginType: parser. Sein einziges Feld, capabilities, nennt die Quellformate, die das Plugin in einen kanonischen strukturierten Baum überführt, jeweils geschrieben als parse:<format>. Das Präfix ist Teil des Eintrags, daher listet ein Plugin, das mehrere Formate liest, einen Eintrag pro Format. aggrega plugin gen-catalog erfasst die Liste aus dem eigenen describe() des Plugins, ein Autor kann sie vor der Veröffentlichung einschränken, und Einträge behalten die Reihenfolge, in der sie erfasst werden. Der Block ist nur bei Parser-Plugins vorhanden.

Ein angefordertes Format wird zu dem Parser aufgelöst, dessen Liste den passenden Eintrag enthält. Ein Format, das kein Parser anbietet, bricht den Build ab, und ein Format, das mehr als ein Parser-Plugin anbietet, bricht als mehrdeutig ab und nennt die Kandidaten — es gibt keinen Fallback, weil ein Parser keinen konfigurationsfreien Standard hat, auf den er zurückgreifen könnte. Eine leere oder fehlende Liste deklariert keinen Formatanspruch, sodass das Plugin nichts parst.

metadata:
pluginType: parser
spec:
abiVersion: v1beta1
parser:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- parse:hcl
- parse:toml

spec.importer

Der Importer-Block für ein Plugin mit pluginType: importer. Sein Feld capabilities nennt die fremden Quellformate, die das Plugin in Entwürfe von Aggrega-Authoring-Dateien überführt, jeweils geschrieben als import:<format>. Das Präfix ist Teil des Eintrags, daher listet ein Plugin, das mehrere Formate verarbeitet, einen Eintrag pro Format. aggrega plugin gen-catalog erfasst die Liste aus dem eigenen describe() des Plugins, ein Autor kann sie vor der Veröffentlichung einschränken, und Einträge behalten die Reihenfolge, in der sie erfasst werden. Der Block ist nur bei Importer-Plugins vorhanden.

Ein angefordertes Importformat wird zu dem Importer aufgelöst, dessen Liste den passenden Eintrag enthält. Ein Format, das kein Importer anbietet, bricht den Import ab, und ein Format, das mehr als ein Importer-Plugin anbietet, bricht als mehrdeutig ab und nennt die Kandidaten, es sei denn, ein Eintrag plugins.importer in der Workspace-Konfiguration bindet einen von ihnen an, der dann ausgeführt wird. Eine leere oder fehlende Liste deklariert keinen Formatanspruch, sodass das Plugin nichts importiert.

Sein Feld detect hält die Signaturen fest, an denen eine Quelle dieser Formate erkannt wird, wenn ein Import kein Format nennt. Es gehört der Maschine, wie die Aufzeichnungen der Host-Funktionen und Befehle: Es wird aus dem abgeleitet, was das describe() des Plugins meldet, wenn die Entität aus dem Plugin erzeugt wird, in der Reihenfolge, in der das Plugin die Signaturen deklariert, und ein Autor schreibt es nicht. Jede Signatur nennt:

  • syntax — das syntaktische Format, in dem die Quelle geparst wird, also das Format, das ein Parser-Plugin als parse:<syntax> anbietet, etwa json oder yaml.
  • files — optionale Dateinamenmuster, die gegen das Ende des Quellnamens abgeglichen werden: ein Muster aus einem Segment gegen den eigenen Namen der Datei, eines aus mehreren durch Schrägstriche getrennten Segmenten gegen ebenso viele abschließende Segmente ihres Pfads, sodass .vscode/mcp.json auf eine Datei namens mcp.json in einem Verzeichnis namens .vscode passt. *, ? und [...] passen innerhalb eines Segments. Fehlt es, gilt die Signatur für eine Quelle, die aus einer einzigen Datei besteht, wie auch immer sie heißt, und für keine Datei eines Verzeichnisses. Die Muster der Signaturen eines Importers bestimmen auch, welche Dateien eines Verzeichnisses aggrega import ihm übergibt.
  • match — die Prädikate, die der geparste Baum erfüllen muss, und zwar alle. Jedes hat einen path, durch Punkte verbundene Schlüssel ab der Wurzel des Baums, wobei ein ganzzahliges Segment eine Array-Position auswählt; ein is, einen der Werte present, absent, object, array, string, number und boolean; und optional equals, eine Zeichenkette, die der Wert sein muss, oder prefix, eine Zeichenkette, mit der er beginnen muss — höchstens eines von beiden.

Wenn ein Import kein Format nennt, werden die Signaturen jedes Importers, den der Katalog des Workspace enthält — jede Version eingeschlossen —, und der Core-Importer des Compilers mit der Quelle abgeglichen. Die Quelle wird für jede Syntax, in der eine auf ihren Namen anwendbare Signatur sie liest, einmal geparst, und zwar über den Parser, den der Katalog des Workspace für diese Syntax bereitstellt — oder, für eine Syntax, für die der Katalog keinen Parser bereitstellt, über den, den der Compiler selbst mitbringt —, und eine Quelle, die sich in einer Syntax nicht parsen lässt, passt auf keine Signatur, die diese Syntax nennt. Ein Verzeichnis wird über seine Dateien abgeglichen: Jede Signatur wird gegen die Dateien des Verzeichnisses ausprobiert, die ihre Muster auswählen, in Namensreihenfolge, und eine Signatur, die kein Muster deklariert, gilt für keine von ihnen. Eine Quelle, auf die eine Signatur passt, wird als jedes Format erkannt, das ihr Importer anbietet. Wird genau ein Format erkannt, wird die Quelle in diesem Format gelesen. Eine Quelle, auf die keine Signatur passt, wird abgelehnt, mit der Aufforderung, das Format anzugeben, und unter Nennung der Formate, die die Importer anbieten — oder, bei einem Verzeichnis, mit der Aufforderung, eine seiner Dateien einzeln oder ein Format anzugeben, dessen Importer Dateimuster deklariert, wobei nur diese genannt werden; eine Quelle, die als mehr als ein Format erkannt wird, wird unter Nennung dieser Formate abgelehnt, mit der Bedingung More than one importer recognises the source (Mehr als ein Importer erkennt die Quelle). Bei einem Importer, der mehr als ein Format anbietet, wird also jede Quelle, auf die seine Signaturen passen, als mehrdeutig abgelehnt, und ein Importer, dessen Quellen erkannt werden sollen, bedient ein einziges Format.

Wo die Entität detect festhält, muss es dem entsprechen, was das describe() des Plugins meldet, Signatur für Signatur und in derselben Reihenfolge: Das Laden des Importers lehnt ein Plugin ab, dessen Meldung abweicht, unter Nennung von importer.detect, und ebenso dessen Veröffentlichung. Eine Entität, die kein detect festhält, erhebt keinen Anspruch und wird nicht verglichen, sodass sie alle Signaturen lädt, die das describe() ihres Plugins meldet, und die Formate ihres Importers sind dann nur erreichbar, indem man sie nennt.

metadata:
pluginType: importer
spec:
abiVersion: v1beta1
importer:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- import:langflow
detect:
- syntax: json
match:
- path: data.nodes
is: array

spec.signature

Ein optionaler beschreibender Verweis auf die angehängte Signatur des Plugins. Der Block dient nur der Dokumentation — er hält für Katalogleser fest, wo die Signatur liegt und wie sie erzeugt wurde; er lässt das Plugin nicht selbst zu. Die durchsetzende Prüfung ist die beim Pull angewendete Vertrauensrichtlinie pro Registry: Eine Signatur wird als OCI-Referrer abgerufen, gegen die vertrauenswürdigen Identitäten oder den festgelegten Schlüssel der Registry verifiziert und als verifizierte Tatsache in der Lockfile festgehalten. Eine Registry, die Signaturen verlangt, bricht den Pull ab, wenn eine erforderliche Signatur fehlt, nicht vertrauenswürdig oder ungültig ist.

  • type — das Signaturschema. sigstore-cosign ist das unterstützte Schema. Erforderlich, wenn der Block vorhanden ist.
  • signatureRef — die OCI-Referrer-Referenz des angehängten Signatur-Bundles, für Dokumentation und Auffindbarkeit. Fehlt, wenn die Signatur beim Pull durch Aufzählung der Referrer gefunden statt hier festgelegt wird.
  • publicKeyRef — ein Verweis auf den öffentlichen Schlüssel, mit dem die Signatur erzeugt wurde, für eine schlüsselbasierte Signatur. Fehlt er, handelt es sich um eine schlüssellose Signatur (OIDC-Identität), die gegen die vertrauenswürdigen Identitäten der Registry verifiziert wird.

spec.runtime

Optionale Ausführungsbeschränkungen, die der Host beim Laden und Ausführen des Plugins anwendet. Ausgehender Netzwerkzugriff ist kein Authoring-Feld: Ein Plugin greift zur Build-Zeit nie auf das Netzwerk zu — die Ahead-of-Time-Grenze —, daher gibt es hier kein Feld für eine Host-Allowlist. Entfernte Inhalte, die ein Plugin benötigt, kommen über den vom Host vermittelten, per Digest festgelegten Kanal für externe Eingaben, der in der Lockfile des Release festgehalten wird, nie über allgemeinen Netzwerkzugriff; der Entwicklerleitfaden dokumentiert den Fetch-Wrapper und die Pinning-Disziplin.

FeldWirkung
maxMemoryPagesBegrenzt den linearen Speicher des Plugins in Wasm-Seiten (64 KiB pro Seite). Null oder fehlend wendet die Standardobergrenze der Plattform an, sodass ein Ladevorgang nie unbegrenzt ist; eine Anbindung, die mehr benötigt, erhöht diesen Wert.
timeoutMsBegrenzt, wie lange der eigene Code des Plugins während eines Aufrufs laufen darf, in Millisekunden, ohne die Zeit innerhalb der Host-Funktionen, die er aufruft. Unter Linux wird die Prozessorzeit gemessen, sodass die Wartezeit auf einen Prozessor auf einer ausgelasteten Maschine nicht zählt; auf anderen Systemen ist es die verstrichene Zeit. Beim ersten Aufruf eines frisch geladenen Plugins zählt auch der eigene Start des Plugins mit. Null oder fehlend wendet die Standardobergrenze der Plattform an, sodass ein Aufruf nie unabbrechbar ist; eine Anbindung, die länger läuft, erhöht diesen Wert.
hostFunctionsDie Namen der Host-Funktionen, die das Plugin importiert. Maschinell abgeleitet und schreibgeschützt — verfassen Sie es nicht selbst: aggrega plugin sync liest die Host-Funktionen aus dem Import-Abschnitt der .wasm und hält dieses Feld fest, die Veröffentlichung lehnt eine Aufzeichnung ab, die von der Binärdatei abweicht, und der Wert spiegelt die veröffentlichte Binärdatei wider, validiert gegen die kuratierte Allowlist. Der Host registriert genau diese Menge und gibt jedem Plugin die Host-Oberfläche mit den geringsten Rechten, die seine Binärdatei benötigt; der Pull leitet den Stempel erneut ab und verifiziert ihn gegen die Binärdatei. Um den Wert vor der Veröffentlichung in der Vorschau zu sehen, führen Sie aggrega inspect --plugin <file.wasm> aus.
configKVPlugin-spezifische Konfiguration, die die Laufzeitumgebung dem Plugin beim Start übergibt, als Schlüssel/Wert-Paare von Zeichenkette zu Zeichenkette. Einträge behalten die Reihenfolge des Autors, damit der ausgegebene Datensatz über Läufe hinweg byteidentisch ist. Fehlt sie, bleibt die leere Standardkonfiguration der Laufzeitumgebung in Kraft.

spec.exports

Die Exporte, die das Plugin anbietet, jeweils mit ihrer deklarierten Fähigkeit, als geordnete Liste, die die Reihenfolge des Autors beibehält. Ein Export ist ein benannter Einstiegspunkt, an den der Host weiterleitet (zum Beispiel render_node, lint_naming, step); der Fähigkeitsblock pro Export gibt an, was dieser Export tut, wie aggrega plugin gen-catalog ihn aus der describe()-Selbstauskunft des Plugins erfasst, und der Host gleicht ihn bei der Veröffentlichung und beim Laden mit dieser Selbstauskunft ab. Fehlt die Liste, wird keine verfasste Export-Oberfläche deklariert.

FeldWirkung
nameDer ABI-Name des Exports — der Name, an den der Host weiterleitet. Für jeden Eintrag erforderlich.
operatesDie Pipeline-Operation, die der Export ausführt: patch (ein vorhandenes gerendertes Dokument ändern) oder emit (ein neues Dokument hinzufügen). Der Host gleicht den Wert mit der Selbstauskunft des Plugins ab; er ist ein validierter Fähigkeitsanspruch, kein Dispatch-Schalter — die Operation, die ein Step ausführt, wird durch das vom Guest zurückgegebene Ergebnis bestimmt. Fehlt er, wird kein Operationsanspruch erhoben.
scopeDie Dokumentwurzel, auf der der Export arbeitet: own (die eigenen gerenderten Dokumente des Knotens) oder host (die Dokumente der Komponente, an die ein FeatureRecipe mit Komponenten-Scope angehängt ist). Der Host liest den deklarierten Scope vor dem Step, um die Provider-Kompatibilität gegenüber dem Provider durchzusetzen, der diesen Scope rendert. Fehlt er, ist der Standardwert own.
selectorEine frei formulierte, menschenlesbare Beschreibung dessen, worauf der Export wirkt (zum Beispiel workloads carrying a pod template). Dokumentation für Katalogleser und die Inspect-Oberfläche; der Compiler interpretiert sie nicht.

spec.commands

Die Top-Level-Verben aggrega <command>, die ein cli-Plugin beisteuert, als geordnete Liste, die die Reihenfolge beibehält, die die describe()-Selbstauskunft des Plugins deklariert. Maschinell verwaltet und schreibgeschützt — nicht selbst verfassen. aggrega plugin sync liest die Befehlsoberfläche aus der describe()-Selbstauskunft des Plugins und hält sie hier fest, sodass die Befehle, die ein CLI-Plugin installiert, aus der Entität lesbar sind, ohne die .wasm zu laden. Ein Nicht-cli-Plugin steuert keine Befehle bei und hält eine leere Liste fest. Der Host installiert genau diese Menge; eine festgehaltene Menge, die von der describe()-Selbstauskunft des Plugins abweicht, bricht beim Laden ab, und die Veröffentlichung lehnt eine Menge ab, die nicht mit der Binärdatei synchron ist, und fordert den Autor auf, sie erneut festzuhalten. Um den Eintrag nach einer Änderung am Plugin neu zu synchronisieren, führen Sie aggrega plugin sync aus.

Jeder Befehlseintrag enthält:

FeldWirkung
nameDas Befehlsverb, das der Host registriert — das Token aggrega <name>, das ein Operator aufruft, und der Diskriminator, den der Host dem Plugin beim Aufruf übergibt, damit ein einzelnes Plugin, das mehrere Befehle bereitstellt, anhand des aufgerufenen Befehls verzweigen kann. Für jeden Eintrag erforderlich.
descriptionDer einzeilige Kurzhilfetext des Befehls, angezeigt in der Befehlsübersicht und in der Hilfeausgabe. Nur Dokumentation; der Host reagiert nicht darauf.
flagsDie Flags des Befehls in deklarierter Reihenfolge. Jeder Eintrag registriert ein Flag am Befehl, sodass aggrega help <command> es wie das Flag eines Kernbefehls darstellt. Ein Befehl ohne Flags lässt es leer.

Jeder flags-Eintrag deklariert ein Flag:

FeldWirkung
nameDer lange Name des Flags — das Token --name, das ein Operator auf der Befehlszeile übergibt. Für jeden Eintrag erforderlich.
shorthandDer optionale kurze Alias des Flags — die Form -x, die ein Operator anstelle des langen Namens übergeben kann — als einzelner ASCII-Buchstabe oder einzelne Ziffer. Fehlt er, hat das Flag keinen kurzen Alias.
descriptionDer einzeilige Hilfetext des Flags, angezeigt in der Hilfeausgabe des Befehls. Optionale Dokumentation; der Host validiert ihn weder, noch reagiert er darauf.
typeDer Werttyp des Flags — string, bool oder int — und die Art von Flag, als die die Hilfe es darstellt. Fehlt er, wird es als String-Flag dargestellt.
defaultDer Standardwert des Flags, wenn der Operator es nicht übergibt, als String angegeben. Bei einem bool- oder int-Flag ist er ein Wert dieses Typs. Fehlt er, deklariert das Flag keinen Standardwert.

Ein CLI-Plugin deklariert seine Befehle und deren Flags in describe(); der Host registriert genau diese Oberfläche und stellt die Flags jedes Befehls in aggrega help <command> auf dieselbe Weise dar wie die Flags eines integrierten Befehls.

Der Host prüft jedes Flag, das ein Plugin deklariert, wenn er die Befehle des Plugins hinzufügt, und ein Plugin, dessen Deklarationen die Prüfung nicht bestehen, wird übersprungen statt hinzugefügt: Keiner seiner Befehle wird registriert, eine Warnung nennt das Plugin, den Befehl, das Flag und was daran falsch ist, und jeder andere Befehl — integriert oder aus einem anderen Plugin — funktioniert weiter. Eine Deklaration besteht die Prüfung nicht, wenn:

  • ein Flag keinen Namen hat oder ein Befehl denselben Namen zweimal deklariert;
  • ein Kurzname etwas anderes als ein einzelner ASCII-Buchstabe oder eine einzelne Ziffer ist oder ein Befehl denselben Kurznamen für zwei Flags deklariert;
  • ein Name oder Kurzname ein Flag wiederverwendet, das jeder aggrega-Befehl bereits hat — --help, sein -h und die globalen Flags wie --offline und --config;
  • ein Typ etwas anderes als string, bool oder int ist;
  • ein Standardwert sich nicht als Typ des Flags parsen lässt — maybe für ein bool, three für ein int.

Die Einzelzeichenform von shorthand und die drei Werte von type sind auch Teil des Schemas dieser Entität, sodass eine Plugin-Entität, die einen anderen Wert festhält, beim Laden des Katalogs abgelehnt wird. Dass ein Name oder Kurzname einmal pro Befehl vorkommt, dass keiner ein Flag wiederverwendet, das jeder Befehl hat, und dass sich ein Standardwert als sein Typ parsen lässt, prüft allein der Host. Die Prüfung deckt ab, ob der Host ein Flag für die Hilfe so deklarieren kann, wie es geschrieben ist; sie sieht nicht, ob das Plugin die Flags liest, die es deklariert, denn das Plugin parst seine eigenen Argumente.

metadata:
pluginType: cli
spec:
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: world

Ein Plugin untersuchen

aggrega inspect <path-to-Plugin.yaml> stellt eine Plugin-Datei dar: ihre Identität und ihren Socket-Typ, die Fähigkeiten, die ihr Block deklariert, die Fähigkeitstabelle pro Export in Autorenreihenfolge, die Laufzeitbeschränkungen und — bei --detail — den Signaturverweis und die Laufzeit-Konfigurationsschlüssel. Ein Plugin ist über den Dateipfad adressierbar oder über seine Koordinate <pluginType>/<name> im Katalog. Siehe ../cli/aggrega-inspect.md.

Querverweise

  • Entwicklerleitfaden für Wasm-Plugins — der durchgängige Arbeitsablauf für Autoren: describe(), Fähigkeitsangaben, Laufzeitlimits, Lebenszyklus, Signierung, Versionierung.
  • Vertrag für Wasm-Plugins — die Socket-Punkte, an die sich ein Plugin anbindet, und ihre Eingabe- und Ausgabeformen.
  • entities/featurerecipe.md — die pipeline:-Oberfläche des FeatureRecipe, die ein Plugin per Entitäts-URI referenziert.
  • cli/aggrega-lint.md — der Veröffentlichungs-Linter, die Kriterien für Versionserhöhungen und die Durchsetzung der Unveränderlichkeit, die die Veröffentlichung eines Plugin regeln.