Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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, então cada Recipe escrita para a base já implementa o Component que a estende. Publicar uma variante especializada de um componente da biblioteca padrão custa, portanto, uma entidade de catálogo e uma linha de Manifest — nenhuma Recipe própria e nenhuma mudança na base.

O wrapper aqui é example/gateway/nginx-reviewed. Ele vem no catálogo ao lado de core/gateway/nginx, o componente que estende.

O que o wrapper adiciona, 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.com
spec:
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 no lugar de um bloco schema:. Ele 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 pode fazê-lo: o contrato pertence à base, em cada nível de profundidade de uma cadeia.

Tudo o que o wrapper não menciona, ele herda. aggrega inspect example/gateway/nginx-reviewed --resolved mostra a entidade mesclada, e duas coisas nela merecem uma leitura atenta:

  • Três sockets uses, não um: upstream e guard (os da base, com upstream selecionando component.aggrega.ai/type=server) e reviewed_upstream (o do wrapper). Estender adiciona um socket; não substitui o conjunto.
  • Os três pilares da base, literalmente — values.upstream_path, infra.port / engine_version / compute / overrides, e provides.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, na frente de um console de banco 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/adminer

upstream_path é a chave a observar. Ela é declarada no pilar values de core/gateway/nginx e não aparece em lugar nenhum no arquivo do wrapper, e mesmo assim um autor a escreve em uma instância do wrapper e ela chega à configuração renderizada do gateway. É isso que herdar os pilares inteiros 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.0

As 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 Component que estende essa base — então o wrapper é servido por ela sem alterações. Dois fatos 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 sendo necessário. A seleção da Recipe é feita pela chave de mapeamento exata, então o wrapper precisa da sua própria entrada type; ele 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

Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.

Escreva o exemplo em uma nova pasta com o nome dele:

Terminal window
aggrega scaffold --example extends-wrapper

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd extends-wrapper

Build

Terminal window
aggrega build --release release-reviewed.yaml --auto-pull

A 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 o build; aggrega pull --release release-reviewed.yaml executado uma vez antes faz a mesma coisa e permite que builds posteriores sejam executados sem nenhuma flag.

Tanto o wrapper quanto a base que ele estende ficam no catálogo compartilhado, que é resolvido a partir de hub.aggrega.ai, o registro padrão que .aggrega-config.yaml declara. O comando de build não precisa de nenhuma flag --catalog, e nem aggrega inspect executado a partir deste diretório.

O pull busca core/gateway/nginx porque o wrapper o estende: uma base é uma dependência de tudo o que a estende, então o pull segue a chave extends: do wrapper e fixa a base no arquivo de lock, quer o Manifest a nomeie ou não. Aqui o Manifest mapeia a base por outro motivo — a implantação de controle mais abaixo declara uma instância da própria base.

O dist/compose/docker-compose.yaml renderizado traz a evidência:

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, na ordem do que provam:

  • aggrega.ai/recipe-uri: nginx:1.0.0 — a Recipe da base deu forma a este serviço. O rótulo de proveniência em uma instância do wrapper nomeia a Recipe da base porque é a Recipe que a renderizou.
  • location /api/ — values.upstream_path, uma chave que só a base declara, escrita em uma instância do wrapper e renderizada.
  • proxy_pass http://internal:8081 — a aresta reviewed_upstream resolvida. provides.host e provides.port do componente de destino chegaram ao contexto de injeção sob as chaves de entrega que a Recipe da base lê, então um socket que o wrapper adicionou flui por uma Recipe que nunca ouviu falar dele.

O lockfile que o build resolve registra o mesmo fato 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.

Os rótulos e as anotações do wrapper viajam com a aresta resolvida: o contexto de renderização de um nó consumidor traz os provides, os labels e as anotações de cada destino, então o contexto de edge sabe que o seu upstream é audit-tier=reviewed e quem o revisou. Se algo disso aparece em um artefato renderizado é escolha da Recipe — esses rótulos e anotações são identidade do componente para seletores e políticas lerem, não uma saída que o compilador carimba.

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.

Use somente as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do espaço de trabalho ainda não contém uma pasta `extends-wrapper`, chame uma vez a ferramenta `scaffold` com `example` definido como `extends-wrapper` e sem `dir`: ela grava o exemplo em uma 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. Diga-me quais arquivos o build gravou; eles ficam em `extends-wrapper/dist/`.

O controle: para que serve o rótulo adicionado

aggregate-unreviewed.yaml é aggregate-reviewed.yaml com uma única alteração — a camada interna é declarada como a base core/gateway/nginx pura em vez do wrapper — e espera-se que falhe:

Terminal window
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 — ela é component.aggrega.ai/type=server, e a camada interna é ligada por esse socket exatamente da mesma forma —, mas não traz nenhum rótulo audit-tier, então o socket mais estrito do wrapper a rejeita. O rótulo que o wrapper adiciona é o que torna uma instância dele selecionável, e é no seletor que isso aparece.

Vale a pena conhecer mais duas interrupções, e ambas são o esquema fazendo o seu trabalho:

  • Um Component que declara extends e escreve conteúdo de pilares sob schema: é recusado quando o documento é carregado, nomeando a restrição. O mesmo acontece com um que omite schema: por completo. schema: inherited é a única forma aceita, e é escrita em vez de implícita para que um leitor nunca confunda um bloco de pilares herdado com um esquecido.
  • Uma chave values que a base não declara é recusada em uma instância do wrapper, no caminho em que foi escrita, porque o contrato aplicado é o da base.

Por que isso é útil

Uma organização que definiu uma forma revisada para um componente da biblioteca padrão precisa de um lugar para guardá-la. Guardados em prosa, os rótulos, as anotações e os sockets são repetidos em cada Aggregate que precisa deles, e divergem à medida que são repetidos. Publicada como um Component que estende a base, a forma se torna uma entidade de catálogo versionada, revisável e com nome: uma equipe que a consome escreve type: example/gateway/nginx-reviewed e uma linha de Manifest, e herda todo o contrato da base junto com cada Recipe já escrita para ela, em cada destino que a base suporta.

O custo do wrapper é o que faz isso funcionar: ele adiciona 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.