Écrire un fournisseur : un parcours guidé avec exemple
Cette page parcourt toute la tâche d’écriture d’un guest de fournisseur, d’un répertoire vide jusqu’à un build qui écrit les fichiers rendus par le fournisseur. Elle est le compagnon pratique du guide du développeur de plugins, qui documente l’entité et le cycle de vie, et du contrat des plugins, qui documente les sockets.
Le fournisseur construit ici est assez petit pour se lire d’une traite et accomplit un vrai travail : il rend des fichiers d’environnement. Cette cible est un bon premier fournisseur, car sa traduction est réellement propre au format — un fichier d’environnement a sa propre grammaire de clés, ses propres règles de guillemets et aucun bloc de métadonnées où placer la provenance du build — si bien que le guest doit prendre chaque décision que prend un fournisseur plus grand, sans qu’un grand volume de code ne les masque.
À propos des blocs de cette page. Chaque bloc montrant une sortie a été copié d’une exécution réelle des étapes ci-dessous, dans l’ordre où elles apparaissent, selon la convention de sortie : un bloc est soit complet, soit un extrait qui signale où des lignes ont été omises. Il s’agit d’un parcours que vous assemblez vous-même plutôt que d’un espace de travail que vous pouvez cloner, si bien que les blocs de source sont les fichiers à créer plutôt que des fichiers à extraire.
Ce dont vous avez besoin
- La chaîne d’outils Go, qui compile vers WebAssembly sans outillage supplémentaire.
- Un checkout du kit de développement de plugins, que présente le guide du développeur de plugins, et du paquet ABI sur lequel s’appuie le kit : le
go.moddu guest ci-dessous pointe vers les deux. - Le binaire
aggrega.
La structure du résultat final
Un fournisseur se compose de deux artefacts : un guest .wasm et une entité Plugin qui le porte dans un catalogue. Rien d’autre — aucune modification de l’hôte, aucun enregistrement, aucun build du compilateur. Ajouter un fournisseur, c’est ajouter ces deux fichiers là où un build peut les voir.
L’espace de travail auquel aboutit ce parcours :
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’auto-description du guest
Chaque plugin exporte describe(). L’hôte l’appelle une fois lorsqu’il charge le guest et lit la réponse comme le compte rendu que le guest donne de lui-même. Pour un fournisseur, quatre parties de cette réponse comptent.
Créez 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 indique quel socket ce guest sert. Capabilities est la liste par rapport à laquelle une Recipe se résout : une Recipe dont le spec.capability vaut dotenv sera acheminée vers ce guest. Exports nomme les points d’entrée vers lesquels l’hôte peut acheminer ; render_node est celui que tout fournisseur doit avoir.
Ce descripteur est délibérément incomplet, comme l’est généralement un premier jet. C’est le premier build, plus bas, qui le fait apparaître.
2. Rendre un nœud
render_node est appelé une fois par composant que le build rend via ce fournisseur. Il reçoit l’identité du nœud, le contexte de rendu et les entrées pré-évaluées que la Recipe liée a déclarées — ici, un ensemble d’artefacts que l’hôte a déjà lu et évalué comme modèle.
Tout le travail du guest consiste à décider quels octets sortent. Ajoutez à 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}Trois décisions dans ce fragment appartiennent au fournisseur, et aucune autre couche ne pourrait les prendre. Les caractères qui imposent des guillemets sont une propriété des fichiers d’environnement. Il en va de même de la grammaire des noms de variables, et du choix de refuser une clé qui ne s’y conforme pas plutôt que de la renommer — une variable renommée est une variable que l’application cherchera sans la trouver, ce qui est pire qu’un build arrêté.
Restent les deux dernières pièces : où va la provenance, et l’export lui-même.
// 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() {}La charge utile transite dans un encodage binaire, et le kit la lit et l’écrit. L’hôte transmet à render_node son entrée en CBOR canonique et lit la réponse dans le même encodage, si bien que le guest décode avec le DecodeCBOR du type d’entrée et encode avec le EncodeCBOR du type de sortie — aucune bibliothèque CBOR, et rien d’analysé à la main. Le Content d’un fichier est une tranche d’octets que le guest remplit avec les octets exacts à écrire ; l’encodeur les transporte comme octets bruts et l’hôte les écrit tels quels.
L’hôte transmet au guest un contenu qu’il a déjà évalué. Le Content de chaque entrée d’artefact est le corps écrit par l’auteur, dont les expressions de modèle sont déjà résolues par rapport au contexte de rendu — le guest n’évalue jamais de modèle et ne lit jamais de fichier. C’est ce qui préserve la frontière de compilation anticipée du compilateur : le guest est une fonction pure de la charge utile vers des octets.
Le déterminisme est la responsabilité du guest. Lors d’un build ordinaire, rien ne le vérifie à votre place. Ici, il provient du tri des clés de provenance avant de les émettre et du parcours des entrées d’artefact dans l’ordre que porte la charge utile, et les vérifications vers la fin de cette page en mesurent le résultat.
guest/go.mod référence votre checkout du 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. Compiler le guest
Un guest est un build Go ordinaire avec la cible WebAssembly sélectionnée :
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 écrit go.sum, les sommes de contrôle des dépendances, sans lequel le build refuse de s’exécuter. -trimpath et -buildvcs=false tiennent les chemins de build et les marques du contrôle de version hors du binaire, si bien que la même source au même commit produit les mêmes octets. Les deux valeurs de -ldflags inscrivent dans le guest sa propre version, que l’étape suivante lit.
Vérifiez les exports avant d’aller plus loin :
aggrega inspect --plugin dotenv.wasmPlugin .wasm: dotenv.wasmExports: render_nodehostFunctions (derived from binary, not yet recorded by aggrega plugin sync): (none)Ce guest n’importe aucune fonction hôte, ce qui est le réglage par défaut du moindre privilège : il n’a besoin ni du système de fichiers ni du réseau, car tout ce qu’il rend arrive dans la charge utile.
4. Générer l’entité Plugin
Les champs de contrat de l’entité ne s’écrivent pas à la main — ils sont lus dans le guest, si bien que l’entité ne peut pas promettre quelque chose que le binaire ne fait pas. Vous ne fournissez que l’identité, dans une petite surcouche.
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é générée :
# 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: - dotenvRemarquez ce qui n’y est pas : un quelconque pointeur vers le .wasm. L’emplacement d’un plugin est dérivé de son identité — la coordonnée pluginType/name plus le registre configuré, quel qu’il soit — si bien qu’il n’y a aucun champ d’emplacement à écrire, et aucun sur lequel se tromper. Le digest du contenu est enregistré lorsqu’une Release est résolue, dans le fichier de verrouillage de cette Release, et non dans l’entité.
5. Placer le guest là où un build le cherchera
Tant que vous développez un guest, il n’y a rien de publié à récupérer, si bien que le build le lit depuis un répertoire de catalogue : le .wasm placé à côté de son entité, nommé d’après le socket et le 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.wasmLe nom du fichier porte le socket en plus du nom, car un nom de plugin seul n’est unique qu’au sein de son propre socket — deux plugins appelés dotenv sur des sockets différents doivent atteindre deux fichiers.
Copiez-y le fichier compilé plutôt que de créer un lien vers lui. Un lien à cet endroit n’est suivi que vers une destination à l’intérieur de l’espace de travail — ou, pour un répertoire de catalogue listé hors de l’espace de travail, à l’intérieur de ce répertoire ; un lien qui mène plus loin arrête le build et le pull en nommant le lien, comme l’expose la frontière de l’espace de travail.
L’entité plugin d’un fournisseur dans un répertoire de catalogue n’est jamais épinglée, et ni un pull ni un build ne récupèrent son .wasm, si bien que le fichier doit être présent lorsque la Release est résolue. Un pull vérifie avant d’écrire le fichier de verrouillage : s’il ne trouve le .wasm ni à côté de l’entité ni à aucun autre endroit d’où un build lit des plugins, il s’arrête et nomme le fichier et le répertoire où il l’attendait, comme le décrit A plugin’s .wasm is not on this machine (Le fichier Wasm d’un plugin n’est pas sur cette machine).
Pointez l’espace de travail vers les deux répertoires de catalogue dans .aggrega-config.yaml :
workspace: catalog_dirs: - catalog - dev-catalogauto_pull: trueauto_pull permet à aggrega build de résoudre la Release au sein du processus, si bien qu’un premier build n’a pas besoin d’une étape de résolution séparée.
6. Les documents qui ciblent le fournisseur
Quatre fichiers. Le Component déclare ce qu’un auteur peut définir ; la Recipe lie la capacité et rédige l’artefact ; l’Aggregate énonce l’intention ; la Release la place.
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 constitue toute la liaison. Il nomme une capacité, pas un plugin : le build la résout vers le plugin fournisseur, quel qu’il soit, qui déclare cette capacité. Là où il y en a exactement un — comme ici — rien d’autre n’est nécessaire.
Les clés écrites ne sont délibérément pas sous forme de variables d’environnement. service-name et log.level sont les graphies qu’un auteur écrirait naturellement, et les normaliser est le travail du fournisseur.
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. Le premier build, et ce qu’il refuse
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-onlyLisez les deux lignes séparément, car elles disent des choses différentes.
L’avertissement est attendu pendant le développement, et il ne disparaîtra pas. Il dit que le guest s’est exécuté sans digest de contenu enregistré par rapport auquel le vérifier, ce qui correspond à la réalité d’un guest que vous avez compilé il y a une minute : personne ne l’a publié, donc aucun digest n’est enregistré. Il dit aussi pourquoi résoudre à nouveau la Release n’y changerait rien — un guest lu à côté de son entité dans un répertoire de catalogue est relu à neuf par chaque build, et un pull n’enregistre son digest que pour un plugin de gouvernance rattaché à un rôle de transformation, ce que ce guest n’est pas — et ce qui y changerait quelque chose : publier le plugin et référencer l’entité publiée. Lisez l’avertissement comme le build qui refuse à juste titre de revendiquer une vérification qu’il n’a pas effectuée, et attendez-vous à le voir tant que le guest est local.
L’erreur est la vraie constatation, et la parenthèse est le diagnostic. Le fournisseur a été trouvé, chargé et interrogé sur ce qu’il rend, et il a répondu none — this provider supports: none. Le descripteur écrit au début nommait le socket, la capacité et les exports, mais ne disait jamais lequel des trois types d’entrée de Recipe le guest gère. L’hôte ne devine pas : le contrôle des types d’entrée lit l’ensemble déclaré par le guest et refuse un nœud que le guest n’a jamais revendiqué.
C’est la forme de la plupart des échecs d’un premier fournisseur. Le guest est correct ; son auto-description est incomplète. describe() n’est pas une formalité que l’hôte tolère — c’est toute la base sur laquelle un hôte agnostique vis-à-vis du format décide quoi envoyer où.
8. Déclarer le contrat de comportement de rendu
Ajoutez le contrat au descripteur dans 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 est l’affirmation que le contrôle cherchait. Les deux valeurs false sont aussi des affirmations, et les énoncer est tout l’intérêt : une Recipe qui embarque une arborescence de sources, ou une qui déclare une charge de travail, est désormais refusée avant tout rendu, avec un message nommant ce fournisseur — plutôt que d’atteindre render_node et d’échouer quelque part à l’intérieur.
BoundaryAssembly: "none" indique que la sortie de chaque nœud est écrite là où elle arrive, sans rien à combiner. Un fournisseur qui regroupe plusieurs composants en un seul document déclare plutôt merge ou nest, et exporte assemble_boundary pour le faire. C’est la prochaine chose naturelle à ajouter à ce fournisseur, et elle est documentée dans le contrat des plugins.
Recompilez le guest, régénérez l’entité et remettez le nouveau .wasm à côté d’elle :
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é régénérée porte désormais le contrat, lu dans le binaire :
[… 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: noneRégénérer l’entité après chaque recompilation du guest fait partie de la boucle. L’entité reprend ce que le binaire déclare, et les deux sont comparés au chargement du guest : un export ou une valeur de contrat que l’entité affirme et que le binaire ne déclare pas est une incohérence sur laquelle le build s’arrête, en nommant l’affirmation. Une affirmation que l’entité omet n’est pas vérifiée, si bien qu’une entité laissée en arrière par une recompilation qui a ajouté quelque chose au binaire — comme l’a fait cette étape — se charge quand même, tout en ne le décrivant plus.
9. Le build qui rend
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 ligne finale nomme le répertoire de sortie en entier, où <workspace> représente la racine de l’espace de travail. L’arborescence rendue en dessous :
dist/infra/dotenv/app/app.envEt le fichier que le fournisseur a écrit, complet :
# aggrega.ai/boundary-path=infraSERVICE_NAME=checkoutLOG_LEVEL=debugGREETING="hello world"ENDPOINT=https://checkout.example.netChaque décision que prend le guest est visible dans ces sept lignes.
service-nameetlog.levelsont arrivées telles qu’écrites et sont reparties sous la formeSERVICE_NAMEetLOG_LEVEL. L’auteur n’a jamais eu à écrire la grammaire de la cible.GREETINGest entre guillemets et les trois autres ne le sont pas.hello worldcontient une espace, si bien que sans guillemets il s’arrêterait àhello; le point de terminaison ne contient aucun des caractères que le format lit comme de la syntaxe, si bien que le mettre entre guillemets ajouterait du bruit.- Les deux clés de provenance sont des commentaires, car un fichier d’environnement n’a nulle part ailleurs où les mettre. Un fournisseur dont la sortie a un bloc de métadonnées y met plutôt les mêmes clés. L’hôte a calculé les clés ; le guest a choisi l’emplacement.
- Les valeurs viennent de deux auteurs différents.
service_name,log_leveletgreetingsont l’intention du développeur, venue de l’Aggregate.endpointest celle de l’opérateur, venue de la Release. Le guest n’a vu aucune de ces distinctions — il a reçu un seul corps évalué.
10. Deux choses à vérifier avant de lui faire confiance
Qu’il est déterministe. Capturez la sortie, recompilez et comparez :
cp -r dist ../capture && rm -rf distaggrega build --release release.yamldiff -r ../capture distQue diff n’affiche rien est le résultat voulu. Le déterminisme est le contrat du guest, pas de l’hôte, et un guest qui itère sur une map Go quelque part dans son chemin de sortie échouera à cette vérification tout en paraissant parfaitement correct lors d’un build unique.
Que ses refus sont visibles. Cassez une ligne de l’artefact de la Recipe, de sorte qu’elle ne déclare aucune valeur :
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=valueLe message propre au guest atteint l’auteur intact, avec le fichier et la ligne d’où il provient. Cela vaut la peine d’être vérifié délibérément, car l’autre échec possible — un guest qui saute silencieusement une ligne qu’il ne sait pas analyser — produit un build qui réussit et une Release à laquelle il manque une variable, et rien dans la sortie ne le signale.
11. Ce qu’il faut ajouter ensuite
Le fournisseur construit ici est complet mais minimal. Dans l’ordre approximatif de la fréquence à laquelle chacun est demandé :
-
assemble_boundary, pour regrouper la sortie de plusieurs composants en un seul document, déclaré viaBoundaryAssembly. -
validate_node_input, pour vérifier structurellement l’entrée d’un nœud avant tout rendu, si bien qu’une entrée mal formée est signalée à la frontière de la rédaction plutôt qu’en plein rendu. -
Faits de rendu, pour signaler sur ce que le guest a écrit quelque chose que seule la connaissance qu’a ce fournisseur du format des fichiers d’environnement peut voir — ici, les noms des variables que chaque fichier définit. Un fait est un nom et une liste, tous deux issus du vocabulaire propre à ce fournisseur, renvoyés à côté des fichiers — et la valeur est toujours un tableau JSON, même avec une seule entrée, faute de quoi le build s’arrête :
// 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}},}Le compilateur conserve les faits dans l’ordre où le guest les liste, vérifie seulement que chaque valeur est une liste, transmet les listes aux modèles de Feature qui les lisent, et écrit les mêmes fichiers qu’ils soient signalés ou non. Documentez le nom de chaque fait et ce que contiennent ses entrées dans le cadre du contrat du fournisseur.
-
Entrées d’omission, une fois que le fournisseur rend une source. L’entrée d’un rendu de source peut porter
Omits, des entrées nommant des unités rendues à laisser de côté, à côté de sonSourceListing; un fournisseur qui les respecte exclut de ce qu’il renvoie chaque unité correspondante, signale un compte par entrée dansOmittedet déclareOmits: truedans son contrat. Elles n’accompagnent jamais un rendu d’artefacts seuls comme celui de ce fournisseur, si bien qu’il ne les rencontre qu’après avoir rendu une entrée sourcée. Exclure des unités rendues dans le contrat des plugins en donne la structure complète. -
Publication, qui transforme l’arrangement local
dev-catalogen un artefact épinglé par digest qu’une Release résout et vérifie. Le guide du développeur de plugins couvre ce cycle de vie, sous les étapes de publication, de pull et de build.
Les structures de charge utile et de résultat de chaque socket se trouvent dans le contrat des plugins.
Références associées
- Guide du développeur de plugins Wasm — l’entité
Plugin, la surface des capacités et le cycle de vie de la publication. - Contrat du Plugin — les structures d’entrée et de sortie de chaque socket.
- Architecture des Provider — comment les fournisseurs s’insèrent dans le pipeline de compilation.
- Index de référence des Provider — ce que produit chaque fournisseur de la bibliothèque standard.
- Lire la sortie sur ces pages — la convention que suivent les blocs de sortie ci-dessus.