Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Опубликованная обёртка, обслуживаемая 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.com
spec:
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; запись базы она не наследует. Экземпляр обёртки без собственной записи останавливается с диагностикой несопоставленного экземпляра, даже если его база сопоставлена.

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

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

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

Terminal window
aggrega scaffold --example extends-wrapper

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

Terminal window
cd extends-wrapper

Сборка

Terminal window
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 вместо обёртки, — и он должен завершиться ошибкой:

Terminal window
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, написанный для базы, никогда не будет застигнут врасплох её специализацией.