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

Escrever um fornecedor: um guia passo a passo com exemplo

Esta página percorre toda a tarefa de escrever um guest de fornecedor, desde um diretório vazio até uma compilação que escreve os ficheiros que o fornecedor renderizou. É o complemento prático do guia do programador de plugins, que documenta a entidade e o ciclo de vida, e do contrato de plugins, que documenta os sockets.

O fornecedor construído aqui é suficientemente pequeno para ser lido de uma só vez e faz um trabalho real: renderiza ficheiros de ambiente. Esse destino é um bom primeiro fornecedor porque a sua tradução é genuinamente específica do formato — um ficheiro 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 da compilação —, pelo que o guest tem de tomar todas as decisões que um fornecedor 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 dos passos abaixo, pela ordem em que aparecem, seguindo a convenção de saída: um bloco ou está completo ou é um excerto que marca onde foram omitidas linhas. Este é um guia que se monta por conta própria, e não um espaço de trabalho que se possa clonar, pelo que os blocos de código-fonte são os ficheiros a criar, e não ficheiros a obter do repositório.

O que é necessário

  • A cadeia de ferramentas do Go, que compila para WebAssembly sem ferramentas adicionais.
  • Um checkout do kit de desenvolvimento de plugins, que o guia do programador de plugins apresenta, e do pacote ABI sobre o qual o kit assenta: o go.mod do guest mais abaixo aponta para ambos.
  • O binário aggrega.

A estrutura do resultado final

Um fornecedor são dois artefactos: um guest .wasm e uma entidade Plugin que o leva para um catálogo. Nada mais — nenhuma alteração no host, nenhuma inscrição, nenhuma compilação do compilador. Adicionar um fornecedor é adicionar esses dois ficheiros onde uma compilação os possa ver.

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

Todos os plugins exportam describe(). O host chama-o uma vez quando carrega o guest e lê a resposta como o relato que o guest faz de si próprio. Para um fornecedor, contam quatro partes dessa resposta.

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 indica qual o socket que este guest serve. Capabilities é a lista em relação à qual uma Recipe é resolvida: uma Recipe cujo spec.capability é dotenv será encaminhada para este guest. Exports nomeia os pontos de entrada para os quais o host pode encaminhar; render_node é aquele que todos os fornecedores têm de ter.

Este descritor é deliberadamente incompleto, como costuma ser um primeiro rascunho. É na primeira compilação, mais abaixo, que isso se revela.

2. Renderizar um nó

render_node é chamado uma vez por cada componente que a compilação renderiza através deste fornecedor. Recebe a identidade do nó, o contexto de renderização e as entradas pré-avaliadas que a Recipe associada declarou — aqui, um conjunto de artefactos que o host já leu e avaliou como template.

Todo o trabalho do guest é decidir que bytes saem. Acrescente 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 fornecedor, e nenhuma outra camada as poderia tomar. Que caracteres obrigam ao uso de aspas é um facto dos ficheiros de ambiente. O mesmo se aplica à gramática dos nomes de variável, e à escolha de recusar uma chave que não encaixa em vez de lhe mudar o nome — uma variável com o nome mudado é uma que a aplicação vai procurar e não vai encontrar, o que é pior do que uma compilação interrompida.

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 circula numa codificação binária, e o kit lê-a e escreve-a. O host entrega a render_node a sua entrada como CBOR canónico e lê a resposta na mesma codificação, pelo que o guest descodifica 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 ficheiro é um slice de bytes que o guest preenche com os bytes exatos a escrever; o codificador transporta-os como bytes em bruto e o host escreve-os tal como estão.

O host entrega ao guest conteúdo que já avaliou. O Content de cada entrada de artefacto é o corpo escrito pelo autor com as suas expressões de template já resolvidas em relação ao contexto de renderização — o guest nunca avalia um template e nunca lê um ficheiro. É 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. Numa compilação normal, nada o verifica pelo utilizador. Aqui resulta de ordenar as chaves de proveniência antes de as emitir e de percorrer as entradas de artefacto pela 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 é uma compilação normal 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 escreve go.sum, as somas de verificação das dependências, sem o qual a compilação se recusa a ser executada. -trimpath e -buildvcs=false mantêm caminhos de compilação e carimbos do controlo de versões 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 o passo seguinte lê.

Confirme as exportações antes de avançar:

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, o que constitui a predefinição de menor privilégio: não precisa nem do sistema de ficheiros 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 a partir do guest, para que a entidade não possa prometer algo que o binário não faz. O utilizador fornece apenas a identidade, numa 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

Repare no 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 registo que estiver configurado —, pelo que não há nenhum campo de localização a escrever e nenhum em que errar. O digest do conteúdo é registado quando uma Release é resolvida, no ficheiro de bloqueio dessa Release, e não na entidade.

5. Colocar o guest onde uma compilação o vai procurar

Enquanto se desenvolve um guest não há nada publicado para obter, pelo que a compilação 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 ficheiro inclui 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 têm de chegar a dois ficheiros.

Copie o ficheiro compilado para lá em vez de criar uma ligação para ele. Uma ligação nesse local só é seguida 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; uma que leve mais longe interrompe a compilação e o pull nomeando a ligação, como expõe a fronteira do espaço de trabalho.

A entidade plugin de um fornecedor num diretório de catálogo nunca é fixada, e nem um pull nem uma compilação obtêm o seu .wasm, pelo que o ficheiro tem de estar presente quando a Release é resolvida. Um pull verifica antes de escrever o ficheiro de bloqueio: quando não encontra o .wasm nem ao lado da entidade nem em nenhum outro local de onde uma compilação lê plugins, é interrompido e nomeia o ficheiro e o diretório onde o esperava, como descreve A plugin’s .wasm is not on this machine (O ficheiro 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, pelo que uma primeira compilação não precisa de um passo de resolução separado.

6. Os documentos que visam o fornecedor

Quatro ficheiros. O Component declara o que um autor pode definir; a Recipe associa a capacidade e define o artefacto; o Aggregate exprime a intenção; a Release posiciona-a.

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. Nomeia uma capacidade, não um plugin: a compilação resolve-a para o plugin de fornecedor, seja ele qual for, que declara essa capacidade. Onde existe exatamente um — como aqui — nada mais é necessário.

As chaves escritas não estão, propositadamente, 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 fornecedor.

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. A primeira compilação, e o que ela 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 dizem coisas diferentes.

O aviso é esperado durante o desenvolvimento, e não vai desaparecer. Diz que o guest foi executado sem um digest de conteúdo registado com o qual o verificar, o que corresponde à verdade de um guest compilado há um minuto: ninguém o publicou, pelo que não há nenhum digest registado. Diz também porque é que resolver de novo a Release não mudaria isso — um guest lido ao lado da sua entidade num diretório de catálogo é lido de novo por cada compilação, e um pull regista o seu digest apenas para um plugin de governação anexado num 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 a compilação a abster-se corretamente de afirmar uma verificação que não fez, e conte com ele enquanto o guest for local.

O erro é a verdadeira constatação, e o parêntese é o diagnóstico. O fornecedor foi encontrado, carregado e interrogado 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 controlo de tipos de entrada lê o conjunto declarado pelo guest e recusa um nó que o guest nunca reivindicou.

Esta é a forma da maioria das falhas de um primeiro fornecedor. 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

Acrescente 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 controlo procurava. Os dois valores false também são afirmações, e declará-los é precisamente o objetivo: uma Recipe que incorpora uma árvore de código-fonte, ou uma que declara uma carga de trabalho, passa a ser recusada antes de qualquer renderização ser executada, com uma mensagem que nomeia este fornecedor — em vez de chegar a render_node e falhar algures dentro dele.

BoundaryAssembly: "none" indica que a saída de cada nó é escrita onde cai, sem nada a combinar. Um fornecedor que reúne vários componentes num único documento declara, em vez disso, merge ou nest, e exporta assemble_boundary para o fazer. Essa é a próxima coisa natural a acrescentar a este fornecedor, e está documentada no contrato de plugins.

Volte a compilar o guest, gere de novo a entidade e volte a colocar o novo .wasm 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 traz agora o contrato, lido a partir 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 de novo a entidade após cada recompilação do guest faz parte do ciclo. A entidade repete o que o binário comunica, 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 comunica é uma divergência na qual a compilação é interrompida, nomeando a afirmação. Uma afirmação que a entidade omite não é verificada, pelo que uma entidade que ficou para trás após uma recompilação que acrescentou algo ao binário — como fez este passo — continua a ser carregada, embora já não o descreva.

9. A compilação 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 ficheiro que o fornecedor escreveu, 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 tal como foram escritas e saíram como SERVICE_NAME e LOG_LEVEL. O autor nunca teve de escrever a gramática do destino.
  • GREETING está entre aspas e as outras três não. hello world contém um espaço, pelo que sem aspas terminaria em hello; o endpoint não contém nenhum dos caracteres que o formato lê como sintaxe, pelo que pô-lo entre aspas só acrescentaria ruído.
  • As duas chaves de proveniência são comentários, porque um ficheiro de ambiente não tem nenhum outro sítio onde as colocar. Um fornecedor cuja saída tem um bloco de metadados coloca lá as mesmas chaves. O host calculou as chaves; o guest escolheu onde as colocar.
  • Os valores vieram de dois autores diferentes. service_name, log_level e greeting são a intenção do programador, vinda do Aggregate. endpoint é do operador, vindo da Release. O guest não viu nenhuma das duas distinções — recebeu um único corpo avaliado.

10. Duas coisas que vale a pena verificar antes de confiar nele

Que é determinístico. Capture a saída, volte a compilar 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 pretendido. O determinismo é contrato do guest, não do host, e um guest que itera um map de Go algures no seu caminho de saída vai falhar nesta verificação parecendo perfeitamente correto numa única compilação.

Que as suas recusas são visíveis. Parta uma linha do artefacto 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 ficheiro e a linha de onde veio. Vale a pena verificar isto deliberadamente, porque a falha alternativa — um guest que salta silenciosamente uma linha que não consegue analisar — produz uma compilação bem-sucedida e uma Release a que falta uma variável, e nada na saída o indica.

11. O que acrescentar a seguir

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

  • assemble_boundary, para reunir a saída de vários componentes num único documento, declarado através de BoundaryAssembly.

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

  • Factos de renderização, para comunicar algo sobre o que o guest escreveu que só o conhecimento que este fornecedor tem do formato dos ficheiros de ambiente consegue ver — aqui, os nomes de variável que cada ficheiro define. Um facto é um nome e uma lista, ambos do vocabulário próprio deste fornecedor, devolvidos ao lado dos ficheiros — e o valor é sempre um array JSON, mesmo com uma única entrada, caso contrário a compilação é interrompida:

    // 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 factos pela 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 escreve os mesmos ficheiros, quer sejam comunicados quer não. Documente o nome de cada facto e o que as suas entradas contêm como parte do contrato do fornecedor.

  • Entradas de omissão, quando o fornecedor 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 fornecedor que as respeita deixa de fora do que devolve cada unidade correspondente, comunica uma contagem por entrada em Omitted e declara Omits: true no seu contrato. Nunca acompanham uma renderização apenas de artefactos como a deste fornecedor, pelo que este só as encontra depois de renderizar uma entrada com fonte. Omitir unidades renderizadas no contrato de plugins apresenta a estrutura completa.

  • Publicação, que transforma a disposição local dev-catalog num artefacto fixado por digest que uma Release resolve e verifica. O guia do programador de plugins cobre esse ciclo de vida, nas fases de publicação, pull e compilação.

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