Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

provides, inject, uses

Контракт ін’єкції та попередньо розв’язана мапа

Оскільки Aggrega є статичним компілятором Ahead-of-Time (AOT), під час компіляції жодні дані не надходять назад із робочої інфраструктури. Компілятор механічно не може активно отримати фізичні облікові дані (наприклад, секрет AWS) і передати їх «назад» у середовище контейнера розробника.

Натомість платформа спирається на справжню інверсію керування. Коли розробник пише inject: { env: [{ in: ORACLE_PASSWORD, from: "password" }] }, він не ініціює отримання даних; він диктує інфраструктурі строгий контракт.

  1. Намір (домен 1): розробник оголошує абстрактний інтерфейс: «Мені потрібен секрет. Я не знаю, де він зберігається. Просто впровадьте його в моє середовище як ORACLE_PASSWORD, зіставивши з ключем каталогу password.»
  2. Передача компілятором (під час рендерингу): компілятор Go бере запис { in: ORACLE_PASSWORD, from: "password" } і передає його Ops Recipe. Жоден фізичний секрет не отримується.
  3. Вихід Plugin (домен 3): конвеєр Wasm сутності FeatureRecipe для облікових даних генерує точні взаємопов’язані артефакти, потрібні цільовій інфраструктурі. Наприклад, у Kubernetes він виводить CRD ExternalSecret (що вказує кластеру отримати дані зі сховища) І виконує JSONPatch для цільового Pod, щоб зіставити отриманий локальний K8s Secret саме зі змінною середовища "ORACLE_PASSWORD", яку запитав розробник.
  4. Реальність під час виконання: під час виконання оператор у кластері просто виконує ці згенеровані артефакти — отримує облікові дані й фізично монтує їх у контейнер, — повністю відокремлюючи фізичну механіку безпеки від AOT-компілятора.

Щоб доставити цю фізичну реальність до застосунку, не порушуючи розділення відповідальності, Aggrega використовує контракт ін’єкції. Проте цей контракт чітко розрізняє власний код застосунку та готову комерційну (COTS) інфраструктуру:

  • White-Box (власний код): компонент є універсальним виконавцем (наприклад, власним агентом на Python). Компілятор Go і Ops Recipe не мають уявлення, яких змінних очікує власний скрипт розробника. Тому скрізь, де код читає імена, яких його Recipe не доставляє за замовчуванням, розробник задає доставку через блок inject: — як для залежностей між компонентами (через uses[].inject з from:, що посилається на provides цілі), так і для власних значень компонента (через inject на рівні компонента з літералами value: або from:, що посилається на його власні provides). Дозволені механізми оголошуються для кожної поверхні окремо, і ці два оголошення незалежні: власні значення компонента регулює список дозволених spec.inject (наприклад, inject: ["env", "file"]), а ребро uses: регулює список дозволених на сокеті, через який його під’єднано, — spec.usesSchema.<socket>.inject. Якщо задати механізм, якого не названо у відповідному списку дозволених, збірка зупиняється на будь-якій із поверхонь.
  • Black-Box (пакетні обчислення): компонент є закритою системою (наприклад, Redis, керований API Gateway). Ops Recipe уже точно знає, як система споживає свої дані. Тому сутність каталогу Component пропускає список дозволених, що повністю забороняє диктування, а не звужує його: пропуск spec.inject забороняє self-inject на рівні компонента, а сокет, оголошений без списку дозволених inject:, забороняє будь-який блок inject: на ребрі, під’єднаному через нього. Розробник просто вказує ціль залежності через uses, а платформа нативно виконує внутрішнє з’єднання через valuesMapping сутності Recipe.

Правило детермінованої адресації (фізика внутрішньої мережі) Конвеєр .context.uses в Aggrega динамічно впроваджує цільові рядки в контейнери під час компіляції. Оскільки ядро компілятора Go повністю агностичне щодо фізичної мережі, те, що вважається допустимим рядком адреси, повністю залежить від суспільного договору, якого дотримується Platform Ops, а не від функції компілятора: компілятор без інтерпретації передає в контекст подальшого шаблону будь-який детермінований рядок-вказівник, який створив Ops Recipe.

Правило: Ops Recipe має експортувати детермінований, стабільний вказівник адреси. Provider не обчислює IP-адреси. Натомість Ops Recipe цілі має сформувати передбачуваний рядок і відкрити його через свій контракт provides: (наприклад, опублікувавши provides.internal_host: "http://agent-b.namespace.svc.cluster.local" у Kubernetes або рядок інтерполяції на кшталт "${module.db.endpoint}" у Terraform, де модуль оголошує відповідний output для значення).

Покладатися на те, що компілятор отримає динамічні IP-адреси після розгортання, — пряме порушення моделі виконання AOT. Оскільки компілятор обчислює топологію до того, як хмара розгорне будь-які реальні обчислювальні ресурси, він фізично не може отримати дані, яких ще не існує. Якщо сервісу потрібна випадкова IP-адреса, що генерується лише після запуску обчислювальних ресурсів, компілятор фізично не може її отримати. Єдине завдання компілятора — дослівно передати детермінований рядок-вказівник, наданий Ops Recipe, у змінні середовища контейнера, що викликає, залишаючи остаточне розв’язання DNS кластера або активному менеджеру стану IaC.

Застосування детермінованої адресації нативно розв’язує проблему циклічних залежностей (наприклад, Agent A делегує Agent B, а Agent B делегує назад Agent A). Оскільки стабільну URL-адресу або вказівник IaC можна обчислити як рядок ще до запуску будь-якого з контейнерів, компілятор безпечно з’єднує обох агентів, не створюючи часових станів гонитви.

(Примітка: це правило стосується й зовнішнього вхідного трафіку. Якщо архітектура відкриває публічний API Gateway і потребує, щоб цю URL-адресу було впроваджено назад у внутрішній контейнер, компілятор Go не може отримати випадкову URL-адресу, згенеровану хмарою (наприклад, xyz123.execute-api.aws.com), бо її не існує під час компіляції. Ops мають написати свій Recipe так, щоб або зіставити детермінований власний домен (наприклад, api.enterprise.com), або експортувати нативний рядок інтерполяції IaC, щоб AOT-компілятор мав відоме посилання для безпечного впровадження).

Механіка реалізації (каталог як контракт API) Щоб реалізувати це без тісного зв’язування розробників з Ops, Aggrega використовує каталог платформи (домен 2) як строгий контракт API із трьома окремими рівнями валідації:

  1. Схема Feature для облікових даних (з міткою feature.aggrega.ai/kind: secret): валідує ЛИШЕ запит до сховища (path, key). Вона повністю агностична щодо того, як контейнер споживає дані.
  2. Схема Component (список дозволених spec.inject): застосовує правило Black-Box/White-Box через поле spec.inject. Якщо spec.inject присутнє (наприклад, inject: ["env", "file"]), розробник може використовувати self-inject на рівні компонента з цими механізмами доставки. Якщо spec.inject пропущено, компілятор структурно забороняє self-inject: компоненти Black-Box для внутрішнього з’єднання повністю покладаються на valuesMapping сутності Recipe. Збірка забезпечує це під час розв’язання Aggregate, відхиляючи блок inject: компонента й називаючи механізм; це відрізняється від валідації вмісту кожного стовпа в schema:.
  3. Мапа featuresSchema: визначена в каталозі Component, вона явно оголошує слоти облікових даних, які розробник мусить (або може) використовувати. Кожен запис задає required (типово false), список дозволених inject ([] = blackbox, [env, file] = прозорий) і description. Оскільки ці ключі стабільні й гарантовані контрактом, Ops-інженер може напряму покладатися на них, щоб надійно задавати детерміновані цілі у своєму шаблоні Go (наприклад, existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}" для цілі helm), явно експортуючи суфікс імені через .locals — локальна змінна не може читати .context.rendered_name, — тож подальша FeatureRecipe для облікових даних поєднує ті самі дві частини й виконує вимогу, не порушуючи порядку виконання AOT. Повний дизайн featuresSchema див. у entities/component.md.

Правило строгого розміщення: механізм inject: доступний у трьох місцях сутності Aggregate розробника:

  1. Self-inject на рівні компонента: як безпосередній сусід values: в екземплярі компонента. Ін’єктує у канал доставки власні літеральні значення компонента або його власні ключі provides. Дозволено лише тоді, коли каталог Component оголошує spec.inject з відповідними механізмами.
  2. Cross-inject на рівні uses: усередині явних визначень цілей у блоці uses:. Ін’єктує у канал доставки ключі provides цілі залежності.
  3. Inject на рівні Feature/Secret: як сусід values: під час приєднання функцій і секретів. Ін’єктує у канал доставки власні розв’язані ключі provides приєднання — розв’язані облікові дані для секрету або надані значення функції.

Усі три форми заповнюють той самий канал .context.inject. Recipe читає єдиний уніфікований канал, хоч скільки джерел зробили до нього внесок.

Схема inject визначає стандартні переліки (env, file, arg) для інструментів, але залишає additionalProperties відкритим, тож можна назвати власний механізм (наприклад, ssm_param для AWS Systems Manager Parameter Store). Одна назва зайнята: all — це об’єднане подання всіх механізмів, які Recipe читає в .context.inject.all, тож блок inject, що називає механізм all, зупиняє збірку на рівні конверта документа й повідомляє про це.

Синтаксис запису inject: у блоці inject кожен механізм доставки — env, file, arg або власний — є списком записів, і в кожному розміщенні використовується та сама форма запису. Що означає рядок запису, визначає ключове слово, яке несе запис, а не розміщення, у якому він стоїть, тож запис читається однаково, хоч би де він з’явився. Механізм, записаний як мапа замість списку, або запис, що несе обидва ключові слова, зупиняє збирання на етапі оболонки документа Aggregate з зазначенням шляху в Aggregate, де форма неправильна.

Ключові слова запису (from: і value:): кожен запис використовує ключове слово in для локального ідентифікатора — імені змінної середовища, шляху до файлу, прапорця аргументу — плюс рівно одне з from: (посилання на ключ provides) або value: (літеральний рядок). from: розв’язується щодо provides вузла, який називає його розміщення: власних ключів компонента в component.inject, ключів цілі в uses[target].inject і власних ключів вкладення в features[<name>].inject:

Ключове словоЗначенняДозволено в component.injectДозволено в uses[].injectДозволено в features[<name>].inject
from:Розв’язання відносно provides✅ Provides власного вузла✅ Provides цільового вузла✅ Власні provides приєднання
value:Літеральний рядок (підтримує шаблони Go)✅❌ (value: недійсне в uses[].inject; для self-inject використовуйте inject на рівні компонента)❌ (value: зупиняє збірку в inject приєднання; для self-inject використовуйте inject на рівні компонента)

Приклади:

# Component-level self-inject (White-Box custom code)
components:
my-worker:
type: core/python-worker:1.0.0
values:
app_token: "xyz"
inject:
env:
- in: MY_TOKEN
value: "xyz" # Literal value
- in: LOG_LEVEL
value: "debug" # Literal value
- in: CALLBACK_HOST
from: "host" # From own provides (already evaluated)
- in: APP_VERSION
value: '{{"{{"}} .values.app_token }}' # Go template expanding own values
uses:
databases:
my_db:
target: postgres-db
inject:
env:
- in: DB_HOST
from: "host" # Provides key from target
- in: DB_PORT
from: "port" # Provides key from target
- in: DB_URL
from: "dsn" # From target's provides

Шаблон у value: для APP_VERSION починається з {{"{{"}}, а не з {{: увесь текст Aggregate один раз читається як шаблон для інтерполяції параметрів ще до розв’язання self-inject, а .values на цей момент не існує, тож екранування повертає {{ на місце, щоб його обчислило розв’язання self-inject. Див. Текст, що містить власні подвійні фігурні дужки.

Примітка щодо Provider (compose). Коли ребра uses: розв’язуються між вузлами з ціллю compose, провайдер compose виводить записи depends_on із цих ребер. Ці записи завжди використовують семантику service_started незалежно від блоку health: будь-якої цілі; прив’язку їх до стану здоров’я цілі не реалізовано. Повні правила виведення див. у providers/compose.md.

Правило колізії ключів inject: Запит розробника на той самий ключ доставки (наприклад, ту саму назву змінної середовища) з двох різних джерел є фатальною помилкою, а не злиттям. Компілятор виявляє колізію та зупиняє збирання:

Джерело AДжерело BРезультат
component.injectuses[].inject❌ фатальна зупинка — дубльований ключ доставки
uses[target_A].injectuses[target_B].inject❌ фатальна зупинка — дубльований ключ доставки
component.injectfeatures[<name>].inject❌ фатальна зупинка — дубльований ключ доставки
uses[].injectfeatures[<name>].inject❌ фатальна зупинка — дубльований ключ доставки
features[A].injectfeatures[B].inject❌ фатальна зупинка — дубльований ключ доставки
component.inject (той самий ключ двічі)—❌ фатальна зупинка — дубльований ключ доставки
injectMapping сутності FeatureRecipe для features[A]injectMapping сутності FeatureRecipe для features[B]❌ фатальна зупинка — дубльований ключ доставки у двох приєднаннях
features[A].injectinjectMapping сутності FeatureRecipe для features[B]❌ фатальна зупинка — дубльований ключ доставки у двох приєднаннях
component.inject або uses[].injectinjectMapping сутності FeatureRecipe✅ Дозволено — перехоплення за задумом: значення мапінгу замінює цей запис

Таблиця однаково трактує кожну приєднану сутність Feature, де б її не було приєднано — до компонента, на межі підсистеми чи сутності Release, через розгортання анотації або до з’єднання. injectMapping сутності FeatureRecipe рендериться після того, як кожен блок inject: виконав доставку, тому вона завжди є пізнішою з двох заявок: вона може переписати те, що доставив компонент або одне з його з’єднань, і може переписати те, що доставив блок inject: її власного приєднання, але ключ, який уже доставила інша приєднана сутність Feature, зупиняє збирання з зазначенням обох.

Сутність Feature, приєднана до межі сутності Release, чия сутність FeatureRecipe рендериться один раз для межі (executionScope: boundary), досягає компонентів, що містить межа, тим самим шляхом: її injectMapping виконується один раз для кожного з них, у контексті цього компонента, і підлягає рядкам таблиці вище, як і будь-який інший мапінг. Міст compose, що переписує змінну хоста споживача, щоб той досягав своєї цілі через її шлюз, — один із таких мапінгів, тож інша приєднана сутність Feature, яка доставила ту саму змінну, зупиняє збирання з зазначенням обох.

Щоб уникнути шаблонного коду Go в сутностях Recipes, компілятор надає обидва:

  • .context.uses: збагачена мапа топологічних ребер (для складної логіки, посилань на секрети та відстеження походження).
  • .context.inject: попередньо розв’язаний плаский словник, у якому компілятор уже розв’язав усі джерела inject (літерали self-inject, посилання self-inject на provides і міжкомпонентні посилання на provides) у кінцеві рядкові значення, а потім застосував перехоплення injectMapping сутностей FeatureRecipe.

Двостановий контекст ін’єкції (null-безпека проти чистоти наміру) Генеруючи конфігурації для модифікаторів (сутності FeatureRecipe, прив’язаної до будь-якого приєднання, облікових даних чи іншого), компілятор має збалансувати безпеку щодо null-вказівників для шаблонів Go, динамічну мережеву маршрутизацію та збереження графа, агностичного щодо можливостей. Для цього компілятор надає шаблону двостановий контекст:

  • .inject_raw (незмінний намір): представляє власний блок inject: компонента точно так, як розробник написав його в домені 1. Він незмінний. Якщо розробник пропустив блок, це значення дорівнює null. Ops використовує його саме для логічних перевірок (наприклад, {{ if not .inject_raw }} для застосування резервної поведінки). Оскільки він незмінний, він захищає шаблони Ops від хибнопозитивних результатів, якщо функції маршрутизації перехоплюють і змінюють фізичний канал доставки.
  • .context.inject (попередньо наповнений і перехоплений канал): паралельна, згенерована компілятором структура, що представляє фізичну реальність доставки. Вона починається як попередньо наповнена мапа (наприклад, що зіставляє API_HOST з базовим рядком цілі "backend-instance"). Важливо, що цей канал призначений для перехоплення та глибокого злиття сутностями Features (наприклад, мережевою маршрутизацією) за допомогою блоку injectMapping. На момент рендерингу базової сутності Recipe цей канал містить повністю відформатовані, фізично правильні рядки (наприклад, правильну повну мережеву назву на кшталт "backend-instance.backend-zone.svc.cluster.local"). Його вміст структуровано як env, file, arg (плюс будь-які власні механізми доставки, дозволені списками дозволених inject сутності Component), із попередньо злитим словником .all, що поєднує всі механізми для зручної серіалізації всього каналу.
  • .context.self_inject (Яке власне значення доставляє кожна назва): Зчитується з того самого блоку inject: на рівні компонента, що й .inject_raw, у тій формі, у якій .context.uses.<alias>.inject подає назви з’єднання: для кожного механізму кожна назва, яку написав розробник, зіставляється з власним ключем компонента, який доставляє її запис, — provides.<key> для запису from:, values.<key> для шаблону value:, який зчитує рівно одне з власних значень компонента й нічого більше, і порожній рядок для будь-чого іншого (літерал, два значення, зчитування чогось, окрім значень). Це дає змогу сутності Recipe, що запускає власний образ розробника, розглядати власні назви змінних як типові — доставляючи власне значення під його типовою назвою лише тоді, коли жоден запис ще не зіставлений із values.<key>, тож розробник, який перейменовує одне значення, зберігає всі інші типові значення. Це домовленість каталогу стандартної бібліотеки, а не правило компілятора; корпоративний каталог може доставляти власні значення своїх компонентів будь-яким обраним способом.

Ops використовує структуру .context.inject виключно для безпечної серіалізації (наприклад, {{ toJson .context.inject.all }}) і генерування маршрутизації, забезпечуючи, що фізична інфраструктура отримує повністю розв’язані координати, тоді як початковий намір розробника залишається повністю незмінним у .inject_raw.

Приклад YAML розробника (деталізована мапа):

uses:
databases:
my-postgres-cluster:
target: db-main
inject:
ssm_param: # Agnostic injection paradigm (AWS Systems Manager)
- in: MY_DB_HOST # Local identifier
from: "host" # Target provides key

Компілятор розв’язує це під час компіляції (зіставляючи зі статичними рядками або внутрішніми DNS-назвами) і передає два об’єкти до сутності Recipe:

"context": {
"uses": { ... raw graph ... },
"inject": {
"all": { "MY_DB_HOST": "db-main.internal" },
"ssm_param": { "MY_DB_HOST": "db-main.internal" }
}
}

Конфігурація в межах з’єднання (values та infra). Окрім доставлення ключів provides цілі через inject, ребро може нести власну конфігурацію — налаштування окремого з’єднання, які споживацький Recipe читає з розширеного топологічного каналу:

  • .context.uses.<alias>.values — створюється розробником, оголошується в розгорнутому записі uses сутності Aggregate, перевіряється за valueSchema сокета.
  • .context.uses.<alias>.infra — створюється оператором, оголошується в сутності Release, перевіряється за infraSchema сокета.

Сокет (usesSchema[<socket>]) — це контракт архітектора щодо того, які з’єднання можливі та яку конфігурацію вони можуть нести; values та infra розділяють цю конфігурацію за доменом авторства, так само як розділення values/infra у компонентів. Отже, ребро має двох авторів: розробник з’єднує топологію та налаштовує її за допомогою values в сутності Aggregate, а оператор задає infra для окремого з’єднання в сутності Release у межах сокетів, оголошених архітектором. Release також може під’єднати ребро в оголошеному, але не прив’язаному сокеті до наявного компонента; змінювати ціль ребра, оголошеного розробником, він не може — див. entities/release.md §«Per-edge connection configuration».

Конфігурація окремого ребра обмежена споживачем: вона з’являється лише в контексті вузла, який створив ребро (джерела з’єднання), і ніколи — в контексті цілі. Тому власний відрендерений результат цілі не залежить від споживачів, що до неї під’єднуються. Feature, приєднана до цілі, — єдине місце, де з’єднання видно: її FeatureRecipe читає, які компоненти використовують ціль, у .context.used_by — ідентичність кожного, сокет, опубліковані provides, простір імен і межу, у яких він розміщений, а для FeatureRecipe, яка оголошує, що читає їх, — факти рендерингу, повідомлені його провайдерами; але ніколи не власні values чи infra з’єднання. Feature, приєднана до споживача, так само читає, що повідомили рендери кожної з його цілей, у записі цього з’єднання в .context.uses.<alias>.render_facts, якщо її FeatureRecipe оголошує, що читає їх.

Приєднання з’єднання (features). З’єднання також може нести власні приєднання — наприклад, облікові дані, які споживач пред’являє компоненту, до якого веде це з’єднання, — у features: свого запису, з ключем за слотом, який сокет оголошує у своїй featuresSchema. Ті самі два автори розділяють їх: розробник приєднує в записі з’єднання сутності Aggregate за допомогою type та values, а оператор задає розміри цього приєднання за допомогою infra або приєднує власне за допомогою type та infra у записі сутності Release. Приєднання на з’єднанні не несе власного блоку inject, тому його немає в наведеному вище правилі розміщення: це не одне з місць, де розробник визначає доставлення.

Кожне стає приєднанням споживацького компонента з назвою <alias>.<slot>, тож воно обмежене споживачем так само, як конфігурація окремого ребра: його FeatureRecipe рендериться на боці споживача, і результат цілі від нього не змінюється. Воно не потрапляє до .features споживацького Recipe, що містить лише приєднання, оголошені власним блоком компонента; натомість Recipe читає його в межах свого з’єднання, у .context.uses.<alias>.features.<slot>. З’єднання, створене приєднанням Feature, не несе приєднань. Див. entities/aggregate.md §«A connection’s own attachments» та entities/component.md §«Topology Sockets».

A. Змінні середовища (env) і динамічне визначення призначення Стандартний механізм доставлення для сучасних хмарно-нативних застосунків. Для явних топологічних ребер (наприклад, агент, що звертається до бази даних) Aggrega використовує .context.uses, щоб впровадити зіставлення змінних середовища.

  • Сценарій використання: отримання детермінованих внутрішніх DNS-імен, рядків інтерполяції Infrastructure-as-Code (наприклад, ${module.db.endpoint}) або статичних вказівників Vault. Компілятор зв’язує ці статичні посилання AOT, щоб інфраструктура під час виконання або контролер GitOps могли визначити актуальні значення.

B. Монтування файлів (file) Багато корпоративних AI-фреймворків очікують, що структурований config.json або сертифікат .pem існуватиме за певним шляхом на диску, а не покладаються на змінні середовища.

  • Сценарій використання: впровадження складних JSON-конфігурацій або підтримка застарілих SDK, які читають із диска.

  • Намір розробника:

    features:
    openai_key:
    type: core/aws-secrets-manager
    values:
    path: /prod/ai/openai
    key: "api_token"
    inject:
    file:
    - in: "/etc/secrets/openai.json" # Local path
    from: "api_token" # The attachment's provides key
  • Реальність Ops: Ops Recipe динамічно генерує Kubernetes Volume, VolumeMount та ExternalSecret, потрібні для безпечного отримання даних зі сховища та монтування їх у /etc/secrets/openai.json.

C. Аргументи командного рядка (arg) Попередньо скомпільовані бінарні файли (як-от робочі вузли на Rust чи Go) часто повністю оминають змінні середовища й очікують, що значення передаватимуться як прапорці під час виконання в їхній команді запуску.

  • Сценарій використання: додавання фізичних реалій до команди запуску контейнера.

  • Намір розробника:

    features:
    public-ingress:
    type: core/external-ingress
    inject:
    arg:
    - in: "--callback-url=" # Local flag
    from: "hostname" # The attachment's provides key
  • Реальність Ops: ім’я хоста — це назва компонента в середовищі, тому оператор записує його, api.enterprise.com, в infra цього приєднання в записі сутності Release для компонента. Wasm-плагін Feature отримує визначену публічну URL-адресу через контракт впровадження та генерує JSONPatch, щоб динамічно доповнити масив Kubernetes args: ["/app/binary", "--callback-url=https://api.enterprise.com"], повністю оминаючи базовий Recipe сутності Component.