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 socket que ninguém declarou, entregando valores reais

Este exemplo ensina uma linha divisória, e as suas duas metades:

Um consumidor pode inventar a conexão. Ele só pode consumir o que o produtor declara.

O autor de um Aggregate escreve uma entrada uses: no seu próprio componente sob um nome de socket que nenhuma entidade do catálogo declara. A aresta é construída e entrega — o valor chega ao artefato renderizado exatamente como chegaria por um socket declarado. Mas declarar as chaves que essa aresta pode transportar continua cabendo ao destino: nomeie uma que o destino não declara, e o build é interrompido.

Tudo aqui é resolvido a partir do catálogo da biblioteca padrão. O workspace não cria nenhum Component, Feature ou Recipe próprio.

A pilha

Três componentes, e um deles é ligado de duas maneiras diferentes:

instânciatipoo que é
dbcore/datastore/mariadbo banco de dados
modelcore/ai-model/anthropicum endpoint de modelo; uma realização em forma de referência, então nenhuma computação é executada para ele
webcore/devtool/adminero console, que consome os dois

core/devtool/adminer declara exatamente um socket:

usesSchema:
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: [env]

Isso é tudo o que o seu autor previu. Um console à frente de um banco de dados é a conexão que ele tinha em mente; um console que leva um endpoint de modelo no seu ambiente não é.

O que o Aggregate escreve

aggregate-delivers.yaml liga as duas arestas a partir de um único bloco uses::

web:
type: core/devtool/adminer
uses:
databases: # DECLARED — the socket the Component's usesSchema names
db:
target: db
inject:
env:
- in: ADMINER_DEFAULT_SERVER
from: host
assistant: # AD-HOC — declared nowhere
model:
target: model
inject:
env:
- in: ASSISTANT_ENDPOINT
from: endpoint
- in: ASSISTANT_MODEL
from: model

assistant não aparece em nenhum usesSchema, nem neste Component nem em nenhum outro. Ainda assim é permitido: o silêncio do catálogo sobre um socket significa que a conexão não foi prevista, não que ela é proibida, e o desenvolvedor é dono da topologia da sua própria aplicação.

O que o socket ad hoc perde é exatamente o que a entrada usesSchema ausente teria trazido — nenhum selector, então nada restringe qual componente a aresta pode alcançar e a verificação de segurança de tipos entre nós não tem nada a avaliar; nenhuma allowlist inject:; nenhum valueSchema ou infraSchema por aresta, então values: e infra: por aresta não têm contrato contra o qual ser verificados nem valores padrão declarados a herdar. A configuração por aresta escrita em um socket assim é aceita e trafega sem verificação, que é como se comporta todo socket sem contrato para esse pilar — um socket declarado que não define nenhum valueSchema está na mesma posição.

O que ele não perde é o que a aresta pode transportar. endpoint e model são ambas chaves que core/ai-model/anthropic declara no seu pilar provides.

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 adhoc-uses-socket

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

Terminal window
cd adhoc-uses-socket

Build

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

A saída renderizada e o lockfile são gerados, não distribuídos: este exemplo faz commit das suas entradas e regenera todo o resto. --auto-pull resolve o lockfile durante o build; executar aggrega pull --release release-delivers.yaml uma vez antes faz o mesmo e permite que os builds seguintes sejam executados sem nenhuma flag. As entidades do catálogo são resolvidas a partir de hub.aggrega.ai, o registro padrão que .aggrega-config.yaml nomeia, então nem o build nem aggrega inspect precisam de uma flag --catalog.

Com um assistente de IA

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

Use apenas as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `adhoc-uses-socket`, chame a ferramenta `scaffold` uma única vez com `example` definido como `adhoc-uses-socket` e sem `dir`: ela escreve o exemplo em uma nova pasta `adhoc-uses-socket`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `adhoc-uses-socket`, `release` definido como `release-delivers.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build escreveu; eles ficam em `adhoc-uses-socket/dist/`.

Leia a saída

dist/compose/docker-compose.yaml, o serviço web:

web:
image: adminer:4
environment:
ADMINER_DESIGN: pepa-linha-dark
ADMINER_DEFAULT_SERVER: db
ASSISTANT_ENDPOINT: https://api.anthropic.com
ASSISTANT_MODEL: claude-sonnet-4-5
[… omitted: the service's ports, provenance labels, networks, depends_on and healthcheck]

Quatro variáveis, três delas entregues por arestas, e a saída não registra qual socket foi declarado:

  • ADMINER_DEFAULT_SERVER: db chegou por databases, o socket declarado. O seu valor é o provides.host da Recipe do banco de dados — um nome de serviço do Compose.
  • ASSISTANT_ENDPOINT e ASSISTANT_MODEL chegaram por assistant, o socket ad hoc, levando o provides.endpoint e o provides.model da Recipe do modelo.

Elas ficam em um único mapa, na ordem do autor, sem marcador, sem anotação e sem diferença de ordenação entre elas. Esse é o ponto: um socket ad hoc é algo diferente de declarar, não algo diferente de entregar. Existe um único caminho de entrega e as duas arestas o seguem.

ASSISTANT_ENDPOINT também vale a pena ser lido como um fato da compilação ahead-of-time. O compilador não contatou a Anthropic para descobrir https://api.anthropic.com; a Recipe o emitiu como uma string de ponteiro determinística obtida do infra.endpoint do componente do modelo, e o compilador roteou essa string sem interpretá-la. O próprio Adminer não lê nenhuma das variáveis ASSISTANT_* — o desenvolvedor escolheu essas chaves de entrega, e o contêiner do console as carrega para o que as ler ali.

O grafo que o build emite registra a distinção mesmo que o artefato renderizado não o faça: toda aresta carrega um campo socket_declaration com o valor declared ou ad-hoc, então uma organização que quer que toda conexão passe por um socket declarado pelos seus arquitetos expressa isso como uma política de governança em vez de depender de o compilador ter uma opinião. Veja architecture/11-governance-and-compliance.md.

O controle: o que o consumidor ainda não pode inventar

aggregate-undeclared-key.yaml é aggregate-delivers.yaml com uma única alteração. A aresta ad hoc pede uma terceira chave:

- in: ASSISTANT_API_KEY
from: api_key

core/ai-model/anthropic declara endpoint e model no seu pilar provides, e nada mais. O build deve falhar:

Terminal window
aggrega build --release release-negative-undeclared-key.yaml --auto-pull
# [… omitted: a refused: line carrying the message below]
# [DEVELOPER_ERROR E0156] .spec.components.web.uses.assistant.model
# invalid inject key: the from-key must name a provides key its source publishes
# (Aggregate adhoc-uses-socket-undeclared-key,
# at .spec.components.web.uses.assistant.model, "env", "ASSISTANT_API_KEY", "api_key",
# "core/ai-model/anthropic", "endpoint", "model")

A interrupção é a lição, e onde ela dispara é a parte que vale notar: o caminho com problema nomeia o socket ad hoc, uses.assistant, e para na conexão em vez de na entrada de entrega dentro dela. A chave from: é verificada contra os provides declarados do Component de destino em toda aresta, e o fato de o socket ser ad hoc não muda nada nessa verificação. Um autor que pode inventar um nome de socket ainda não pode inventar uma chave de saída no componente de outra pessoa.

Primeiro vem a recusa, depois o Aggregate e o caminho em que a aresta foi escrita, o mecanismo e a chave de entrega sob a qual a entrada foi escrita, a chave com erro, o tipo de componente contra o qual ela foi resolvida e as chaves declaradas desse tipo em ordem — de modo que a correção fica visível apenas pela mensagem. Um Component de destino que não declara nenhum provides rejeita da mesma forma toda referência from: a ele; simplesmente não há chaves declaradas para listar, então a mensagem termina depois do tipo de componente.

Qual escrever

Declarar o socket no catálogo continua sendo o melhor caminho, e é o que o catálogo da biblioteca padrão faz. Um socket declarado carrega um selector que restringe quais componentes a aresta pode alcançar, uma allowlist inject:, um contrato por aresta com os seus próprios valores padrão e uma descrição — uma declaração revisável de uma conexão prevista, versionada com a entidade que a estabelece. Um socket ad hoc não carrega nada disso, e a aresta é tão segura quanto o autor que a escreveu.

A forma ad hoc é uma via de escape, para o caso que este exemplo mostra: uma conexão que o autor do catálogo não previu, necessária para uma única Release, em que esperar por uma mudança no catálogo significaria esperar para entregar. Recorra a ela sabendo o que custa.

Dois custos merecem ser declarados com clareza:

  • Um nome de socket com erro de digitação é um socket ad hoc permitido, não um erro. Escrever databses onde se queria databases produz um build verde em que nada flui pelo socket pretendido. O compilador reporta um nome de socket a uma edição de distância de um declarado como um aviso que nomeia as duas grafias — veja errors/warnings.md “Uses-socket near-miss lint (Lint de quase correspondência de sockets uses)” — mas é um aviso e nunca muda o veredito do build.
  • Duas superfícies não são abertas dessa forma deliberadamente. O uses de uma vinculação de Feature só pode nomear um socket que a Feature vinculada declara, e o uses por aresta de uma Release só pode nomear um socket que o Component consumidor declara. Um operador configura e liga dentro de uma arquitetura; ele não a cria. Por isso release-delivers.yaml carrega infra: e nada sobre sockets — o socket assistant é do autor do Aggregate, e somente dele.

Para o contrato completo, veja entities/component.md “Topology Sockets: usesSchema (Sockets de topologia)” e architecture/07-dependency-resolution.md.