Un wrapper publié, servi par la Recipe de sa base
Cet exemple enseigne une seule chose : un Component qui en extends un autre hérite de tout le contrat de données de cette base, si bien que chaque Recipe écrite pour la base implémente déjà le Component qui l’étend. Publier une variante spécialisée d’un composant de la bibliothèque standard coûte donc une entité de catalogue et une ligne de Manifest — aucune Recipe propre, et aucune modification de la base.
Le wrapper est ici example/gateway/nginx-reviewed. Il est livré dans le catalogue à côté de core/gateway/nginx, le composant qu’il étend.
Ce que le wrapper ajoute, et ce dont il hérite
Toute la surface rédigée du wrapper se compose de métadonnées plus un socket :
metadata: name: example/gateway/nginx-reviewed labels: component.aggrega.ai/type: server component.aggrega.ai/category: gateway gateway.example.com/audit-tier: reviewed # added gateway.example.com/data-zone: eu-west # added annotations: governance.example.com/review-board: platform-architecture # added governance.example.com/contact: platform-architecture@example.comspec: extends: core/gateway/nginx:1.0.0 schema: inherited usesSchema: reviewed_upstream: # added selector: "gateway.example.com/audit-tier=reviewed" inject: [env]schema: inherited est le marqueur littéral qu’un Component qui en étend un autre écrit à la place d’un bloc schema:. Il indique que les trois piliers de données — values, infra et provides — sont ceux de la base, exactement tels que la base les a rédigés. Le wrapper ne déclare aucune clé de pilier qui lui soit propre et ne le peut pas : le contrat appartient à la base, à chaque profondeur d’une chaîne.
Tout ce que le wrapper ne mentionne pas, il en hérite. aggrega inspect example/gateway/nginx-reviewed --resolved affiche l’entité fusionnée, et deux choses y méritent une lecture attentive :
- Trois sockets
uses, et non un seul :upstreametguard(ceux de la base,upstreamsélectionnantcomponent.aggrega.ai/type=server) etreviewed_upstream(celui du wrapper). Étendre ajoute un socket ; cela ne remplace pas l’ensemble. - Les trois piliers de la base, tels quels —
values.upstream_path,infra.port/engine_version/compute/overrides, etprovides.host/port/protocol, chacun avec les descriptions propres à la base.
Ce qu’écrit un Aggregate consommateur
aggregate-reviewed.yaml déclare deux niveaux de passerelle comme le wrapper, devant une console de base de données :
components: edge: type: example/gateway/nginx-reviewed values: upstream_path: /api/ # declared by the base; the wrapper never mentions it uses: reviewed_upstream: # the socket the wrapper ADDS internal: { target: internal, inject: { env: [ ... ] } } internal: type: example/gateway/nginx-reviewed values: upstream_path: / uses: upstream: # the socket the wrapper INHERITS console: { target: console, inject: { env: [ ... ] } } console: type: core/devtool/adminerupstream_path est la clé à remarquer. Elle est déclarée dans le pilier values de core/gateway/nginx et n’apparaît nulle part dans le fichier du wrapper, et pourtant un auteur l’écrit sur une instance du wrapper et elle atteint la configuration rendue de la passerelle. Voilà ce que signifie en pratique hériter des piliers en entier.
Le Manifest est l’autre moitié, et c’est une ligne par type :
mappings: components: type: example/gateway/nginx-reviewed:1.0.0: compose/nginx:1.0.0 core/gateway/nginx:1.0.0: compose/nginx:1.0.0 core/devtool/adminer:1.0.0: compose/adminer:1.0.0Les deux lignes de passerelle nomment la même Recipe. compose/nginx déclare implements: core/gateway/nginx:1.0.0, et une Recipe qui nomme une base est l’implémentation de chaque Component qui étend cette base — si bien que le wrapper est servi par elle sans modification. Deux faits valent ici en même temps, et ils sont distincts :
- La Recipe correspond. Aucune Recipe implémentant le type propre au wrapper n’existe, et aucune n’est nécessaire.
- Le mappage reste nécessaire. La sélection de la Recipe se fait par clé de mappage exacte, si bien que le wrapper a besoin de sa propre entrée
type; il n’hérite pas de celle de la base. Une instance du wrapper sans entrée propre s’arrête avec le diagnostic d’instance non mappée même lorsque sa base est mappée.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example extends-wrapperElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd extends-wrapperBuild
aggrega build --release release-reviewed.yaml --auto-pullLa sortie rendue et le lockfile sont générés, et non livrés : cet exemple committe ses entrées et régénère tout le reste. --auto-pull résout le lockfile pendant le build ; aggrega pull --release release-reviewed.yaml exécuté une fois au préalable fait la même chose et permet aux builds suivants de s’exécuter sans aucun flag.
Le wrapper comme la base qu’il étend se trouvent dans le catalogue partagé, qui se résout depuis hub.aggrega.ai, le registre par défaut que déclare .aggrega-config.yaml. La commande de build n’a besoin d’aucun flag --catalog, pas plus que aggrega inspect exécuté depuis ce répertoire.
Le pull récupère core/gateway/nginx parce que le wrapper l’étend : une base est une dépendance de tout ce qui l’étend, si bien que le pull suit la clé extends: du wrapper et épingle la base dans le fichier de verrouillage, que le Manifest la nomme ou non. Le Manifest mappe ici la base pour une autre raison — le déploiement de contrôle ci-dessous déclare une instance de la base elle-même.
Le dist/compose/docker-compose.yaml rendu en apporte la preuve :
edge: image: nginx:1.27.5-alpine entrypoint: - /bin/sh - -c - echo 'server { listen 8080; location /api/ { proxy_pass http://internal:8081; } }' > /etc/nginx/conf.d/default.conf && exec nginx -g 'daemon off;' [… omitted: the published port] labels: [… omitted: the other provenance labels every rendered document carries] aggrega.ai/recipe-uri: nginx:1.0.0 [… omitted: the service's network, its depends_on naming internal, and its healthcheck]Trois lectures, dans l’ordre de ce qu’elles prouvent :
aggrega.ai/recipe-uri: nginx:1.0.0— la Recipe de la base a façonné ce service. L’étiquette de provenance sur une instance du wrapper nomme la Recipe de la base, parce que c’est la Recipe qui l’a rendue.location /api/—values.upstream_path, une clé que seule la base déclare, rédigée sur une instance du wrapper et rendue.proxy_pass http://internal:8081— l’arêtereviewed_upstreamrésolue. Lesprovides.hostetprovides.portde la cible sont arrivés dans le contexte d’injection sous les clés de livraison que lit la Recipe de la base, si bien qu’un socket ajouté par le wrapper passe par une Recipe qui n’en a jamais entendu parler.
Le lockfile que résout le build enregistre le même fait du côté du résolveur : une seule entrée compose/nginx:1.0.0 à un seul digest, référencée par les deux clés de mappage — le type de la base et celui du wrapper.
Les étiquettes et les annotations du wrapper voyagent avec l’arête résolue : le contexte de rendu d’un nœud consommateur porte les provides, les labels et les annotations de chaque cible, si bien que le contexte de edge sait que son upstream est audit-tier=reviewed et qui l’a revu. Que l’un de ces éléments apparaisse ou non dans un artefact rendu relève du choix de la Recipe — ces étiquettes et annotations sont l’identité du composant, destinée à être lue par les sélecteurs et les politiques, et non une sortie que le compilateur appose.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `extends-wrapper`, appelez une fois l’outil `scaffold` avec `example` défini sur `extends-wrapper` et sans `dir` : il écrit l’exemple dans un nouveau dossier `extends-wrapper`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `extends-wrapper`, `release` défini sur `release-reviewed.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi les fichiers écrits par le build ; ils se trouvent sous `extends-wrapper/dist/`.Le témoin : à quoi sert l’étiquette ajoutée
aggregate-unreviewed.yaml est aggregate-reviewed.yaml avec une seule modification — le niveau interne est déclaré comme la base core/gateway/nginx nue au lieu du wrapper — et il est censé échouer :
aggrega build --release release-negative-unreviewed.yaml --auto-pull# [DEVELOPER_ERROR E0007] aggregate-unreviewed.yaml at .spec.components.edge.uses.reviewed_upstream.internal# selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.L’arrêt est la leçon. La base satisfait son propre socket upstream — elle est component.aggrega.ai/type=server, et le niveau interne est câblé par ce socket exactement de la même manière — mais elle ne porte aucune étiquette audit-tier, si bien que le socket plus strict du wrapper la rejette. L’étiquette qu’ajoute le wrapper est ce qui rend une instance de celui-ci sélectionnable, et c’est dans le sélecteur que cela se voit.
Deux autres arrêts méritent d’être connus, et tous deux sont le schéma qui fait son travail :
- Un Component qui déclare
extendset rédige du contenu de piliers sousschema:est refusé au chargement du document, avec l’indication de la contrainte. Il en va de même pour celui qui omet entièrementschema:.schema: inheritedest la seule forme acceptée, et elle est écrite plutôt que sous-entendue pour qu’un lecteur ne puisse jamais confondre un bloc de piliers hérité avec un bloc oublié. - Une clé
valuesque la base ne déclare pas est refusée sur une instance du wrapper, au chemin où elle a été rédigée, parce que le contrat appliqué est celui de la base.
Pourquoi c’est utile
Une organisation qui a arrêté une forme revue pour un composant de la bibliothèque standard a besoin d’un endroit où la conserver. Conservés en prose, les étiquettes, les annotations et les sockets sont reformulés dans chaque Aggregate qui en a besoin, et divergent à mesure qu’ils le sont. Publiée comme un Component qui étend la base, la forme devient une entité de catalogue versionnée, révisable et nommée : une équipe qui la consomme écrit type: example/gateway/nginx-reviewed et une ligne de Manifest, et hérite de tout le contrat de la base ainsi que de chaque Recipe déjà écrite pour elle, sur chaque cible que la base prend en charge.
C’est le coût du wrapper qui fait que cela fonctionne : il ajoute de la structure et des métadonnées, et rien d’autre. Comme il ne déclare aucun pilier, une instance du wrapper et une instance de la base sont validées par rapport à un seul contrat, et une Recipe écrite pour la base ne peut jamais être surprise par une spécialisation de celle-ci.