Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Plugin

Un Plugin est un plugin WebAssembly adressé par contenu : un artefact .wasm hébergé sur OCI, épinglé par son digest sha256, qui déclare le type de socket qu’il implémente, la version d’ABI qu’il cible, un pointeur de signature facultatif et un bloc runtime facultatif. L’entité est la surface de rédaction et de métadonnées d’un plugin ; la résolution des dépendances épingle l’artefact par son digest et la politique de confiance par registre vérifie sa signature au pull. Le compilateur n’interprète pas le comportement du plugin — il achemine la référence épinglée ; le runtime WebAssembly exécute les octets.

Cette page décrit champ par champ la surface de rédaction du catalogue pour Plugin. Pour le flux de travail complet de l’auteur — ce qu’est un plugin, l’auto-description describe(), le cycle de vie publish→pull→build, la signature et le versionnage — voir le guide du développeur de plugins Wasm. Pour les points de socket auxquels un plugin se rattache et leurs formes d’entrée/sortie, voir le contrat des plugins Wasm.

Le rôle du Plugin

Un Plugin relie une identité logique de plugin à un artefact .wasm concret ainsi qu’aux métadonnées de capacités et de runtime dont l’hôte a besoin pour le charger et l’exécuter en toute sécurité. Une étape de pipeline ou un socket de plugin référence l’entité par son URI ; l’entité porte les capacités déclarées, les limites de runtime et le pointeur de signature, tandis que le digest du contenu résolu se trouve dans le lockfile de la release. L’emplacement du .wasm est dérivé de l’identité du plugin — la coordonnée adressable plugin/<pluginType>/<name>, elle-même composée de metadata.pluginType et du metadata.name nu, plus le registre configuré — et n’est pas un champ rédigé. L’indirection par l’entité est obligatoire — une référence nue à un .wasm ou à un artefact est rejetée au chargement car aucune entité ne lui correspond.

Les déclarations d’un Plugin sont regroupées par type de socket, et c’est par ce regroupement que commence la lecture de l’entité :

  • Un bloc par type de socket — spec.provider, spec.pipelineStep, spec.parser, spec.importer. Un plugin porte le seul bloc que nomme son metadata.pluginType, et chaque bloc contient une liste capabilities: — enregistrée à partir du describe() du plugin lui-même par aggrega plugin gen-catalog — dont la signification appartient à ce seul bloc : la liste d’un fournisseur nomme les capacités qu’il sert, celle d’une étape de pipeline nomme les capacités de fournisseur avec lesquelles son étape est compatible, et celles d’un parser et d’un importateur nomment des formats source, écrits parse:<format> et import:<format>. C’est la contenance qui porte la signification — une entrée de capacité ne peut être atteinte sans lire d’abord le bloc qui dit de quel type d’affirmation il s’agit.
  • Un bloc fournisseur contient plus que sa liste — spec.provider déclare aussi comment le plugin traduit le type Workload, quelles annotations natives de la plateforme il lit, et son contrat de comportement de rendu (spec.provider.contract : types d’entrée, assemblage des frontières, délimiteurs d’artefacts, réutilisation d’instances). Ceux-ci décrivent un comportement de rendu plutôt qu’une dimension servie, c’est pourquoi ils se trouvent à côté de la liste de capacités du fournisseur plutôt qu’à l’intérieur.
  • Un socket transversal ne déclare aucune capacité — un plugin linter, governance ou cli ne porte aucun des quatre blocs, car il ne sert aucune dimension de rendu ni aucun format source.
apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
# capabilities is recorded by `aggrega plugin gen-catalog` from the plugin's describe(); an author may narrow it.
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

metadata

Métadonnées standard du catalogue. name, version et pluginType sont obligatoires ; version est une Semantic Version stricte (par ex. 1.2.0). Les champs facultatifs — description, maintainers, license, repository, home, keywords — suivent la même forme que toute entité de catalogue, et metadata n’accepte aucune autre clé. Une version publiée est immuable : republier une version existante est rejeté au contrôle de publication.

metadata.name est nu — il ne porte aucun préfixe de socket. La coordonnée adressable du plugin, plugin/<pluginType>/<name>, est dérivée de metadata.pluginType et du metadata.name nu ; elle n’est pas écrite dans le nom.

metadata.pluginType

Le type de socket que ce plugin implémente. Il se trouve dans le bloc d’adressage à côté de name et version parce qu’il fait partie de l’identité du plugin : il fournit le segment <pluginType> de la coordonnée dérivée plugin/<pluginType>/<name>. Un plugin implémente exactement un type de socket, tiré de la taxonomie des types de plugins que le runtime reconnaît :

  • provider — rend les nœuds IR en artefacts natifs du fournisseur.
  • linter — inspecte le contenu rédigé et émet des diagnostics.
  • pipeline-step — une étape de la pipeline: d’une FeatureRecipe ou d’une Recipe qui applique des correctifs à l’ensemble des documents rendus.
  • governance — assure les rôles de gouvernance du pipeline de build. Lors de la construction de la topologie, il pose automatiquement des labels sur les nœuds du graphe de topologie, en renvoyant des documents JSON Patch que l’hôte applique à une projection du graphe limitée aux labels. Lors de l’analyse statique ou de l’étape de rendu, il évalue le graphe IR ou les artefacts rendus et renvoie un verdict d’acceptation ou de rejet ; une règle non respectée arrête le build. C’est le rôle auquel il est rattaché, et non son type, qui fixe ce qu’il peut émettre.
  • parser — analyse un format source étranger (HCL, TOML, YAML, JSON, …) en un arbre JSON structuré, de sorte qu’un consommateur qui doit lire un format que le compilateur n’analyse pas nativement travaille à partir d’un arbre analysé plutôt que du texte brut.
  • importer — transforme une source étrangère d’infrastructure ou de définition d’agents en brouillons de fichiers de rédaction Aggrega, en annonçant les formats qu’il gère comme capacités import:<format>.
  • cli — fournit une sous-commande d’exécution aggrega <cmd> qu’un opérateur invoque en ligne de commande. Un socket d’exécution, distinct des sockets de rendu et de pipeline de la compilation.

Obligatoire.

spec.abiVersion

La version d’ABI hôte/invité que cible le plugin. v1beta1 est la valeur acceptée ; une nouvelle révision de l’ABI en ajoute une. Obligatoire.

Déclarer les capacités : un bloc par type de socket

Une capacité est ce qu’un consommateur demande à un plugin — une capacité de rendu qu’une Recipe demande, ou un format source qu’un build doit lire. Les capacités d’un plugin sont enregistrées dans le bloc qui appartient à son type de socket, de sorte que c’est le bloc où se trouve la liste qui fixe la signification de ses entrées :

metadata.pluginTypeOù ses capacités sont déclaréesCe que nomme une entrée
providerspec.provider.capabilitiesUne capacité de rendu que ce plugin sert, comme helm ou compose.
pipeline-stepspec.pipelineStep.capabilitiesUn fournisseur dont la sortie rendue est compatible avec l’étape de ce plugin.
parserspec.parser.capabilitiesUn format source que ce plugin lit, écrit parse:<format>.
importerspec.importer.capabilitiesUn format source étranger à partir duquel ce plugin rédige des brouillons d’entités, écrit import:<format>.
linter, governance, cli—Rien. Ces sockets ne servent aucune capacité, ils ne portent donc aucun des quatre blocs.

Un plugin implémente exactement un type de socket, son entité porte donc un seul bloc. La liste est le propre rapport du plugin : aggrega plugin gen-catalog lit le describe() du plugin et écrit dans le bloc chaque capacité qu’il signale. Un auteur peut restreindre la liste avant la publication, en omettant une capacité que le plugin signale mais que l’entité publiée ne doit pas offrir ; aggrega validate <entity> --plugin <file.wasm> et aggrega push acceptent une liste restreinte et affichent un avis nommant chaque capacité signalée par le plugin que la liste omet. Aucun des deux n’accepte une liste qui nomme une capacité que le plugin ne signale pas : tous deux la refusent, en nommant chacune de ces capacités et les capacités que le plugin signale effectivement, de sorte qu’une liste publiée n’offre jamais plus que ce que le plugin fournit. Une entité pipeline-step dont le plugin signale helm et helm-chart, et qui liste aussi compose, est refusée ainsi :

[E0080]
entity "probe-step:1.0.0-rc.1" lists capabilities ["compose"], which the plugin's describe() does not report (it reports ["helm" "helm-chart"]); remove them from the list, which may name only capabilities the plugin reports: wasm: entity contract claim does not match plugin describe()

Un consommateur résout exactement par rapport à ce qui est listé.

spec.provider

Le bloc du socket fournisseur pour un plugin pluginType: provider : les capacités qu’il sert, la manière dont il traduit le type Workload aggrega.ai/v1beta1 détenu par la plateforme, les annotations natives de la plateforme qu’il lit, et son contrat de comportement de rendu. Le bloc est présent sur chaque plugin de rendu de fournisseur et absent de tout autre type de plugin. Un fournisseur qui ne rend que du contenu sourcé ou des artefacts, sans synthèse de Workload, porte tout de même le bloc — il y déclare ses capacités et son contrat, et omet simplement workloadSchema.

spec.provider.capabilities

Les capacités que ce fournisseur sert — des noms de capacités tels que helm ou compose — dont il rend la forme de sortie. Un fournisseur est générique pour les artefacts qui partagent la forme de sortie d’une capacité, et non pour toutes les capacités, si bien que la liste nomme les capacités que le plugin lui-même déclare : aggrega plugin gen-catalog l’enregistre à partir du describe() du plugin, et un auteur peut la restreindre avant la publication. Les entrées conservent l’ordre dans lequel elles sont enregistrées.

La cible de fournisseur demandée par une Recipe (spec.capability: helm) se résout vers le plugin fournisseur dont la liste contient cette cible. Lorsque plusieurs plugins fournisseurs listent la même cible, c’est l’espace de travail qui choisit : la sélection plugins.providers dans la configuration de l’espace de travail nomme le plugin à utiliser, est résolue lors de aggrega pull et enregistrée dans le lockfile. Sans sélection et avec exactement un candidat, ce candidat est utilisé ; sans sélection et avec plusieurs candidats, le build s’arrête et nomme chaque candidat. L’ambiguïté est tranchée par espace de travail, au point d’utilisation, plutôt que par une règle d’unicité à l’échelle du catalogue. Une liste vide ou absente ne déclare aucune capacité, si bien que le plugin ne sert aucune cible.

Un nom de capacité ne contient ici aucun deux-points. Le spec.capability d’une Recipe est lu comme la capacité jusqu’à son dernier deux-points, suivie d’un épinglage de version, si bien qu’un nom en contenant un ne pourrait jamais être demandé ; un plugin dont le describe() déclare un tel nom est refusé au chargement, et aucune entité n’en est générée pour publication. Il en va de même pour les capacités de fournisseur qu’un plugin pipeline-step liste. Le deux-points de parse:<format> d’un parser et de import:<format> d’un importer fait partie de ces noms et reste.

spec.provider.workloadSchema

Une déclaration JSON Schema 2020-12 qui documente la manière dont ce fournisseur traduit le type Workload aggrega.ai/v1beta1 en manifestes natifs du fournisseur. Elle est déclarée par convention sur un fournisseur qui effectue une synthèse : un tel fournisseur déclare workloadSchema comme contrat de traduction documenté, en décrivant les champs du Workload que le fournisseur consomme, les ensembles fermés qu’accepte chaque champ de type énumération et les contraintes de plage qui s’appliquent.

Le corps est compilé en JSON Schema 2020-12 lorsque le Plugin se charge — un garde-fou structurel qui rejette un schéma mal formé au chargement plutôt qu’au rendu. La prise en charge d’une Recipe workload: est déterminée par la capacité de synthèse du fournisseur associé, et non par la présence de ce champ : une Recipe en mode synthétisé associée à un fournisseur incapable de synthèse s’arrête de manière explicite au moment du rendu. Le catalogue de la bibliothèque standard maintient workloadSchema en phase avec la capacité du fournisseur. Le champ est le contrat documenté ; rien d’autre ne le lit. Les corps de Workload eux-mêmes sont validés par rapport au schéma de Workload intégré détenu par la plateforme, et non par rapport à ce champ propre à chaque fournisseur.

spec.provider.wellKnownAnnotations

Un tableau ordonné qui énumère les clés d’annotation bien connues natives de la plateforme — celles de l’espace de noms réservé aggrega.ai/ — que ce fournisseur lit, ainsi que le comportement appliqué lorsque chacune est absente. Chaque entrée porte une key (l’annotation lue par le fournisseur, par exemple aggrega.ai/namespace), un purpose (ce que l’annotation contrôle lorsqu’elle est présente), un defaultBehavior facultatif (ce que fait le fournisseur lorsque l’annotation est absente) et un scope facultatif qui liste où le fournisseur lit la clé — sourced, synthesized ou artifactsStandalone, les types d’entrée de la Recipe, ou boundary pour une clé lue une fois par frontière. key et purpose sont obligatoires ; les entrées conservent l’ordre de l’auteur.

Le champ est la déclaration de prise en charge du fournisseur, et le compilateur le lit de deux manières. Une entrée dont le scope nomme un type d’entrée que le contract.inputKinds du même bloc ne déclare pas contredit cette déclaration, et le Plugin est refusé, avec le nom de la clé et du scope. Et lorsqu’un build effectue un rendu via ce fournisseur, une annotation aggrega.ai/ qu’aucune entrée ne couvre pour aucun des types d’entrée que le rendu déclare donne lieu à un avertissement qui nomme la clé, le fournisseur et ces types d’entrée ; la valeur passe tout de même sans modification et le build ne s’arrête pas. Absent, le champ ne déclare rien du tout, et aucun avertissement de ce type n’est émis pour ce fournisseur. La validation du schéma ne vérifie que la forme de chaque entrée (la clé se trouve sous l’espace de noms aggrega.ai/, purpose est présent) ; elle est distincte de la vérification à l’exécution qui régit la liaison d’une valeur dans l’espace de noms réservé.

metadata:
pluginType: provider
spec:
abiVersion: v1beta1
provider:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- helm
workloadSchema: |
# how the Workload kind translates to this provider's native output
...
wellKnownAnnotations:
- key: aggrega.ai/namespace
purpose: Overrides the target namespace the provider renders into.
defaultBehavior: Renders into the boundary's default namespace.

Les ensembles d’annotations propres à chaque fournisseur et le contenu de workloadSchema que livrent les fournisseurs de la bibliothèque standard sont documentés dans ../providers/well-known-annotations.md, ../providers/helm.md, ../providers/helm-chart.md et ../providers/compose.md.

spec.provider.readsNoWellKnownAnnotations

Déclare que ce fournisseur ne lit aucune des clés d’annotation bien connues natives de la plateforme. C’est une déclaration de prise en charge qui ne couvre aucune clé, et elle dit quelque chose que l’omission à la fois de ce champ et de wellKnownAnnotations ne dit pas : une déclaration absente est un silence, alors que celle-ci est l’affirmation du fournisseur lui-même qu’il ne lit rien sous l’espace de noms réservé aggrega.ai/. Un build qui effectue un rendu via un tel fournisseur émet un avertissement pour chaque annotation aggrega.ai/ qui atteint le rendu, en nommant la clé, le fournisseur et les types d’entrée que le rendu déclare ; la valeur passe tout de même sans modification et le build ne s’arrête pas.

Seul true peut être écrit, si bien qu’omettre le champ reste la seule façon de ne rien dire. Il ne peut pas être écrit avec wellKnownAnnotations : un fournisseur qui lit certaines des clés les liste plutôt là. Les deux refus se situent au niveau du schéma, si bien que le Plugin est refusé dès sa lecture.

spec:
provider:
capabilities:
- terraform
readsNoWellKnownAnnotations: true

Le fournisseur terraform de la bibliothèque standard le déclare ; ../providers/terraform.md explique ce que cela signifie pour une Release rendue par son intermédiaire.

spec.provider.contract

Le contrat de comportement de rendu à la compilation qu’un plugin de rendu de fournisseur déclare lui-même : les types d’entrée qu’il rend, la manière dont il assemble la sortie par nœud d’un groupe de dispatch, la paire de délimiteurs de template qu’il applique aux fichiers d’artefact importés, si une seule instance chargée peut servir chaque traversée, s’il respecte les entrées d’omission et s’il accepte les fichiers qu’une Recipe apporte à la sortie partagée de sa frontière. Il se trouve à côté de capabilities dans le même bloc, mais répond à une autre question : la liste des capacités dit quelles capacités ce plugin sert, tandis que le contrat dit comment il les rend. aggrega plugin gen-catalog l’enregistre à partir de l’autodéclaration describe() du plugin lui-même, et l’hôte le confronte à cette autodéclaration à la publication et au chargement ; un désaccord provoque l’arrêt. Absent, il ne déclare aucun contrat de comportement de rendu, et la vérification croisée ne compare que les déclarations par export. Tous les champs sont facultatifs.

ChampEffet
inputKindsLesquels des trois types d’entrée de la Recipe le plugin rend, chacun étant une déclaration booléenne indépendante : sourced (un ensemble de fichiers source — un chart, un module, un fichier compose), synthesized (un Workload synthétisé) et artifactsStandalone (un nœud autonome portant des documents d’artefact importés et ni source ni workload). L’hôte vérifie le type d’entrée d’un nœud par rapport à cet ensemble.
boundaryAssemblyLa manière dont le plugin combine la sortie de rendu par nœud d’un groupe de dispatch : none écrit la sortie de chaque nœud directement au chemin de dispatch ; merge fusionne les fragments par nœud en un seul document ; nest place la sortie de chaque nœud à sa propre position dans une structure parapluie. Absent, aucune déclaration d’assemblage n’est portée.
artifactDelimitersLa paire de délimiteurs de template Go que le plugin applique aux fichiers d’artefact importés, sous la forme left et right. Absent, la paire par défaut {{/}} s’applique ; un plugin dont la syntaxe cible entre en conflit avec cette paire déclare une paire alternative (par exemple [[/]]).
reusableInstanceSi une seule instance chargée du plugin peut servir chaque traversée de rendu, d’assemblage et de validation d’un build plutôt qu’une nouvelle instance par traversée. Déclaré true uniquement lorsque le plugin ne conserve aucun état d’une traversée à l’autre, de sorte qu’une seule instance produit une sortie identique à l’octet près, qu’elle soit réutilisée ou fraîchement chargée. Absent (false), une nouvelle instance est chargée par traversée, ce qui isole un plugin qui porte un état par construction. aggrega build --verify-determinism prouve que la sortie d’un plugin réutilisable est stable en rendant chaque nœud deux fois et en s’arrêtant à la moindre différence.
omitsSi le plugin respecte les entrées d’omission — des entrées qui nomment des unités rendues à exclure de la sortie d’un nœud : il exclut de ce qu’il rend chaque unité à laquelle une entrée correspond, et indique combien d’unités chaque entrée a trouvées. La valeur enregistre la déclaration que rapporte le describe() du plugin, si bien que true n’est correct que pour un plugin qui la rapporte, et une valeur qui diffère du rapport provoque l’arrêt. Absent (false), aucune prise en charge de ce type n’est déclarée.
boundaryArtifactsSi la cible du plugin accepte les fichiers qu’une Recipe apporte à la sortie partagée de la frontière dans laquelle il effectue le rendu, sous le spec.boundary.artifacts de la Recipe : le compilateur écrit chacun de ces fichiers une seule fois, à côté de ce que le plugin assemble pour la frontière, et la cible le lit comme faisant partie de cette sortie. La valeur enregistre la déclaration que rapporte le describe() du plugin, et une valeur qui diffère du rapport provoque l’arrêt. Absent (false), aucune prise en charge de ce type n’est déclarée, et une Recipe qui déclare le bloc pour ce plugin est refusée avant tout rendu.
metadata:
pluginType: provider
spec:
provider:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- helm-chart
contract:
inputKinds:
sourced: true
synthesized: false
artifactsStandalone: false
boundaryAssembly: nest
artifactDelimiters:
left: "[["
right: "]]"
reusableInstance: true

spec.pipelineStep

Le bloc d’étape de pipeline pour un plugin pluginType: pipeline-step. Son unique champ, capabilities, nomme les fournisseurs dont l’étape du plugin sait transformer la sortie rendue — des noms de capacités tels que helm ou compose. Une étape est écrite pour la forme de sortie d’un seul fournisseur à la fois, si bien que la liste nomme les fournisseurs que le plugin lui-même déclare ; les entrées conservent l’ordre dans lequel elles sont enregistrées. Le bloc n’est présent que sur les plugins d’étape de pipeline.

Le bloc est l’enregistrement, lisible dans le catalogue, de cette déclaration : aggrega plugin gen-catalog l’enregistre à partir de l’autodéclaration describe() du plugin lui-même, et un auteur peut le restreindre avant la publication. L’application lit la même déclaration depuis le plugin : lorsqu’une étape touche un scope, le build s’arrête, sauf si le fournisseur qui rend les documents de ce scope fait partie de ceux que le plugin déclare. Une liste vide ou absente ne déclare aucune compatibilité, si bien qu’aucun scope n’admet l’étape.

metadata:
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- helm
- compose

spec.parser

Le bloc parser pour un plugin pluginType: parser. Son unique champ, capabilities, nomme les formats source que le plugin transforme en un arbre structuré canonique, chacun écrit parse:<format>. Le préfixe fait partie de l’entrée, si bien qu’un plugin qui lit plusieurs formats liste une entrée par format. aggrega plugin gen-catalog enregistre la liste à partir du describe() du plugin lui-même, un auteur peut la restreindre avant la publication, et les entrées conservent l’ordre dans lequel elles sont enregistrées. Le bloc n’est présent que sur les plugins parser.

Un format demandé se résout vers le parser dont la liste contient l’entrée correspondante. Un format qu’aucun parser n’annonce arrête le build, et un format annoncé par plusieurs plugins parser s’arrête comme ambigu, en nommant les candidats — il n’y a pas de repli, car un parser n’a pas de valeur par défaut sans configuration vers laquelle se replier. Une liste vide ou absente ne déclare aucun format, si bien que le plugin n’analyse rien.

metadata:
pluginType: parser
spec:
abiVersion: v1beta1
parser:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- parse:hcl
- parse:toml

spec.importer

Le bloc importer pour un plugin pluginType: importer. Son champ capabilities nomme les formats source étrangers que le plugin transforme en brouillons de fichiers de rédaction Aggrega, chacun écrit import:<format>. Le préfixe fait partie de l’entrée, si bien qu’un plugin qui traite plusieurs formats liste une entrée par format. aggrega plugin gen-catalog enregistre la liste à partir du describe() du plugin lui-même, un auteur peut la restreindre avant la publication, et les entrées conservent l’ordre dans lequel elles sont enregistrées. Le bloc n’est présent que sur les plugins importer.

Un format d’import demandé se résout vers l’importer dont la liste contient l’entrée correspondante. Un format qu’aucun importer n’annonce arrête l’import, et un format annoncé par plusieurs plugins importer s’arrête comme ambigu, en nommant les candidats, sauf si une entrée plugins.importer dans la configuration de l’espace de travail rattache l’un d’eux, qui est alors celui qui s’exécute. Une liste vide ou absente ne déclare aucun format, si bien que le plugin n’importe rien.

Son champ detect enregistre les signatures auxquelles une source de ces formats est reconnue lorsqu’un import ne nomme aucun format. Il appartient à la machine, comme les enregistrements des fonctions hôtes et des commandes : il est dérivé de ce que rapporte le describe() du plugin lorsque l’entité est générée à partir du plugin, dans l’ordre où le plugin déclare les signatures, et un auteur ne l’écrit pas. Chaque signature nomme :

  • syntax — le format syntaxique dans lequel la source est analysée, le format qu’un plugin parser annonce sous la forme parse:<syntax>, par exemple json ou yaml.
  • files — des motifs de noms de fichiers facultatifs, comparés à la fin du nom de la source : un motif d’un seul segment au nom du fichier lui-même, un motif de plusieurs segments séparés par des barres obliques à autant de segments finaux de son chemin, si bien que .vscode/mcp.json correspond à un fichier nommé mcp.json dans un répertoire nommé .vscode. *, ? et [...] correspondent à l’intérieur d’un segment. Absent, la signature s’applique à une source constituée d’un seul fichier, quel que soit son nom, et à aucun fichier d’un répertoire. Les motifs des signatures d’un importer sont aussi ce qui décide quels fichiers d’un répertoire aggrega import lui transmet.
  • match — les prédicats que l’arbre analysé doit satisfaire, tous. Chacun a un path, des clés jointes par des points depuis le haut de l’arbre, un segment en nombre entier sélectionnant une position de tableau ; un is, l’un de present, absent, object, array, string, number et boolean ; et, de manière facultative, equals, une chaîne que la valeur doit être, ou prefix, une chaîne par laquelle elle doit commencer — au plus l’un des deux.

Lorsqu’un import ne nomme aucun format, les signatures de chaque importer que contient le catalogue de l’espace de travail — toutes versions comprises — et des importers de base du compilateur sont comparées à la source. La source est analysée une fois pour chaque syntaxe dans laquelle une signature applicable à son nom la lit, via le parser que le catalogue de l’espace de travail fournit pour cette syntaxe — ou, pour une syntaxe pour laquelle le catalogue ne fournit aucun parser, celui que le compilateur embarque lui-même — et une source qui ne s’analyse pas dans une syntaxe ne correspond à aucune signature qui la nomme. Un répertoire est comparé à travers ses fichiers : chaque signature est essayée sur les fichiers du répertoire que ses motifs sélectionnent, dans l’ordre des noms, et une signature qui ne déclare aucun motif ne s’applique à aucun d’eux. Une source à laquelle une signature correspond est reconnue comme chaque format que son importer annonce. Lorsqu’exactement un format est reconnu, la source est lue dans ce format. Une source à laquelle aucune signature ne correspond est refusée, avec une demande du format et le nom des formats annoncés par les importers — ou, pour un répertoire, avec la demande de l’un de ses fichiers pris isolément ou d’un format dont l’importer déclare des motifs de fichier, en ne nommant que ceux-ci ; une source reconnue comme plus d’un format est refusée en les nommant, avec la condition More than one importer recognises the source (Plusieurs importers reconnaissent la source). Ainsi, un importer qui annonce plus d’un format voit chaque source à laquelle ses signatures correspondent refusée comme ambiguë, et un importer dont les sources doivent être reconnues sert un seul format.

Lorsque l’entité enregistre detect, celui-ci doit être égal à ce que rapporte le describe() du plugin, signature par signature et dans le même ordre : le chargement de l’importer refuse un plugin dont le rapport diffère, en nommant importer.detect, et sa publication fait de même. Une entité qui n’enregistre aucun detect ne déclare rien et n’est pas comparée, si bien qu’elle charge toutes les signatures que rapporte le describe() de son plugin, et les formats de son importer ne sont alors accessibles qu’en les nommant.

metadata:
pluginType: importer
spec:
abiVersion: v1beta1
importer:
capabilities: # recorded by `aggrega plugin gen-catalog` from describe()
- import:langflow
detect:
- syntax: json
match:
- path: data.nodes
is: array

spec.signature

Un pointeur descriptif facultatif vers la signature attachée du plugin. Le bloc n’est que de la documentation — il indique aux lecteurs du catalogue où se trouve la signature et comment elle a été produite ; il n’admet pas le plugin à lui seul. La vérification qui fait foi est la politique de confiance propre à chaque registry, appliquée au pull : une signature est récupérée en tant que referrer OCI, vérifiée par rapport aux identités de confiance ou à la clé épinglée du registry, et enregistrée comme un fait vérifié dans le lockfile. Un registry qui exige des signatures arrête le pull lorsqu’une signature requise est manquante, non fiable ou invalide.

  • type — le schéma de signature. sigstore-cosign est le schéma pris en charge. Obligatoire lorsque le bloc est présent.
  • signatureRef — la référence de referrer OCI du bundle de signature attaché, à des fins de documentation et de découverte. Absent lorsque la signature est découverte par énumération des referrers au pull plutôt qu’épinglée ici.
  • publicKeyRef — un pointeur vers la clé publique avec laquelle la signature a été produite, pour une signature avec clé. Son absence indique une signature sans clé (identité OIDC), vérifiée par rapport aux identités de confiance du registry.

spec.runtime

Des contraintes d’exécution facultatives que l’hôte applique lors du chargement et de l’exécution du plugin. L’accès réseau sortant n’est pas un champ de rédaction : un plugin n’accède jamais au réseau au moment du build — la frontière ahead-of-time — si bien qu’il n’existe ici aucun champ de liste d’hôtes autorisés. Le contenu distant dont un plugin a besoin arrive par le canal d’entrée externe arbitré par l’hôte et épinglé par digest, enregistré dans le lockfile de la Release, jamais par un accès réseau ambiant ; le guide du développeur documente l’enveloppe de récupération et la discipline d’épinglage.

ChampEffet
maxMemoryPagesPlafonne la mémoire linéaire du plugin en pages Wasm (64 KiB par page). Zéro ou absent applique le plafond par défaut de la plateforme, si bien qu’un chargement n’est jamais illimité ; un rattachement qui a besoin de davantage augmente cette valeur.
timeoutMsPlafonne la durée pendant laquelle le code du plugin lui-même peut s’exécuter au cours d’un appel, en millisecondes, sans compter le temps passé dans les fonctions hôtes qu’il appelle. Sous Linux, la mesure est le temps processeur, si bien que le temps passé à attendre un processeur sur une machine chargée ne compte pas ; sur les autres systèmes, c’est le temps écoulé. Le premier appel à un plugin fraîchement chargé compte aussi le démarrage du plugin lui-même. Zéro ou absent applique le plafond par défaut de la plateforme, si bien qu’un appel n’est jamais impossible à annuler ; un rattachement qui s’exécute plus longtemps augmente cette valeur.
hostFunctionsLes noms des fonctions hôtes que le plugin importe. Dérivé par la machine et en lecture seule — ne le rédigez pas : aggrega plugin sync lit les fonctions hôtes dans la section d’import du .wasm et enregistre ce champ, la publication refuse un enregistrement qui diffère du binaire, et la valeur reflète le binaire publié, validé par rapport à la liste d’autorisation organisée. L’hôte enregistre exactement cet ensemble, donnant à chaque plugin la surface hôte de moindre privilège dont son binaire a besoin ; le pull redérive le marquage et le vérifie par rapport au binaire. Pour prévisualiser la valeur avant la publication, exécutez aggrega inspect --plugin <file.wasm>.
configKVUne configuration propre au Plugin que le runtime lui transmet au démarrage, sous forme de paires clé/valeur de chaîne à chaîne. Les entrées conservent l’ordre de l’auteur afin que l’enregistrement émis soit identique à l’octet près d’une exécution à l’autre. Absent, la configuration vide par défaut du runtime reste en vigueur.

spec.exports

Les exports que le plugin propose, chacun avec sa capacité déclarée, sous forme de liste ordonnée qui conserve l’ordre de l’auteur. Un export est un point d’entrée nommé vers lequel l’hôte effectue le dispatch (par exemple render_node, lint_naming, step) ; le bloc de capacité par export indique ce que fait cet export, tel que aggrega plugin gen-catalog l’enregistre à partir de l’autodéclaration describe() du plugin, et l’hôte le confronte à cette autodéclaration à la publication et au chargement. Absent, aucune surface d’export rédigée n’est déclarée.

ChampEffet
nameLe nom ABI de l’export — le nom vers lequel l’hôte effectue le dispatch. Obligatoire pour chaque entrée.
operatesL’opération de pipeline que l’export effectue : patch (modifier un document rendu existant) ou emit (ajouter un nouveau document). L’hôte confronte la valeur à l’autodéclaration du plugin ; il s’agit d’une déclaration de capacité validée, et non d’un commutateur de dispatch — l’opération qu’effectue une étape est portée par le résultat renvoyé par l’invité. Absent, aucune déclaration d’opération n’est portée.
scopeLa racine de documents sur laquelle l’export opère : own (les documents rendus du nœud lui-même) ou host (les documents du composant auquel est attachée une FeatureRecipe de portée composant). L’hôte lit le scope déclaré avant l’étape afin d’appliquer la compatibilité de fournisseur par rapport au fournisseur qui rend ce scope. Absent, la valeur par défaut est own.
selectorUne description libre et lisible par un humain de ce sur quoi l’export agit (par exemple workloads carrying a pod template). De la documentation pour les lecteurs du catalogue et la surface d’inspection ; le compilateur ne l’interprète pas.

spec.commands

Les verbes de premier niveau aggrega <command> qu’un plugin cli apporte, sous forme de liste ordonnée qui conserve l’ordre que déclare l’auto-déclaration describe() du plugin. Géré par la machine et en lecture seule — ne le rédigez pas. aggrega plugin sync lit la surface de commandes dans l’auto-déclaration describe() du plugin et l’enregistre ici, de sorte que les commandes qu’installe un plugin CLI sont lisibles depuis l’entité sans charger le .wasm. Un plugin non cli n’apporte aucune commande et enregistre une liste vide. L’hôte installe exactement cet ensemble ; un ensemble enregistré qui diverge de l’auto-déclaration describe() du plugin interrompt le chargement, et la publication refuse un ensemble désynchronisé du binaire et invite l’auteur à l’enregistrer de nouveau. Pour resynchroniser l’enregistrement après avoir modifié le plugin, exécutez aggrega plugin sync.

Chaque entrée de commande contient :

ChampEffet
nameLe verbe de commande que l’hôte enregistre — le jeton aggrega <name> qu’un opérateur invoque, et le discriminant que l’hôte transmet au plugin lors de l’invocation, afin qu’un même plugin qui fournit plusieurs commandes puisse aiguiller selon la commande appelée. Obligatoire pour chaque entrée.
descriptionLe texte d’aide court, sur une ligne, de la commande, affiché dans la liste des commandes et dans la sortie d’aide. Documentation uniquement ; l’hôte n’en tient pas compte.
flagsLes flags de la commande, dans l’ordre déclaré. Chaque entrée enregistre un flag sur la commande, de sorte que aggrega help <command> l’affiche comme le flag d’une commande native. Une commande sans flag le laisse vide.

Chaque entrée de flags déclare un flag :

ChampEffet
nameLe nom long du flag — le jeton --name qu’un opérateur passe sur la ligne de commande. Obligatoire pour chaque entrée.
shorthandL’alias court facultatif du flag — la forme -x qu’un opérateur peut passer au lieu du nom long — sous la forme d’une seule lettre ou d’un seul chiffre ASCII. S’il est absent, le flag n’a pas d’alias court.
descriptionLe texte d’aide sur une ligne du flag, affiché dans la sortie d’aide de la commande. Documentation facultative ; l’hôte ne la valide pas et n’en tient pas compte.
typeLe type de valeur du flag — string, bool ou int — et le genre de flag sous lequel l’aide l’affiche. S’il est absent, le flag est affiché comme un flag de type chaîne.
defaultLa valeur par défaut du flag lorsque l’opérateur ne le passe pas, exprimée sous forme de chaîne. Pour un flag bool ou int, c’est une valeur de ce type. Si elle est absente, le flag ne déclare aucune valeur par défaut.

Un plugin CLI déclare ses commandes et leurs flags dans describe() ; l’hôte enregistre exactement cette surface et affiche les flags de chaque commande dans aggrega help <command> de la même manière que ceux d’une commande intégrée.

L’hôte vérifie chaque flag qu’un plugin déclare lorsqu’il ajoute les commandes du plugin, et un plugin dont les déclarations échouent est ignoré plutôt qu’ajouté : aucune de ses commandes n’est enregistrée, un avertissement nomme le plugin, la commande, le flag et ce qui ne va pas, et toutes les autres commandes — intégrées ou issues d’un autre plugin — continuent de fonctionner. Une déclaration échoue lorsque :

  • un flag n’a pas de nom, ou une commande déclare deux fois le même nom ;
  • une forme abrégée est autre chose qu’une seule lettre ou un seul chiffre ASCII, ou une commande déclare la même forme abrégée pour deux flags ;
  • un nom ou une forme abrégée réutilise un flag que possède déjà chaque commande aggrega — --help, son -h, et les flags globaux tels que --offline et --config ;
  • un type est autre chose que string, bool ou int ;
  • une valeur par défaut ne s’analyse pas selon le type du flag — maybe pour un bool, three pour un int.

La forme à un seul caractère de shorthand et les trois valeurs de type font aussi partie du schéma de cette entité, de sorte qu’une entité Plugin qui enregistre toute autre valeur est refusée au chargement du catalogue. Qu’un nom ou une forme abrégée n’apparaisse qu’une fois par commande, qu’aucun ne réutilise un flag que possède chaque commande, et qu’une valeur par défaut s’analyse selon son type, seul l’hôte le vérifie. La vérification porte sur la capacité de l’hôte à déclarer un flag pour l’aide tel qu’il est écrit ; elle ne voit pas si le plugin lit les flags qu’il déclare, car le plugin analyse lui-même ses arguments.

metadata:
pluginType: cli
spec:
abiVersion: v1beta1
# commands is recorded by `aggrega plugin sync` from the plugin's describe() — do not author it.
commands:
- name: greet
description: Print a friendly greeting
flags:
- name: name
shorthand: n
description: Who to greet
type: string
default: world

Inspecter un Plugin

aggrega inspect <path-to-Plugin.yaml> affiche un fichier Plugin : son identité et son type de socket, les capacités que déclare son bloc, la table des capacités par export dans l’ordre de l’auteur, les contraintes d’exécution et — avec --detail — le pointeur de signature et les clés de configuration d’exécution. Un Plugin est adressable par chemin de fichier, ou par sa coordonnée <pluginType>/<name> dans le catalogue. Voir ../cli/aggrega-inspect.md.

Références croisées

  • Guide du développeur de plugins Wasm — le flux de travail complet de l’auteur : describe(), déclarations de capacités, limites d’exécution, cycle de vie, signature, gestion des versions.
  • Contrat des plugins Wasm — les points de socket auxquels un plugin se rattache et leurs formes d’entrée et de sortie.
  • entities/featurerecipe.md — la surface pipeline: de la FeatureRecipe qui référence un plugin par URI d’entité.
  • cli/aggrega-lint.md — le linter de publication, la grille d’incrément de version et l’application de l’immuabilité qui régissent la publication d’un Plugin.