Опубликованная обёртка, обслуживаемая Recipe своей базы
Этот пример учит одному: сущность Component, которая расширяет (extends) другую, наследует весь контракт данных этой базы, поэтому каждый Recipe, написанный для базы, уже
реализует расширяющий Component. Поэтому публикация специализированного варианта
компонента стандартной библиотеки стоит одной сущности каталога и одной строки в Manifest
— без собственного Recipe и без изменений в базе.
Обёртка здесь — example/gateway/nginx-reviewed. Она поставляется в каталоге
рядом с core/gateway/nginx, компонентом, который она расширяет.
Что обёртка добавляет и что наследует
Вся написанная автором часть обёртки — это метаданные плюс один сокет:
metadata: name: example/gateway/nginx-reviewed labels: component.aggrega.ai/type: server component.aggrega.ai/category: gateway gateway.example.com/audit-tier: reviewed # added gateway.example.com/data-zone: eu-west # added annotations: governance.example.com/review-board: platform-architecture # added governance.example.com/contact: platform-architecture@example.comspec: extends: core/gateway/nginx:1.0.0 schema: inherited usesSchema: reviewed_upstream: # added selector: "gateway.example.com/audit-tier=reviewed" inject: [env]schema: inherited — буквальный маркер, который расширяющий Component пишет вместо
блока schema:. Он означает, что три столпа данных — values, infra
и provides — принадлежат базе, точно в том виде, в каком их написала база. Обёртка
не объявляет собственных ключей столпов и не может этого сделать: контракт принадлежит базе
на любой глубине цепочки.
Всё, что обёртка не упоминает, она наследует. aggrega inspect example/gateway/nginx-reviewed --resolved показывает объединённую сущность, и две
вещи в ней стоит прочитать внимательно:
- Три сокета
uses, а не один:upstreamиguard(сокеты базы, причёмupstreamвыбираетcomponent.aggrega.ai/type=server) иreviewed_upstream(сокет обёртки). Расширение добавляет сокет, а не заменяет набор. - Три столпа базы дословно —
values.upstream_path,infra.port/engine_version/compute/overridesиprovides.host/port/protocol, каждый с собственными описаниями базы.
Что пишет потребляющий Aggregate
aggregate-reviewed.yaml объявляет два уровня шлюза как обёртку перед
консолью базы данных:
components: edge: type: example/gateway/nginx-reviewed values: upstream_path: /api/ # declared by the base; the wrapper never mentions it uses: reviewed_upstream: # the socket the wrapper ADDS internal: { target: internal, inject: { env: [ ... ] } } internal: type: example/gateway/nginx-reviewed values: upstream_path: / uses: upstream: # the socket the wrapper INHERITS console: { target: console, inject: { env: [ ... ] } } console: type: core/devtool/adminerОбратите внимание на ключ upstream_path. Он объявлен в столпе values компонента core/gateway/nginx
и нигде не встречается в файле обёртки, и всё же автор
пишет его в экземпляре обёртки, и он попадает в отрендеренную конфигурацию
шлюза. Вот что на практике означает наследование столпов целиком.
Manifest — вторая половина, и в нём по одной строке на тип:
mappings: components: type: example/gateway/nginx-reviewed:1.0.0: compose/nginx:1.0.0 core/gateway/nginx:1.0.0: compose/nginx:1.0.0 core/devtool/adminer:1.0.0: compose/adminer:1.0.0Обе строки шлюза называют один и тот же Recipe. compose/nginx объявляет
implements: core/gateway/nginx:1.0.0, а Recipe, называющий базу, является
реализацией для каждого Component, расширяющего эту базу, — поэтому обёртка
обслуживается им без изменений. Здесь одновременно верны два факта, и они независимы:
- Recipe подходит. Recipe, реализующего собственный тип обёртки, не существует, и он не нужен.
- Сопоставление всё равно требуется. Recipe выбирается по точному ключу сопоставления, поэтому
обёртке нужна собственная запись
type; запись базы она не наследует. Экземпляр обёртки без собственной записи останавливается с диагностикой несопоставленного экземпляра, даже если его база сопоставлена.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example extends-wrapperЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd extends-wrapperСборка
aggrega build --release release-reviewed.yaml --auto-pullОтрендеренный вывод и lock-файл генерируются, а не поставляются: этот пример
фиксирует свои входные данные и генерирует всё остальное заново. --auto-pull разрешает
lock-файл во время сборки; однократный запуск aggrega pull --release release-reviewed.yaml
заранее делает то же самое и позволяет последующим сборкам выполняться вовсе без флага.
И обёртка, и расширяемая ею база находятся в общем каталоге, который разрешается из hub.aggrega.ai — реестра по умолчанию, объявленного в .aggrega-config.yaml. Команде сборки не нужен флаг --catalog, как и aggrega inspect, запущенной из этого каталога.
Операция pull загружает core/gateway/nginx, потому что обёртка его расширяет: база является зависимостью всего, что её расширяет, поэтому операция pull следует за extends: обёртки и закрепляет базу в lock-файле независимо от того, называет ли её сущность Manifest. Сущность Manifest здесь сопоставляет базу по другой причине — контрольный выпуск ниже объявляет экземпляр самой базы.
Отрендеренный dist/compose/docker-compose.yaml содержит доказательства:
edge: image: nginx:1.27.5-alpine entrypoint: - /bin/sh - -c - echo 'server { listen 8080; location /api/ { proxy_pass http://internal:8081; } }' > /etc/nginx/conf.d/default.conf && exec nginx -g 'daemon off;' [… omitted: the published port] labels: [… omitted: the other provenance labels every rendered document carries] aggrega.ai/recipe-uri: nginx:1.0.0 [… omitted: the service's network, its depends_on naming internal, and its healthcheck]Три наблюдения, в порядке того, что они доказывают:
aggrega.ai/recipe-uri: nginx:1.0.0— этот сервис сформирован Recipe базы. Метка происхождения на экземпляре обёртки называет Recipe базы, потому что именно этот Recipe его отрендерил.location /api/—values.upstream_path, ключ, который объявляет только база, написан в экземпляре обёртки и отрендерен.proxy_pass http://internal:8081— реброreviewed_upstreamразрешено.provides.hostиprovides.portцели попали в контекст внедрения под ключами доставки, которые читает Recipe базы, поэтому сокет, добавленный обёрткой, проходит через Recipe, который о нём никогда не слышал.
Lock-файл, который разрешает сборка, фиксирует тот же факт со стороны резолвера:
одна запись compose/nginx:1.0.0 с одним дайджестом, на которую ссылаются оба ключа
сопоставления — тип базы и тип обёртки.
Метки и аннотации обёртки передаются вместе с разрешённым ребром: контекст рендеринга
потребляющего узла содержит provides, labels и аннотации каждой цели,
поэтому контекст edge знает, что его upstream — audit-tier=reviewed, и кто его
проверил. Появится ли что-либо из этого в отрендеренном артефакте, решает Recipe —
эти метки и аннотации являются идентичностью компонента, которую читают селекторы и политики,
а не выводом, который проставляет компилятор.
С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочей области ещё нет папки `extends-wrapper`, вызовите инструмент `scaffold` один раз, задав `example` равным `extends-wrapper` и не указывая `dir`: он запишет пример в новую папку `extends-wrapper`. Затем вызовите инструмент `build`, задав `workspace_root` равным `extends-wrapper`, `release` равным `release-reviewed.yaml`, `auto_pull` равным true и `write` равным true. Сообщите мне, какие файлы записала сборка; они находятся в `extends-wrapper/dist/`.Контрольный пример: для чего нужна добавленная метка
aggregate-unreviewed.yaml — это aggregate-reviewed.yaml с одной правкой:
внутренний уровень объявлен как голая база core/gateway/nginx вместо
обёртки, — и он должен завершиться ошибкой:
aggrega build --release release-negative-unreviewed.yaml --auto-pull# [DEVELOPER_ERROR E0007] aggregate-unreviewed.yaml at .spec.components.edge.uses.reviewed_upstream.internal# selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.Остановка и есть урок. База удовлетворяет собственному сокету upstream — она
component.aggrega.ai/type=server, и внутренний уровень подключён через этот
сокет точно так же, — но у неё нет метки audit-tier, поэтому
более строгий сокет обёртки её отвергает. Именно метка, которую добавляет обёртка, делает
её экземпляр выбираемым, и это видно в селекторе.
Стоит знать ещё о двух остановках, и в обоих случаях схема делает свою работу:
- Component, который объявляет
extendsи пишет содержимое столпов вschema:, отклоняется при загрузке документа с указанием ограничения. Так же отклоняется Component, который вовсе опускаетschema:.schema: inherited— единственная допустимая форма, и она пишется явно, а не подразумевается, чтобы читатель никогда не спутал унаследованный блок столпов с забытым. - Ключ
values, который база не объявляет, отклоняется в экземпляре обёртки по пути, где он написан, потому что применяемый контракт принадлежит базе.
Чем это полезно
Организации, остановившейся на проверенной форме компонента стандартной
библиотеки, нужно где-то её хранить. Если хранить её в тексте, метки, аннотации и
сокеты повторяются в каждом Aggregate, которому они нужны, и при этом расходятся.
Если опубликовать её как Component, расширяющий базу, форма становится
версионируемой, проверяемой сущностью каталога с именем: команда, которая её использует, пишет
type: example/gateway/nginx-reviewed и одну строку в Manifest и наследует
весь контракт базы вместе с каждым Recipe, уже написанным для неё, на
каждой цели, которую поддерживает база.
Это работает благодаря цене обёртки: она добавляет структуру и метаданные и ничего больше. Поскольку она не объявляет столпов, экземпляр обёртки и экземпляр базы проверяются по одному контракту, и Recipe, написанный для базы, никогда не будет застигнут врасплох её специализацией.