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 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ânciatipoo que é
dbcore/datastore/mariadba base de dados
modelcore/ai-model/anthropicum endpoint de modelo; uma realização em forma de referência, pelo que não é executada nenhuma computação para ele
webcore/devtool/adminera 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: 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 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:

Terminal window
aggrega scaffold --example adhoc-uses-socket

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

Terminal window
cd adhoc-uses-socket

Compilação

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 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: db chegou através de databases, o socket declarado. O seu valor é o provides.host da Recipe da base de dados — um nome de serviço do Compose.
  • ASSISTANT_ENDPOINT e ASSISTANT_MODEL chegaram através de assistant, o socket ad hoc, transportando o provides.endpoint e o provides.model da 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_key

core/ai-model/anthropic declara endpoint e model no seu pilar provides, e nada mais. A compilação deverá 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 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 databses onde se pretendia databases produz 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 uses de um anexo de Feature só pode nomear um socket que a Feature anexada 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; não a cria. Por isso, release-delivers.yaml transporta infra: e nada sobre sockets — o socket assistant é 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.