Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Guida per sviluppatori di plugin Wasm

Questa è la guida canonica per scrivere un plugin WebAssembly (Wasm) di Aggrega e pubblicarlo come entità del catalogo. Insegna il contratto dell’autore di plugin dall’inizio alla fine: che cos’è un plugin, come un plugin si descrive all’host, come scriverne gli export e le dichiarazioni di capacità, i limiti di runtime e le funzioni host che l’host applica, l’entità Plugin che porta un plugin nel catalogo, come una Recipe o una FeatureRecipe fa riferimento a un plugin, e il ciclo di vita publish→pull→build che porta un plugin da un file .wasm su disco a un artefatto verificato e fissato tramite digest che una build consuma.

La pagina complementare plugin-contract.md documenta i socket — i punti della pipeline a cui i plugin vengono associati e le forme di input/output che ciascun socket consuma e produce. Questa guida documenta il plugin — l’entità, la superficie delle capacità e il ciclo di vita. Leggi la pagina del contratto per sapere a quale socket è destinato il tuo plugin; leggi questa pagina per sapere come scriverlo e distribuirlo.

Per un percorso guidato attraverso l’intero compito anziché un riferimento su di esso, scrivere un provider costruisce dall’inizio alla fine un piccolo guest di provider — descrittore, build, entità, associazione e un rendering di cui puoi leggere l’output — incluso il rifiuto in cui di solito si imbatte una prima bozza e come leggerlo.

1. Che cos’è un plugin Wasm

Un plugin Wasm è un modulo WebAssembly che estende il compilatore in un socket designato. Il binario host in Go non contiene alcuna logica specifica del cloud o dell’infrastruttura; tutta l’intelligenza specifica del dominio — rendering dei template, traduzione dei formati, valutazione delle policy, linting — risiede nei plugin. L’host orchestra la pipeline e passa il payload di ciascun socket al guest attraverso il confine dell’ABI; il guest svolge il lavoro di dominio e restituisce la forma di risultato di quel socket. Il payload e il risultato di ogni socket viaggiano come CBOR canonico, con due eccezioni: un plugin CLI riceve il proprio vettore degli argomenti come testo JSON e risponde con un codice di uscita e il testo che trasmette in streaming, e l’autodescrizione describe è testo JSON. La sezione di ciascun socket nel contratto dei plugin indica la sua codifica, e un guest la legge e la scrive tramite i punti di ingresso che il tipo di payload del suo kit già porta, così nessun guest analizza i byte a mano.

Un plugin viene eseguito dietro un firewall di purezza ahead-of-time. L’host carica ed esegue il modulo tramite un runtime Wasm integrato in una configurazione con capacità negate: nessun socket di rete, nessun filesystem, nessun ambiente, stdio scartato e un orologio di sistema osservabile congelato su un istante invariante tra le build. Qualsiasi chiamata di I/O che un guest tenta fallisce al confine della chiamata, quindi un plugin non può accedere allo stato di runtime. Scrivi i plugin tenendo presente questo firewall: un plugin trasforma il payload che riceve e restituisce un risultato che l’host consuma alla lettera, e il determinismo è una tua responsabilità — un input identico deve produrre byte di output identici. L’unico canale sancito per il contenuto remoto è il recupero degli input esterni mediato dall’host (Sezione 4), che serve byte secondo una disciplina di fissaggio tramite digest anziché dare al guest un accesso diretto alla rete.

I socket a cui un plugin può essere destinato — tra cui il punto di controllo di mutazione alla costruzione della topologia, il punto di controllo di validazione all’analisi statica, la pipeline della FeatureRecipe, il linter fuori banda e il socket di rendering dei provider — e le loro forme di input/output per socket sono documentati in plugin-contract.md. Il socket servito da un plugin è l’unico valore che esso dichiara in metadata.pluginType, e l’intero insieme dei valori che quel campo accetta è la voce di riferimento per esso in entities/plugin.md §«metadata.pluginType». Gli esempi di questa guida usano provider (renderizza nodi IR in artefatti nativi del provider), linter (ispeziona il contenuto scritto dall’autore e solleva diagnostiche) e pipeline-step (un passo nella pipeline: di una FeatureRecipe o di una Recipe che applica patch all’insieme dei documenti renderizzati).

Scrivi il guest rispetto all’host tramite il kit di sviluppo per plugin (PDK) in tre linguaggi — Go, Rust o TypeScript. Il PDK incapsula la toolchain Wasm sottostante con builder tipizzati di Aggrega per le forme di input e di output che ciascun socket trasporta.

2. L’autodescrizione describe()

Ogni plugin esporta una funzione describe() che restituisce l’autodescrizione del plugin: il tipo o i tipi di socket che implementa, la versione dell’ABI a cui è destinato, le capacità che dichiara — lette in base al tipo di socket, quindi nomi di capacità per un provider o un passo di pipeline e formati di sorgente con prefisso per un parser o un importatore — le funzioni host che importa e la capacità per export di ciascun punto di ingresso che offre. describe() è il resoconto che il plugin dà di sé stesso: che cosa è e che cosa fa.

L’autodescrizione è l’ancora del modello di fiducia. L’entità Plugin che porta il plugin nel catalogo (Sezione 5) riformula gli stessi fatti come dichiarazioni scritte dall’autore, e l’host confronta le dichiarazioni dell’entità con l’output di describe() del plugin in due momenti — alla pubblicazione, prima che qualsiasi byte arrivi nel registry, e al caricamento, prima che il plugin venga eseguito. Una discrepanza causa un arresto esplicito. L’entità è la superficie leggibile da una persona e visibile nel catalogo; describe() è il riferimento lato macchina rispetto al quale l’host la verifica. Scrivi entrambe in modo che concordino; il controllo incrociato esiste proprio per cogliere il caso in cui divergono. Verifica ciò che l’entità dichiara e non ciò che tralascia: un’entità che dichiara meno di quanto il binario riporta — per esempio una rimasta indietro dopo una ricompilazione che ha aggiunto un export — si carica comunque, pur non descrivendo più tutto ciò che il binario fa.

3. Scrivere gli export e le loro dichiarazioni di capacità

Un plugin offre uno o più export — punti di ingresso con nome verso cui l’host smista le chiamate (per esempio render_node, lint_naming, step). Ogni export porta un blocco di capacità: la dichiarazione dell’autore su che cosa fa quell’export. La capacità di un export ha quattro campi:

  • name — il nome ABI dell’export, il nome verso cui l’host smista le chiamate. Obbligatorio.
  • operates — l’operazione di pipeline che l’export esegue: patch (modifica un documento renderizzato esistente) o emit (aggiunge un nuovo documento). È una dichiarazione di capacità esplicita. L’host la confronta con l’autodescrizione describe() del plugin alla pubblicazione e al caricamento, quindi la dichiarazione scritta nell’entità e il resoconto proprio del plugin devono concordare. È una dichiarazione convalidata sull’export, non un interruttore di smistamento: al momento del rendering l’operazione che un passo esegue davvero è portata dal risultato restituito dal guest, non selezionata da questo campo. Se assente, non porta alcuna dichiarazione di operazione.
  • scope — la radice dei documenti su cui l’export opera: own (i documenti renderizzati propri del nodo) o host (i documenti del componente a cui è associata una FeatureRecipe con ambito di componente). Prima che venga eseguito il plugin di un passo di pipeline, l’host legge l’ambito di export dichiarato dal passo e impone che il provider che renderizza i documenti di quell’ambito compaia nelle spec.pipelineStep.capabilities del plugin (Sezione 5) — un export con ambito own viene verificato rispetto al provider che renderizza i documenti propri del nodo, un export con ambito host rispetto al provider del componente ospitante, e un ambito vuoto vale own per questa verifica. Questo è il punto di controllo della compatibilità dei provider, eseguito prima del passo; il documento che un’operazione del guest tocca davvero è indicato per ciascuna operazione nel risultato restituito dal guest, non selezionato da questo campo dichiarato. Se assente, vale own.
  • selector — una descrizione libera e leggibile da una persona di ciò su cui l’export agisce (per esempio workloads carrying a pod template). Documentazione per chi legge il catalogo e per la superficie aggrega inspect; il compilatore non la interpreta.

Scrivi gli export nell’ordine in cui vuoi che vengano letti; le voci mantengono l’ordine dell’autore nell’entità e in inspect. Un plugin senza export scritti non dichiara alcuna superficie di export — valido per un plugin il cui socket non ha bisogno di una dichiarazione di capacità per export.

4. Limiti di runtime e funzioni host

Un’entità di plugin può portare un blocco runtime facoltativo che vincola il modo in cui l’host carica ed esegue il plugin.

Limiti di memoria e di tempo. maxMemoryPages limita la memoria lineare del plugin in pagine Wasm (64 KiB per pagina); timeoutMs limita per quanto tempo il codice proprio del plugin può essere eseguito durante una chiamata, in millisecondi. Il tempo trascorso all’interno delle funzioni host che il plugin chiama non viene conteggiato. Su Linux la misura è il tempo di processore del thread che esegue il guest, quindi nemmeno il tempo che il guest passa in attesa di un processore su una macchina carica viene conteggiato; su altri sistemi è il tempo trascorso. La prima chiamata a un plugin appena caricato conteggia anche l’inizializzazione una tantum del runtime del linguaggio guest, che avviene all’interno di quella chiamata. Entrambi i limiti sono facoltativi con valori predefiniti: zero o assente applica il limite predefinito della piattaforma. Il loader limita ogni plugin al valore predefinito della piattaforma quando l’entità non ne dichiara alcuno, quindi un caricamento non è mai illimitato e una chiamata non è mai impossibile da annullare. Aumenta un limite nell’entità quando un’associazione ha davvero bisogno di più memoria o di più tempo di quanto il valore predefinito consenta.

Funzioni host. hostFunctions registra i nomi delle funzioni host che il plugin importa. È un campo derivato automaticamente — non scriverlo. aggrega plugin sync legge le funzioni host direttamente dalla sezione di import del .wasm e registra il campo nel file dell’entità al posto tuo, e la pubblicazione le ricava di nuovo dal binario e rifiuta un’entità il cui record differisce; così un plugin ottiene esattamente le funzioni host che il suo binario importa davvero, convalidate rispetto a una lista consentita selezionata (un import fuori dalla lista consentita viene rifiutato in modo esplicito). Il record è un’istantanea del binario pubblicato, allo stesso modo in cui il riferimento plugin: indirizzato per contenuto è un’istantanea dei byte pubblicati: riflette il binario al momento della pubblicazione e viene ricavato di nuovo e verificato quando il plugin viene recuperato con pull. Per vedere le funzioni host che un .wasm locale importa prima di pubblicarlo — il valore che aggrega plugin sync registra — esegui aggrega inspect --plugin <file.wasm>.

La superficie host selezionata. Tre delle funzioni host sono di uso generale: aggrega_log (un livello e un messaggio, emessi come una riga di log sulla destinazione dei log dell’host), aggrega_emit_warning (un codice, un messaggio e un percorso, accumulati come un avviso strutturato che l’host mostra dopo la chiamata) e aggrega_fetch_external_input (un URL, a cui si risponde con i byte dell’input secondo la disciplina di fissaggio descritta più sotto). Il PDK incapsula tutte e tre in ciascun linguaggio — Go: aggrega.Log, aggrega.EmitWarning, aggrega.FetchExternalInput; Rust: log, emit_warning, fetch_external_input; TypeScript: log, emitWarning, fetchExternalInput — così un guest chiama una funzione tipizzata anziché l’ABI grezza. Le callback della sorgente e di parsing — per un guest che legge porzioni di una sorgente acquisita od ottiene un albero analizzato tramite l’host — e la codifica che portano gli slot di ciascuna callback sono elencate in plugin-contract.md.

Il contenuto della sorgente locale arriva attraverso l’host — mai dal filesystem. Un plugin di rendering di provider non legge mai la propria sorgente dal disco; una chiamata al filesystem fallisce al confine della chiamata. L’host consegna al guest un elenco della sorgente all’interno del payload di rendering — il percorso di ogni voce relativo alla radice della sorgente e se si tratta di una directory, in ordine, senza alcun contenuto dei file — e il guest vi applica la propria logica di layout, poi rilegge esattamente i file che seleziona tramite le callback della sorgente, che restituiscono i byte che l’host legge sotto la radice della sorgente. Le forme dei payload per socket e le callback sono documentate in plugin-contract.md.

Il contenuto remoto arriva attraverso il recupero degli input esterni. Un plugin che ha bisogno di contenuto remoto — un archivio di chart, un documento di schema remoto — chiama il wrapper di recupero del PDK. A livello di trasmissione, il guest passa l’URL a aggrega_fetch_external_input come testo UTF-8 e riceve un’unica risposta in CBOR canonico, che porta o i byte recuperati, grezzi, o un messaggio di errore accanto al suo codice confrontabile automaticamente; il wrapper decodifica la risposta in byte o errore. I byte arrivano esattamente come sono stati recuperati, compreso un payload che non è UTF-8 valido, e un payload di lunghezza zero torna come byte vuoti anziché come errore. L’host serve l’URL secondo la disciplina di fissaggio degli input esterni:

  • Un URL già fissato nel lockfile della Release viene servito dall’archivio locale indirizzato per contenuto e verificato rispetto al digest registrato a ogni lettura. Un blob mancante nell’archivio viene ripristinato dalla rete tramite il digest registrato — un ripristino verificato tramite digest non può modificare l’output.
  • Un URL non fissato viene rifiutato, con un errore che nomina l’URL e il rimedio. Una build renderizza la chiusura registrata dal suo lockfile, quindi nessuna build recupera un riferimento non fissato e non esiste alcuna impostazione che lo consenta.
  • Il fissaggio avviene quando vengono risolte le dipendenze della Release: aggrega pull renderizza la Release per scoprire quali input esterni richiede il suo rendering, recupera ciascuno di essi e lo registra nel lockfile accanto ai fissaggi delle dipendenze. Quindi il ciclo di lavoro dell’autore di un plugin è: risolvere una volta, poi eseguire la build offline tutte le volte che vuoi.

Gli schemi consentiti sono https, http solo verso host di loopback, e oci (fissato tramite il digest del manifest). Il lockfile registra ogni input fissato — il suo URL, il digest sha256, la dimensione e i plugin che lo hanno richiesto — così una nuova build serve gli stessi byte dall’archivio locale: riproducibile, e offline una volta fissato.

Con il 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)
}

Che cosa fallisce, e perché.

  • Una chiamata al filesystem o alla rete fallisce al confine della chiamata: il guest non dispone di directory preaperte né di socket. Questo vale per ogni percorso di codice, inclusa una dipendenza di libreria che tenta di leggere un file — leggi invece la sorgente tramite le callback della sorgente.
  • Un import sotto un modulo diverso da wasi_snapshot_preview1, extism:host/env e extism:host/user fallisce al caricamento, con una diagnostica che nomina il modulo e l’import. I singoli nomi di funzione WASI all’interno di un modulo consentito non vengono mai censurati — gli import di filesystem e di socket inutilizzati del runtime di un linguaggio collegato staticamente non sono un problema, perché nominare un import non concede nulla.
  • Il recupero di un URL che il lockfile non fissa fallisce con un errore che nomina l’URL; il rimedio è eseguire aggrega pull --release <release>, che fissa ogni input esterno consumato dal rendering della Release, e poi eseguire la build.

Non esiste alcun campo di lista consentita degli host per l’accesso di rete in uscita. Un plugin non raggiunge mai la rete in fase di build — è il confine ahead-of-time — quindi non esiste alcun campo di questo tipo da scrivere. Il contenuto remoto arriva attraverso il canale degli input esterni mediato dall’host e fissato tramite digest descritto sopra, mai attraverso un accesso di rete ambientale.

Configurazione. configKV è una mappa da stringa a stringa che il runtime consegna al plugin all’avvio. Le voci mantengono l’ordine dell’autore, così il record emesso è identico byte per byte tra un’esecuzione e l’altra. Se assente, resta in vigore la configurazione vuota predefinita del runtime.

5. L’entità Plugin

Un plugin entra nel catalogo come entità Plugin — la superficie di authoring e di metadati del plugin. L’entità dichiara che cosa è il plugin e punta all’artefatto .wasm; il compilatore non interpreta il comportamento del plugin e instrada il riferimento fissato, mentre il runtime Wasm esegue i byte.

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

I campi:

  • Nessun campo per la posizione dell’artefatto, deliberatamente. L’entità non porta alcun puntatore al .wasm e lo schema non ne accetta alcuno. La posizione dell’artefatto di un plugin è derivata dalla sua identità — la coordinata metadata.pluginType/metadata.name, che forma il percorso del repository plugin/<pluginType>/<name> — più il registry rispetto a cui è configurato il workspace, quindi non c’è alcuna posizione da scrivere né da sbagliare. Il digest del contenuto risolto viene registrato per ogni Release nel lockfile di quella Release, e la build verifica i byte recuperati rispetto a esso: l’identità nell’entità, i byte verificati nel lockfile.
  • metadata.version — la release che l’entità pubblica, che deve essere uguale alla versione di provenienza della build del guest stesso, come riportata in describe(). L’autore di un plugin assegna la versione al .wasm in fase di build — la build imprime la versione nel guest, e una build che la prende da un tag di release imprime la versione della release solo sul commit indicato da quel tag — e il metadata.version dell’entità nomina quella stessa release. Il controllo di pubblicazione confronta le due e si arresta in caso di divergenza, così l’entità nomina sempre la versione esatta del binario che distribuisce. aggrega plugin gen-catalog --plugin (più sotto) copia la versione riportata dal guest nell’entità che genera, ed è la versione della release quando il guest è stato compilato dal commit con il tag. Obbligatorio.
  • metadata.pluginType — il tipo di socket che questo plugin implementa, scelto tra provider, linter, pipeline-step, governance, cli, parser e importer. Un plugin ne implementa esattamente uno. Si trova nel blocco di indirizzamento accanto a name e version e fornisce il segmento <pluginType> della coordinata derivata. Obbligatorio.
  • spec.abiVersion — la versione dell’ABI host/guest a cui il plugin è destinato. v1beta1 è il valore accettato; una futura revisione dell’ABI aggiunge un valore accettato. Obbligatorio.
  • Il blocco del tuo tipo di socket, che porta capabilities — un plugin dichiara che cosa serve all’interno del blocco che appartiene al suo metadata.pluginType, ed è il blocco a stabilire che cosa significa una voce. spec.provider.capabilities nomina le capacità servite da un provider (nomi di capacità come helm o compose). spec.pipelineStep.capabilities nomina i provider con il cui output renderizzato il tuo passo è compatibile. spec.parser.capabilities nomina i formati di sorgente che un parser legge, ciascuno scritto parse:<format>. spec.importer.capabilities nomina i formati esterni a partire dai quali un importatore redige bozze di entità, ciascuno scritto import:<format>. Un importatore scritto in Go può prendere tutto ciò che non dipende dal suo formato — la valutazione, la decisione di fare riferimento o di redigere una bozza, le bozze e il loro rendering, e le sue impostazioni — dal pacchetto importer del kit Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Un plugin linter, governance o cli non serve alcuna capacità e non porta nessuno dei quattro blocchi. Le voci mantengono l’ordine dell’autore, e ogni elenco è una dichiarazione esplicita e testata: dichiara ciò rispetto a cui hai effettivamente compilato e testato il plugin, perché un consumatore risolve esattamente rispetto a ciò che è elencato. Per un passo di pipeline quella dichiarazione è imposta al momento del rendering — quando un passo tocca un ambito, la build si arresta a meno che il provider che renderizza i documenti di quell’ambito non sia tra quelli dichiarati dal tuo plugin — quindi un elenco vuoto non corrisponde ad alcun provider e non ammette il passo da nessuna parte.
  • spec.signature — un puntatore descrittivo facoltativo alla firma allegata del plugin (Sezione 8). Questo blocco è solo documentazione: registra dove si trova la firma e come è stata prodotta, per chi legge il catalogo; non ammette di per sé il plugin. Il controllo che si applica davvero è la policy di fiducia per registry applicata al pull.
  • spec.runtime — il blocco facoltativo dei vincoli di esecuzione della Sezione 4. L’autore scrive maxMemoryPages, timeoutMs e configKV; hostFunctions è derivato automaticamente e registrato da aggrega plugin sync, che la pubblicazione verifica, e non viene scritto dall’autore.
  • spec.exports — le dichiarazioni di capacità per export della Sezione 3 (name, operates, scope, selector).

Generare l’entità dal tuo .wasm. Non devi scrivere a mano le parti dell’entità gestite dalla macchina. aggrega plugin gen-catalog --plugin <file.wasm> legge l’autodescrizione describe() del guest e ne produce un’entità Plugin pronta per la pubblicazione, insieme a un piccolo overlay scritto da te (l’identità, i limiti di runtime e un eventuale blocco del provider). Il generatore imprime i campi di cui il binario è la fonte di verità — le dichiarazioni degli export, il contratto delle capacità, lo specchio dei comandi e il record delle funzioni host — e copia metadata.version dalla versione di provenienza della build in describe() del guest, mentre l’overlay fornisce solo ciò che il binario non riporta. Questo è il percorso supportato per l’autore di un plugin di terze parti: compila e versiona il tuo .wasm, poi rigenera l’entità in modo che i suoi campi gestiti dalla macchina restino allineati al binario. La versione è l’unico campo copiato che nomina una release anziché un fatto sui byte, quindi genera a partire da una build del commit indicato dal tag della release — oppure, partendo da una build di sviluppo, imposta metadata.version alla release nell’entità generata prima di applicare il tag al commit che la contiene. Un guest che non porta alcuna versione di provenienza della build non può essere trasformato in un’entità con versione — assegna prima la versione al guest in fase di build.

Il .wasm accanto alla sua entità. Mentre scrivi un plugin, non c’è nulla di pubblicato che una compilazione possa recuperare, quindi una compilazione legge il .wasm del plugin da accanto alla sua entità Plugin in una directory del catalogo, con un nome derivato dal tipo di plugin e dal nome dell’entità: per pipeline-step/patch è pipeline-step--patch.wasm. Lettere minuscole, cifre e la maggior parte dei trattini vengono scritti in quel nome così come sono; ogni altro carattere viene scritto in forma codificata, e così anche un trattino in alcune posizioni — quindi, dove conta, il rifiuto di un .wasm mancante, A plugin’s .wasm is not on this machine (Il modulo di un plugin non è su questa macchina), riporta il nome per intero. aggrega lint <plugin.yaml> legge il .wasm dallo stesso posto — accanto al file dell’entità che riceve, in qualunque directory si trovi quel file — a meno che il binario non contenga il plugin stesso, e stampa un avviso per ogni export, capacità o contratto che il .wasm riporta e che l’entità omette. Dove lì non c’è alcun .wasm, il lint dice di aver saltato quella segnalazione, indicando il file che ha cercato e la directory, e il suo risultato non cambia.

Per il riferimento campo per campo, vedi la pagina dell’entità ../entities/plugin.md.

6. Fare riferimento a un plugin

Un passo di pipeline o un socket di plugin fa riferimento a un plugin tramite il suo URI dell’entità Plugin — l’identità dell’entità, non direttamente l’artefatto .wasm. L’entità è il livello che porta il fissaggio tramite digest, le dichiarazioni di capacità, i limiti di runtime e la firma; fare riferimento all’entità è il modo in cui un consumatore riceve tutto questo.

Un percorso .wasm nudo o un riferimento grezzo a un artefatto lasciato in un campo plugin viene rifiutato al caricamento: nessuna entità Plugin vi corrisponde, quindi la risoluzione del plugin fallisce in modo esplicito. L’URI dell’entità è obbligatorio — l’indirezione attraverso l’entità è il contratto, non una comodità facoltativa. Un passo di pipeline di una FeatureRecipe nomina l’entità in pipeline[].plugin; vedi ../entities/featurerecipe.md per la superficie di authoring della pipeline.

Quando due o più plugin sono accoppiati — devono concordare su un contratto di passaggio condiviso, come in una coppia Fetcher e Injector in cui l’output di un plugin è l’input dell’altro (il principio del Plugin in due parti descritto in plugin-contract.md) — scrivi quel contratto una sola volta e fai dipendere ciascun plugin dall’unica definizione, anziché riformulare la forma JSON del passaggio in modo indipendente in ciascun plugin. La forma condivisa è la struttura JSON che i plugin si scambiano, che può risiedere in un’unica voce di SchemaLibrary a cui entrambi i plugin fanno riferimento. Un’unica fonte per il contratto mantiene sincronizzati i plugin accoppiati man mano che evolve; le riformulazioni indipendenti divergono, e la divergenza emerge solo quando le due non concordano più a runtime. La raccomandazione è di condividere il contratto, non il codice Wasm — ogni plugin resta un artefatto a sé.

7. Il ciclo di vita publish → pull → build

Un plugin passa da un file .wasm su disco a un artefatto verificato e consumabile da una build attraverso tre fasi.

Publish. aggrega push pubblica un’entità Plugin e il suo .wasm insieme come un unico manifest OCI, con tag pari a metadata.version: lo YAML dell’entità è il blob di configurazione del manifest e il .wasm viaggia come layer dello stesso manifest. Pubblicare la coppia come un unico manifest con tag è ciò che rende il push atomico — non esiste alcuna finestra in cui una metà è pubblicata e l’altra no — ed è il motivo per cui un’unica firma su quel manifest copre entrambe le metà. Entrambe le metà sono nominate nel manifest, quindi un client OCI generico che recupera il tag di versione scrive l’entità in entity.yaml e l’eseguibile in entity.wasm.

Prima che arrivi qualsiasi byte, la pubblicazione esegue i suoi controlli. L’entità viene letta prima rispetto allo schema Plugin, nel modo in cui la legge un caricamento del catalogo, quindi un metadata.version che non è una versione semantica — o qualsiasi altro scostamento dallo schema — viene rifiutato prima che il .wasm venga letto. Il .wasm viene poi caricato e la sua autodescrizione describe() viene confrontata con le dichiarazioni di capacità scritte nell’entità — una discrepanza causa un arresto esplicito, così un’entità pubblicata non dichiara mai ciò che il plugin che distribuisce non riporta. Un guest la cui versione di provenienza della build in describe() porta il marcatore -dirty, con cui viene contrassegnata una build da un working tree con modifiche non committate, viene rifiutato: quella versione nomina un commit che non contiene ciò che è stato compilato. Una versione di sviluppo compilata da un commit (1.0.0-3-g1a2b3c4) e una prerelease (1.0.0-rc.1) vengono pubblicate. Il metadata.version registrato viene confrontato con la versione di provenienza della build in describe() del guest, e una divergenza arresta la pubblicazione, quindi le due devono concordare. Entrambi i rifiuti si risolvono allo stesso modo: compila il plugin da un checkout pulito del commit indicato dal tag della release, così che riporti esso stesso la versione della release — per una nuova release, committa l’entità insieme alla sorgente che rilascia e applica prima il tag a quel commit. Copiare nell’entità la versione riportata da una build di sviluppo non è una correzione: pubblica quella build con una versione che nessun tag di release nomina. Le funzioni host che il .wasm importa vengono ricavate dal binario e confrontate con il record committato in spec.runtime.hostFunctions; una divergenza arresta la pubblicazione e nomina aggrega plugin sync, che registra di nuovo il campo, perché il campo è gestito dalla macchina e una pubblicazione non riscrive mai il file dell’entità committato. L’entità pubblicata porta il record impresso delle funzioni host; il digest del contenuto del .wasm è una proprietà del manifest con cui la coppia viene pubblicata, e per un consumatore viene registrato nel lockfile della Release anziché scritto nell’entità.

Pull. aggrega pull risolve tutte le dipendenze di una Release e scrive un lockfile per Release che fissa ogni entità del catalogo e ogni artefatto remoto a una versione e a un digest del contenuto. Un Plugin pubblicato si risolve attraverso questa risoluzione delle dipendenze; il suo .wasm viene recuperato con il manifest che lo contiene e i byte vengono verificati rispetto al digest del contenuto registrato nel lockfile. Il pull inoltre ricava di nuovo le funzioni host dal .wasm verificato e le confronta con il record hostFunctions impresso, arrestandosi se i due non concordano — un controllo di difesa in profondità sopra il fissaggio tramite digest, che coglie un binario il cui record impresso non è stato prodotto dai suoi stessi import. Se la policy di fiducia del registry richiede le firme, la firma dell’entità viene recuperata e verificata in questa fase e registrata come fatto verificato nel lockfile (Sezione 8). La verifica avviene al pull, mai alla build — la build resta pura ahead-of-time.

Build. aggrega build consuma il plugin fissato e verificato dalle dipendenze risolte. Il compilatore instrada il riferimento fissato tramite digest e il runtime Wasm esegue i byte; il controllo al caricamento riesegue il confronto con describe() e l’applicazione delle funzioni host e dei limiti di runtime prima che il plugin venga eseguito.

8. Firma e fiducia

Un’entità Plugin viene firmata esattamente come ogni altra entità del catalogo: il digest del manifest viene firmato e allegato come referrer OCI. L’artefatto .wasm non viene firmato separatamente, e non ha bisogno di una firma separata — è un layer dello stesso manifest il cui digest viene firmato, quindi la firma lo copre direttamente: manomettere il .wasm cambia il digest del manifest e invalida la firma.

La firma è su adesione volontaria alla pubblicazione; la verifica è imposta dalla policy di fiducia per registry al pull. Un registry configurato per richiedere le firme arresta il pull quando una firma richiesta manca, non è attendibile o non è valida. Il blocco spec.signature dell’entità è un puntatore di documentazione che indica dove si trova la firma e come è stata prodotta; registra fatti per chi legge il catalogo e non regola di per sé l’ammissione. Il punto di controllo è la policy applicata al momento del pull.

I comandi e i loro flag sono documentati con le superfici di pubblicazione e di consumo — vedi ../cli/aggrega-sign.md, ../cli/aggrega-push.md e ../cli/aggrega-pull.md. Questa guida non riformula le tabelle dei flag; quelle pagine sono l’unica sede della superficie dei comandi.

9. Versionare l’entità

Un’entità Plugin porta una Semantic Version rigorosa in metadata.version. Una versione pubblicata è immutabile: ripubblicare una versione già esistente nel registry con un contenuto diverso viene rifiutato al controllo di pubblicazione.

Quando modifichi un’entità di plugin e la ripubblichi, la disciplina di pubblicazione classifica la modifica rispetto alla versione pubblicata in precedenza e richiede che l’incremento di versione corrisponda. La classificazione segue la griglia degli incrementi di versione: una modifica solo di documentazione o di commenti è PATCH; una modifica strettamente additiva (un nuovo campo facoltativo, una nuova voce) è MINOR; una rimozione, un restringimento di tipo o un campo prima facoltativo che diventa obbligatorio è MAJOR. Un incremento eccessivo è sempre consentito; un incremento insufficiente si arresta con una diagnostica che nomina l’incremento richiesto. La prima pubblicazione di un’entità salta il controllo dell’incremento e mostra un avviso che nessuna verifica è stata eseguita. Esegui il controllo prima della pubblicazione con aggrega lint --pre-publish; vedi ../cli/aggrega-lint.md per la griglia completa e le impostazioni per regola.

Un Plugin non ha alcuna superficie extends, quindi le regole di ereditarietà che governano i Components e le Features del catalogo non lo raggiungono. La griglia degli incrementi di versione e l’immutabilità sono la disciplina di versionamento che governa un’entità di plugin.

10. Riferimenti incrociati

  • authoring-a-provider-walkthrough.md — un guest di provider costruito dall’inizio alla fine, da una directory vuota fino all’output renderizzato.
  • plugin-contract.md — i punti di socket a cui un plugin è destinato e le forme di input/output per socket.
  • policy-socket.md — il socket di governance in dettaglio: i suoi quattro ruoli, le severità dei verdetti, il canale di input dell’operatore, la scrittura di una policy per uno dei due motori inclusi nel compilatore e i guest di policy di riferimento.
  • core-importers.md — gli importatori propri del compilatore, uno per ogni formato che legge, costruiti sul pacchetto importer del kit Go: che cosa legge ciascuno, le loro impostazioni e la loro pubblicazione a ogni release del compilatore.
  • ../compatibility.md — come vengono versionati i kit per plugin e che cosa permette a un plugin compilato per un rilascio di continuare a caricarsi in quello successivo.
  • ../entities/plugin.md — il riferimento campo per campo dell’entità Plugin.
  • ../entities/featurerecipe.md — la superficie di authoring pipeline: della FeatureRecipe che fa riferimento a un plugin tramite URI dell’entità.
  • ../cli/aggrega-lint.md — il publishing-linter, la griglia degli incrementi di versione e l’applicazione dell’immutabilità.
  • ../cli/aggrega-inspect.md — l’ispezione delle capacità, dei limiti di runtime e della firma di un’entità Plugin.
  • ../cli/aggrega-push.md, ../cli/aggrega-pull.md, ../cli/aggrega-sign.md — le superfici dei comandi di pubblicazione, di consumo e di firma.