Опублікована обгортка, яку обслуговує 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: обгортки й закріплює базу у файлі блокування незалежно від того, чи називає її сутність 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:, відхиляється під час завантаження документа із зазначенням обмеження. Так само відхиляється той, що взагалі пропускаєschema:.schema: inherited— єдина прийнятна форма, і її пишуть явно, а не мають на увазі, щоб читач ніколи не сплутав успадкований блок стовпів із забутим. - Ключ
values, який база не оголошує, відхиляється в екземплярі обгортки за написаним шляхом, бо контракт, що застосовується, належить базі.
Чому це корисно
Організації, яка вже визначилася з перевіреною формою компонента стандартної бібліотеки, потрібно десь її зберігати. Якщо описати її текстом, мітки, анотації й сокети доводиться повторювати в кожній сутності Aggregate, якій вони потрібні, і вони поступово розходяться. Опублікована як Component, що розширює базу, ця форма стає версіонованою сутністю каталогу з назвою, яку можна рецензувати: команда, що її використовує, пише
type: example/gateway/nginx-reviewed і один рядок у Manifest та успадковує весь контракт бази разом із кожним Recipe, уже написаним для неї, на кожній цілі, яку підтримує база.
Саме ціна обгортки забезпечує це: вона додає структуру й метадані і нічого більше. Оскільки вона не оголошує стовпів, екземпляр обгортки й екземпляр бази перевіряються за одним контрактом, і Recipe, написаний для бази, ніколи не зіткнеться з несподіванкою від її спеціалізації.