Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

É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.mod du 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.yaml

1. 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 describe
func 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_node
func 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/go

3. Compiler le guest

Un guest est un build Go ordinaire avec la cible WebAssembly sélectionnée :

Terminal window
cd guest
go mod tidy
GOWORK=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 :

Terminal window
aggrega inspect --plugin dotenv.wasm
Plugin .wasm: dotenv.wasm
Exports:
render_node
hostFunctions (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/v1beta1
kind: Plugin
metadata:
name: dotenv
Terminal window
aggrega plugin gen-catalog --plugin dotenv.wasm \
--overlay overlay.yaml --output-dir dev-catalog/plugin
generated dev-catalog/plugin/provider/dotenv/0.1.0/plugin.yaml

L’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/v1beta1
kind: Plugin
metadata:
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:
- dotenv

Remarquez 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.yaml
dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasm
Terminal window
cp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasm

Le 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-catalog
auto_pull: true

auto_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/v1beta1
kind: Component
metadata:
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: compute
spec:
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/v1beta1
kind: Recipe
metadata:
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/v1beta1
kind: Aggregate
metadata:
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 world

manifest.yaml :

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
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.0

release.yaml :

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
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

Terminal window
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-only

Lisez 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 :

Terminal window
cd guest
GOWORK=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/plugin
cp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasm

L’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: none

Ré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

Terminal window
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
Pull 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>/dist

La 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.env

Et le fichier que le fournisseur a écrit, complet :

1.0.0
# aggrega.ai/boundary-path=infra
SERVICE_NAME=checkout
LOG_LEVEL=debug
GREETING="hello world"
ENDPOINT=https://checkout.example.net

Chaque décision que prend le guest est visible dans ces sept lignes.

  • service-name et log.level sont arrivées telles qu’écrites et sont reparties sous la forme SERVICE_NAME et LOG_LEVEL. L’auteur n’a jamais eu à écrire la grammaire de la cible.
  • GREETING est entre guillemets et les trois autres ne le sont pas. hello world contient 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_level et greeting sont l’intention du développeur, venue de l’Aggregate. endpoint est 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 :

Terminal window
cp -r dist ../capture && rm -rf dist
aggrega build --release release.yaml
diff -r ../capture dist

Que 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=value

Le 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é via BoundaryAssembly.

  • 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 son SourceListing ; un fournisseur qui les respecte exclut de ce qu’il renvoie chaque unité correspondante, signale un compte par entrée dans Omitted et déclare Omits: true dans 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-catalog en 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.