콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

아무도 선언하지 않은 소켓이 실제 값을 전달하는 예

이 예제는 한 문장과 그 두 부분을 모두 가르칩니다.

소비자는 연결을 새로 만들 수 있습니다. 그러나 생산자가 선언한 것만 소비할 수 있습니다.

Aggregate 작성자가 자신의 컴포넌트에 어떤 카탈로그 엔티티도 선언하지 않은 소켓 이름으로 uses: 항목을 작성합니다. 엣지가 만들어지고 값을 전달합니다. 값은 선언된 소켓을 통할 때와 똑같이 렌더링된 아티팩트에 도달합니다. 그러나 그 엣지가 전달할 수 있는 키는 여전히 대상이 선언합니다. 대상이 선언하지 않은 키를 지정하면 빌드가 중단됩니다.

여기의 모든 것은 표준 라이브러리 카탈로그에서 해석됩니다. 워크스페이스는 자체 Component, Feature, Recipe를 작성하지 않습니다.

스택

컴포넌트는 세 개이며, 그중 하나는 두 가지 방식으로 연결됩니다.

인스턴스타입설명
dbcore/datastore/mariadb데이터베이스
modelcore/ai-model/anthropic모델 엔드포인트. 참조 형식의 실현이므로 이를 위한 컴퓨팅은 실행되지 않습니다
webcore/devtool/adminer둘 다 소비하는 콘솔

core/devtool/adminer는 정확히 하나의 소켓을 선언합니다.

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

그것이 작성자가 예상한 전부입니다. 데이터베이스 앞에 놓이는 콘솔은 작성자가 염두에 둔 연결이지만, 환경에 모델 엔드포인트를 담는 콘솔은 그렇지 않습니다.

Aggregate가 작성하는 내용

aggregate-delivers.yaml은 하나의 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는 이 Component에서도, 다른 어떤 컴포넌트에서도 usesSchema에 나타나지 않습니다. 그래도 유효합니다. 카탈로그가 어떤 소켓에 대해 침묵한다는 것은 그 연결이 예상되지 않았다는 뜻일 뿐 금지되었다는 뜻이 아니며, 개발자는 자신의 애플리케이션 토폴로지를 소유합니다.

애드혹 소켓이 포기하는 것은 정확히 누락된 usesSchema 항목이 담았을 내용입니다. selector가 없으므로 엣지가 어떤 컴포넌트에 도달할 수 있는지 제약하는 것이 없고 노드 간 타입 안전성 검사는 평가할 대상이 없습니다. inject: 허용 목록이 없습니다. 엣지별 valueSchema나 infraSchema가 없으므로 엣지별 values:와 infra:는 검사받을 계약도, 상속할 선언된 기본값도 없습니다. 이런 소켓에 작성된 엣지별 구성은 받아들여지고 검사 없이 전달됩니다. 이는 해당 축에 대한 계약이 없는 모든 소켓의 동작 방식이며, valueSchema를 작성하지 않은 선언된 소켓도 같은 처지입니다.

애드혹 소켓이 포기하지 않는 것은 엣지가 전달할 수 있는 내용입니다. endpoint와 model은 모두 core/ai-model/anthropic이 provides 축에 선언한 키입니다.

예제 생성하기

아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.

예제 이름을 딴 새 폴더에 예제를 씁니다:

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

그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:

Terminal window
cd adhoc-uses-socket

빌드

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

렌더링된 출력과 lockfile은 배포되지 않고 생성됩니다. 이 예제는 입력만 커밋하고 나머지는 모두 재생성합니다. --auto-pull은 빌드 중에 lockfile을 해석합니다. 미리 aggrega pull --release release-delivers.yaml을 한 번 실행해도 같은 효과가 있으며 이후 빌드는 플래그 없이 실행할 수 있습니다. 카탈로그 엔티티는 .aggrega-config.yaml이 지정하는 기본 레지스트리인 hub.aggrega.ai에서 해석되므로, 빌드와 aggrega inspect 모두 --catalog 플래그가 필요하지 않습니다.

AI 어시스턴트 사용

Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.

Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 워크스페이스 폴더에 아직 `adhoc-uses-socket` 폴더가 없으면 `example`에 `adhoc-uses-socket`을 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `adhoc-uses-socket` 폴더에 쓰입니다. 그런 다음 `workspace_root`에 `adhoc-uses-socket`, `release`에 `release-delivers.yaml`, `auto_pull`에 true, `write`에 true를 지정하여 `build` 도구를 호출하십시오. 빌드가 어떤 파일을 썼는지 알려 주십시오. 파일은 `adhoc-uses-socket/dist/` 아래에 있습니다.

출력 읽기

dist/compose/docker-compose.yaml의 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]

변수는 네 개이고 그중 세 개가 엣지를 통해 전달되었으며, 출력에는 어떤 소켓이 선언된 것이었는지 기록되지 않습니다.

  • ADMINER_DEFAULT_SERVER: db는 선언된 소켓인 databases를 통해 도착했습니다. 그 값은 데이터베이스 Recipe의 provides.host, 즉 Compose 서비스 이름입니다.
  • ASSISTANT_ENDPOINT와 ASSISTANT_MODEL은 애드혹 소켓인 assistant를 통해 도착했으며, 모델 Recipe의 provides.endpoint와 provides.model을 전달합니다.

이들은 하나의 맵에 작성자 순서대로 놓이며, 서로 간에 표시도, 주석도, 순서 차이도 없습니다. 이것이 핵심입니다. 애드혹 소켓은 선언하는 방식이 다를 뿐, 전달하는 방식이 다르지 않습니다. 전달 경로는 하나이며 두 엣지 모두 그 경로를 따릅니다.

ASSISTANT_ENDPOINT는 AOT(사전) 컴파일의 사실로도 읽어 볼 만합니다. 컴파일러는 https://api.anthropic.com을 알아내기 위해 Anthropic에 접속하지 않았습니다. Recipe가 모델 컴포넌트의 infra.endpoint에서 가져온 결정적 포인터 문자열로 이를 내보냈고, 컴파일러는 그 문자열을 해석하지 않고 라우팅했습니다. Adminer 자체는 두 ASSISTANT_* 변수 중 어느 것도 읽지 않습니다. 개발자가 그 전달 키를 선택했고, 콘솔의 컨테이너는 그 안에서 이를 읽는 무엇이든을 위해 이 변수들을 담습니다.

렌더링된 아티팩트에는 구분이 기록되지 않지만 빌드가 내보내는 그래프에는 기록됩니다. 모든 엣지에는 declared 또는 ad-hoc 값을 갖는 socket_declaration 필드가 있으므로, 모든 연결이 Architect가 선언한 소켓을 거치기를 원하는 조직은 컴파일러가 주관을 갖기를 기대하는 대신 이를 거버넌스 정책으로 표현합니다. architecture/11-governance-and-compliance.md를 참조하십시오.

대조군: 소비자가 여전히 새로 만들 수 없는 것

aggregate-undeclared-key.yaml은 aggregate-delivers.yaml에서 한 곳만 수정한 것입니다. 애드혹 엣지가 세 번째 키를 요청합니다.

- in: ASSISTANT_API_KEY
from: api_key

core/ai-model/anthropic은 provides 축에 endpoint와 model만 선언하고 그 밖에는 아무것도 선언하지 않습니다. 빌드는 실패할 것으로 예상됩니다.

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")

중단 자체가 교훈이며, 중단이 어디서 발생하는지가 주목할 부분입니다. 문제가 된 경로는 애드혹 소켓 uses.assistant를 지정하며, 그 안의 전달 항목이 아니라 연결에서 멈춥니다. from: 키는 모든 엣지에서 대상 Component가 선언한 provides와 대조하여 검사되며, 소켓이 애드혹이라는 사실은 이 검사를 전혀 바꾸지 않습니다. 소켓 이름을 새로 만들 수 있는 작성자라도 다른 사람의 컴포넌트에 출력 키를 새로 만들 수는 없습니다.

거부 문구가 먼저 나오고, 이어서 Aggregate와 엣지가 작성된 경로, 메커니즘과 항목이 작성된 전달 키, 문제가 된 키, 해석 대상이 된 컴포넌트 타입, 그리고 그 타입이 선언한 키가 정렬된 순서로 나옵니다. 따라서 메시지만으로 수정 방법을 알 수 있습니다. provides를 전혀 선언하지 않은 대상 Component도 자신에 대한 모든 from: 참조를 똑같이 거부합니다. 다만 나열할 선언된 키가 없으므로 메시지는 컴포넌트 타입 뒤에서 끝납니다.

어느 쪽을 작성해야 하는가

카탈로그에 소켓을 선언하는 것이 여전히 더 나은 방법이며, 표준 라이브러리 카탈로그도 그렇게 합니다. 선언된 소켓에는 엣지가 도달할 수 있는 컴포넌트를 제약하는 selector, inject: 허용 목록, 자체 기본값을 갖는 엣지별 계약, 그리고 설명이 있습니다. 이는 예상된 연결에 대한 검토 가능한 진술이며, 그 연결을 만드는 엔티티와 함께 버전이 관리됩니다. 애드혹 소켓에는 그중 아무것도 없으며, 엣지의 안전성은 그것을 작성한 작성자의 역량에 달려 있습니다.

애드혹 형식은 탈출구이며, 이 예제가 보여 주는 경우를 위한 것입니다. 즉 카탈로그 작성자가 예상하지 못했고, 하나의 배포에 필요하며, 카탈로그 변경을 기다리는 것이 출시를 기다리는 것을 의미하는 연결입니다. 그 비용을 알고 사용하십시오.

분명히 밝혀 둘 비용이 두 가지 있습니다.

  • 철자가 틀린 소켓 이름은 유효한 애드혹 소켓이며, 오류가 아닙니다. databases를 의도하고 databses라고 쓰면 빌드는 성공하지만 의도한 소켓으로는 아무것도 흐르지 않습니다. 컴파일러는 선언된 소켓 이름과 한 번의 편집 거리 안에 있는 소켓 이름을 두 철자를 모두 명시한 권고로 보고합니다. errors/warnings.md의 “Uses-socket near-miss lint”를 참조하십시오. 그러나 이는 경고일 뿐이며 빌드 결과를 결코 바꾸지 않습니다.
  • 두 표면은 의도적으로 이런 방식으로 열려 있지 않습니다. Feature 첨부의 uses는 첨부된 Feature가 선언한 소켓만 지정할 수 있으며, Release의 엣지별 uses는 소비하는 Component가 선언한 소켓만 지정할 수 있습니다. 운영자는 아키텍처 안에서 구성하고 연결할 뿐, 아키텍처를 작성하지 않습니다. 따라서 release-delivers.yaml은 infra:만 담고 소켓에 관해서는 아무것도 담지 않습니다. assistant 소켓은 Aggregate 작성자의 것이며, 오직 그들만의 것입니다.

전체 계약은 entities/component.md의 “Topology Sockets: usesSchema”와 architecture/07-dependency-resolution.md를 참조하십시오.