Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Escrever um provedor: um guia passo a passo com exemplo

Esta página percorre toda a tarefa de escrever um guest de provedor, de um diretório vazio até um build que grava os arquivos que o provedor renderizou. Ela é o complemento prático do guia do desenvolvedor de plugins, que documenta a entidade e o ciclo de vida, e do contrato de plugins, que documenta os sockets.

O provedor construído aqui é pequeno o bastante para ser lido de uma vez e faz um trabalho real: ele renderiza arquivos de ambiente. Esse destino é um bom primeiro provedor porque a sua tradução é genuinamente específica do formato — um arquivo de ambiente tem a sua própria gramática de chaves, as suas próprias regras de aspas e nenhum bloco de metadados onde colocar a proveniência do build —, então o guest precisa tomar cada decisão que um provedor maior toma, sem um grande volume de código que as esconda.

Sobre os blocos desta página. Cada bloco que mostra uma saída foi copiado de uma execução real das etapas abaixo, na ordem em que aparecem, seguindo a convenção de saída: um bloco é completo ou é um trecho que marca onde linhas foram omitidas. Este é um guia que você monta por conta própria, e não um espaço de trabalho que você pode clonar, então os blocos de código-fonte são os arquivos a criar, e não arquivos a obter do repositório.

Do que você precisa

  • A toolchain do Go, que compila para WebAssembly sem ferramentas extras.
  • Um checkout do kit de desenvolvimento de plugins, que o guia do desenvolvedor de plugins apresenta, e do pacote ABI sobre o qual o kit é construído: o go.mod do guest mais abaixo aponta para ambos.
  • O binário aggrega.

A estrutura do resultado final

Um provedor são dois artefatos: um guest .wasm e uma entidade Plugin que o leva para um catálogo. Nada mais — nenhuma alteração no host, nenhuma inscrição, nenhum build do compilador. Adicionar um provedor é adicionar esses dois arquivos onde um build possa vê-los.

O espaço de trabalho com que este guia termina:

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. A autodescrição do guest

Todo plugin exporta describe(). O host o chama uma vez quando carrega o guest e lê a resposta como o relato que o guest faz de si mesmo. Para um provedor, quatro partes dessa resposta importam.

Crie 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 diz qual socket este guest atende. Capabilities é a lista com base na qual uma Recipe é resolvida: uma Recipe cujo spec.capability é dotenv será roteada para este guest. Exports nomeia os pontos de entrada para os quais o host pode despachar; render_node é o que todo provedor precisa ter.

Este descritor é deliberadamente incompleto, como um primeiro rascunho costuma ser. O primeiro build, mais abaixo, é onde isso aparece.

2. Renderizar um nó

render_node é chamado uma vez por componente que o build renderiza por meio deste provedor. Ele recebe a identidade do nó, o contexto de renderização e as entradas pré-avaliadas que a Recipe associada declarou — aqui, um conjunto de artefatos que o host já leu e avaliou como template.

Todo o trabalho do guest é decidir quais bytes saem. Adicione 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
}

Três decisões nesse fragmento são do próprio provedor, e nenhuma outra camada poderia tomá-las. Quais caracteres exigem aspas é um fato dos arquivos de ambiente. Assim como a gramática dos nomes de variável, e assim como a escolha de recusar uma chave que não se encaixa em vez de renomeá-la — uma variável renomeada é uma que a aplicação vai procurar e não vai encontrar, o que é pior do que um build interrompido.

Agora as duas peças restantes: para onde vai a proveniência, e a própria exportação.

// 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() {}

A carga útil trafega em uma codificação binária, e o kit a lê e a escreve. O host entrega a render_node a sua entrada como CBOR canônico e lê a resposta na mesma codificação, então o guest decodifica com o DecodeCBOR do tipo de entrada e codifica com o EncodeCBOR do tipo de saída — nenhuma biblioteca CBOR, e nada analisado à mão. O Content de um arquivo é um slice de bytes que o guest preenche com os bytes exatos a gravar; o codificador os transporta como bytes brutos e o host os grava literalmente.

O host entrega ao guest conteúdo que já avaliou. O Content de cada entrada de artefato é o corpo escrito pelo autor com as suas expressões de template já resolvidas com base no contexto de renderização — o guest nunca avalia um template e nunca lê um arquivo. É isso que mantém intacta a fronteira de compilação antecipada do compilador: o guest é uma função pura da carga útil para bytes.

O determinismo é responsabilidade do guest. Em um build comum, nada o verifica por você. Aqui ele vem de ordenar as chaves de proveniência antes de emiti-las e de percorrer as entradas de artefato na ordem em que a carga útil as traz, e as verificações perto do fim desta página medem o resultado.

guest/go.mod referencia o seu checkout do 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. Compilar o guest

Um guest é um build comum de Go com o destino WebAssembly selecionado:

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 grava go.sum, os checksums das dependências, sem o qual o build se recusa a executar. -trimpath e -buildvcs=false mantêm caminhos de build e carimbos do controle de versão fora do binário, de modo que o mesmo código-fonte no mesmo commit produz os mesmos bytes. Os dois valores de -ldflags carimbam no guest a sua própria versão, que a próxima etapa lê.

Confirme as exportações antes de continuar:

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)

Este guest não importa funções host, que é o padrão de menor privilégio: ele não precisa nem do sistema de arquivos nem da rede, porque tudo o que renderiza chega na carga útil.

4. Gerar a entidade Plugin

Os campos de contrato da entidade não são escritos à mão — são lidos do guest para que a entidade não possa prometer algo que o binário não faz. Você fornece apenas a identidade, em uma pequena sobreposição.

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

A entidade gerada:

# 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

Observe o que não está lá: qualquer ponteiro para o .wasm. A localização de um plugin é derivada da sua identidade — a coordenada pluginType/name mais o registro que estiver configurado —, então não há nenhum campo de localização a escrever e nenhum a errar. O digest do conteúdo é registrado quando uma Release é resolvida, no arquivo de bloqueio dessa Release, e não na entidade.

5. Colocar o guest onde um build vai procurá-lo

Enquanto você desenvolve um guest não há nada publicado para baixar, então o build o lê de um diretório de catálogo: o .wasm colocado ao lado da sua entidade, com um nome que indica o socket e o 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

O nome do arquivo traz o socket além do nome porque um nome de plugin simples só é único dentro do seu próprio socket — dois plugins chamados dotenv em sockets diferentes precisam chegar a dois arquivos.

Copie o arquivo compilado para lá em vez de criar um link para ele. Um link nesse lugar só é seguido até um destino dentro do espaço de trabalho — ou, para um diretório de catálogo listado fora do espaço de trabalho, dentro desse diretório; um que leve mais longe interrompe o build e o pull nomeando o link, como expõe a fronteira do espaço de trabalho.

A entidade plugin de um provedor em um diretório de catálogo nunca é fixada, e nem um pull nem um build baixam o seu .wasm, então o arquivo precisa estar lá quando a Release é resolvida. Um pull verifica antes de gravar o arquivo de bloqueio: quando não encontra o .wasm nem ao lado da entidade nem em nenhum outro lugar de onde um build lê plugins, ele é interrompido e nomeia o arquivo e o diretório em que o esperava, como descreve A plugin’s .wasm is not on this machine (O arquivo Wasm de um plugin não está nesta máquina).

Aponte o espaço de trabalho para os dois diretórios de catálogo em .aggrega-config.yaml:

workspace:
catalog_dirs:
- catalog
- dev-catalog
auto_pull: true

auto_pull permite que aggrega build resolva a Release dentro do processo, então um primeiro build não precisa de uma etapa de resolução separada.

6. Os documentos que apontam para o provedor

Quatro arquivos. O Component declara o que um autor pode definir; a Recipe associa a capacidade e define o artefato; o Aggregate expressa a intenção; a Release a posiciona.

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 é toda a associação. Ele nomeia uma capacidade, não um plugin: o build a resolve para o plugin de provedor, qualquer que seja, que declara essa capacidade. Onde há exatamente um — como aqui — nada mais é necessário.

As chaves escritas não estão, de propósito, na forma de variável de ambiente. service-name e log.level são as grafias que um autor escreveria naturalmente, e normalizá-las é tarefa do provedor.

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. O primeiro build, e o que ele recusa

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

Leia as duas linhas separadamente, porque elas dizem coisas diferentes.

O aviso é esperado durante o desenvolvimento, e não vai desaparecer. Ele diz que o guest foi executado sem um digest de conteúdo registrado com o qual verificá-lo, o que corresponde à verdade de um guest que você compilou há um minuto: ninguém o publicou, então não há digest registrado. Ele também diz por que resolver a Release de novo não mudaria isso — um guest lido ao lado da sua entidade em um diretório de catálogo é lido de novo a cada build, e um pull registra o seu digest apenas para um plugin de governança vinculado em um papel de transformação, o que este guest não é — e o que mudaria: publicar o plugin e referenciar a entidade publicada. Leia o aviso como o build se abstendo corretamente de afirmar uma verificação que não fez, e conte com ele enquanto o guest for local.

O erro é a constatação real, e o parêntese é o diagnóstico. O provedor foi encontrado, carregado e questionado sobre o que renderiza, e respondeu none — this provider supports: none. O descritor escrito no início nomeava o socket, a capacidade e as exportações, mas nunca dizia qual dos três tipos de entrada de Recipe o guest trata. O host não adivinha: o controle de tipos de entrada lê o conjunto declarado pelo guest e recusa um nó que o guest nunca reivindicou.

Essa é a forma da maioria das falhas de um primeiro provedor. O guest está bem; a sua autodescrição está incompleta. describe() não é uma formalidade que o host tolera — é toda a base sobre a qual um host agnóstico em relação ao formato decide o que enviar e para onde.

8. Declarar o contrato de comportamento de renderização

Adicione o contrato ao descritor em 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 é a afirmação que o controle procurava. Os dois valores false também são afirmações, e declará-los é justamente o objetivo: uma Recipe que incorpora uma árvore de código-fonte, ou uma que declara uma carga de trabalho, agora é recusada antes que qualquer renderização seja executada, com uma mensagem que nomeia este provedor — em vez de chegar a render_node e falhar em algum ponto dentro dele.

BoundaryAssembly: "none" diz que a saída de cada nó é gravada onde cai, sem nada a combinar. Um provedor que reúne vários componentes em um único documento declara, em vez disso, merge ou nest, e exporta assemble_boundary para fazê-lo. Essa é a próxima coisa natural a adicionar a este provedor, e está documentada no contrato de plugins.

Recompile o guest, gere a entidade de novo e coloque o novo .wasm de volta ao lado dela:

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

A entidade gerada de novo agora traz o contrato, lido do binário:

[… 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

Gerar a entidade de novo após cada recompilação do guest faz parte do ciclo. A entidade repete o que o binário informa, e os dois são comparados quando o guest é carregado: uma exportação ou um valor de contrato que a entidade afirma e o binário não informa é uma divergência na qual o build é interrompido, nomeando a afirmação. Uma afirmação que a entidade omite não é verificada, então uma entidade que ficou para trás após uma recompilação que acrescentou algo ao binário — como fez esta etapa — ainda é carregada, embora não o descreva mais.

9. O build que renderiza

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

A linha final nomeia o diretório de saída por completo, em que <workspace> representa a raiz do espaço de trabalho. A árvore renderizada abaixo dele:

dist/infra/dotenv/app/app.env

E o arquivo que o provedor gravou, completo:

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

Cada decisão que o guest toma é visível nessas sete linhas.

  • service-name e log.level chegaram como foram escritas e saíram como SERVICE_NAME e LOG_LEVEL. O autor nunca precisou escrever a gramática do destino.
  • GREETING está entre aspas e as outras três não. hello world contém um espaço, então sem aspas terminaria em hello; o endpoint não contém nenhum dos caracteres que o formato lê como sintaxe, então colocá-lo entre aspas só acrescentaria ruído.
  • As duas chaves de proveniência são comentários, porque um arquivo de ambiente não tem nenhum outro lugar para colocá-las. Um provedor cuja saída tem um bloco de metadados coloca as mesmas chaves lá. O host calculou as chaves; o guest escolheu onde colocá-las.
  • Os valores vieram de dois autores diferentes. service_name, log_level e greeting são a intenção do desenvolvedor, vinda do Aggregate. endpoint é do operador, vindo da Release. O guest não viu nenhuma das duas distinções — ele recebeu um único corpo avaliado.

10. Duas coisas que vale verificar antes de confiar nele

Que ele é determinístico. Capture a saída, recompile e compare:

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

Que diff não imprima nada é o resultado que você quer. O determinismo é contrato do guest, não do host, e um guest que itera um map de Go em algum ponto do seu caminho de saída vai falhar nesta verificação parecendo perfeitamente correto em um único build.

Que as suas recusas são visíveis. Quebre uma linha do artefato da Recipe, de modo que ela não declare nenhum valor:

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

A própria mensagem do guest chega intacta ao autor, com o arquivo e a linha de onde veio. Vale a pena verificar isso deliberadamente, porque a falha alternativa — um guest que pula silenciosamente uma linha que não consegue analisar — produz um build que é bem-sucedido e uma Release sem uma variável, e nada na saída indica isso.

11. O que adicionar em seguida

O provedor construído aqui está completo, mas é mínimo. Em ordem aproximada da frequência com que cada um é necessário:

  • assemble_boundary, para reunir a saída de vários componentes em um único documento, declarado por meio de BoundaryAssembly.

  • validate_node_input, para verificar estruturalmente a entrada de um nó antes que qualquer renderização seja executada, de modo que uma entrada malformada seja informada na fronteira da autoria em vez de no meio da renderização.

  • Fatos de renderização, para informar algo sobre o que o guest gravou que só o conhecimento que este provedor tem do formato de arquivos de ambiente consegue ver — aqui, os nomes de variável que cada arquivo define. Um fato é um nome e uma lista, ambos do vocabulário próprio deste provedor, retornados ao lado dos arquivos — e o valor é sempre um array JSON, mesmo com uma única entrada, ou o build é interrompido:

    // 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}},
    }

    O compilador mantém os fatos na ordem em que o guest os lista, verifica apenas que cada valor é uma lista, entrega as listas aos templates de Feature que as leem e grava os mesmos arquivos, sejam eles informados ou não. Documente o nome de cada fato e o que as suas entradas contêm como parte do contrato do provedor.

  • Entradas de omissão, quando o provedor passar a renderizar uma fonte. A entrada de uma renderização de fonte pode trazer Omits, entradas que nomeiam unidades renderizadas a deixar de fora, ao lado do seu SourceListing; um provedor que as respeita deixa de fora do que retorna cada unidade correspondente, informa uma contagem por entrada em Omitted e declara Omits: true no seu contrato. Elas nunca acompanham uma renderização apenas de artefatos como a deste provedor, então ele só as encontra depois de renderizar uma entrada com fonte. Omitir unidades renderizadas no contrato de plugins traz a estrutura completa.

  • Publicação, que transforma o arranjo local dev-catalog em um artefato fixado por digest que uma Release resolve e verifica. O guia do desenvolvedor de plugins cobre esse ciclo de vida, nas etapas de publicação, pull e build.

As estruturas de carga útil e de resultado de cada socket estão no contrato de plugins.