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.moddo 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.yaml1. 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 describefunc 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_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 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/go3. Compilar o guest
Um guest é uma compilação normal 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 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:
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, 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/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: - dotenvRepare 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.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 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-catalogauto_pull: trueauto_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/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. 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/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. A primeira compilação, e o que ela 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 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:
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 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: noneGerar 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
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 ficheiro que o fornecedor escreveu, 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 tal como foram escritas e saíram comoSERVICE_NAMEeLOG_LEVEL. O autor nunca teve de escrever a gramática do destino.GREETINGestá entre aspas e as outras três não.hello worldcontém um espaço, pelo que sem aspas terminaria emhello; 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_levelegreetingsã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:
cp -r dist ../capture && rm -rf distaggrega build --release release.yamldiff -r ../capture distQue 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=valueA 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 deBoundaryAssembly. -
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 seuSourceListing; um fornecedor que as respeita deixa de fora do que devolve cada unidade correspondente, comunica uma contagem por entrada emOmittede declaraOmits: trueno 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-catalognum 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.
Referências relacionadas
- Guia do programador 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 fornecedores se integram no pipeline de compilação.
- Índice de referência de Provider — o que cada fornecedor da biblioteca padrão produz.
- Ler a saída nestas páginas — a convenção que os blocos de saída acima seguem.