Um socket que ninguém declarou, a entregar valores reais
Este exemplo ensina uma linha divisória, e as suas duas metades:
Um consumidor pode inventar a ligação. 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 artefacto renderizado exatamente como chegaria através de um socket declarado. Mas declarar as chaves que essa aresta pode transportar continua a caber ao destino: se for nomeada uma que o destino não declara, a compilação é interrompida.
Tudo aqui é resolvido a partir do catálogo da biblioteca standard. O workspace não cria nenhum Component, Feature ou Recipe próprio.
A pilha
Três componentes, e um deles está ligado de duas maneiras diferentes:
| instância | tipo | o que é |
|---|---|---|
db | core/datastore/mariadb | a base de dados |
model | core/ai-model/anthropic | um endpoint de modelo; uma realização em forma de referência, pelo que não é executada nenhuma computação para ele |
web | core/devtool/adminer | a consola, que consome ambos |
core/devtool/adminer declara exatamente um socket:
usesSchema: databases: selector: "component.aggrega.ai/type=stateful-server" inject: [env]É tudo o que o seu autor previu. Uma consola à frente de uma base de dados é a ligação que tinha em mente; uma consola que leva um endpoint de modelo no seu ambiente não 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: modelassistant 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 ligação não foi prevista, não que seja proibida, e o programador é dono da topologia da sua própria aplicação.
Aquilo de que o socket ad hoc abdica é exatamente o que a entrada usesSchema em falta teria trazido — nenhum selector, pelo que nada restringe o componente que 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, pelo que values: e infra: por aresta não têm nenhum contrato com o qual ser verificados nem valores predefinidos declarados a herdar. A configuração por aresta escrita num socket destes é aceite e circula sem verificação, que é como se comporta qualquer socket sem contrato para esse pilar — um socket declarado que não define nenhum valueSchema está na mesma posição.
Aquilo de que não abdica é 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
É 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 adhoc-uses-socketDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd adhoc-uses-socketCompilação
aggrega build --release release-delivers.yaml --auto-pullA 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 a compilação; executar aggrega pull --release release-delivers.yaml uma vez antes faz o mesmo e permite que as compilações seguintes sejam executadas sem qualquer flag. As entidades do catálogo são resolvidas a partir de hub.aggrega.ai, o registo predefinido que .aggrega-config.yaml indica, pelo que nem a compilação 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-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta do espaço de trabalho 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`: esta escreve o exemplo numa 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 que ficheiros a compilação escreveu; encontram-se em `adhoc-uses-socket/dist/`.Ler 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 através de arestas, e a saída não regista qual socket foi declarado:
ADMINER_DEFAULT_SERVER: dbchegou através dedatabases, o socket declarado. O seu valor é oprovides.hostda Recipe da base de dados — um nome de serviço do Compose.ASSISTANT_ENDPOINTeASSISTANT_MODELchegaram através deassistant, o socket ad hoc, transportando oprovides.endpointe oprovides.modelda Recipe do modelo.
Estão num único mapa, pela ordem do autor, sem marcador, sem anotação e sem diferença de ordenação entre elas. É precisamente esse o ponto: um socket ad hoc é algo diferente de declarar, não algo diferente de entregar. Existe um único caminho de entrega e ambas as arestas o seguem.
ASSISTANT_ENDPOINT também merece ser lido como um facto da compilação ahead-of-time. O compilador não contactou a Anthropic para descobrir https://api.anthropic.com; a Recipe emitiu-o como uma cadeia de ponteiro determinística obtida a partir do infra.endpoint do componente do modelo, e o compilador encaminhou essa cadeia sem a interpretar. O próprio Adminer não lê nenhuma das variáveis ASSISTANT_* — o programador escolheu essas chaves de entrega, e o contentor da consola transporta-as para o que quer que as leia aí.
O grafo que a compilação emite regista a distinção, mesmo que o artefacto renderizado não o faça: cada aresta transporta um campo socket_declaration com o valor declared ou ad-hoc, pelo que uma organização que quer que cada ligação passe por um socket declarado pelos seus arquitetos exprime isso como uma política de governação, em vez de depender de o compilador ter uma opinião. Ver architecture/11-governance-and-compliance.md.
O controlo: o que o consumidor continua a não poder 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_keycore/ai-model/anthropic declara endpoint e model no seu pilar provides, e nada mais. A compilação deverá falhar:
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 merece atenção: o caminho problemático nomeia o socket ad hoc, uses.assistant, e termina na ligação em vez de na entrada de entrega que esta contém. A chave from: é verificada em relação aos provides declarados do Component de destino em cada aresta, e o facto de o socket ser ad hoc não muda nada nessa verificação. Um autor que pode inventar um nome de socket continua a não poder 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 em causa, o tipo de componente em relação ao qual foi resolvida e as chaves declaradas desse tipo por ordem — de modo que a correção é visível apenas a partir da mensagem. Um Component de destino que não declara nenhum provides rejeita da mesma forma qualquer referência from: a ele; simplesmente não há chaves declaradas a listar, pelo que a mensagem termina depois do tipo de componente.
Qual escrever
Declarar o socket no catálogo continua a ser o melhor caminho, e é o que faz o catálogo da biblioteca standard. Um socket declarado transporta um selector que restringe os componentes que a aresta pode alcançar, uma allowlist inject:, um contrato por aresta com os seus próprios valores predefinidos e uma descrição — uma declaração revisível de uma ligação prevista, versionada com a entidade que a estabelece. Um socket ad hoc não transporta 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 ligação que o autor do catálogo não previu, necessária a uma única Release, em que esperar por uma alteração do catálogo significaria esperar para entregar. Deve recorrer-se a ela sabendo o que custa.
Vale a pena enunciar claramente dois custos:
- Um nome de socket mal escrito é um socket ad hoc permitido, não um erro. Escrever
databsesonde se pretendiadatabasesproduz uma compilação verde na qual nada flui pelo socket pretendido. O compilador assinala um nome de socket a uma edição de distância de um declarado com um aviso que nomeia ambas as grafias — ver errors/warnings.md «Uses-socket near-miss lint (Lint de quase correspondência de sockets uses)» — mas é um aviso e nunca altera o veredicto da compilação. - Duas superfícies não estão deliberadamente abertas desta forma. O
usesde um anexo de Feature só pode nomear um socket que a Feature anexada declara, e ousespor aresta de uma Release só pode nomear um socket que o Component consumidor declara. Um operador configura e liga dentro de uma arquitetura; não a cria. Por isso,release-delivers.yamltransportainfra:e nada sobre sockets — o socketassistanté do autor do Aggregate, e só dele.
Para o contrato completo, ver entities/component.md «Topology Sockets: usesSchema (Sockets de topologia)» e architecture/07-dependency-resolution.md.