Guide du développeur de plugins Wasm
Ceci est le guide canonique pour créer un plugin WebAssembly (Wasm) Aggrega et le publier comme entité du catalogue. Il enseigne le contrat de l’auteur de plugin de bout en bout : ce qu’est un plugin, comment un plugin se décrit à l’hôte, comment créer ses exports et ses déclarations de capacités, les limites d’exécution et les fonctions hôtes que l’hôte applique, l’entité Plugin qui fait entrer un plugin dans le catalogue, comment une Recipe ou une FeatureRecipe référence un plugin, et le cycle de vie publish→pull→build qui fait passer un plugin d’un fichier .wasm sur disque à un artefact vérifié, épinglé par digest, qu’un build consomme.
La page compagnon plugin-contract.md documente les sockets — les points du pipeline où les plugins se rattachent et les formes d’entrée/sortie que chaque socket consomme et produit. Ce guide documente le plugin — l’entité, la surface des capacités et le cycle de vie. Lisez la page du contrat pour savoir quel socket votre plugin cible ; lisez cette page pour savoir comment le créer et le livrer.
Pour un parcours guidé à travers toute la tâche plutôt qu’une référence sur celle-ci, créer un fournisseur construit de bout en bout un petit guest de fournisseur — descripteur, build, entité, rattachement et un rendu dont vous pouvez lire la sortie — y compris le refus qu’une première ébauche rencontre habituellement et la façon de le lire.
1. Ce qu’est un plugin Wasm
Un plugin Wasm est un module WebAssembly qui étend le compilateur à un socket désigné. Le binaire hôte Go ne contient aucune logique propre au cloud ou à l’infrastructure ; toute l’intelligence propre au domaine — rendu des templates, traduction de formats, évaluation des politiques, linting — réside dans les plugins. L’hôte orchestre le pipeline et transmet la charge utile de chaque socket au guest à travers la frontière de l’ABI ; le guest effectue le travail de domaine et renvoie la forme de résultat de ce socket. La charge utile et le résultat de chaque socket voyagent en CBOR canonique, à deux exceptions près : un plugin CLI reçoit son vecteur d’arguments sous forme de texte JSON et répond par un code de sortie et le texte qu’il diffuse, et l’auto-description describe est du texte JSON. La section de chaque socket dans le contrat des plugins indique son encodage, et un guest le lit et l’écrit au moyen des points d’entrée que le type de charge utile de son kit porte déjà, si bien qu’aucun guest n’analyse des octets à la main.
Un plugin s’exécute derrière un pare-feu de pureté ahead-of-time. L’hôte charge et exécute le module au moyen d’un runtime Wasm embarqué, dans une configuration où les capacités sont refusées : pas de sockets réseau, pas de système de fichiers, pas d’environnement, stdio ignoré et une horloge murale observable figée sur un instant invariant d’un build à l’autre. Tout appel d’E/S qu’un guest tente échoue à la frontière de l’appel, si bien qu’un plugin ne peut pas atteindre l’état d’exécution. Créez vos plugins en gardant ce pare-feu à l’esprit : un plugin transforme la charge utile qu’on lui remet et renvoie un résultat que l’hôte consomme tel quel, et le déterminisme relève de votre responsabilité — une entrée identique doit produire des octets de sortie identiques. Le seul canal sanctionné pour le contenu distant est la récupération des entrées externes par l’intermédiaire de l’hôte (section 4), qui sert des octets selon une discipline d’épinglage par digest au lieu de donner au guest un accès réseau direct.
Les sockets qu’un plugin peut cibler — parmi lesquels le point de contrôle de mutation à la construction de la topologie, le point de contrôle de validation à l’analyse statique, le pipeline de FeatureRecipe, le linter hors bande et le socket de rendu des fournisseurs — et leurs formes d’entrée/sortie par socket sont documentés dans plugin-contract.md. Le socket que sert un plugin est la seule valeur qu’il déclare dans metadata.pluginType, et l’ensemble complet des valeurs que ce champ accepte est son entrée de référence dans entities/plugin.md §« metadata.pluginType ». Les exemples de ce guide utilisent provider (rend des nœuds IR en artefacts natifs du fournisseur), linter (inspecte le contenu créé par l’auteur et lève des diagnostics) et pipeline-step (une étape du pipeline: d’une FeatureRecipe ou d’une Recipe qui applique des correctifs à l’ensemble des documents rendus).
Vous créez le guest face à l’hôte au moyen du kit de développement de plugins (PDK) en trois langages — Go, Rust ou TypeScript. Le PDK encapsule la chaîne d’outils Wasm sous-jacente avec des builders typés Aggrega pour les formes d’entrée et de sortie que porte chaque socket.
2. L’auto-description describe()
Chaque plugin exporte une fonction describe() qui renvoie l’auto-description du plugin : le ou les types de socket qu’il implémente, la version de l’ABI qu’il cible, les capacités qu’il déclare — lues selon le type de socket, donc des noms de capacités pour un fournisseur ou une étape de pipeline et des formats de source préfixés pour un parseur ou un importateur —, les fonctions hôtes qu’il importe et la capacité par export de chaque point d’entrée qu’il offre. describe() est le compte rendu que le plugin fait lui-même de ce qu’il est et de ce qu’il fait.
L’auto-description est l’ancre du modèle de confiance. L’entité Plugin qui fait entrer le plugin dans le catalogue (section 5) reprend les mêmes faits sous forme de déclarations rédigées par l’auteur, et l’hôte recoupe les déclarations de l’entité avec la sortie describe() du plugin à deux moments — à la publication, avant que le moindre octet n’arrive dans le registre, et au chargement, avant que le plugin ne s’exécute. Une divergence provoque un arrêt manifeste. L’entité est la surface lisible par un humain et visible dans le catalogue ; describe() est la référence machine par rapport à laquelle l’hôte la vérifie. Rédigez les deux pour qu’elles concordent ; le recoupement existe précisément pour détecter le cas où elles divergent. Il vérifie ce que l’entité déclare et non ce qu’elle omet : une entité qui déclare moins que ce que le binaire rapporte — par exemple une entité restée en arrière après une recompilation qui a ajouté un export — se charge tout de même, tout en ne décrivant plus tout ce que fait le binaire.
3. Créer les exports et leurs déclarations de capacités
Un plugin offre un ou plusieurs exports — des points d’entrée nommés vers lesquels l’hôte distribue les appels (par exemple render_node, lint_naming, step). Chaque export porte un bloc de capacité : la déclaration de l’auteur sur ce que fait cet export. La capacité d’un export comporte quatre champs :
name— le nom ABI de l’export, le nom vers lequel l’hôte distribue les appels. Obligatoire.operates— l’opération de pipeline que l’export effectue :patch(modifier un document rendu existant) ouemit(ajouter un nouveau document). C’est une déclaration de capacité explicite. L’hôte la recoupe avec l’auto-descriptiondescribe()du plugin à la publication et au chargement, si bien que la déclaration rédigée dans l’entité et le compte rendu propre du plugin doivent concorder. C’est une déclaration validée sur l’export, et non un commutateur de distribution : au moment du rendu, l’opération qu’une étape effectue réellement est portée par le résultat renvoyé par le guest, et non sélectionnée à partir de ce champ. En son absence, aucune déclaration d’opération n’est portée.scope— la racine de documents sur laquelle l’export opère :own(les documents rendus propres au nœud) ouhost(les documents du composant auquel une FeatureRecipe de portée composant est rattachée). Avant que le plugin d’une étape de pipeline ne s’exécute, l’hôte lit la portée d’export déclarée de l’étape et impose que le fournisseur qui rend les documents de cette portée figure dans lesspec.pipelineStep.capabilitiesdu plugin (section 5) — un export de portéeownest vérifié par rapport au fournisseur qui rend les documents propres au nœud, un export de portéehostpar rapport au fournisseur du composant hôte, et une portée vide vautownpour cette vérification. C’est le point de contrôle de compatibilité des fournisseurs, exécuté avant l’étape ; le document qu’une opération du guest touche réellement est nommé par opération dans le résultat renvoyé par le guest, et non sélectionné à partir de ce champ déclaré. En son absence, la valeur par défaut estown.selector— une description libre et lisible par un humain de ce sur quoi agit l’export (par exempleworkloads carrying a pod template). Documentation destinée aux lecteurs du catalogue et à la surfaceaggrega inspect; le compilateur ne l’interprète pas.
Créez les exports dans l’ordre dans lequel vous voulez qu’ils soient lus ; les entrées conservent l’ordre de l’auteur dans l’entité et dans inspect. Un plugin sans export créé ne déclare aucune surface d’export — ce qui est valide pour un plugin dont le socket n’a pas besoin d’une déclaration de capacité par export.
4. Limites d’exécution et fonctions hôtes
Une entité de plugin peut porter un bloc runtime facultatif qui contraint la façon dont l’hôte charge et exécute le plugin.
Limites de mémoire et de temps. maxMemoryPages plafonne la mémoire linéaire du plugin en pages Wasm (64 KiB par page) ; timeoutMs plafonne la durée pendant laquelle le code propre du plugin peut s’exécuter au cours d’un appel, en millisecondes. Le temps passé dans les fonctions hôtes que le plugin appelle n’est pas décompté. Sous Linux, la mesure est le temps processeur du thread qui exécute le guest, si bien que le temps que le guest passe à attendre un processeur sur une machine chargée n’est pas décompté non plus ; sur les autres systèmes, c’est le temps écoulé. Le premier appel à un plugin fraîchement chargé décompte aussi l’initialisation unique du runtime du langage guest, qui s’exécute au sein de cet appel. Les deux limites sont facultatives avec des valeurs par défaut : zéro ou l’absence de valeur applique le plafond par défaut de la plateforme. Le chargeur plafonne chaque plugin à la valeur par défaut de la plateforme lorsque l’entité n’en déclare aucune, si bien qu’un chargement n’est jamais illimité et qu’un appel n’est jamais impossible à annuler. Augmentez une limite sur l’entité lorsqu’un rattachement a réellement besoin de plus de mémoire ou de plus de temps que la valeur par défaut ne le permet.
Fonctions hôtes. hostFunctions enregistre les noms des fonctions hôtes que le plugin importe. C’est un champ dérivé par la machine — ne le rédigez pas. aggrega plugin sync lit les fonctions hôtes directement dans la section d’import du .wasm et enregistre le champ dans le fichier de l’entité à votre place, et la publication les dérive de nouveau du binaire et refuse une entité dont l’enregistrement diffère ; ainsi un plugin obtient exactement les fonctions hôtes que son binaire importe réellement, validées par rapport à une liste d’autorisation sélectionnée (un import en dehors de la liste d’autorisation est rejeté de façon manifeste). L’enregistrement est un instantané du binaire publié, de la même façon que la référence plugin: adressée par contenu est un instantané des octets publiés : il reflète le binaire au moment de la publication et il est dérivé de nouveau et vérifié lorsque le plugin est récupéré par pull. Pour voir les fonctions hôtes qu’un .wasm local importe avant la publication — la valeur que aggrega plugin sync enregistre — exécutez aggrega inspect --plugin <file.wasm>.
La surface hôte sélectionnée. Trois des fonctions hôtes sont à usage général : aggrega_log (un niveau et un message, émis comme une ligne de journal vers la destination de journalisation de l’hôte), aggrega_emit_warning (un code, un message et un chemin, accumulés sous forme d’avertissement structuré que l’hôte présente après l’appel) et aggrega_fetch_external_input (une URL, à laquelle il est répondu par les octets de l’entrée selon la discipline d’épinglage ci-dessous). Le PDK encapsule les trois dans chaque langage — Go : aggrega.Log, aggrega.EmitWarning, aggrega.FetchExternalInput ; Rust : log, emit_warning, fetch_external_input ; TypeScript : log, emitWarning, fetchExternalInput — si bien qu’un guest appelle une fonction typée plutôt que l’ABI brute. Les callbacks de source et d’analyse — pour un guest qui lit des portions d’une source acquise ou obtient un arbre analysé par l’intermédiaire de l’hôte — et l’encodage que portent les emplacements de chaque callback sont listés dans plugin-contract.md.
Le contenu source local passe par l’hôte — jamais par le système de fichiers. Un plugin de rendu de fournisseur ne lit jamais sa source depuis le disque ; un appel au système de fichiers échoue à la frontière de l’appel. L’hôte remet au guest une liste de la source dans la charge utile de rendu — pour chaque entrée, son chemin relatif à la racine de la source et s’il s’agit d’un répertoire, dans un ordre trié, sans contenu de fichier — et le guest y applique sa propre logique de disposition, puis relit exactement les fichiers qu’il sélectionne au moyen des callbacks de source, qui renvoient les octets que l’hôte lit sous la racine de la source. Les formes de charge utile par socket et les callbacks sont documentées dans plugin-contract.md.
Le contenu distant passe par la récupération des entrées externes. Un plugin qui a besoin de contenu distant — une archive de chart, un document de schéma distant — appelle le wrapper de récupération du PDK. Lors de la transmission, le guest passe l’URL à aggrega_fetch_external_input sous forme de texte UTF-8 et reçoit une seule réponse en CBOR canonique, qui porte soit les octets récupérés, bruts, soit un message d’erreur à côté de son code comparable par machine ; le wrapper décode la réponse en octets ou en erreur. Les octets arrivent exactement tels qu’ils ont été récupérés, y compris une charge utile qui n’est pas de l’UTF-8 valide, et une charge utile de longueur nulle revient sous forme d’octets vides plutôt que d’erreur. L’hôte sert l’URL selon la discipline d’épinglage des entrées externes :
- Une URL déjà épinglée dans le fichier de verrouillage de la Release est servie depuis le magasin local adressé par contenu et vérifiée par rapport à son digest enregistré à chaque lecture. Un blob manquant dans le magasin est rechargé depuis le réseau d’après le digest enregistré — un rechargement vérifié par digest ne peut pas modifier la sortie.
- Une URL non épinglée est refusée, avec une erreur qui nomme l’URL et le remède. Un build rend la fermeture que son fichier de verrouillage enregistre, si bien qu’aucun build ne récupère une référence non épinglée et qu’aucun paramètre ne permet de le faire.
- L’épinglage a lieu lorsque les dépendances de la Release sont résolues :
aggrega pullrend la Release pour déterminer quelles entrées externes son rendu demande, récupère chacune d’elles et l’enregistre dans le fichier de verrouillage à côté des épinglages de dépendances. La boucle de travail d’un auteur de plugin est donc : résoudre une fois, puis faire le build hors ligne aussi souvent que vous le souhaitez.
Les schémas autorisés sont https, http vers des hôtes de bouclage uniquement, et oci (épinglé par le digest du manifeste). Le fichier de verrouillage enregistre chaque entrée épinglée — son URL, son digest sha256, sa taille et les plugins qui l’ont requise — si bien qu’un nouveau build sert les mêmes octets depuis le magasin local : reproductible, et hors ligne une fois épinglé.
Avec le 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)}Ce qui échoue, et pourquoi.
- Un appel au système de fichiers ou au réseau échoue à la frontière de l’appel : le guest ne dispose d’aucun répertoire pré-ouvert ni d’aucun socket. Cela s’applique à tous les chemins de code, y compris une dépendance de bibliothèque qui tente de lire un fichier — lisez plutôt la source au moyen des callbacks de source.
- Un import sous un module autre que
wasi_snapshot_preview1,extism:host/envetextism:host/useréchoue au chargement, avec un diagnostic qui nomme le module et l’import. Les noms de fonctions WASI individuels au sein d’un module autorisé ne sont jamais censurés — les imports de système de fichiers et de socket inutilisés du runtime d’un langage lié statiquement ne posent pas de problème, car nommer un import n’accorde rien. - La récupération d’une URL que le fichier de verrouillage n’épingle pas échoue avec une erreur qui nomme l’URL ; le remède consiste à exécuter
aggrega pull --release <release>, qui épingle chaque entrée externe que consomme le rendu de la Release, puis à faire le build.
Il n’existe aucun champ de liste d’autorisation d’hôtes pour l’accès réseau sortant. Un plugin n’atteint jamais le réseau au moment du build — c’est la frontière ahead-of-time — si bien qu’aucun champ de ce type n’existe à rédiger. Le contenu distant arrive par le canal des entrées externes décrit ci-dessus, qui passe par l’hôte et est épinglé par digest, jamais par un accès réseau ambiant.
Configuration. configKV est une table de chaîne à chaîne que le runtime remet au plugin au démarrage. Les entrées conservent l’ordre de l’auteur, si bien que l’enregistrement émis est identique à l’octet près d’une exécution à l’autre. En son absence, la configuration vide par défaut du runtime reste en vigueur.
5. L’entité Plugin
Un plugin entre dans le catalogue sous la forme d’une entité Plugin — la surface de création et de métadonnées du plugin. L’entité déclare ce qu’est le plugin et pointe vers l’artefact .wasm ; le compilateur n’interprète pas le comportement du plugin et achemine la référence épinglée, tandis que le runtime Wasm exécute les octets.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: aws-secrets-manager version: 1.2.0 pluginType: pipeline-stepspec: 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 credentialLes champs :
- Aucun champ d’emplacement de l’artefact, délibérément. L’entité ne porte aucun pointeur vers le
.wasmet le schéma n’en accepte aucun. L’emplacement de l’artefact d’un plugin est dérivé de son identité — la coordonnéemetadata.pluginType/metadata.name, qui forme le chemin de dépôtplugin/<pluginType>/<name>— à laquelle s’ajoute le registre pour lequel l’espace de travail est configuré, si bien qu’il n’y a aucun emplacement à rédiger ni sur lequel se tromper. Le digest de contenu résolu est enregistré par Release dans le fichier de verrouillage de cette Release, et le build vérifie les octets récupérés par rapport à lui : l’identité dans l’entité, les octets vérifiés dans le fichier de verrouillage. metadata.version— la release que publie l’entité, qui doit être égale à la version de provenance du build propre au guest telle que la rapportedescribe(). Un auteur de plugin versionne le.wasmau moment du build — le build inscrit la version dans le guest, et un build qui la prend d’un tag de release n’inscrit la version de la release que sur le commit que nomme ce tag — et lemetadata.versionde l’entité nomme cette même release. Le contrôle de publication recoupe les deux et s’arrête en cas de divergence, si bien que l’entité nomme toujours la version exacte du binaire qu’elle livre.aggrega plugin gen-catalog --plugin(ci-dessous) copie la version que rapporte le guest dans l’entité qu’il génère, qui est la version de la release lorsque le guest a été construit à partir du commit tagué. Obligatoire.metadata.pluginType— le type de socket que ce plugin implémente, choisi parmiprovider,linter,pipeline-step,governance,cli,parseretimporter. Un plugin en implémente exactement un. Il se trouve dans le bloc d’adressage à côté denameetversionet fournit le segment<pluginType>de la coordonnée dérivée. Obligatoire.spec.abiVersion— la version de l’ABI hôte/guest que cible le plugin.v1beta1est la valeur acceptée ; une future révision de l’ABI ajoute une valeur acceptée. Obligatoire.- Le bloc de votre type de socket, qui porte
capabilities— un plugin déclare ce qu’il sert à l’intérieur du bloc qui appartient à sonmetadata.pluginType, et c’est le bloc qui fixe ce que signifie une entrée.spec.provider.capabilitiesnomme les capacités que sert un fournisseur (des noms de capacités commehelmoucompose).spec.pipelineStep.capabilitiesnomme les fournisseurs avec la sortie rendue desquels votre étape est compatible.spec.parser.capabilitiesnomme les formats de source que lit un parseur, chacun écritparse:<format>.spec.importer.capabilitiesnomme les formats étrangers à partir desquels un importateur rédige des brouillons d’entités, chacun écritimport:<format>. Un importateur écrit en Go peut prendre tout ce qui ne dépend pas de son format — l’évaluation, la décision de référencer ou de rédiger un brouillon, les brouillons et leur rendu, et ses paramètres — dans le paquet importer du kit Go,github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Un pluginlinter,governanceoucline sert aucune capacité et ne porte aucun des quatre blocs. Les entrées conservent l’ordre de l’auteur, et chaque liste est une déclaration explicite et testée : déclarez ce par rapport à quoi vous avez réellement construit et testé le plugin, car un consommateur résout exactement par rapport à ce qui est listé. Pour une étape de pipeline, cette déclaration est imposée au moment du rendu — lorsqu’une étape touche une portée, le build s’arrête sauf si le fournisseur qui rend les documents de cette portée figure parmi ceux que déclare votre plugin — si bien qu’une liste vide ne correspond à aucun fournisseur et n’admet l’étape nulle part. spec.signature— un pointeur descriptif facultatif vers la signature attachée du plugin (section 8). Ce bloc n’est que de la documentation : il enregistre, pour les lecteurs du catalogue, où se trouve la signature et comment elle a été produite ; il n’admet pas lui-même le plugin. La vérification qui fait foi est la politique de confiance par registre appliquée au pull.spec.runtime— le bloc facultatif des contraintes d’exécution de la section 4. L’auteur rédigemaxMemoryPages,timeoutMsetconfigKV;hostFunctionsest dérivé par la machine et enregistré paraggrega plugin sync, ce que la publication vérifie, et n’est pas rédigé par l’auteur.spec.exports— les déclarations de capacités par export de la section 3 (name,operates,scope,selector).
Générer l’entité à partir de votre .wasm. Vous n’avez pas à écrire à la main les parties de l’entité gérées par la machine. aggrega plugin gen-catalog --plugin <file.wasm> lit l’auto-description describe() du guest et en produit une entité Plugin prête à être publiée, complétée d’une petite surcouche que vous rédigez (l’identité, les limites d’exécution et un éventuel bloc de fournisseur). Le générateur inscrit les champs dont le binaire est la source de vérité — les déclarations d’export, le contrat de capacités, le miroir des commandes et l’enregistrement des fonctions hôtes — et copie metadata.version à partir de la version de provenance du build de describe() du guest, tandis que la surcouche ne fournit que ce que le binaire ne rapporte pas. C’est le chemin pris en charge pour un auteur de plugin tiers : construisez et versionnez votre .wasm, puis régénérez l’entité afin que ses champs gérés par la machine restent en phase avec le binaire. La version est le seul champ copié qui nomme une release plutôt qu’un fait sur les octets ; générez donc à partir d’un build du commit que nomme le tag de la release — ou, en partant d’un build de développement, réglez metadata.version sur la release dans l’entité générée avant de taguer le commit qui la porte. Un guest qui ne porte aucune version de provenance du build ne peut pas être généré en une entité versionnée — versionnez d’abord le guest au moment du build.
Le .wasm à côté de son entité. Pendant que vous écrivez un plugin, rien n’est publié qu’une compilation puisse récupérer ; une compilation lit donc le .wasm du plugin à côté de son entité Plugin dans un répertoire de catalogue, sous un nom dérivé du type de plugin et du nom de l’entité : pour pipeline-step/patch, c’est pipeline-step--patch.wasm. Les lettres minuscules, les chiffres et la plupart des traits d’union sont écrits tels quels dans ce nom ; tout autre caractère est écrit sous une forme échappée, de même qu’un trait d’union à quelques positions — de sorte que, là où cela compte, le refus d’un .wasm manquant, A plugin’s .wasm is not on this machine (Le module d’un plugin n’est pas sur cette machine), donne le nom en entier. aggrega lint <plugin.yaml> lit le .wasm au même endroit — à côté du fichier d’entité qu’il reçoit, quel que soit le répertoire où se trouve ce fichier — sauf si le binaire embarque le plugin lui-même, et affiche un avis pour chaque export, capacité ou contrat que le .wasm signale et que l’entité omet. Là où aucun .wasm ne s’y trouve, le lint indique qu’il a sauté ce rapport, en nommant le fichier qu’il a cherché et le répertoire, et son résultat ne change pas.
Pour la référence champ par champ, voir la page de l’entité ../entities/plugin.md.
6. Référencer un plugin
Une étape de pipeline ou un socket de plugin référence un plugin par son URI d’entité Plugin — l’identité de l’entité, et non directement l’artefact .wasm. L’entité est la couche qui porte l’épinglage par digest, les déclarations de capacités, les limites d’exécution et la signature ; référencer l’entité est la façon dont un consommateur récupère tout cela.
Un chemin .wasm nu ou une référence d’artefact brute laissé dans un champ plugin est rejeté au chargement : aucune entité Plugin ne lui correspond, si bien que la résolution du plugin échoue de façon manifeste. L’URI d’entité est obligatoire — l’indirection par l’entité est le contrat, et non une commodité facultative. Une étape de pipeline de FeatureRecipe nomme l’entité dans pipeline[].plugin ; voir ../entities/featurerecipe.md pour la surface de création du pipeline.
Lorsque deux plugins ou plus sont couplés — ils doivent s’accorder sur un contrat de transmission partagé, comme dans une paire Fetcher et Injector où la sortie d’un plugin est l’entrée de l’autre (le principe du Plugin en deux parties décrit dans plugin-contract.md) — rédigez ce contrat une seule fois et faites dépendre chaque plugin de cette définition unique plutôt que de reformuler indépendamment la forme JSON de la transmission dans chaque plugin. La forme partagée est la structure JSON qu’échangent les plugins, qui peut résider dans une seule entrée de SchemaLibrary que les deux plugins référencent. Une source unique pour le contrat maintient les plugins couplés synchronisés à mesure qu’il évolue ; des reformulations indépendantes divergent, et la divergence n’apparaît que lorsque les deux ne concordent plus à l’exécution. La recommandation est de partager le contrat, et non le code Wasm — chaque plugin reste son propre artefact.
7. Le cycle de vie publish → pull → build
Un plugin passe d’un fichier .wasm sur disque à un artefact vérifié et consommable par un build en trois étapes.
Publish. aggrega push publie une entité Plugin et son .wasm ensemble sous la forme d’un manifeste OCI unique, tagué par metadata.version : le YAML de l’entité est le blob de configuration du manifeste et le .wasm voyage comme couche du même manifeste. Publier la paire sous la forme d’un seul manifeste tagué est ce qui rend le push atomique — il n’existe aucune fenêtre pendant laquelle une moitié est publiée et l’autre non — et c’est pourquoi une seule signature sur ce manifeste couvre les deux moitiés. Les deux moitiés sont nommées dans le manifeste, si bien qu’un client OCI générique qui récupère le tag de version écrit l’entité dans entity.yaml et l’exécutable dans entity.wasm.
Avant que le moindre octet n’arrive, la publication exécute ses vérifications. L’entité est d’abord lue par rapport au schéma Plugin, comme le fait un chargement du catalogue, si bien qu’un metadata.version qui n’est pas une version sémantique — ou tout autre écart par rapport au schéma — est refusé avant que le .wasm ne soit lu. Le .wasm est ensuite chargé et son auto-description describe() est recoupée avec les déclarations de capacités rédigées dans l’entité — une divergence provoque un arrêt manifeste, si bien qu’une entité publiée ne déclare jamais ce que le plugin qu’elle livre ne rapporte pas. Un guest dont la version de provenance du build dans describe() porte la marque -dirty, apposée sur un build issu d’un arbre de travail comportant des modifications non commitées, est refusé : cette version nomme un commit qui ne contient pas ce qui a été construit. Une version de développement construite à partir d’un commit (1.0.0-3-g1a2b3c4) et une préversion (1.0.0-rc.1) sont publiées. Le metadata.version enregistré est recoupé avec la version de provenance du build dans describe() du guest, et une divergence arrête la publication ; les deux doivent donc concorder. Les deux refus se lèvent de la même façon : construisez le plugin à partir d’un checkout propre du commit que nomme le tag de la release, afin qu’il rapporte lui-même la version de la release — pour une nouvelle release, commitez l’entité avec la source qu’elle publie et taguez d’abord ce commit. Copier dans l’entité la version que rapporte un build de développement n’est pas une réparation : cela publie ce build sous une version qu’aucun tag de release ne nomme. Les fonctions hôtes que le .wasm importe sont dérivées du binaire et comparées à l’enregistrement commité dans spec.runtime.hostFunctions ; une divergence arrête la publication et nomme aggrega plugin sync, qui réenregistre le champ, car le champ est géré par la machine et une publication ne réécrit jamais le fichier d’entité commité. L’entité publiée porte l’enregistrement inscrit des fonctions hôtes ; le digest de contenu du .wasm est une propriété du manifeste sous lequel la paire est publiée, et il est enregistré pour un consommateur dans le fichier de verrouillage de la Release plutôt qu’écrit dans l’entité.
Pull. aggrega pull résout toutes les dépendances d’une Release et écrit un fichier de verrouillage par Release qui épingle chaque entité du catalogue et chaque artefact distant à une version et à un digest de contenu. Un Plugin publié se résout par cette résolution des dépendances ; son .wasm est récupéré avec le manifeste qui le porte et les octets sont vérifiés par rapport au digest de contenu que le fichier de verrouillage enregistre. Le pull dérive aussi de nouveau les fonctions hôtes à partir du .wasm vérifié et les compare à l’enregistrement hostFunctions inscrit, en s’arrêtant si les deux divergent — une vérification de défense en profondeur par-dessus l’épinglage par digest, qui détecte un binaire dont l’enregistrement inscrit n’a pas été produit à partir de ses propres imports. Si la politique de confiance du registre exige des signatures, la signature de l’entité est récupérée et vérifiée à cette étape, et enregistrée comme un fait vérifié dans le fichier de verrouillage (section 8). La vérification a lieu au pull, jamais au build — le build reste pur ahead-of-time.
Build. aggrega build consomme le plugin épinglé et vérifié à partir des dépendances résolues. Le compilateur achemine la référence épinglée par digest et le runtime Wasm exécute les octets ; le contrôle au chargement réexécute le recoupement avec describe() ainsi que l’application des fonctions hôtes et des limites d’exécution avant que le plugin ne s’exécute.
8. Signature et confiance
Une entité Plugin est signée exactement comme toute autre entité du catalogue : le digest du manifeste est signé et attaché comme référent OCI. L’artefact .wasm n’est pas signé séparément, et il n’a pas besoin d’une signature séparée — c’est une couche du manifeste même dont le digest est signé, si bien que la signature le couvre directement : altérer le .wasm modifie le digest du manifeste et invalide la signature.
La signature est à activer volontairement à la publication ; la vérification est imposée par la politique de confiance par registre au pull. Un registre configuré pour exiger des signatures arrête le pull lorsqu’une signature requise est absente, non approuvée ou invalide. Le bloc spec.signature de l’entité est un pointeur de documentation indiquant où se trouve la signature et comment elle a été produite ; il enregistre des faits pour les lecteurs du catalogue et ne conditionne pas lui-même l’admission. Le point de contrôle est la politique appliquée au moment du pull.
Les commandes et leurs indicateurs sont documentés avec les surfaces de publication et de consommation — voir ../cli/aggrega-sign.md, ../cli/aggrega-push.md et ../cli/aggrega-pull.md. Ce guide ne reprend pas les tableaux d’indicateurs ; ces pages sont l’emplacement unique de la surface des commandes.
9. Versionner l’entité
Une entité Plugin porte une Semantic Version stricte dans metadata.version. Une version publiée est immuable : republier une version qui existe déjà dans le registre avec un contenu différent est rejeté au contrôle de publication.
Lorsque vous modifiez une entité de plugin et la republiez, la discipline de publication classe la modification par rapport à la version précédemment publiée et exige que l’incrément de version corresponde. La classification suit la grille d’incrément de version : une modification ne portant que sur la documentation ou les commentaires est PATCH ; une modification strictement additive (un nouveau champ facultatif, une nouvelle entrée) est MINOR ; une suppression, un rétrécissement de type ou un champ auparavant facultatif devenant obligatoire est MAJOR. Un incrément excessif est toujours autorisé ; un incrément insuffisant s’arrête avec un diagnostic qui nomme l’incrément requis. La première publication d’une entité saute la vérification de l’incrément et présente un avertissement indiquant qu’aucune vérification n’a été effectuée. Exécutez la vérification avant la publication avec aggrega lint --pre-publish ; voir ../cli/aggrega-lint.md pour la grille complète et les paramètres par règle.
Un Plugin n’a pas de surface extends, si bien que les règles d’héritage qui régissent les Components et les Features du catalogue ne l’atteignent pas. La grille d’incrément de version et l’immuabilité constituent la discipline de versionnement qui régit une entité de plugin.
10. Références croisées
authoring-a-provider-walkthrough.md— un guest de fournisseur construit de bout en bout, d’un répertoire vide jusqu’à la sortie rendue.plugin-contract.md— les points de socket que cible un plugin et les formes d’entrée/sortie par socket.policy-socket.md— le socket de gouvernance en détail : ses quatre rôles, les niveaux de gravité des verdicts, le canal d’entrée de l’opérateur, l’écriture d’une politique pour l’un ou l’autre des deux moteurs livrés dans le compilateur et les guests de politique de référence.core-importers.md— les importateurs propres au compilateur, un pour chaque format qu’il lit, construits sur le paquet importer du kit Go : ce que lit chacun, leurs paramètres et leur publication avec chaque version du compilateur.../compatibility.md— comment les kits de plugin sont versionnés, et ce qui permet à un plugin construit pour une version de continuer à se charger dans la suivante.../entities/plugin.md— la référence champ par champ de l’entitéPlugin.../entities/featurerecipe.md— la surface de créationpipeline:de la FeatureRecipe qui référence un plugin par URI d’entité.../cli/aggrega-lint.md— le publishing-linter, la grille d’incrément de version et l’application de l’immuabilité.../cli/aggrega-inspect.md— l’inspection des capacités, des limites d’exécution et de la signature d’une entitéPlugin.../cli/aggrega-push.md,../cli/aggrega-pull.md,../cli/aggrega-sign.md— les surfaces des commandes de publication, de consommation et de signature.