Einen Provider schreiben: eine Schritt-für-Schritt-Anleitung mit Beispiel
Diese Seite führt durch die gesamte Aufgabe, einen Provider-Guest zu schreiben, von einem leeren Verzeichnis bis zu einem Build, der Dateien schreibt, die der Provider gerendert hat. Sie ist das praktische Gegenstück zum Plugin-Entwicklerhandbuch, das die Entität und den Lebenszyklus dokumentiert, und zum Plugin-Vertrag, der die Sockets dokumentiert.
Der hier gebaute Provider ist klein genug, um ihn in einem Zug zu lesen, und leistet echte Arbeit: Er rendert Umgebungsdateien. Dieses Ziel eignet sich gut als erster Provider, weil seine Übersetzung wirklich formatspezifisch ist — eine Umgebungsdatei hat ihre eigene Schlüsselgrammatik, ihre eigenen Regeln für Anführungszeichen und keinen Metadatenblock, in dem die Build-Herkunft abgelegt werden könnte —, sodass der Guest jede Entscheidung treffen muss, die ein größerer Provider trifft, ohne dass ein großer Codeumfang sie verbirgt.
Zu den Blöcken auf dieser Seite. Jeder Block, der eine Ausgabe zeigt, wurde aus einem echten Durchlauf der folgenden Schritte kopiert, in der Reihenfolge, in der sie erscheinen, gemäß der Ausgabekonvention: Ein Block ist entweder vollständig oder ein Auszug, der kennzeichnet, wo Zeilen weggelassen wurden. Dies ist ein Rundgang, den Sie selbst zusammenstellen, kein Workspace, den Sie klonen können, daher sind die Quellblöcke die Dateien, die Sie anlegen, und keine Dateien zum Auschecken.
Was Sie brauchen
- Die Go-Toolchain, die ohne zusätzliche Werkzeuge nach WebAssembly kompiliert.
- Ein Checkout des Plugin-Entwicklungskits, das das Plugin-Entwicklerhandbuch vorstellt, und des ABI-Pakets, auf dem das Kit aufbaut: Das
go.moddes Guests weiter unten verweist auf beide. - Die Binärdatei
aggrega.
Die Struktur des fertigen Ergebnisses
Ein Provider besteht aus zwei Artefakten: einem Guest im Format .wasm und einer Entität vom Typ Plugin, die ihn in einen Katalog bringt. Sonst nichts — keine Änderung am Host, keine Registrierung, kein Build des Compilers. Einen Provider hinzuzufügen heißt, diese zwei Dateien dort abzulegen, wo ein Build sie sehen kann.
Der Workspace, mit dem dieser Rundgang endet:
dotenv-walkthrough/ guest/ the Go module that compiles to the .wasm go.mod go.sum main.go catalog/ the Component and Recipe you author component/example/compute/checkout/1.0.0/component.yaml recipe/dotenv/checkout/1.0.0/recipe.yaml dev-catalog/ the generated Plugin entity, with the .wasm beside it plugin/provider/dotenv/0.1.0/plugin.yaml plugin/provider/dotenv/0.1.0/provider--dotenv.wasm dotenv.wasm the compiled guest overlay.yaml the identity you supply to the entity generator aggregate.yaml manifest.yaml release.yaml .aggrega-config.yaml1. Die Selbstauskunft des Guests
Jedes Plugin exportiert describe(). Der Host ruft es einmal auf, wenn er den Guest lädt, und liest die Antwort als die eigene Darstellung des Guests davon, was er ist. Für einen Provider zählen vier Teile dieser Antwort.
Legen Sie guest/main.go an:
// A provider guest that renders environment-file artifacts.package main
import ( "bytes" "fmt" "sort" "strings"
pdk "github.com/extism/go-pdk"
"github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega")
func descriptor() aggrega.PluginDescriptor { return aggrega.PluginDescriptor{ AbiVersion: aggrega.APIVersion, PluginType: "provider", Description: "Render artifact bodies into environment files, quoting and escaping each value as the format requires.", Capabilities: []string{"dotenv"}, Exports: []aggrega.PluginExport{ {Name: "render_node"}, }, Metadata: &aggrega.PluginDescriptorMeta{License: "Apache-2.0"}, }}
//go:wasmexport describefunc describe() int32 { out, err := aggrega.MarshalDescriptor(descriptor()) if err != nil { pdk.SetError(err) return 1 } pdk.Output(out) return 0}PluginType gibt an, welchen Socket dieser Guest bedient. Capabilities ist die Liste, gegen die ein Recipe aufgelöst wird: Ein Recipe, dessen spec.capability dotenv ist, wird an diesen Guest geleitet. Exports benennt die Einstiegspunkte, an die der Host weiterleiten darf; render_node ist derjenige, den jeder Provider haben muss.
Dieser Deskriptor ist absichtlich unvollständig, so wie es ein erster Entwurf meist ist. Der erste Build weiter unten ist die Stelle, an der sich das zeigt.
2. Einen Knoten rendern
render_node wird einmal pro Komponente aufgerufen, die der Build über diesen Provider rendert. Es erhält die Identität des Knotens, den Render-Kontext und die vorab ausgewerteten Eingaben, die das gebundene Recipe deklariert hat — hier eine Artefaktmenge, die der Host bereits gelesen und als Template ausgewertet hat.
Die ganze Aufgabe des Guests besteht darin zu entscheiden, welche Bytes herauskommen. Fügen Sie zu guest/main.go hinzu:
// needsQuoting reports whether a value cannot be written bare in an// environment file. A bare value ends at the first space, so anything// carrying whitespace has to be quoted; the quote characters, the comment// introducer and the expansion introducer would each be read as syntax.func needsQuoting(v string) bool { if v == "" { return true } return strings.ContainsAny(v, " \t\n\r\"'#$\\")}
// quote wraps a value in double quotes and escapes what the format reads as// syntax inside them. Order matters: the backslash is escaped first, or the// escapes introduced afterwards would be escaped a second time.func quote(v string) string { v = strings.ReplaceAll(v, `\`, `\\`) v = strings.ReplaceAll(v, `"`, `\"`) v = strings.ReplaceAll(v, "\n", `\n`) v = strings.ReplaceAll(v, "\r", `\r`) v = strings.ReplaceAll(v, "\t", `\t`) return `"` + v + `"`}
// normaliseKey maps an authored key into the environment-variable grammar:// upper case, with the separators an author reaches for folded to// underscores. It reports an error rather than correcting a key that still// does not fit, because a silently-renamed variable is one the application// never reads.func normaliseKey(k string) (string, error) { n := strings.ToUpper(k) n = strings.NewReplacer("-", "_", ".", "_", "/", "_").Replace(n) if n == "" { return "", fmt.Errorf("empty key") } for i, r := range n { switch { case r >= 'A' && r <= 'Z', r == '_': case r >= '0' && r <= '9' && i > 0: default: return "", fmt.Errorf("key %q maps to %q, which is not a valid environment-variable name", k, n) } } return n, nil}Drei Entscheidungen in diesem Fragment gehören dem Provider selbst, und keine andere Schicht könnte sie treffen. Welche Zeichen Anführungszeichen erzwingen, ist eine Tatsache über Umgebungsdateien. Ebenso die Grammatik der Variablennamen, und ebenso die Entscheidung, einen Schlüssel, der nicht passt, zurückzuweisen, statt ihn umzubenennen — eine umbenannte Variable ist eine, die die Anwendung suchen und nicht finden wird, was schlimmer ist als ein abgebrochener Build.
Nun die beiden verbleibenden Teile: wohin die Herkunftsangaben gehen, und der Export selbst.
// provenanceComment renders the build-provenance key set the host computed as// comment lines. An environment file has no metadata block, so a comment// header is where provenance can go; the keys are emitted in sorted order so// the bytes are identical across runs of identical input.func provenanceComment(annotations map[string]string) []byte { if len(annotations) == 0 { return nil } keys := make([]string, 0, len(annotations)) for k := range annotations { keys = append(keys, k) } sort.Strings(keys) var out bytes.Buffer for _, k := range keys { fmt.Fprintf(&out, "# %s=%s\n", k, annotations[k]) } out.WriteByte('\n') return out.Bytes()}
// renderBody translates one artifact body into environment-file lines. A// blank line and a comment pass through untouched; every other line is// KEY=value, and a line carrying no separator is a loud failure rather than a// line the guest guesses at.func renderBody(name string, body []byte) ([]byte, error) { var out bytes.Buffer for i, raw := range strings.Split(string(body), "\n") { line := strings.TrimSpace(raw) if line == "" || strings.HasPrefix(line, "#") { continue } k, v, found := strings.Cut(line, "=") if !found { return nil, fmt.Errorf("%s line %d: %q declares no value; an entry is KEY=value", name, i+1, line) } key, err := normaliseKey(strings.TrimSpace(k)) if err != nil { return nil, fmt.Errorf("%s line %d: %w", name, i+1, err) } val := strings.TrimSpace(v) if needsQuoting(val) { val = quote(val) } fmt.Fprintf(&out, "%s=%s\n", key, val) } return out.Bytes(), nil}
//go:wasmexport render_nodefunc render_node() int32 { var in aggrega.RenderNodeInput if err := in.DecodeCBOR(pdk.Input()); err != nil { pdk.SetError(fmt.Errorf("dotenv: decode RenderNodeInput: %w", err)) return 1 }
if in.ArtifactsProjection == nil || len(in.ArtifactsProjection.Entries) == 0 { pdk.SetError(fmt.Errorf("dotenv: node %q supplied no artifacts to render", in.Node.ID)) return 1 }
var files []aggrega.RenderedFile for _, e := range in.ArtifactsProjection.Entries { body, err := renderBody(e.Name, e.Content) if err != nil { pdk.SetError(fmt.Errorf("dotenv: %w", err)) return 1 } files = append(files, aggrega.RenderedFile{ Path: e.Name, Content: append(provenanceComment(e.Annotations), body...), Format: "text", }) }
outputBytes, err := aggrega.RenderNodeOutput{Files: files}.EncodeCBOR() if err != nil { pdk.SetError(fmt.Errorf("dotenv: encode RenderNodeOutput: %w", err)) return 1 } pdk.Output(outputBytes) return 0}
func main() {}Die Payload wird in einer binären Kodierung übergeben, und das Kit liest und schreibt sie. Der Host übergibt render_node seine Eingabe als kanonisches CBOR und liest die Antwort in derselben Kodierung, daher dekodiert der Guest mit DecodeCBOR des Eingabetyps und kodiert mit EncodeCBOR des Ausgabetyps — keine CBOR-Bibliothek und nichts von Hand geparst. Der Content einer Datei ist ein Byte-Slice, das der Guest mit genau den zu schreibenden Bytes füllt; der Encoder transportiert sie als Rohbytes, und der Host schreibt sie unverändert.
Der Host übergibt dem Guest Inhalte, die er bereits ausgewertet hat. Der Content jedes Artefakteintrags ist der verfasste Rumpf, dessen Template-Ausdrücke bereits gegen den Render-Kontext aufgelöst sind — der Guest wertet nie ein Template aus und liest nie eine Datei. Genau das hält die Ahead-of-Time-Grenze des Compilers intakt: Der Guest ist eine reine Funktion von der Payload zu Bytes.
Determinismus liegt in der Verantwortung des Guests. In einem gewöhnlichen Build prüft ihn nichts für Sie. Hier entsteht er dadurch, dass die Herkunftsschlüssel vor der Ausgabe sortiert und die Artefakteinträge in der Reihenfolge durchlaufen werden, in der die Payload sie enthält, und die Prüfungen gegen Ende dieser Seite messen das Ergebnis.
guest/go.mod verweist auf Ihren Checkout des Kits:
module example.com/dotenv-provider
go 1.26.0
require ( github.com/aggrega-ai/aggrega-pdk/go v0.0.0 github.com/extism/go-pdk v1.1.3)
require github.com/aggrega-ai/aggrega-abi/go v0.0.0 // indirect
replace github.com/aggrega-ai/aggrega-pdk/go => /path/to/aggrega-pdk/go
replace github.com/aggrega-ai/aggrega-abi/go => /path/to/aggrega-abi/go3. Den Guest bauen
Ein Guest ist ein gewöhnlicher Go-Build mit ausgewähltem WebAssembly-Ziel:
cd guestgo mod tidyGOWORK=off GOOS=wasip1 GOARCH=wasm go build -trimpath -buildvcs=false \ -ldflags "-X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Version=0.1.0 \ -X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Commit=walkthru" \ -buildmode=c-shared -o ../dotenv.wasm ./go mod tidy schreibt go.sum, die Prüfsummen der Abhängigkeiten, ohne die der Build die Ausführung verweigert. -trimpath und -buildvcs=false halten Build-Pfade und Versionskontroll-Stempel aus der Binärdatei heraus, sodass dieselbe Quelle beim selben Commit dieselben Bytes erzeugt. Die beiden Werte von -ldflags stempeln die eigene Version des Guests in ihn ein, die der nächste Schritt liest.
Prüfen Sie die Exporte, bevor Sie weitermachen:
aggrega inspect --plugin dotenv.wasmPlugin .wasm: dotenv.wasmExports: render_nodehostFunctions (derived from binary, not yet recorded by aggrega plugin sync): (none)Dieser Guest importiert keine Host-Funktionen, was der Standard nach dem Prinzip der geringsten Rechte ist: Er braucht weder das Dateisystem noch das Netzwerk, weil alles, was er rendert, in der Payload ankommt.
4. Die Plugin-Entität erzeugen
Die Vertragsfelder der Entität werden nicht von Hand geschrieben — sie werden aus dem Guest ausgelesen, damit die Entität nichts versprechen kann, was die Binärdatei nicht tut. Sie liefern nur die Identität, in einer kleinen Überlagerung.
overlay.yaml:
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: dotenvaggrega plugin gen-catalog --plugin dotenv.wasm \ --overlay overlay.yaml --output-dir dev-catalog/plugingenerated dev-catalog/plugin/provider/dotenv/0.1.0/plugin.yamlDie erzeugte Entität:
# Generated from the plugin by `aggrega plugin gen-catalog`. You may narrow its capability lists; edit nothing else here.apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: dotenv version: 0.1.0 pluginType: provider description: Render artifact bodies into environment files, quoting and escaping each value as the format requires.spec: abiVersion: v1beta1 exports: - name: render_node provider: capabilities: - dotenvBeachten Sie, was nicht vorhanden ist: irgendein Verweis auf die .wasm. Wo ein Plugin liegt, wird aus seiner Identität abgeleitet — der Koordinate pluginType/name plus der jeweils konfigurierten Registry —, daher gibt es kein Ortsfeld, das zu verfassen wäre, und keines, das falsch sein könnte. Der Inhalts-Digest wird erfasst, wenn ein Release aufgelöst wird, im Lockfile dieses Release, nicht in der Entität.
5. Den Guest dort ablegen, wo ein Build nach ihm sucht
Während Sie einen Guest entwickeln, gibt es nichts Veröffentlichtes abzurufen, daher liest der Build ihn aus einem Katalogverzeichnis: die .wasm neben ihrer Entität, benannt nach dem Socket und dem Plugin.
dev-catalog/plugin/provider/dotenv/0.1.0/plugin.yamldev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasmcp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasmDer Dateiname enthält neben dem Namen auch den Socket, weil ein bloßer Plugin-Name nur innerhalb seines eigenen Sockets eindeutig ist — zwei Plugins namens dotenv an verschiedenen Sockets müssen zwei Dateien erreichen.
Kopieren Sie die gebaute Datei dorthin, statt auf sie zu verlinken. Ein Link an dieser Stelle wird nur bis zu einem Ziel innerhalb des Workspace verfolgt — oder, bei einem außerhalb des Workspace aufgeführten Katalogverzeichnis, bis zu einem Ziel innerhalb dieses Verzeichnisses; einer, der weiter führt, bricht den Build und den Pull ab und nennt den Link, wie die Grenze des Workspace ausführt.
Die Plugin-Entität zu einem Provider in einem Katalogverzeichnis ist nie gepinnt, und weder ein Pull noch ein Build ruft ihre .wasm ab, daher muss die Datei vorhanden sein, wenn das Release aufgelöst wird. Ein Pull prüft, bevor er das Lockfile schreibt: Findet er die .wasm weder neben der Entität noch an einem anderen Ort, von dem ein Build Plugins liest, bricht er ab und nennt die Datei und das Verzeichnis, in dem er sie erwartet hat, wie A plugin’s .wasm is not on this machine (Die Wasm-Datei zu einem Plugin ist nicht auf diesem Rechner) beschreibt.
Richten Sie den Workspace in .aggrega-config.yaml auf beide Katalogverzeichnisse aus:
workspace: catalog_dirs: - catalog - dev-catalogauto_pull: trueauto_pull lässt aggrega build das Release im selben Prozess auflösen, sodass ein erster Build keinen separaten Auflösungsschritt braucht.
6. Die Dokumente, die auf den Provider abzielen
Vier Dateien. Die Component deklariert, was ein Autor setzen darf; das Recipe bindet die Fähigkeit und verfasst das Artefakt; das Aggregate formuliert die Absicht; das Release platziert sie.
catalog/component/example/compute/checkout/1.0.0/component.yaml:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: example/compute/checkout version: 1.0.0 description: An application whose configuration is delivered as an environment file. labels: component.aggrega.ai/type: server component.aggrega.ai/category: computespec: schema: values: service_name: type: string default: checkout description: The name the application reports itself under. log_level: type: string default: info description: The application's log verbosity. greeting: type: string default: hello description: A value carrying characters the environment-file format must quote. infra: endpoint: type: string default: http://localhost:8080 description: The endpoint the operator points the application at.catalog/recipe/dotenv/checkout/1.0.0/recipe.yaml:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: checkout version: 1.0.0 description: Renders the application's configuration as an environment file.spec: capability: dotenv implements: example/compute/checkout:1.0.0
artifacts: app.env: | service-name = {{ .values.service_name }} log.level = {{ .values.log_level }} greeting = {{ .values.greeting }} endpoint = {{ .infra.endpoint }}spec.capability: dotenv ist die gesamte Bindung. Sie benennt eine Fähigkeit, kein Plugin: Der Build löst sie zu demjenigen Provider-Plugin auf, das diese Fähigkeit deklariert. Wo es genau eines gibt — wie hier —, ist nichts weiter nötig.
Die verfassten Schlüssel stehen absichtlich nicht in Form von Umgebungsvariablen. service-name und log.level sind die Schreibweisen, die ein Autor natürlicherweise wählen würde, und sie zu normalisieren ist die Aufgabe, die dem Provider zufällt.
aggregate.yaml:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: aggregate version: "1.0.0" description: One application whose configuration is an environment file.spec: components: app: type: example/compute/checkout values: service_name: checkout log_level: debug greeting: hello worldmanifest.yaml:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: manifest version: "1.0.0" description: Binds the component type to the environment-file recipe.spec: mappings: components: type: example/compute/checkout:1.0.0: checkout:1.0.0release.yaml:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: walkthrough environment: production version: "1.0.0"spec: aggregate: aggregate manifest: manifest boundaries: infra: directory: infra components: app: infra: endpoint: "https://checkout.example.net"7. Der erste Build und was er zurückweist
aggrega build --release release.yaml --auto-pull warning: plugin "provider/dotenv" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recorded[… omitted: the notice saying the Release could not be rendered to discover its external inputs, carrying the error below beneath its first line]Pull complete: release.lock (entities=5, source_artifacts=0, external_inputs=0)[… omitted: a line saying again that external inputs were not fully discovered][CATALOG_ERROR E0265] instance app provider does not support the node's input kind (node "app"). provider "dotenv" does not support artifacts-only recipes (this provider supports: none); declare one of the supported input kinds, or target a provider that supports artifacts-onlyLesen Sie die beiden Zeilen getrennt, denn sie sagen Verschiedenes.
Die Warnung ist während der Entwicklung zu erwarten, und sie wird nicht verschwinden. Sie besagt, dass der Guest ohne einen erfassten Inhalts-Digest lief, gegen den er geprüft werden könnte, was der Wahrheit über einen Guest entspricht, den Sie vor einer Minute gebaut haben: Niemand hat ihn veröffentlicht, also ist kein Digest erfasst. Sie sagt auch, warum ein erneutes Auflösen des Release daran nichts ändern würde — ein Guest, der neben seiner Entität in einem Katalogverzeichnis gelesen wird, wird von jedem Build neu gelesen, und ein Pull erfasst seinen Digest nur für ein Governance-Plugin, das in einer Transform-Rolle angebunden ist, was dieser Guest nicht ist — und was es ändern würde: das Plugin zu veröffentlichen und auf die veröffentlichte Entität zu verweisen. Lesen Sie die Warnung so, dass der Build korrekterweise darauf verzichtet, eine Überprüfung zu behaupten, die er nicht durchgeführt hat, und rechnen Sie mit ihr, solange der Guest lokal ist.
Der Fehler ist der eigentliche Befund, und die Klammer ist die Diagnose. Der Provider wurde gefunden, geladen und gefragt, was er rendert, und er antwortete none — this provider supports: none. Der zu Beginn geschriebene Deskriptor benannte den Socket, die Fähigkeit und die Exporte, sagte aber nie, welchen der drei Recipe-Eingabetypen der Guest verarbeitet. Der Host rät nicht: Das Gate für Eingabetypen liest die vom Guest deklarierte Menge und weist einen Knoten zurück, den der Guest nie beansprucht hat.
Das ist die typische Form, in der erste Provider scheitern. Der Guest ist in Ordnung; seine Selbstauskunft ist unvollständig. describe() ist keine Formalität, die der Host duldet — sie ist die gesamte Grundlage, auf der ein gegenüber dem Format agnostischer Host entscheidet, was wohin gesendet wird.
8. Den Render-Verhaltensvertrag deklarieren
Fügen Sie den Vertrag dem Deskriptor in guest/main.go hinzu:
Capabilities: []string{"dotenv"}, Contract: &aggrega.ProviderContract{ InputKinds: aggrega.InputKinds{ Sourced: false, Synthesized: false, ArtifactsStandalone: true, }, BoundaryAssembly: "none", }, Exports: []aggrega.PluginExport{ArtifactsStandalone: true ist die Angabe, nach der das Gate gesucht hat. Die beiden Werte false sind ebenfalls Angaben, und sie zu machen ist genau der Punkt: Ein Recipe, das einen Quellbaum mitliefert, oder eines, das eine Arbeitslast deklariert, wird jetzt zurückgewiesen, bevor irgendein Rendering läuft, mit einer Meldung, die diesen Provider benennt — statt render_node zu erreichen und irgendwo darin zu scheitern.
BoundaryAssembly: "none" besagt, dass die Ausgabe jedes Knotens dort geschrieben wird, wo sie landet, ohne dass etwas zu kombinieren ist. Ein Provider, der mehrere Komponenten zu einem Dokument zusammenfasst, deklariert stattdessen merge oder nest und exportiert assemble_boundary, um das zu tun. Das ist das naheliegend Nächste, das man diesem Provider hinzufügt, und es ist im Plugin-Vertrag dokumentiert.
Bauen Sie den Guest neu, erzeugen Sie die Entität neu und legen Sie die neue .wasm wieder daneben:
cd guestGOWORK=off GOOS=wasip1 GOARCH=wasm go build -trimpath -buildvcs=false \ -ldflags "-X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Version=0.1.0 \ -X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Commit=walkthru" \ -buildmode=c-shared -o ../dotenv.wasm ./cd ..aggrega plugin gen-catalog --plugin dotenv.wasm \ --overlay overlay.yaml --output-dir dev-catalog/plugincp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasmDie neu erzeugte Entität trägt jetzt den Vertrag, aus der Binärdatei ausgelesen:
[… omitted: the header comments and the metadata block, unchanged from the first generation]spec: abiVersion: v1beta1 exports: - name: render_node provider: capabilities: - dotenv contract: inputKinds: artifactsStandalone: true boundaryAssembly: noneDie Entität nach jedem Neubau des Guests neu zu erzeugen, gehört zum Ablauf. Die Entität wiederholt, was die Binärdatei meldet, und beide werden beim Laden des Guests gegeneinander geprüft: Ein Export oder ein Vertragswert, den die Entität angibt und die Binärdatei nicht meldet, ist eine Abweichung, bei der der Build abbricht und die Angabe nennt. Eine Angabe, die die Entität weglässt, wird nicht geprüft, sodass eine Entität, die nach einem Neubau zurückgeblieben ist, der der Binärdatei etwas hinzugefügt hat — wie dieser Schritt —, trotzdem lädt, sie aber nicht mehr beschreibt.
9. Der Build, der rendert
aggrega build --release release.yaml --auto-pull warning: plugin "provider/dotenv" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recordedPull complete: release.lock (entities=5, source_artifacts=0, external_inputs=0)[… omitted: a line reporting total build time, which differs on every run]Build completed: 1 file written to <workspace>/distDie abschließende Zeile nennt das Ausgabeverzeichnis vollständig, wobei <workspace> für das Workspace-Stammverzeichnis steht. Der gerenderte Baum darunter:
dist/infra/dotenv/app/app.envUnd die Datei, die der Provider geschrieben hat, vollständig:
# aggrega.ai/boundary-path=infraSERVICE_NAME=checkoutLOG_LEVEL=debugGREETING="hello world"ENDPOINT=https://checkout.example.netJede Entscheidung, die der Guest trifft, ist in diesen sieben Zeilen sichtbar.
service-nameundlog.levelkamen so an, wie sie verfasst wurden, und gingen alsSERVICE_NAMEundLOG_LEVELhinaus. Der Autor musste die Grammatik des Ziels nie schreiben.GREETINGsteht in Anführungszeichen, die anderen drei nicht.hello worldenthält ein Leerzeichen und würde daher ohne Anführungszeichen beihelloenden; der Endpunkt enthält keines der Zeichen, die das Format als Syntax liest, daher würden Anführungszeichen nur Rauschen hinzufügen.- Die beiden Herkunftsschlüssel sind Kommentare, weil eine Umgebungsdatei keinen anderen Ort für sie hat. Ein Provider, dessen Ausgabe einen Metadatenblock hat, legt dieselben Schlüssel stattdessen dort ab. Der Host hat die Schlüssel berechnet; der Guest hat die Platzierung gewählt.
- Die Werte stammen von zwei verschiedenen Autoren.
service_name,log_levelundgreetingsind Entwicklerabsicht, aus dem Aggregate.endpointstammt vom Operator, aus dem Release. Der Guest hat keine der beiden Unterscheidungen gesehen — er hat einen einzigen ausgewerteten Rumpf erhalten.
10. Zwei Dinge, die Sie prüfen sollten, bevor Sie ihm vertrauen
Dass er deterministisch ist. Erfassen Sie die Ausgabe, bauen Sie neu und vergleichen Sie:
cp -r dist ../capture && rm -rf distaggrega build --release release.yamldiff -r ../capture distDass diff nichts ausgibt, ist das gewünschte Ergebnis. Determinismus ist der Vertrag des Guests, nicht des Hosts, und ein Guest, der irgendwo in seinem Ausgabepfad über eine Go-Map iteriert, wird hier scheitern, während er in einem einzelnen Build völlig korrekt aussieht.
Dass seine Zurückweisungen deutlich sichtbar sind. Beschädigen Sie eine Zeile des Artefakts im Recipe, sodass sie keinen Wert deklariert:
artifacts: app.env: | service-name = {{ .values.service_name }} this line declares no value[… omitted: the unverified-plugin warning, and the pull's lines saying the Release could not be rendered to discover its external inputs][CATALOG_ERROR] instance app rendering node "app" caused by: wasm: plugin "provider/dotenv:0.1.0" call to render_node: dotenv: app.env line 2: "this line declares no value" declares no value; an entry is KEY=valueDie eigene Meldung des Guests erreicht den Autor unverändert, mit der Datei und der Zeile, aus der sie stammt. Es lohnt sich, das gezielt zu prüfen, denn der alternative Fehlerfall — ein Guest, der eine Zeile, die er nicht parsen kann, stillschweigend überspringt — erzeugt einen erfolgreichen Build und ein Release, dem eine Variable fehlt, und nichts in der Ausgabe weist darauf hin.
11. Was als Nächstes hinzukommt
Der hier gebaute Provider ist vollständig, aber minimal. In grober Reihenfolge danach, wie oft jedes gebraucht wird:
-
assemble_boundary, um die Ausgabe mehrerer Komponenten in einem Dokument zusammenzufassen, deklariert überBoundaryAssembly. -
validate_node_input, um die Eingabe eines Knotens strukturell zu prüfen, bevor irgendein Rendering läuft, sodass eine fehlerhafte Eingabe an der Authoring-Grenze gemeldet wird statt mitten im Rendern. -
Render-Fakten, um etwas darüber zu melden, was der Guest geschrieben hat, das nur die Kenntnis, die dieser Provider vom Format der Umgebungsdateien hat, erkennen kann — hier die Variablennamen, die jede Datei definiert. Ein Fakt ist ein Name und eine Liste, beide aus dem Vokabular, das diesem Provider eigen ist, neben den Dateien zurückgegeben — und der Wert ist immer ein JSON-Array, auch mit nur einem Eintrag, sonst bricht der Build ab:
// names lists the variables the files define, in the order they were written.value, err := json.Marshal(names)if err != nil {pdk.SetError(fmt.Errorf("dotenv: marshal render fact: %w", err))return 1}out := aggrega.RenderNodeOutput{Files: files,RenderFacts: []aggrega.RenderFact{{Name: "variable_names", Value: value}},}Der Compiler behält die Fakten in der Reihenfolge bei, in der der Guest sie aufführt, prüft nur, dass jeder Wert eine Liste ist, übergibt die Listen an die Feature-Templates, die sie lesen, und schreibt dieselben Dateien, ob sie gemeldet werden oder nicht. Dokumentieren Sie den Namen jedes Fakts und was seine Einträge enthalten als Teil des Provider-Vertrags.
-
Auslassungseinträge, sobald der Provider eine Quelle rendert. Die Eingabe eines Quell-Renderings kann neben ihrem
SourceListingOmitsenthalten, Einträge, die auszulassende gerenderte Einheiten benennen; ein Provider, der sie berücksichtigt, lässt jede passende Einheit aus dem weg, was er zurückgibt, meldet pro Eintrag eine Anzahl inOmittedund deklariertOmits: truein seinem Vertrag. Sie begleiten nie ein reines Artefakt-Rendering wie das hier gebaute, daher begegnet er ihnen erst, wenn er eine Eingabe mit Quelle rendert. Gerenderte Einheiten auslassen im Plugin-Vertrag beschreibt die ganze Struktur. -
Veröffentlichen, was die lokale Anordnung
dev-catalogin ein per Digest gepinntes Artefakt verwandelt, das ein Release auflöst und verifiziert. Das Plugin-Entwicklerhandbuch behandelt diesen Lebenszyklus in den Phasen Veröffentlichen, Pull und Build.
Die Payload- und Ergebnisstrukturen jedes Sockets stehen im Plugin-Vertrag.
Verwandte Referenzen
- Wasm-Plugin-Entwicklerhandbuch — die Entität
Plugin, die Fähigkeitsoberfläche und der Veröffentlichungslebenszyklus. - Plugin-Vertrag — die Eingabe- und Ausgabestrukturen jedes Sockets.
- Provider-Architektur — wie sich Provider in die Kompilierungspipeline einfügen.
- Provider-Referenzindex — was jeder Provider der Standardbibliothek erzeugt.
- Die Ausgabe auf diesen Seiten lesen — die Konvention, der die obigen Ausgabeblöcke folgen.