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.moddo 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.yaml1. 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 describefunc 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_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() {}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/go3. Compilar o guest
Um guest é um build comum de Go com o destino WebAssembly selecionado:
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 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:
aggrega inspect --plugin dotenv.wasmPlugin .wasm: dotenv.wasmExports: render_nodehostFunctions (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/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.yamlA entidade gerada:
# 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: - dotenvObserve 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.yamldev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasmcp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasmO 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-catalogauto_pull: trueauto_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/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 é 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/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. O primeiro build, e o que ele recusa
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-onlyLeia 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:
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.wasmA 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: noneGerar 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
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>/distA 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.envE o arquivo que o provedor gravou, completo:
# aggrega.ai/boundary-path=infraSERVICE_NAME=checkoutLOG_LEVEL=debugGREETING="hello world"ENDPOINT=https://checkout.example.netCada decisão que o guest toma é visível nessas sete linhas.
service-nameelog.levelchegaram como foram escritas e saíram comoSERVICE_NAMEeLOG_LEVEL. O autor nunca precisou escrever a gramática do destino.GREETINGestá entre aspas e as outras três não.hello worldcontém um espaço, então sem aspas terminaria emhello; 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_levelegreetingsã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:
cp -r dist ../capture && rm -rf distaggrega build --release release.yamldiff -r ../capture distQue 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=valueA 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 deBoundaryAssembly. -
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 seuSourceListing; um provedor que as respeita deixa de fora do que retorna cada unidade correspondente, informa uma contagem por entrada emOmittede declaraOmits: trueno 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-catalogem 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.
Referências relacionadas
- Guia do desenvolvedor de plugins Wasm — a entidade
Plugin, a superfície de capacidades e o ciclo de vida da publicação. - Contrato do Plugin — as estruturas de entrada e de saída de cada socket.
- Arquitetura de Provider — como os provedores se encaixam no pipeline de compilação.
- Índice de referência de Provider — o que cada provedor da biblioteca padrão produz.
- Ler a saída nestas páginas — a convenção que os blocos de saída acima seguem.