Un wrapper publicado, servido por la Recipe de su base
Este ejemplo enseña una sola cosa: un Component que hace extends de otro hereda todo el contrato de datos de esa base, así que cada Recipe escrita para la base ya implementa el Component que la extiende. Publicar una variante especializada de un componente de la biblioteca estándar cuesta, por tanto, una entidad de catálogo y una línea de Manifest — ninguna Recipe propia y ningún cambio en la base.
El wrapper aquí es example/gateway/nginx-reviewed. Se incluye en el catálogo junto a core/gateway/nginx, el componente que extiende.
Qué añade el wrapper, y qué hereda
Toda la superficie escrita del wrapper son metadatos más 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 es el marcador literal que un Component que extiende otro escribe en lugar de un bloque schema:. Indica que los tres pilares de datos — values, infra y provides — son los de la base, exactamente como la base los escribió. El wrapper no declara ninguna clave de pilar propia y no puede hacerlo: el contrato pertenece a la base, en cada nivel de profundidad de una cadena.
Todo lo que el wrapper no menciona, lo hereda. aggrega inspect example/gateway/nginx-reviewed --resolved muestra la entidad fusionada, y dos cosas en ella merecen una lectura atenta:
- Tres sockets
uses, no uno:upstreamyguard(los de la base, conupstreamseleccionandocomponent.aggrega.ai/type=server) yreviewed_upstream(el del wrapper). Extender añade un socket; no reemplaza el conjunto. - Los tres pilares de la base, textualmente —
values.upstream_path,infra.port/engine_version/compute/overrides, yprovides.host/port/protocol, cada uno con las descripciones propias de la base.
Qué escribe un Aggregate consumidor
aggregate-reviewed.yaml declara dos niveles de gateway como el wrapper, delante de una consola de base de datos:
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 es la clave en la que fijarse. Se declara en el pilar values de core/gateway/nginx y no aparece en ninguna parte del archivo del wrapper, y aun así un autor la escribe en una instancia del wrapper y llega a la configuración renderizada del gateway. Eso es lo que significa en la práctica heredar los pilares enteros.
El Manifest es la otra mitad, y es una línea por tipo:
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.0Las dos líneas de gateway nombran la misma Recipe. compose/nginx declara implements: core/gateway/nginx:1.0.0, y una Recipe que nombra una base es la implementación de todo Component que extiende esa base — así que el wrapper es servido por ella sin cambios. Aquí se cumplen dos hechos a la vez, y son distintos:
- La Recipe coincide. No existe ninguna Recipe que implemente el tipo propio del wrapper, y no hace falta ninguna.
- La asignación sigue siendo necesaria. La selección de la Recipe se hace por clave de asignación exacta, así que el wrapper necesita su propia entrada
type; no hereda la de la base. Una instancia del wrapper sin entrada propia se detiene con el diagnóstico de instancia no asignada incluso cuando su base está asignada.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example extends-wrapperDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd extends-wrapperCompilación
aggrega build --release release-reviewed.yaml --auto-pullLa salida renderizada y el lockfile se generan, no se incluyen: este ejemplo hace commit de sus entradas y regenera todo lo demás. --auto-pull resuelve el lockfile durante la compilación; aggrega pull --release release-reviewed.yaml ejecutado una vez de antemano hace lo mismo y permite que las compilaciones posteriores se ejecuten sin ningún flag.
Tanto el wrapper como la base que extiende están en el catálogo compartido, que se resuelve desde hub.aggrega.ai, el registro predeterminado que declara .aggrega-config.yaml. El comando de compilación no necesita ningún flag --catalog, y tampoco aggrega inspect ejecutado desde este directorio.
El pull obtiene core/gateway/nginx porque el wrapper lo extiende: una base es una dependencia de todo lo que la extiende, así que el pull sigue la clave extends: del wrapper y fija la base en el archivo de bloqueo, lo nombre o no el Manifest. Aquí el Manifest mapea la base por otro motivo — el despliegue de control de más abajo declara una instancia de la propia base.
El dist/compose/docker-compose.yaml renderizado contiene la evidencia:
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]Tres lecturas, por orden de lo que demuestran:
aggrega.ai/recipe-uri: nginx:1.0.0— la Recipe de la base dio forma a este servicio. La etiqueta de procedencia de una instancia del wrapper nombra la Recipe de la base porque es la Recipe que la renderizó.location /api/—values.upstream_path, una clave que solo declara la base, escrita en una instancia del wrapper y renderizada.proxy_pass http://internal:8081— la aristareviewed_upstreamresuelta.provides.hostyprovides.portdel componente de destino llegaron al contexto de inyección bajo las claves de entrega que lee la Recipe de la base, así que un socket que añadió el wrapper fluye a través de una Recipe que nunca ha oído hablar de él.
El lockfile que resuelve la compilación registra el mismo hecho desde el lado del resolutor: una única entrada compose/nginx:1.0.0 con un único digest, referenciada desde ambas claves de asignación — el tipo de la base y el del wrapper.
Las etiquetas y anotaciones del wrapper viajan con la arista resuelta: el contexto de renderizado de un nodo consumidor lleva los provides, las labels y las anotaciones de cada destino, así que el contexto de edge sabe que su upstream es audit-tier=reviewed y quién lo revisó. Que algo de eso aparezca en un artefacto renderizado es decisión de la Recipe — estas etiquetas y anotaciones son identidad del componente para que la lean selectores y políticas, no una salida que el compilador estampe.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `extends-wrapper`, llama una vez a la herramienta `scaffold` con `example` establecido en `extends-wrapper` y sin `dir`: escribe el ejemplo en una nueva carpeta `extends-wrapper`. Después llama a la herramienta `build` con `workspace_root` establecido en `extends-wrapper`, `release` establecido en `release-reviewed.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `extends-wrapper/dist/`.El control: para qué sirve la etiqueta añadida
aggregate-unreviewed.yaml es aggregate-reviewed.yaml con un solo cambio — el nivel interno se declara como la base core/gateway/nginx sin más en lugar del wrapper — y se espera que falle:
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.La detención es la lección. La base satisface su propio socket upstream — es component.aggrega.ai/type=server, y el nivel interno se conecta a través de ese socket exactamente de la misma manera —, pero no lleva ninguna etiqueta audit-tier, así que el socket más estricto del wrapper la rechaza. La etiqueta que añade el wrapper es lo que hace seleccionable una instancia suya, y es en el selector donde se ve.
Vale la pena conocer dos detenciones más, y ambas son el esquema haciendo su trabajo:
- Un Component que declara
extendsy escribe contenido de pilares bajoschema:se rechaza cuando se carga el documento, nombrando la restricción. Lo mismo ocurre con uno que omiteschema:por completo.schema: inheritedes la única forma aceptada, y se escribe en lugar de darse por supuesta para que un lector nunca pueda confundir un bloque de pilares heredado con uno olvidado. - Una clave
valuesque la base no declara se rechaza en una instancia del wrapper, en la ruta en que se escribió, porque el contrato que se aplica es el de la base.
Por qué es útil
Una organización que ha fijado una forma revisada para un componente de la biblioteca estándar necesita un lugar donde guardarla. Guardados en prosa, las etiquetas, las anotaciones y los sockets se repiten en cada Aggregate que los necesita, y divergen a medida que se repiten. Publicada como un Component que extiende la base, la forma se convierte en una entidad de catálogo versionada, revisable y con nombre: un equipo que la consume escribe type: example/gateway/nginx-reviewed y una línea de Manifest, y hereda todo el contrato de la base junto con cada Recipe ya escrita para ella, en cada destino que admite la base.
El costo del wrapper es lo que hace que esto funcione: añade estructura y metadatos y nada más. Como no declara ningún pilar, una instancia del wrapper y una instancia de la base se validan contra un único contrato, y una Recipe escrita para la base nunca puede verse sorprendida por una especialización de ella.