Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler 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, 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.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 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: upstream e guard (os da base, com upstream a selecionar component.aggrega.ai/type=server) e reviewed_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, 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, à 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/adminer

upstream_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.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 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:

Terminal window
aggrega scaffold --example extends-wrapper

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd extends-wrapper

Compilação

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 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 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ê, 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:

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 — é 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 extends e escreve conteúdo de pilares sob schema: é recusado quando o documento é carregado, nomeando a restrição. O mesmo acontece com um que omita schema: 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 values que 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.