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

Guia do programador de plugins Wasm

Este é o guia canónico para criar um plugin WebAssembly (Wasm) do Aggrega e publicá-lo como entidade do catálogo. Ensina o contrato do autor de plugins de ponta a ponta: o que é um plugin, como um plugin se descreve ao anfitrião, como criar os seus exports e as suas declarações de capacidades, os limites de execução e as funções do anfitrião que o anfitrião aplica, a entidade Plugin que leva um plugin para o catálogo, como uma Recipe ou uma FeatureRecipe referencia um plugin, e o ciclo de vida publish→pull→build que leva um plugin de um ficheiro .wasm em disco até um artefacto verificado e fixado por digest que uma compilação consome.

A página complementar plugin-contract.md documenta os sockets — os pontos do pipeline onde os plugins são anexados e as formas de entrada/saída que cada socket consome e produz. Este guia documenta o plugin — a entidade, a superfície de capacidades e o ciclo de vida. A página do contrato indica que socket o plugin visa; esta página indica como criá-lo e distribuí-lo.

Para um percurso prático por toda a tarefa em vez de uma referência sobre ela, criar um fornecedor constrói de ponta a ponta um pequeno guest de fornecedor — descritor, compilação, entidade, anexo e uma renderização cuja saída se pode ler —, incluindo a recusa que um primeiro rascunho costuma encontrar e como a ler.

1. O que é um plugin Wasm

Um plugin Wasm é um módulo WebAssembly que estende o compilador num socket designado. O binário anfitrião em Go não contém qualquer lógica específica da cloud ou da infraestrutura; toda a inteligência específica do domínio — renderização de templates, tradução de formatos, avaliação de políticas, linting — reside nos plugins. O anfitrião orquestra o pipeline e passa o payload de cada socket ao guest através da fronteira da ABI; o guest faz o trabalho de domínio e devolve a forma de resultado desse socket. O payload e o resultado de cada socket viajam como CBOR canónico, com duas exceções: um plugin CLI recebe o seu vetor de argumentos como texto JSON e responde com um código de saída e o texto que transmite, e a autodescrição describe é texto JSON. A secção de cada socket no contrato de plugins indica a sua codificação, e um guest lê-a e escreve-a através dos pontos de entrada que o tipo de payload do seu kit já inclui, pelo que nenhum guest analisa bytes à mão.

Um plugin é executado por detrás de uma firewall de pureza ahead-of-time. O anfitrião carrega e executa o módulo através de um runtime Wasm integrado, numa configuração com capacidades recusadas: sem sockets de rede, sem sistema de ficheiros, sem ambiente, stdio descartado e um relógio de parede observável congelado num instante invariante entre compilações. Qualquer chamada de E/S que um guest tente falha na fronteira da chamada, pelo que um plugin não pode recorrer ao estado de tempo de execução. Os plugins devem ser criados tendo esta firewall em conta: um plugin transforma o payload que lhe é entregue e devolve um resultado que o anfitrião consome literalmente, e o determinismo é responsabilidade de quem cria o plugin — uma entrada idêntica tem de produzir bytes de saída idênticos. O único canal sancionado para conteúdo remoto é a obtenção de entradas externas mediada pelo anfitrião (secção 4), que serve bytes segundo uma disciplina de fixação por digest em vez de dar ao guest acesso direto à rede.

Os sockets que um plugin pode visar — entre eles o ponto de controlo de mutação na construção da topologia, o ponto de controlo de validação na análise estática, o pipeline de FeatureRecipe, o linter fora de banda e o socket de renderização de fornecedores — e as suas formas de entrada/saída por socket estão documentados em plugin-contract.md. O socket que um plugin serve é o único valor que declara em metadata.pluginType, e o conjunto completo de valores que esse campo aceita é a respetiva entrada de referência em entities/plugin.md §«metadata.pluginType». Os exemplos deste guia usam provider (renderiza nós de IR em artefactos nativos do fornecedor), linter (inspeciona o conteúdo criado pelo autor e emite diagnósticos) e pipeline-step (um passo no pipeline: de uma FeatureRecipe ou de uma Recipe que aplica patches ao conjunto de documentos renderizados).

O guest é criado face ao anfitrião através do kit de desenvolvimento de plugins (PDK) em três linguagens — Go, Rust ou TypeScript. O PDK encapsula a toolchain Wasm subjacente com builders tipados do Aggrega para as formas de entrada e saída que cada socket transporta.

2. A autodescrição describe()

Todo o plugin exporta uma função describe() que devolve a autodescrição do plugin: o tipo ou os tipos de socket que implementa, a versão da ABI que visa, as capacidades que declara — lidas de acordo com o tipo de socket, ou seja, nomes de capacidades para um fornecedor ou um passo de pipeline e formatos de fonte com prefixo para um analisador ou um importador —, as funções do anfitrião que importa e a capacidade por export de cada ponto de entrada que oferece. describe() é o relato que o próprio plugin faz daquilo que é e daquilo que faz.

A autodescrição é a âncora do modelo de confiança. A entidade Plugin que leva o plugin para o catálogo (secção 5) reafirma os mesmos factos como declarações criadas pelo autor, e o anfitrião confronta as declarações da entidade com a saída de describe() do plugin em dois momentos — na publicação, antes de qualquer byte chegar ao registo, e no carregamento, antes de o plugin ser executado. Uma divergência causa uma interrupção explícita. A entidade é a superfície legível por pessoas e visível no catálogo; describe() é a referência de máquina face à qual o anfitrião a verifica. Ambas devem ser criadas de forma a concordarem; a verificação cruzada existe precisamente para detetar o caso em que divergem. Verifica aquilo que a entidade declara e não aquilo que omite: uma entidade que declara menos do que o binário comunica — por exemplo, uma que ficou para trás após uma recompilação que acrescentou um export — continua a ser carregada, embora já não descreva tudo o que o binário faz.

3. Criar os exports e as suas declarações de capacidades

Um plugin oferece um ou mais exports — pontos de entrada nomeados para os quais o anfitrião despacha chamadas (por exemplo render_node, lint_naming, step). Cada export transporta um bloco de capacidade: a declaração do autor sobre o que esse export faz. A capacidade de um export tem quatro campos:

  • name — o nome ABI do export, o nome para o qual o anfitrião despacha chamadas. Obrigatório.
  • operates — a operação de pipeline que o export executa: patch (modificar um documento renderizado existente) ou emit (acrescentar um novo documento). Esta é uma declaração de capacidade explícita. O anfitrião confronta-a com a autodescrição describe() do plugin na publicação e no carregamento, pelo que a declaração criada na entidade e o relato próprio do plugin têm de concordar. É uma declaração validada sobre o export, e não um seletor de despacho: no momento da renderização, a operação que um passo efetivamente executa é transportada pelo resultado devolvido pelo guest, e não selecionada a partir deste campo. Se ausente, não transporta qualquer declaração de operação.
  • scope — a raiz de documentos sobre a qual o export opera: own (os documentos renderizados próprios do nó) ou host (os documentos do componente ao qual uma FeatureRecipe com âmbito de componente está anexada). Antes de o plugin de um passo de pipeline ser executado, o anfitrião lê o âmbito de export declarado do passo e impõe que o fornecedor que renderiza os documentos desse âmbito apareça nas spec.pipelineStep.capabilities do plugin (secção 5) — um export com âmbito own é verificado face ao fornecedor que renderiza os documentos próprios do nó, um export com âmbito host face ao fornecedor do componente anfitrião, e um âmbito vazio equivale a own para esta verificação. Este é o ponto de controlo de compatibilidade de fornecedores, executado antes do passo; o documento em que uma operação do guest efetivamente toca é nomeado por operação no resultado devolvido pelo guest, e não selecionado a partir deste campo declarado. Se ausente, o valor predefinido é own.
  • selector — uma descrição livre e legível por pessoas daquilo sobre o que o export atua (por exemplo workloads carrying a pod template). Documentação para os leitores do catálogo e para a superfície aggrega inspect; o compilador não a interpreta.

Os exports devem ser criados pela ordem em que se pretende que sejam lidos; as entradas preservam a ordem do autor na entidade e em inspect. Um plugin sem exports criados não declara qualquer superfície de export — o que é válido para um plugin cujo socket não precisa de uma declaração de capacidade por export.

4. Limites de execução e funções do anfitrião

Uma entidade de plugin pode ter um bloco runtime opcional que restringe a forma como o anfitrião carrega e executa o plugin.

Limites de memória e de tempo. maxMemoryPages limita a memória linear do plugin em páginas Wasm (64 KiB por página); timeoutMs limita durante quanto tempo o código próprio do plugin pode ser executado numa chamada, em milissegundos. O tempo passado dentro das funções do anfitrião que o plugin chama não é contabilizado. Em Linux, a medida é o tempo de processador da thread que executa o guest, pelo que o tempo que o guest passa à espera de um processador numa máquina ocupada também não é contabilizado; noutros sistemas, é o tempo decorrido. A primeira chamada a um plugin acabado de carregar contabiliza também a inicialização única do runtime da linguagem guest, que é executada dentro dessa chamada. Ambos os limites são opcionais com valores predefinidos: zero ou ausente aplica o limite predefinido da plataforma. O carregador limita cada plugin ao valor predefinido da plataforma quando a entidade não declara nenhum, pelo que um carregamento nunca é ilimitado e uma chamada nunca é impossível de cancelar. Um limite deve ser aumentado na entidade quando um anexo precisar efetivamente de mais memória ou de mais tempo do que o valor predefinido permite.

Funções do anfitrião. hostFunctions regista os nomes das funções do anfitrião que o plugin importa. É um campo derivado por máquina — não deve ser escrito à mão. aggrega plugin sync lê as funções do anfitrião diretamente da secção de importações do .wasm e regista o campo no ficheiro da entidade, e a publicação volta a derivá-las do binário e recusa uma entidade cujo registo difira; assim, um plugin obtém exatamente as funções do anfitrião que o seu binário efetivamente importa, validadas face a uma lista de permissões selecionada (uma importação fora da lista de permissões é rejeitada de forma explícita). O registo é um instantâneo do binário publicado, da mesma forma que a referência plugin: endereçada por conteúdo é um instantâneo dos bytes publicados: reflete o binário no momento da publicação e é novamente derivado e verificado quando o plugin é obtido por pull. Para ver as funções do anfitrião que um .wasm local importa antes da publicação — o valor que aggrega plugin sync regista —, executa-se aggrega inspect --plugin <file.wasm>.

A superfície do anfitrião selecionada. Três das funções do anfitrião são de uso geral: aggrega_log (um nível e uma mensagem, emitidos como uma linha de log no destino de logs do anfitrião), aggrega_emit_warning (um código, uma mensagem e um caminho, acumulados como um aviso estruturado que o anfitrião apresenta após a chamada) e aggrega_fetch_external_input (um URL, respondido com os bytes da entrada segundo a disciplina de fixação abaixo). O PDK encapsula as três em cada linguagem — Go: aggrega.Log, aggrega.EmitWarning, aggrega.FetchExternalInput; Rust: log, emit_warning, fetch_external_input; TypeScript: log, emitWarning, fetchExternalInput —, pelo que um guest chama uma função tipada em vez da ABI em bruto. Os callbacks de fonte e de análise — para um guest que lê fatias de uma fonte adquirida ou obtém uma árvore analisada através do anfitrião — e a codificação que as ranhuras de cada callback transportam estão listados em plugin-contract.md.

O conteúdo da fonte local chega através do anfitrião — nunca do sistema de ficheiros. Um plugin de renderização de fornecedor nunca lê a sua fonte do disco; uma chamada ao sistema de ficheiros falha na fronteira da chamada. O anfitrião entrega ao guest uma listagem da fonte dentro do payload de renderização — o caminho de cada entrada relativo à raiz da fonte e se é um diretório, por ordem, sem conteúdo de ficheiros — e o guest aplica-lhe a sua própria lógica de estrutura e depois volta a ler exatamente os ficheiros que seleciona através dos callbacks de fonte, que devolvem os bytes que o anfitrião lê sob a raiz da fonte. As formas de payload por socket e os callbacks estão documentados em plugin-contract.md.

O conteúdo remoto chega através da obtenção de entradas externas. Um plugin que precisa de conteúdo remoto — um arquivo de chart, um documento de esquema remoto — chama o wrapper de obtenção do PDK. Na transmissão, o guest passa o URL a aggrega_fetch_external_input como texto UTF-8 e recebe uma única resposta em CBOR canónico, que transporta ou os bytes obtidos, em bruto, ou uma mensagem de erro ao lado do seu código comparável por máquina; o wrapper descodifica a resposta em bytes ou erro. Os bytes chegam exatamente como foram obtidos, incluindo um payload que não seja UTF-8 válido, e um payload de comprimento zero volta como bytes vazios em vez de um erro. O anfitrião serve o URL segundo a disciplina de fixação de entradas externas:

  • Um URL já fixado no ficheiro de bloqueio da Release é servido a partir do armazenamento local endereçado por conteúdo e verificado face ao seu digest registado em cada leitura. Um blob em falta no armazenamento é recarregado a partir da rede pelo digest registado — um recarregamento verificado por digest não pode alterar a saída.
  • Um URL não fixado é recusado, com um erro que nomeia o URL e a solução. Uma compilação renderiza o fecho que o seu ficheiro de bloqueio regista, pelo que nenhuma compilação obtém uma referência não fixada e não existe qualquer definição que o faça.
  • A fixação acontece quando as dependências da Release são resolvidas: aggrega pull renderiza a Release para descobrir que entradas externas a sua renderização solicita, obtém cada uma delas e regista-a no ficheiro de bloqueio ao lado das fixações de dependências. Assim, o ciclo de trabalho do autor de um plugin é: resolver uma vez e depois compilar offline tantas vezes quantas se quiser.

Os esquemas permitidos são https, http apenas para anfitriões de loopback, e oci (fixado pelo digest do manifesto). O ficheiro de bloqueio regista cada entrada fixada — o seu URL, o digest sha256, o tamanho e os plugins que a exigiram —, pelo que uma nova compilação serve os mesmos bytes a partir do armazenamento local: reproduzível e offline depois de fixada.

Com o PDK Go:

import "github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega"
chart, err := aggrega.FetchExternalInput("https://charts.example.com/postgresql-16.3.2.tgz")
if err != nil {
// The error names the URL and the remedy — an unpinned URL reports exactly
// what to pin and how. Surface it as a render failure; do not mask it.
return fmt.Errorf("fetching chart archive: %w", err)
}

O que falha, e porquê.

  • Uma chamada ao sistema de ficheiros ou à rede falha na fronteira da chamada: o guest não tem diretórios pré-abertos nem sockets. Isto aplica-se a todos os caminhos de código, incluindo uma dependência de biblioteca que tente ler um ficheiro — em vez disso, a fonte deve ser lida através dos callbacks de fonte.
  • Uma importação sob um módulo que não seja wasi_snapshot_preview1, extism:host/env ou extism:host/user falha no carregamento, com um diagnóstico que nomeia o módulo e a importação. Os nomes individuais de funções WASI dentro de um módulo permitido nunca são censurados — as importações não utilizadas de sistema de ficheiros e de sockets do runtime de uma linguagem ligado estaticamente não são um problema, porque nomear uma importação não concede nada.
  • A obtenção de um URL que o ficheiro de bloqueio não fixa falha com um erro que nomeia o URL; a solução é executar aggrega pull --release <release>, que fixa cada entrada externa que a renderização da Release consome, e depois compilar.

Não existe qualquer campo de lista de anfitriões permitidos para o acesso de saída à rede. Um plugin nunca chega à rede em tempo de compilação — essa é a fronteira ahead-of-time —, pelo que não existe nenhum campo desse tipo para escrever. O conteúdo remoto chega através do canal de entradas externas mediado pelo anfitrião e fixado por digest descrito acima, nunca através de acesso ambiente à rede.

Configuração. configKV é um mapa de string para string que o runtime entrega ao plugin no arranque. As entradas preservam a ordem do autor, pelo que o registo emitido é idêntico byte a byte entre execuções. Se ausente, mantém-se em vigor a configuração vazia predefinida do runtime.

5. A entidade Plugin

Um plugin entra no catálogo como entidade Plugin — a superfície de criação e de metadados do plugin. A entidade declara o que o plugin é e aponta para o artefacto .wasm; o compilador não interpreta o comportamento do plugin e encaminha a referência fixada, enquanto o runtime Wasm executa os bytes.

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
capabilities:
- helm
- compose
signature:
type: sigstore-cosign
runtime:
maxMemoryPages: 256
timeoutMs: 5000
# hostFunctions is recorded by `aggrega plugin sync` from the .wasm — do not author it.
exports:
- name: fetch
operates: emit
scope: own
selector: external-secret resources for the bound credential

Os campos:

  • Nenhum campo de localização do artefacto, deliberadamente. A entidade não transporta qualquer ponteiro para o .wasm e o esquema não aceita nenhum. A localização do artefacto de um plugin é derivada da sua identidade — a coordenada metadata.pluginType/metadata.name, que forma o caminho do repositório plugin/<pluginType>/<name> — mais o registo para o qual o espaço de trabalho está configurado, pelo que não existe qualquer localização a escrever nem a errar. O digest de conteúdo resolvido é registado por Release no ficheiro de bloqueio dessa Release, e a compilação verifica os bytes obtidos face a ele: a identidade na entidade, os bytes verificados no ficheiro de bloqueio.
  • metadata.version — a release que a entidade publica, que tem de ser igual à versão de proveniência da compilação do próprio guest, tal como comunicada em describe(). O autor de um plugin atribui a versão ao .wasm no momento da compilação — a compilação grava a versão no guest, e uma compilação que a obtém de uma tag de release grava a versão da release apenas no commit que essa tag nomeia — e o metadata.version da entidade nomeia essa mesma release. O controlo de publicação confronta as duas e interrompe-se perante uma divergência, pelo que a entidade nomeia sempre a versão exata do binário que distribui. aggrega plugin gen-catalog --plugin (abaixo) copia a versão que o guest comunica para a entidade que gera, que é a versão da release quando o guest foi compilado a partir do commit com a tag. Obrigatório.
  • metadata.pluginType — o tipo de socket que este plugin implementa, escolhido entre provider, linter, pipeline-step, governance, cli, parser e importer. Um plugin implementa exatamente um. Situa-se no bloco de endereçamento ao lado de name e version e fornece o segmento <pluginType> da coordenada derivada. Obrigatório.
  • spec.abiVersion — a versão da ABI anfitrião/guest a que o plugin se destina. v1beta1 é o valor aceite; uma futura revisão da ABI acrescenta um valor aceite. Obrigatório.
  • O bloco do tipo de socket do plugin, que transporta capabilities — um plugin declara o que serve dentro do bloco que pertence ao seu metadata.pluginType, e é o bloco que fixa o que uma entrada significa. spec.provider.capabilities nomeia as capacidades que um fornecedor serve (nomes de capacidades como helm ou compose). spec.pipelineStep.capabilities nomeia os fornecedores com cuja saída renderizada o passo é compatível. spec.parser.capabilities nomeia os formatos de fonte que um analisador lê, cada um escrito parse:<format>. spec.importer.capabilities nomeia os formatos externos a partir dos quais um importador redige rascunhos de entidades, cada um escrito import:<format>. Um importador escrito em Go pode obter tudo o que não depende do seu formato — a pontuação, a decisão entre referenciar ou redigir um rascunho, os rascunhos e a respetiva renderização, e as suas definições — do pacote importer do kit Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Um plugin linter, governance ou cli não serve qualquer capacidade e não transporta nenhum dos quatro blocos. As entradas preservam a ordem do autor, e cada lista é uma declaração explícita e testada: deve declarar-se aquilo face ao qual o plugin foi efetivamente compilado e testado, porque um consumidor resolve exatamente face ao que está listado. Para um passo de pipeline, essa declaração é imposta na renderização — quando um passo toca num âmbito, a compilação é interrompida, a menos que o fornecedor que renderiza os documentos desse âmbito esteja entre os que o plugin declara —, pelo que uma lista vazia não corresponde a nenhum fornecedor e não admite o passo em lado nenhum.
  • spec.signature — um ponteiro descritivo opcional para a assinatura anexada do plugin (secção 8). Este bloco é apenas documentação: regista onde se encontra a assinatura e como foi produzida, para os leitores do catálogo; não admite, por si só, o plugin. A verificação que se impõe é a política de confiança por registo aplicada no pull.
  • spec.runtime — o bloco opcional de restrições de execução da secção 4. O autor escreve maxMemoryPages, timeoutMs e configKV; hostFunctions é derivado por máquina e registado por aggrega plugin sync, o que a publicação verifica, e não é escrito pelo autor.
  • spec.exports — as declarações de capacidade por export da secção 3 (name, operates, scope, selector).

Gerar a entidade a partir do .wasm. Não é necessário escrever à mão as partes da entidade geridas pela máquina. aggrega plugin gen-catalog --plugin <file.wasm> lê a autodescrição describe() do guest e produz a partir dela uma entidade Plugin pronta para publicação, juntamente com uma pequena sobreposição escrita pelo autor (a identidade, os limites de execução e um eventual bloco de fornecedor). O gerador grava os campos dos quais o binário é a fonte de verdade — as declarações de export, o contrato de capacidades, o espelho de comandos e o registo das funções do anfitrião — e copia metadata.version da versão de proveniência da compilação em describe() do guest, enquanto a sobreposição fornece apenas o que o binário não comunica. Este é o caminho suportado para o autor de um plugin de terceiros: compilar e versionar o .wasm e depois voltar a gerar a entidade, para que os seus campos geridos pela máquina se mantenham sincronizados com o binário. A versão é o único campo copiado que nomeia uma release em vez de um facto sobre os bytes, pelo que se deve gerar a partir de uma compilação do commit que a tag da release nomeia — ou, partindo de uma compilação de desenvolvimento, definir metadata.version como a release na entidade gerada antes de aplicar a tag ao commit que a contém. Um guest que não transporte qualquer versão de proveniência da compilação não pode ser gerado como uma entidade versionada — deve atribuir-se primeiro a versão ao guest no momento da compilação.

O .wasm ao lado da sua entidade. Enquanto cria um plugin, nada está publicado para uma compilação ir buscar, pelo que uma compilação lê o .wasm do plugin que está ao lado da sua entidade Plugin num diretório de catálogo, com um nome derivado do tipo de plugin e do nome da entidade: para pipeline-step/patch é pipeline-step--patch.wasm. As letras minúsculas, os dígitos e a maioria dos hífenes são escritos nesse nome tal como são; qualquer outro carácter é escrito numa forma de escape, tal como um hífen em algumas posições — por isso, onde isso importa, a recusa de um .wasm em falta, A plugin’s .wasm is not on this machine (o ficheiro de um plugin não está nesta máquina), indica o nome completo. aggrega lint <plugin.yaml> lê o .wasm do mesmo local — ao lado do ficheiro de entidade que recebe, em qualquer diretório em que esse ficheiro se encontre — a menos que o próprio binário contenha o plugin, e imprime um aviso para cada exportação, capacidade ou contrato que o .wasm reporta e que a entidade omite. Onde não houver nenhum .wasm aí, o lint indica que ignorou esse relatório, nomeando o ficheiro que procurou e o diretório, e o seu resultado não muda.

Para a referência campo a campo, ver a página da entidade ../entities/plugin.md.

6. Referenciar um plugin

Um passo de pipeline ou um socket de plugin referencia um plugin pelo seu URI de entidade Plugin — a identidade da entidade, e não diretamente o artefacto .wasm. A entidade é a camada que transporta a fixação por digest, as declarações de capacidade, os limites de execução e a assinatura; referenciar a entidade é a forma como um consumidor obtém tudo isso.

Um caminho .wasm simples ou uma referência de artefacto em bruto deixada num campo plugin é rejeitada no carregamento: nenhuma entidade Plugin lhe corresponde, pelo que a resolução do plugin falha de forma explícita. O URI da entidade é obrigatório — a indireção através da entidade é o contrato, e não uma conveniência opcional. Um passo de pipeline de uma FeatureRecipe nomeia a entidade em pipeline[].plugin; ver ../entities/featurerecipe.md para a superfície de criação do pipeline.

Quando dois ou mais plugins estão acoplados — têm de concordar num contrato de transferência partilhado, como num par Fetcher e Injector em que a saída de um plugin é a entrada do outro (o princípio do Plugin em duas partes descrito em plugin-contract.md) —, esse contrato deve ser escrito uma única vez e cada plugin deve depender da definição única, em vez de reafirmar a forma JSON da transferência de modo independente em cada plugin. A forma partilhada é a estrutura JSON que os plugins trocam, que pode residir numa única entrada de SchemaLibrary referenciada por ambos os plugins. Uma fonte única para o contrato mantém os plugins acoplados sincronizados à medida que este evolui; as reafirmações independentes divergem, e a divergência só surge quando os dois deixam de concordar em tempo de execução. A recomendação é partilhar o contrato, e não o código Wasm — cada plugin continua a ser um artefacto próprio.

7. O ciclo de vida publish → pull → build

Um plugin passa de um ficheiro .wasm em disco a um artefacto verificado e consumível por uma compilação através de três fases.

Publish. aggrega push publica uma entidade Plugin e o seu .wasm em conjunto como um único manifesto OCI, com a tag metadata.version: o YAML da entidade é o blob de configuração do manifesto e o .wasm segue como uma camada do mesmo manifesto. Publicar o par como um único manifesto com tag é o que torna o push atómico — não existe qualquer janela em que uma metade esteja publicada e a outra não — e é por isso que uma única assinatura sobre esse manifesto cobre ambas as metades. Ambas as metades estão nomeadas no manifesto, pelo que um cliente OCI genérico que obtenha a tag de versão escreve a entidade em entity.yaml e o executável em entity.wasm.

Antes de qualquer byte chegar, a publicação executa as suas verificações. A entidade é lida primeiro face ao esquema Plugin, tal como um carregamento do catálogo a lê, pelo que um metadata.version que não seja uma versão semântica — ou qualquer outro desvio do esquema — é recusado antes de o .wasm ser lido. O .wasm é depois carregado e a sua autodescrição describe() é confrontada com as declarações de capacidade criadas na entidade — uma divergência causa uma interrupção explícita, pelo que uma entidade publicada nunca declara aquilo que o plugin que distribui não comunica. Um guest cuja versão de proveniência da compilação em describe() transporte a marca -dirty, com que é marcada uma compilação feita a partir de uma árvore de trabalho com alterações não submetidas, é recusado: essa versão nomeia um commit que não contém aquilo que foi compilado. Uma versão de desenvolvimento compilada a partir de um commit (1.0.0-3-g1a2b3c4) e uma pré-versão (1.0.0-rc.1) são publicadas. O metadata.version registado é confrontado com a versão de proveniência da compilação em describe() do guest, e uma divergência interrompe a publicação, pelo que as duas têm de concordar. Ambas as recusas se resolvem da mesma forma: compilar o plugin a partir de um checkout limpo do commit que a tag da release nomeia, para que comunique ele próprio a versão da release — para uma nova release, fazer o commit da entidade com a fonte que publica e aplicar primeiro a tag a esse commit. Copiar para a entidade a versão que uma compilação de desenvolvimento comunica não é uma correção: isso publica essa compilação sob uma versão que nenhuma tag de release nomeia. As funções do anfitrião que o .wasm importa são derivadas do binário e comparadas com o registo submetido em spec.runtime.hostFunctions; uma divergência interrompe a publicação e nomeia aggrega plugin sync, que volta a registar o campo, porque o campo é gerido pela máquina e uma publicação nunca reescreve o ficheiro da entidade submetido. A entidade publicada transporta o registo gravado das funções do anfitrião; o digest de conteúdo do .wasm é uma propriedade do manifesto com que o par é publicado, e é registado para um consumidor no ficheiro de bloqueio da Release em vez de ser escrito na entidade.

Pull. aggrega pull resolve todas as dependências de uma Release e escreve um ficheiro de bloqueio por Release que fixa cada entidade do catálogo e cada artefacto remoto a uma versão e a um digest de conteúdo. Um Plugin publicado é resolvido através desta resolução de dependências; o seu .wasm é obtido com o manifesto que o transporta e os bytes são verificados face ao digest de conteúdo que o ficheiro de bloqueio regista. O pull volta também a derivar as funções do anfitrião a partir do .wasm verificado e confronta-as com o registo hostFunctions gravado, interrompendo-se se os dois divergirem — uma verificação de defesa em profundidade sobre a fixação por digest, que deteta um binário cujo registo gravado não foi produzido a partir das suas próprias importações. Se a política de confiança do registo exigir assinaturas, a assinatura da entidade é obtida e verificada nesta fase e registada como um facto verificado no ficheiro de bloqueio (secção 8). A verificação acontece no pull, nunca na compilação — a compilação mantém-se pura ahead-of-time.

Build. aggrega build consome o plugin fixado e verificado a partir das dependências resolvidas. O compilador encaminha a referência fixada por digest e o runtime Wasm executa os bytes; o controlo de carregamento volta a executar a verificação cruzada com describe() e a imposição das funções do anfitrião e dos limites de execução antes de o plugin ser executado.

8. Assinatura e confiança

Uma entidade Plugin é assinada exatamente como qualquer outra entidade do catálogo: o digest do manifesto é assinado e anexado como referrer OCI. O artefacto .wasm não é assinado separadamente, e não precisa de uma assinatura separada — é uma camada do próprio manifesto cujo digest é assinado, pelo que a assinatura o cobre diretamente: adulterar o .wasm altera o digest do manifesto e invalida a assinatura.

A assinatura é de adesão voluntária na publicação; a verificação é imposta pela política de confiança por registo no pull. Um registo configurado para exigir assinaturas interrompe o pull quando uma assinatura exigida está em falta, não é fidedigna ou é inválida. O bloco spec.signature na entidade é um ponteiro de documentação para onde se encontra a assinatura e como foi produzida; regista factos para os leitores do catálogo e não controla, por si só, a admissão. O ponto de controlo é a política no momento do pull.

Os comandos e os respetivos indicadores estão documentados com as superfícies de publicação e de consumo — ver ../cli/aggrega-sign.md, ../cli/aggrega-push.md e ../cli/aggrega-pull.md. Este guia não reproduz as tabelas de indicadores; essas páginas são o lugar único da superfície de comandos.

9. Versionar a entidade

Uma entidade Plugin tem uma Semantic Version estrita em metadata.version. Uma versão publicada é imutável: voltar a publicar uma versão que já existe no registo com um conteúdo diferente é rejeitado no controlo de publicação.

Quando se altera uma entidade de plugin e se volta a publicar, a disciplina de publicação classifica a alteração face à versão publicada anteriormente e exige que o incremento de versão corresponda. A classificação segue a rubrica de incremento de versão: uma alteração apenas de documentação ou de comentários é PATCH; uma alteração estritamente aditiva (um novo campo opcional, uma nova entrada) é MINOR; uma remoção, um estreitamento de tipo ou um campo antes opcional que se torna obrigatório é MAJOR. Um incremento excessivo é sempre permitido; um incremento insuficiente é interrompido com um diagnóstico que nomeia o incremento exigido. A primeira publicação de uma entidade ignora a verificação do incremento e apresenta um aviso de que não foi realizada qualquer verificação. A verificação executa-se antes da publicação com aggrega lint --pre-publish; ver ../cli/aggrega-lint.md para a rubrica completa e as definições por regra.

Um Plugin não tem superfície extends, pelo que as regras de herança que regem os Components e as Features do catálogo não o alcançam. A rubrica de incremento de versão e a imutabilidade são a disciplina de versionamento que rege uma entidade de plugin.

10. Referências cruzadas

  • authoring-a-provider-walkthrough.md — um guest de fornecedor construído de ponta a ponta, desde um diretório vazio até à saída renderizada.
  • plugin-contract.md — os pontos de socket que um plugin visa e as formas de entrada/saída por socket.
  • policy-socket.md — o socket de governação em profundidade: os seus quatro papéis, as severidades dos veredictos, o canal de entrada do operador, como escrever uma política para qualquer um dos dois motores incluídos no compilador e os guests de políticas de referência.
  • core-importers.md — os importadores próprios do compilador, um para cada formato que lê, construídos sobre o pacote importer do kit Go: o que cada um lê, as suas definições e a sua publicação com cada versão do compilador.
  • ../compatibility.md — como são versionados os kits de plugins e o que permite que um plugin compilado para uma versão continue a carregar-se na seguinte.
  • ../entities/plugin.md — a referência campo a campo da entidade Plugin.
  • ../entities/featurerecipe.md — a superfície de criação pipeline: da FeatureRecipe que referencia um plugin por URI de entidade.
  • ../cli/aggrega-lint.md — o publishing-linter, a rubrica de incremento de versão e a imposição da imutabilidade.
  • ../cli/aggrega-inspect.md — a inspeção das capacidades, dos limites de execução e da assinatura de uma entidade Plugin.
  • ../cli/aggrega-push.md, ../cli/aggrega-pull.md, ../cli/aggrega-sign.md — as superfícies de comandos de publicação, de consumo e de assinatura.