Um wrapper publicado, servido pela Recipe da sua base
Este exemplo ensina uma só coisa: um Component que faz extends de outro herda todo o contrato de dados dessa base, pelo que cada Recipe escrita para a base já implementa o Component que a estende. Publicar uma variante especializada de um componente da biblioteca standard custa, portanto, uma entidade de catálogo e uma linha de Manifest — nenhuma Recipe própria e nenhuma alteração à base.
O wrapper aqui é example/gateway/nginx-reviewed. Está incluído no catálogo ao lado de core/gateway/nginx, o componente que estende.
O que o wrapper acrescenta, e o que herda
Toda a superfície escrita do wrapper são metadados mais um 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 é o marcador literal que um Component que estende outro escreve em vez de um bloco schema:. Declara que os três pilares de dados — values, infra e provides — são os da base, exatamente como a base os escreveu. O wrapper não declara nenhuma chave de pilar própria e não o pode fazer: o contrato pertence à base, em cada nível de profundidade de uma cadeia.
Tudo o que o wrapper não menciona, herda. aggrega inspect example/gateway/nginx-reviewed --resolved mostra a entidade combinada, e duas coisas nela merecem uma leitura atenta:
- Três sockets
uses, e não um:upstreameguard(os da base, comupstreama selecionarcomponent.aggrega.ai/type=server) ereviewed_upstream(o do wrapper). Estender acrescenta um socket; não substitui o conjunto. - Os três pilares da base, literalmente —
values.upstream_path,infra.port/engine_version/compute/overrides, eprovides.host/port/protocol, cada um com as descrições próprias da base.
O que um Aggregate consumidor escreve
aggregate-reviewed.yaml declara duas camadas de gateway como o wrapper, à frente de uma consola de base de dados:
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 é a chave a reparar. É declarada no pilar values de core/gateway/nginx e não aparece em lado nenhum no ficheiro do wrapper, e ainda assim um autor escreve-a numa instância do wrapper e ela chega à configuração renderizada do gateway. É isso que herdar os pilares por inteiro significa na prática.
O Manifest é a outra metade, e é uma linha 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.0As duas linhas de gateway nomeiam a mesma Recipe. compose/nginx declara implements: core/gateway/nginx:1.0.0, e uma Recipe que nomeia uma base é a implementação de todo o Component que estende essa base — pelo que o wrapper é servido por ela sem alterações. Dois factos valem aqui ao mesmo tempo, e são distintos:
- A Recipe corresponde. Não existe nenhuma Recipe que implemente o tipo próprio do wrapper, e nenhuma é necessária.
- O mapeamento continua a ser necessário. A seleção da Recipe é feita pela chave de mapeamento exata, pelo que o wrapper precisa da sua própria entrada
type; não herda a da base. Uma instância do wrapper sem entrada própria é interrompida com o diagnóstico de instância não mapeada mesmo quando a sua base está mapeada.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example extends-wrapperDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd extends-wrapperCompilação
aggrega build --release release-reviewed.yaml --auto-pullA saída renderizada e o lockfile são gerados, não incluídos: este exemplo faz commit das suas entradas e regenera todo o resto. --auto-pull resolve o lockfile durante a compilação; aggrega pull --release release-reviewed.yaml executado uma vez antes faz o mesmo e permite que as compilações seguintes sejam executadas sem nenhuma flag.
Tanto o wrapper como a base que estende ficam no catálogo partilhado, que é resolvido a partir de hub.aggrega.ai, o registo predefinido que .aggrega-config.yaml declara. O comando de compilação não precisa de nenhuma flag --catalog, nem aggrega inspect executado a partir deste diretório.
O pull obtém core/gateway/nginx porque o wrapper o estende: uma base é uma dependência de tudo o que a estende, pelo que o pull segue a chave extends: do wrapper e fixa a base no ficheiro de lock, quer o Manifest a indique ou não. Aqui, o Manifest mapeia a base por outro motivo — a implementação de controlo mais abaixo declara uma instância da própria base.
O dist/compose/docker-compose.yaml renderizado contém a prova:
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]Três leituras, pela ordem do que provam:
aggrega.ai/recipe-uri: nginx:1.0.0— a Recipe da base deu forma a este serviço. A etiqueta de proveniência numa instância do wrapper nomeia a Recipe da base porque é essa a Recipe que a renderizou.location /api/—values.upstream_path, uma chave que só a base declara, escrita numa instância do wrapper e renderizada.proxy_pass http://internal:8081— a arestareviewed_upstreamresolvida.provides.hosteprovides.portdo componente de destino chegaram ao contexto de injeção sob as chaves de entrega que a Recipe da base lê, pelo que um socket que o wrapper acrescentou flui através de uma Recipe que nunca ouviu falar dele.
O lockfile que a compilação resolve regista o mesmo facto do lado do resolvedor: uma única entrada compose/nginx:1.0.0 com um único digest, referenciada pelas duas chaves de mapeamento — o tipo da base e o do wrapper.
As etiquetas e as anotações do wrapper viajam com a aresta resolvida: o contexto de renderização de um nó consumidor contém os provides, as labels e as anotações de cada destino, pelo que o contexto de edge sabe que o seu upstream é audit-tier=reviewed e quem o reviu. Se algo disso aparece num artefacto renderizado é escolha da Recipe — estas etiquetas e anotações são identidade do componente para seletores e políticas lerem, e não um resultado que o compilador carimba.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta da área de trabalho ainda não contiver uma pasta `extends-wrapper`, chame uma vez a ferramenta `scaffold` com `example` definido como `extends-wrapper` e sem `dir`: esta escreve o exemplo numa nova pasta `extends-wrapper`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `extends-wrapper`, `release` definido como `release-reviewed.yaml`, `auto_pull` definido como true e `write` definido como true. Indique-me que ficheiros o build escreveu; encontram-se em `extends-wrapper/dist/`.O controlo: para que serve a etiqueta acrescentada
aggregate-unreviewed.yaml é aggregate-reviewed.yaml com uma única alteração — a camada interna é declarada como a base core/gateway/nginx simples em vez do wrapper — e espera-se que falhe:
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.A interrupção é a lição. A base satisfaz o seu próprio socket upstream — é component.aggrega.ai/type=server, e a camada interna é ligada através desse socket exatamente da mesma forma —, mas não tem nenhuma etiqueta audit-tier, pelo que o socket mais estrito do wrapper a rejeita. A etiqueta que o wrapper acrescenta é o que torna uma instância dele selecionável, e é no seletor que isso se vê.
Vale a pena conhecer mais duas interrupções, e ambas são o esquema a fazer o seu trabalho:
- Um Component que declara
extendse escreve conteúdo de pilares sobschema:é recusado quando o documento é carregado, nomeando a restrição. O mesmo acontece com um que omitaschema:por completo.schema: inheritedé a única forma aceite, e é escrita em vez de implícita para que um leitor nunca possa confundir um bloco de pilares herdado com um esquecido. - Uma chave
valuesque a base não declara é recusada numa instância do wrapper, no caminho em que foi escrita, porque o contrato aplicado é o da base.
Porque é que isto é útil
Uma organização que definiu uma forma revista para um componente da biblioteca standard precisa de um sítio onde a guardar. Guardadas em prosa, as etiquetas, as anotações e os sockets são repetidos em cada Aggregate que deles precisa, e divergem à medida que são repetidos. Publicada como um Component que estende a base, a forma torna-se uma entidade de catálogo versionada, revisível e com nome: uma equipa que a consome escreve type: example/gateway/nginx-reviewed e uma linha de Manifest, e herda todo o contrato da base juntamente com cada Recipe já escrita para ela, em cada destino que a base suporta.
O custo do wrapper é o que faz isto funcionar: acrescenta estrutura e metadados e nada mais. Como não declara nenhum pilar, uma instância do wrapper e uma instância da base são validadas contra um único contrato, e uma Recipe escrita para a base nunca pode ser surpreendida por uma especialização dela.