Scrivere un provider: una guida passo passo con esempio
Questa pagina percorre l’intero compito di scrivere un guest di provider, da una directory vuota a una build che scrive i file renderizzati dal provider. È il complemento pratico della guida per sviluppatori di plugin, che documenta l’entità e il ciclo di vita, e del contratto dei plugin, che documenta i socket.
Il provider costruito qui è abbastanza piccolo da leggersi in una sola seduta e svolge un lavoro reale: renderizza file di ambiente. Questo target è un buon primo provider perché la sua traduzione è davvero specifica del formato — un file di ambiente ha la propria grammatica delle chiavi, le proprie regole per le virgolette e nessun blocco di metadati in cui mettere la provenienza della build — quindi il guest deve prendere ogni decisione che prende un provider più grande, senza un grande corpo di codice che le nasconda.
Sui blocchi di questa pagina. Ogni blocco che mostra un output è stato copiato da un’esecuzione reale dei passaggi seguenti, nell’ordine in cui compaiono, secondo la convenzione dell’output: un blocco è completo oppure è un estratto che segnala dove sono state omesse delle righe. Questa è una guida che assembli da te anziché un workspace che puoi clonare, quindi i blocchi di sorgente sono i file da creare anziché file da estrarre.
Cosa ti serve
- La toolchain di Go, che compila in WebAssembly senza strumenti aggiuntivi.
- Un checkout del kit di sviluppo dei plugin, che la guida per sviluppatori di plugin introduce, e del pacchetto ABI su cui il kit si basa: il
go.moddel guest più sotto punta a entrambi. - Il binario
aggrega.
La struttura del risultato finito
Un provider è due artefatti: un guest .wasm e un’entità Plugin che lo porta in un catalogo. Nient’altro — nessuna modifica all’host, nessuna registrazione, nessuna build del compilatore. Aggiungere un provider significa aggiungere quei due file dove una build può vederli.
Il workspace con cui si conclude questa guida:
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. L’autodescrizione del guest
Ogni plugin esporta describe(). L’host lo chiama una volta quando carica il guest e legge la risposta come il resoconto che il guest dà di sé stesso. Per un provider contano quattro parti di quella risposta.
Crea guest/main.go:
// 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 dice quale socket serve questo guest. Capabilities è l’elenco rispetto a cui si risolve una Recipe: una Recipe il cui spec.capability è dotenv verrà instradata a questo guest. Exports indica i punti di ingresso verso cui l’host può inoltrare; render_node è quello che ogni provider deve avere.
Questo descrittore è volutamente incompleto, come lo è di solito una prima bozza. È la prima build, più sotto, a farlo emergere.
2. Renderizzare un nodo
render_node viene chiamato una volta per ogni componente che la build renderizza tramite questo provider. Riceve l’identità del nodo, il contesto di rendering e gli input pre-valutati dichiarati dalla Recipe legata — qui, un insieme di artefatti che l’host ha già letto e valutato come template.
L’unico compito del guest è decidere quali byte escono. Aggiungi a guest/main.go:
// 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}Tre decisioni in quel frammento sono proprie del provider, e nessun altro livello potrebbe prenderle. Quali caratteri impongono le virgolette è un fatto che riguarda i file di ambiente. Lo è anche la grammatica dei nomi di variabile, e lo è la scelta di rifiutare una chiave che non vi rientra anziché rinominarla — una variabile rinominata è una variabile che l’applicazione cercherà senza trovarla, il che è peggio di una build arrestata.
Ora i due pezzi rimanenti: dove va la provenienza, e l’export stesso.
// 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() {}Il payload transita in una codifica binaria, e il kit lo legge e lo scrive. L’host passa a render_node il suo input come CBOR canonico e legge la risposta nella stessa codifica, quindi il guest decodifica con DecodeCBOR del tipo di input e codifica con EncodeCBOR del tipo di output — nessuna libreria CBOR, e niente analizzato a mano. Il Content di un file è uno slice di byte che il guest riempie con i byte esatti da scrivere; l’encoder li trasporta come byte grezzi e l’host li scrive alla lettera.
L’host passa al guest contenuto che ha già valutato. Il Content di ogni voce di artefatto è il corpo scritto dall’autore con le sue espressioni di template già risolte rispetto al contesto di rendering — il guest non valuta mai un template e non legge mai un file. È questo che mantiene intatto il confine ahead-of-time del compilatore: il guest è una funzione pura dal payload ai byte.
Il determinismo è responsabilità del guest. In una build ordinaria nulla lo verifica al posto tuo. Qui deriva dall’ordinare le chiavi di provenienza prima di emetterle e dal percorrere le voci di artefatto nell’ordine in cui le porta il payload, e le verifiche verso la fine di questa pagina misurano il risultato.
guest/go.mod fa riferimento al tuo checkout del kit:
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. Compilare il guest
Un guest è una normale build Go con il target WebAssembly selezionato:
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 scrive go.sum, i checksum delle dipendenze, senza il quale la build si rifiuta di essere eseguita. -trimpath e -buildvcs=false tengono fuori dal binario i percorsi di build e i timbri del controllo di versione, così lo stesso sorgente allo stesso commit produce gli stessi byte. I due valori di -ldflags imprimono nel guest la sua versione, che il passaggio successivo legge.
Verifica gli export prima di proseguire:
aggrega inspect --plugin dotenv.wasmPlugin .wasm: dotenv.wasmExports: render_nodehostFunctions (derived from binary, not yet recorded by aggrega plugin sync): (none)Questo guest non importa funzioni host, che è l’impostazione predefinita del privilegio minimo: non ha bisogno né del filesystem né della rete, perché tutto ciò che renderizza arriva nel payload.
4. Generare l’entità Plugin
I campi di contratto dell’entità non si scrivono a mano — vengono letti dal guest, così l’entità non può promettere qualcosa che il binario non fa. Tu fornisci solo l’identità, in una piccola sovrapposizione.
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.yamlL’entità generata:
# 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: - dotenvNota ciò che non c’è: alcun puntatore al .wasm. La posizione di un plugin deriva dalla sua identità — la coordinata pluginType/name più qualunque registry sia configurato — quindi non c’è alcun campo di posizione da scrivere e nessuno da sbagliare. Il digest del contenuto viene registrato quando una Release viene risolta, nel lockfile di quella Release, non nell’entità.
5. Mettere il guest dove una build lo cercherà
Mentre sviluppi un guest non c’è nulla di pubblicato da scaricare, quindi la build lo legge da una directory di catalogo: il .wasm collocato accanto alla sua entità, con un nome che riporta il socket e il 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.wasmIl nome del file riporta il socket oltre al nome perché un nome di plugin semplice è univoco solo all’interno del proprio socket — due plugin chiamati dotenv su socket diversi devono raggiungere due file.
Copia lì il file compilato anziché creare un link. Un link in quella posizione viene seguito solo verso una destinazione all’interno del workspace — oppure, per una directory di catalogo elencata fuori dal workspace, all’interno di quella directory; uno che porta più lontano arresta la build e il pull indicando il link, come spiega il confine del workspace.
L’entità plugin di un provider in una directory di catalogo non è mai fissata, e né un pull né una build scaricano il suo .wasm, quindi il file deve essere presente quando la Release viene risolta. Un pull verifica prima di scrivere il lockfile: se non trova il .wasm né accanto all’entità né in alcun altro luogo da cui una build legge i plugin, si arresta e indica il file e la directory in cui se lo aspettava, come descrive A plugin’s .wasm is not on this machine (Il file Wasm di un plugin non è su questa macchina).
Fai puntare il workspace a entrambe le directory di catalogo in .aggrega-config.yaml:
workspace: catalog_dirs: - catalog - dev-catalogauto_pull: trueauto_pull permette ad aggrega build di risolvere la Release all’interno del processo, quindi una prima build non richiede un passaggio di risoluzione separato.
6. I documenti che puntano al provider
Quattro file. Il Component dichiara ciò che un autore può impostare; la Recipe lega la capacità e definisce l’artefatto; l’Aggregate esprime l’intento; la Release lo colloca.
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 è l’intero legame. Indica una capacità, non un plugin: la build la risolve in qualunque plugin provider dichiari quella capacità. Dove ce n’è esattamente uno — come qui — non serve altro.
Le chiavi scritte non sono volutamente in forma di variabile d’ambiente. service-name e log.level sono le grafie che un autore scriverebbe naturalmente, e normalizzarle è compito del provider.
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. La prima build, e ciò che rifiuta
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-onlyLeggi separatamente le due righe, perché dicono cose diverse.
L’avviso è previsto durante lo sviluppo, e non scomparirà. Dice che il guest è stato eseguito senza un digest del contenuto registrato con cui verificarlo, il che corrisponde alla realtà di un guest compilato un minuto fa: nessuno lo ha pubblicato, quindi non c’è alcun digest registrato. Dice anche perché risolvere di nuovo la Release non lo cambierebbe — un guest letto da accanto alla sua entità in una directory di catalogo viene riletto da ogni build, e un pull registra il suo digest solo per un plugin di governance associato in un ruolo di trasformazione, cosa che questo guest non è — e che cosa lo cambierebbe: pubblicare il plugin e fare riferimento all’entità pubblicata. Leggi l’avviso come la build che si astiene correttamente dal dichiarare una verifica che non ha eseguito, e aspettatelo finché il guest resta locale.
L’errore è il vero rilievo, e la parentesi è la diagnosi. Il provider è stato trovato, caricato e interrogato su ciò che renderizza, e ha risposto none — this provider supports: none. Il descrittore scritto all’inizio indicava il socket, la capacità e gli export, ma non diceva mai quale dei tre tipi di input della Recipe il guest gestisce. L’host non tira a indovinare: il controllo sui tipi di input legge l’insieme dichiarato dal guest e rifiuta un nodo che il guest non ha mai rivendicato.
È la forma della maggior parte dei fallimenti di un primo provider. Il guest va bene; la sua autodescrizione è incompleta. describe() non è una formalità che l’host tollera — è l’intera base su cui un host agnostico rispetto al formato decide che cosa inviare e dove.
8. Dichiarare il contratto di comportamento di rendering
Aggiungi il contratto al descrittore in guest/main.go:
Capabilities: []string{"dotenv"}, Contract: &aggrega.ProviderContract{ InputKinds: aggrega.InputKinds{ Sourced: false, Synthesized: false, ArtifactsStandalone: true, }, BoundaryAssembly: "none", }, Exports: []aggrega.PluginExport{ArtifactsStandalone: true è l’affermazione che il controllo cercava. Anche i due valori false sono affermazioni, e dichiararli è proprio il punto: una Recipe che incorpora un albero di sorgenti, o una che dichiara un workload, viene ora rifiutata prima che venga eseguito qualsiasi rendering, con un messaggio che indica questo provider — anziché raggiungere render_node e fallire da qualche parte al suo interno.
BoundaryAssembly: "none" dice che l’output di ogni nodo viene scritto dove arriva, senza nulla da combinare. Un provider che riunisce più componenti in un unico documento dichiara invece merge o nest, ed esporta assemble_boundary per farlo. È la prossima cosa naturale da aggiungere a questo provider, ed è documentata nel contratto dei plugin.
Ricompila il guest, rigenera l’entità e rimetti il nuovo .wasm accanto a essa:
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.wasmL’entità rigenerata ora porta il contratto, letto dal binario:
[… 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: noneRigenerare l’entità dopo ogni ricompilazione del guest fa parte del ciclo. L’entità riafferma ciò che il binario riporta, e i due vengono confrontati quando il guest viene caricato: un export o un valore di contratto che l’entità dichiara e il binario non riporta è una discrepanza su cui la build si arresta, indicando l’affermazione. Un’affermazione che l’entità omette non viene verificata, quindi un’entità rimasta indietro rispetto a una ricompilazione che ha aggiunto qualcosa al binario — come ha fatto questo passaggio — si carica comunque, pur non descrivendolo più.
9. La build che renderizza
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>/distLa riga di chiusura indica per intero la directory di output, dove <workspace> sta per la radice del workspace. L’albero renderizzato sotto di essa:
dist/infra/dotenv/app/app.envE il file scritto dal provider, completo:
# aggrega.ai/boundary-path=infraSERVICE_NAME=checkoutLOG_LEVEL=debugGREETING="hello world"ENDPOINT=https://checkout.example.netOgni decisione presa dal guest è visibile in quelle sette righe.
service-nameelog.levelsono arrivate come le ha scritte l’autore e sono uscite comeSERVICE_NAMEeLOG_LEVEL. L’autore non ha mai dovuto scrivere la grammatica del target.GREETINGè tra virgolette e gli altri tre no.hello worldcontiene uno spazio, quindi senza virgolette terminerebbe ahello; l’endpoint non contiene nessuno dei caratteri che il formato legge come sintassi, quindi metterlo tra virgolette aggiungerebbe solo rumore.- Le due chiavi di provenienza sono commenti, perché un file di ambiente non ha nessun altro posto in cui metterle. Un provider il cui output ha un blocco di metadati mette lì le stesse chiavi. L’host ha calcolato le chiavi; il guest ha scelto dove collocarle.
- I valori provengono da due autori diversi.
service_name,log_levelegreetingsono l’intento dello sviluppatore, dall’Aggregate.endpointè dell’operatore, dalla Release. Il guest non ha visto nessuna delle due distinzioni — ha ricevuto un unico corpo valutato.
10. Due cose da verificare prima di fidarti
Che sia deterministico. Cattura l’output, ricompila e confronta:
cp -r dist ../capture && rm -rf distaggrega build --release release.yamldiff -r ../capture distChe diff non stampi nulla è il risultato che vuoi. Il determinismo è un contratto del guest, non dell’host, e un guest che itera una mappa Go da qualche parte nel suo percorso di output fallirà questa verifica pur sembrando perfettamente corretto in una singola build.
Che i suoi rifiuti siano evidenti. Rompi una riga dell’artefatto della Recipe, in modo che non dichiari alcun valore:
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=valueIl messaggio del guest raggiunge l’autore intatto, con il file e la riga da cui proviene. Vale la pena verificarlo deliberatamente, perché il fallimento alternativo — un guest che salta silenziosamente una riga che non riesce ad analizzare — produce una build che riesce e una Release a cui manca una variabile, e nulla nell’output lo segnala.
11. Cosa aggiungere dopo
Il provider costruito qui è completo ma minimale. In ordine approssimativo di quanto spesso ciascuno viene richiesto:
-
assemble_boundary, per riunire l’output di più componenti in un unico documento, dichiarato tramiteBoundaryAssembly. -
validate_node_input, per verificare strutturalmente l’input di un nodo prima che venga eseguito qualsiasi rendering, così un input malformato viene segnalato al confine dell’authoring anziché a metà rendering. -
Fatti di rendering, per riportare qualcosa su ciò che il guest ha scritto che solo la conoscenza del formato dei file di ambiente propria di questo provider può vedere — qui, i nomi delle variabili che ogni file definisce. Un fatto è un nome e un elenco, entrambi del vocabolario proprio di questo provider, restituiti accanto ai file — e il valore è sempre un array JSON, anche con una sola voce, altrimenti la build si arresta:
// 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}},}Il compilatore mantiene i fatti nell’ordine in cui il guest li elenca, verifica solo che ogni valore sia un elenco, passa gli elenchi ai template delle Feature che li leggono, e scrive gli stessi file che siano riportati o meno. Documenta il nome di ogni fatto e ciò che contengono le sue voci come parte del contratto del provider.
-
Voci di omissione, una volta che il provider renderizza una sorgente. L’input di un rendering di sorgente può portare
Omits, voci che indicano le unità renderizzate da lasciare fuori, accanto al suoSourceListing; un provider che le rispetta lascia fuori da ciò che restituisce ogni unità corrispondente, riporta un conteggio per voce inOmittede dichiaraOmits: truenel proprio contratto. Non accompagnano mai un rendering di soli artefatti come quello di questo provider, quindi le incontra solo dopo aver renderizzato un input con sorgente. Escludere le unità renderizzate nel contratto dei plugin ne descrive l’intera struttura. -
Pubblicazione, che trasforma la sistemazione locale
dev-catalogin un artefatto fissato per digest che una Release risolve e verifica. La guida per sviluppatori di plugin copre quel ciclo di vita, nelle fasi di pubblicazione, pull e build.
Le strutture del payload e del risultato di ogni socket si trovano nel contratto dei plugin.
Riferimenti correlati
- Guida per sviluppatori di plugin Wasm — l’entità
Plugin, la superficie delle capacità e il ciclo di vita della pubblicazione. - Contratto del Plugin — le strutture di input e output di ogni socket.
- Architettura dei Provider — come i provider si inseriscono nella pipeline di compilazione.
- Indice di riferimento dei Provider — che cosa produce ciascun provider della libreria standard.
- Leggere l’output in queste pagine — la convenzione seguita dai blocchi di output qui sopra.