Перейти к содержимому
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" } и передаёт её операционному Recipe. Никакой физический секрет не извлекается.
  3. Вывод Plugin (домен 3): конвейер Wasm сущности FeatureRecipe для учётных данных генерирует точно согласованные артефакты, необходимые целевой инфраструктуре. Например, в Kubernetes он выводит CRD ExternalSecret (который поручает кластеру получить данные из хранилища) И применяет JSONPatch к целевому Pod, чтобы сопоставить полученный локальный Secret K8s именно с запрошенной разработчиком переменной среды "ORACLE_PASSWORD".
  4. Реальность во время выполнения: во время выполнения оператор в кластере просто исполняет эти сгенерированные артефакты — получает учётные данные и физически монтирует их в контейнер, — полностью отделяя физические механизмы безопасности от AOT-компилятора.

Чтобы доставить эту физическую реальность приложению, не нарушая разделения ответственности, Aggrega использует контракт внедрения. Однако этот контракт строго различает пользовательский код приложений и готовую коммерческую (COTS) инфраструктуру:

  • White-Box (пользовательский код): компонент — универсальный исполнитель (например, пользовательский агент на Python). Компилятор на Go и операционный 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). Операционный Recipe уже точно знает, как система потребляет свои данные. Поэтому сущность каталога Component опускает список разрешённых, что полностью запрещает указание механизмов, а не сужает его: отсутствие spec.inject запрещает самовнедрение на уровне компонента, а сокет, объявленный без списка разрешённых inject:, запрещает любой блок inject: на подключённом через него ребре. Разработчик просто указывает цель зависимости через uses, а платформа сама выполняет внутреннее связывание через valuesMapping сущности Recipe.

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

Правило: операционный Recipe должен экспортировать детерминированный, стабильный указатель адреса. Провайдер не вычисляет IP-адреса. Вместо этого операционному Recipe цели следует сформировать предсказуемую строку и предоставить её через свой контракт provides: (например, публикуя provides.internal_host: "http://agent-b.namespace.svc.cluster.local" в Kubernetes или строку интерполяции вроде "${module.db.endpoint}" в Terraform, где модуль объявляет соответствующий output для этого значения).

Расчёт на то, что компилятор получит динамические IP-адреса после развёртывания, прямо нарушает модель выполнения AOT. Поскольку компилятор вычисляет топологию до того, как облако создаст реальные вычислительные ресурсы, он физически не может получить ещё не существующие данные. Если сервису нужен случайный IP-адрес, который генерируется только после запуска вычислительного ресурса, компилятор физически не может его получить. Единственная задача компилятора — дословно передать детерминированную строку-указатель, предоставленную операционным Recipe, в переменные среды вызывающего контейнера, оставив окончательное разрешение DNS кластера или активному менеджеру состояния IaC.

Принудительная детерминированная адресация естественным образом решает проблему циклических зависимостей (например, агент A делегирует агенту B, а агент B делегирует обратно агенту 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"]), разработчик может использовать самовнедрение на уровне компонента с этими механизмами доставки. Если spec.inject опущено, компилятор структурно запрещает самовнедрение — компоненты Black-Box полностью полагаются на valuesMapping сущности Recipe для внутреннего связывания. Сборка обеспечивает это при разрешении Aggregate, отклоняя блок inject: компонента и называя механизм; это отличается от проверки содержимого каждого раздела в schema:.
  3. Карта featuresSchema: определённая в каталоге Component, она явно объявляет слоты учётных данных, которые разработчик должен (или может) использовать. Каждая запись задаёт required (по умолчанию false), список разрешённых inject ([] = black-box, [env, file] = прозрачный) и description. Поскольку эти ключи стабильны и гарантированы контрактом, операционный инженер может напрямую опираться на них, чтобы надёжно задавать детерминированные цели в своём шаблоне Go (например, existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}" для цели helm), явно экспортируя суффикс имени через .locals — локальная переменная не может читать .context.rendered_name, — чтобы нижестоящая сущность FeatureRecipe для учётных данных объединила те же две части и выполнила требование, не нарушая порядок выполнения AOT. Полное описание featuresSchema см. в entities/component.md.

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

  1. Самовнедрение на уровне компонента: как прямой соседний элемент values: в экземпляре компонента. Внедряет собственные литеральные значения компонента или его собственные ключи provides в канал доставки. Допускается, только если каталог сущности Component объявляет spec.inject с соответствующими механизмами.
  2. Перекрёстное внедрение на уровне uses: внутри явных определений целей в блоке uses:. Внедряет ключи provides цели зависимости в канал доставки.
  3. Инъекция на уровне Feature/Secret: как соседний элемент values: при подключении сущностей Feature и секретов. Внедряет в канал доставки собственные разрешённые ключи provides подключения — разрешённые учётные данные для секрета или предоставляемые значения для features.

Все три формы заполняют один и тот же канал .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; для самовнедрения используйте 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 один раз читается как шаблон для интерполяции параметров ещё до разрешения самовнедрения, и .values в этот момент не существует, поэтому экранирование возвращает {{ на место, чтобы его вычислило разрешение самовнедрения. См. Текст, содержащий собственные двойные фигурные скобки.

Примечание для Provider (compose). Когда рёбра uses: разрешаются между узлами с целевой платформой compose, Provider 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: предварительно разрешённый плоский словарь, в котором компилятор уже разрешил все источники внедрения (литералы самовнедрения, ссылки самовнедрения на provides и межкомпонентные ссылки на provides) в итоговые строковые значения, а затем применил перехваты injectMapping сущностей FeatureRecipe.

Двухсостоянный контекст внедрения (защита от null против чистоты намерения) При генерации конфигураций для модификаторов (FeatureRecipe, привязанной к любому подключению, учётным данным или иному) компилятор должен соблюдать баланс между защитой от нулевых указателей в шаблонах Go, динамической сетевой маршрутизацией и сохранением графа, агностичного по отношению к возможностям. Для этого компилятор предоставляет шаблону двухсостоянный контекст:

  • .inject_raw (неизменяемое намерение): представляет собственный блок inject: компонента в точности так, как разработчик написал его в домене 1. Оно неизменяемо. Если разработчик опустил блок, оно принимает значение null. Ops используют его именно для логических проверок (например, {{ if not .inject_raw }} для применения резервного поведения). Поскольку оно неизменяемо, оно защищает шаблоны Ops от ложных срабатываний, если маршрутизирующие features перехватывают и изменяют физический канал доставки.
  • .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-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
  • Реальность эксплуатации: имя хоста — это имя компонента в данном окружении, поэтому оператор указывает его, api.enterprise.com, в infra этого вложения в записи Release для компонента. Wasm-плагин сущности Feature получает разрешённый публичный URL через контракт внедрения и выдаёт JSONPatch, динамически дополняющий массив Kubernetes args: ["/app/binary", "--callback-url=https://api.enterprise.com"], полностью минуя базовый Recipe сущности Component.