Перейти к содержимому
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 не встречается ни в одном usesSchema — ни в этой сущности Component, ни в какой-либо другой. Тем не менее это допустимо: молчание каталога о сокете означает, что соединение не было предусмотрено, а не что оно запрещено, и разработчик сам распоряжается топологией своего приложения.

Ad-hoc-сокет теряет ровно то, что несла бы отсутствующая запись usesSchema: нет selector, поэтому ничто не ограничивает, к какому компоненту может вести ребро, и межузловой проверке типобезопасности нечего оценивать; нет списка разрешений inject:; нет valueSchema или infraSchema для отдельного ребра, поэтому у values: и infra: на уровне ребра нет контракта для проверки и нет объявленных значений по умолчанию для наследования. Конфигурация ребра, написанная на таком сокете, принимается и передаётся без проверки — так ведёт себя любой сокет без контракта для этого столпа: объявленный сокет, в котором не задан valueSchema, находится в том же положении.

Чего он не теряет, так это ограничения на то, что может нести ребро. endpoint и model — оба ключа, которые core/ai-model/anthropic объявляет в своём столпе provides.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

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

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd adhoc-uses-socket

Сборка

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

Отрисованный вывод и файл блокировки генерируются, а не поставляются: этот пример фиксирует свои входные данные и генерирует всё остальное заново. --auto-pull разрешает файл блокировки во время сборки; однократный запуск aggrega pull --release release-delivers.yaml заранее делает то же самое и позволяет последующим сборкам выполняться вообще без флага. Сущности каталога разрешаются из hub.aggrega.ai — реестра по умолчанию, который указывает .aggrega-config.yaml, — поэтому ни сборке, ни aggrega inspect не нужен флаг --catalog.

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используйте только инструменты Aggrega и не создавайте папки сами. Если в папке рабочего пространства ещё нет папки `adhoc-uses-socket`, вызовите один раз инструмент `scaffold`, задав для `example` значение `adhoc-uses-socket` и не задавая `dir`: он запишет пример в новую папку `adhoc-uses-socket`. Затем вызовите инструмент `build`, задав для `workspace_root` значение `adhoc-uses-socket`, для `release` — `release-delivers.yaml`, для `auto_pull` — true и для `write` — true. Сообщите мне, какие файлы записала сборка; они находятся в `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, объявленному сокету. Её значение — provides.host сущности Recipe базы данных, имя сервиса Compose.
  • ASSISTANT_ENDPOINT и ASSISTANT_MODEL пришли по assistant, ad-hoc-сокету, неся provides.endpoint и provides.model сущности Recipe модели.

Они находятся в одной карте, в порядке автора, без маркера, без аннотации и без разницы в порядке. В этом и суть: ad-hoc-сокет отличается тем, как его объявляют, а не тем, как он доставляет. Путь доставки один, и оба ребра идут по нему.

ASSISTANT_ENDPOINT стоит рассмотреть и как факт компиляции ahead-of-time. Компилятор не обращался к Anthropic, чтобы узнать https://api.anthropic.com; сущность Recipe выдала его как детерминированную строку-указатель, взятую из infra.endpoint компонента модели, а компилятор передал эту строку, не интерпретируя её. Сам Adminer не читает ни одну из переменных ASSISTANT_* — эти ключи доставки выбрал разработчик, и контейнер консоли несёт их для того, что будет их там читать.

Граф, который выдаёт сборка, фиксирует это различие, хотя отрисованный артефакт его не фиксирует: каждое ребро несёт поле socket_declaration со значением declared или ad-hoc, поэтому организация, которая хочет, чтобы каждое соединение шло через сокет, объявленный её архитекторами, выражает это политикой управления, а не рассчитывает, что у компилятора будет собственное мнение. См. architecture/11-governance-and-compliance.md.

Контрольный случай: что потребитель по-прежнему не может придумать

aggregate-undeclared-key.yaml — это aggregate-delivers.yaml с одной правкой. Ad-hoc-ребро запрашивает третий ключ:

- in: ASSISTANT_API_KEY
from: api_key

core/ai-model/anthropic объявляет endpoint и model в своём столпе provides, и больше ничего. Ожидается, что сборка завершится ошибкой:

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

Остановка и есть урок, и стоит заметить, где она срабатывает: путь-нарушитель указывает на ad-hoc-сокет, uses.assistant, и останавливается на соединении, а не на записи доставки внутри него. Ключ from: проверяется по объявленному provides целевой сущности Component на каждом ребре, и то, что сокет ad-hoc, ничего в этой проверке не меняет. Автор, который может придумать имя сокета, всё равно не может придумать выходной ключ на чужом компоненте.

Сначала идёт отказ, затем сущность Aggregate и путь, по которому было написано ребро, механизм и ключ доставки, под которым написана запись, ошибочный ключ, тип компонента, относительно которого он разрешался, и объявленные ключи этого типа в отсортированном порядке — так что исправление видно из одного сообщения. Целевая сущность Component, которая вообще не объявляет provides, точно так же отклоняет любую ссылку from: на неё; просто объявленных ключей для перечисления нет, поэтому сообщение заканчивается после типа компонента.

Какой вариант писать

Объявление сокета в каталоге остаётся лучшим путём, и именно так поступает каталог стандартной библиотеки. Объявленный сокет несёт selector, ограничивающий, к каким компонентам может вести ребро, список разрешений inject:, контракт для отдельного ребра с собственными значениями по умолчанию и описание — проверяемое заявление о предусмотренном соединении, версионируемое вместе с сущностью, которая его делает. Ad-hoc-сокет ничего этого не несёт, и ребро безопасно лишь настолько, насколько надёжен написавший его автор.

Ad-hoc-форма — это запасной выход для случая, который показывает этот пример: соединение, которое автор каталога не предусмотрел, нужное одному развёртыванию, когда ожидание изменения каталога означало бы ожидание выпуска. Прибегайте к нему, зная, чего он стоит.

Две издержки стоит назвать прямо:

  • Имя сокета с опечаткой — допустимый ad-hoc-сокет, а не ошибка. Если написать databses вместо databases, сборка пройдёт успешно, но по нужному сокету ничего не пойдёт. Компилятор сообщает об имени сокета, отличающемся от объявленного на одну правку, рекомендацией с обоими написаниями — см. errors/warnings.md «Uses-socket near-miss lint» — но это предупреждение, и оно никогда не меняет вердикт сборки.
  • Две поверхности намеренно так не открыты. uses присоединения сущности Feature может указывать только сокет, который объявляет присоединённая сущность Feature, а uses отдельного ребра в сущности Release может указывать только сокет, который объявляет потребляющая сущность Component. Оператор настраивает и связывает внутри архитектуры; он её не создаёт. Поэтому release-delivers.yaml несёт infra: и ничего о сокетах — сокет assistant принадлежит автору сущности Aggregate, и только ему.

Полный контракт см. в entities/component.md «Topology Sockets: usesSchema» и architecture/07-dependency-resolution.md.