Грамматика URI и перечень форматных строк
Сущности Aggrega ссылаются друг на друга через строки URI, которые встречаются в нескольких различных позициях при написании. Одна и та же форма URI (core/postgres:1.0.0) встречается в пяти и более контекстах разных видов сущностей, причём компилятор выводит вид сущности из позиции в схеме, а не из сигила или префикса. Авторам, которые читают или сопровождают YAML-файл, нужно держать в голове правила интерпретации по позиции, чтобы понимать, ссылается ли core/postgres:1.0.0 на тип сущности Component, модуль Aggregate, сущность Recipe, сущность FeatureRecipe или плагин Wasm.
На этой странице сведены воедино грамматика URI во всех позициях, правила приоритета для ключей type: с версией и без версии на уровнях сопоставления сущности Manifest, правила вывода сокращённой записи OCI URI, а также более широкий перечень форматных строк по всей документации (синтаксис шаблонов Go, функции Sprig, объявления JSON Schema 2020-12, JSONPath, шаблоны glob, регулярное выражение SemVer). Авторы, которым нужно узнать, «что Aggrega делает с этой строкой?», должны найти ответ здесь.
Вывод вида сущности по позиции
Одна и та же строка URI обозначает разные виды сущностей в зависимости от того, где она находится в схеме. В таблице ниже перечислены все позиции, в которых Aggrega ожидает URI ссылки на сущность, вместе с выводимым видом сущности:
| Position | Выводимый вид сущности | Раскрытие пути OCI |
|---|---|---|
Aggregate.spec.components.<id>.type | Component | /component/{publisher}/{category}/{name} |
Aggregate.spec.subsystems.<name>.components.<id>.type | Component (как и для components — подсистемы являются группировкой компонентов) | /component/{publisher}/{category}/{name} |
Aggregate.spec.aggregates.<id>.type | Aggregate (модуль вложенного агрегата) | /aggregate/{publisher}/{name} |
Aggregate.spec.components.<id>.features.<id>.type | Feature | /feature/{publisher}/{name} |
Aggregate.spec.components.<id>.features.<id>.type | Feature (учётные данные — с меткой feature.aggrega.ai/kind: secret) | /feature/{publisher}/{name} |
Manifest.spec.mappings.components.type.<key> | Component (URI, используемый как ключ поиска); значение — URI сущности Recipe | ключ: /component/; значение: /recipe/{provider}/{name} |
Manifest.spec.mappings.components.name.<id> | Recipe (точечная привязка переопределения) | /recipe/{provider}/{name} |
Manifest.spec.mappings.features.type.<key> | Feature (ключ поиска); значение — URI сущности FeatureRecipe | ключ: /feature/; значение: /featurerecipe/{provider}/{name} |
Manifest.spec.mappings.features.name.<id> | FeatureRecipe (точечная привязка переопределения) | /featurerecipe/{provider}/{name} |
Manifest.spec.mappings.features.annotations.<key>.feature | Feature (привязка через аннотацию) | /feature/{publisher}/{name} |
Recipe.spec.implements | Component (контракт интерфейса) | /component/{publisher}/{category}/{name} |
FeatureRecipe.spec.implements | Feature (контракт интерфейса) | /feature/{publisher}/{name} |
Component.spec.extends / Feature.spec.extends | Component / Feature (родитель в цепочке наследования) | /component/{publisher}/{category}/{name} или /feature/{publisher}/{name} |
Manifest.spec.extends | Manifest (родитель в цепочке наследования сопоставлений) | не позиция URI — относительный путь или просто metadata.name сущности Manifest, находящейся рядом с Release |
Release.spec.extends | Release (родитель в цепочке наследования) | не позиция URI — относительный путь к файлу Release, и никакая другая форма |
Release.spec.aggregate | Aggregate (цель развёртывания сущности Release) | /aggregate/{publisher}/{name} |
Release.spec.manifest | Manifest (lock-файл сопоставлений сущности Release) | не позиция URI — относительный путь или просто metadata.name сущности Manifest, находящейся рядом с Release |
FeatureRecipe.spec.pipeline.<step>.plugin | Wasm-плагин | /plugin/{pluginType}/{name} |
Три позиции перечислены потому, что авторы ожидают в них URI, но URI там нет. Manifest и Release — это документы стороны развёртывания, создаваемые рядом друг с другом, а не индексируемые в каталоге сущности, поэтому ни extends: одного из них, ни manifest: какой-либо сущности Release не разрешаются по каталогу или реестру. manifest: сущности Release указывает на файл или просто на metadata.name сущности Manifest, находящейся рядом с Release. В двух позициях extends: значение указывает на файл, а координата реестра, записанная в любой из них, отклоняется, и в диагностике называется допустимая форма. Две позиции extends: тоже записываются по-разному: Manifest принимает также просто metadata.name сущности Manifest, находящейся рядом с Release, а Release принимает только относительный путь. Форма для Release описана в entities/release.md, а текст каждого отказа — в errors/fatal-halts.md.
Правило вывода: вид сущности определяется позицией в схеме YAML. Нет никакого внешнего маркера (сигила, префикса, аннотации на уровне схемы), который сообщал бы автору, на какой вид сущности ссылается конкретное поле type:. Авторы держат в уме правила, основанные на позиции, при чтении YAML; инструменты (автодополнение в редакторе, aggrega inspect) используют те же правила, чтобы предлагать подсказки для конкретного вида сущности.
Две формы URI — плагины с производными координатами и сущности каталога с видом в метаданных
URI сущности каталога не содержит символа вида (см. предыдущий раздел). URI сущностей Plugin — намеренная противоположность: URI плагина действительно указывает классифицирующий сегмент — тип сокета — непосредственно в пути. Два семейства ссылок намеренно читаются по-разному, и, зная, к какому семейству относится URI, вы знаете, где искать его классификацию.
Координаты сущностей Plugin выводятся из типа плагина. Ссылка на плагин имеет вид oci://hub.aggrega.ai/plugin/<pluginType>/<name>. Координата выводится: сегмент <pluginType> и простое имя <name> берутся из адресного блока плагина — metadata.pluginType и metadata.name — и составляются в путь. Сокет не кодируется в имени как часть пути; metadata.name — простое имя. Выведенная координата И ЕСТЬ ключ реестра (и встроенного набора плагинов), поэтому реестр упорядочивает плагины по сокетам. Основные плагины разрешаются в координаты вида plugin/provider/helm, plugin/linter/publishing и plugin/parser/yaml — каждая составлена из простого metadata.name (helm, publishing, yaml) и его metadata.pluginType (provider, linter, parser). Сегмент <pluginType> — это в точности тип сокета плагина: то же простое <name> с другим pluginType — это другой плагин, поскольку выведенная координата, а значит, и идентичность, отличается. Полную таксономию сокетов, по которой классифицирует сегмент <pluginType>, см. в entities/plugin.md.
Сущности каталога несут вид в метаданных. Ссылка, которую пишет автор, имеет вид <publisher>/<category>/<name> (например, core/datastore/postgres). Поле kind: сущности находится в файле; вид сущности для URI выводится из позиции в схеме, как описано в разделе Вывод вида сущности по позиции выше. Путь упорядочен по категории, а не по виду: сущность Component содержит сегмент категории (core/datastore/postgres); сущность Recipe или FeatureRecipe содержит свою возможность рендеринга в качестве первого сегмента (helm/postgres); остальные виды имеют плоскую форму <publisher>/<name>. Ничто в пути не указывает вид сущности.
Почему две формы различаются. Сущности Plugins упорядочены в реестре по сокетам, поэтому сегмент сокета — естественный ключ реестра и присутствует в каждом URI плагина. Сущности каталога упорядочены в реестре по категориям, поэтому в пути указывается категория, а не вид. Таким образом, URI сообщает сокет плагина по одному лишь пути, а вид сущности каталога — только после того, как вы прочтёте файл (вид хранится в metadata, а в месте ссылки его задаёт позиция). Эта асимметрия намеренна: путь каждого семейства отражает то, как это семейство упорядочено в реестре, а не единую грамматику, навязанную обоим.
Форма URI — с версией и без версии
Каждая из перечисленных выше позиций URI принимает ссылку в одной из трёх форм: без версии либо с закреплением после двоеточия — точной версией или диапазоном с символом каретки:
| Форма | Пример | Семантика |
|---|---|---|
| Без версии | core/postgres | Разрешается в «любую версию» или в «последнюю зарегистрированную» в зависимости от семантики разрешения позиции |
| Точное закрепление | core/postgres:1.0.0 | Закрепляет одну конкретную версию. Версия — это семантическая версия, в той же форме, что и metadata.version любой сущности |
| Закрепление с кареткой | core/postgres:^1.0.0 | Выбирает наибольшую версию, совместимую с указанной: для ^1.0.0 — не ниже 1.0.0 и ниже 2.0.0 |
Закрепление — это текст после последнего двоеточия ссылки, и только если этот текст не содержит /. Поэтому ссылка на хост реестра с портом — localhost:5000/core/postgres — не содержит закрепления: текст после двоеточия порта продолжает ссылку.
Закрепление, не соответствующее ни одной из этих форм, — каретка, текст которой не читается как диапазон версий (core/postgres:^garbage), или точное закрепление, не являющееся семантической версией (core/postgres:1.x, core/postgres:1.0, core/postgres:v1.0.0), — не называет никакой версии. Когда команда разрешает такую ссылку и разрешение не удаётся, в отказе указываются ссылка, закрепление и три приведённые выше формы, а не сообщается о сущности или версии, которых нет в каталоге; диагностика описана в errors/fatal-halts.md в разделе «A version pin is none of the forms a pin takes (Закрепление версии не соответствует ни одной из форм закрепления)». Закрепление проверяется только там, поэтому некорректное закрепление никогда не меняет то, какие ссылки разрешаются, а о корректном закреплении, которому не удовлетворяет ни одна доступная версия, сообщается именно так. Грамматика закрепления не задана ни в одной схеме, поэтому о некорректном закреплении сообщается, когда что-либо разрешает ссылку — aggrega validate, aggrega pull, aggrega build, — а не при загрузке файла.
Эти формы сосуществуют в одной и той же позиции. Авторы выбирают форму в зависимости от того, нужна ли им фиксация версии или гибкость в выборе версии. Уровень mappings.{components,features}.type сущности Manifest поддерживает оба варианта как отдельные ключи словаря с приоритетом версионированный ключ важнее неверсионированного: версионированный ключ (core/api-server:1.0.0) имеет приоритет над неверсионированным (core/api-server), когда оба соответствуют одному и тому же поиску. Эти два варианта не исключают друг друга: оба могут находиться в одной карте type:, и резолвер выбирает наиболее конкретный. Диспетчеризация Provider определяется полем spec.capability разрешённой сущности Recipe, поэтому Manifest сопоставляет тип с Recipe и ничего больше.
О режиме использования версий для каждой сущности (у каких сущностей поле версии действительно используется при диспетчеризации разрешения, а у каких служит описательным указанием происхождения) см. vocabulary/inheritance-and-interface.md, раздел «Cross-entity version consumption».
Ссылка на сущность Component, Feature, Aggregate или Plugin также принимает диапазон с кареткой (core/postgres:^1.0.0), и в любой форме она выбирает наибольшую удовлетворяющую версию среди имеющихся в каталоге по единому правилу, которое применяет каждая команда, — см. version-resolution.md. О трёхформенном сопоставлении implements:, которое является проверкой согласованности сопоставления, а не выбором, см. 10-status.md, раздел «Version matching».
Идентичность, а не местоположение
Каноническая ссылка на сущность, в том числе ссылка на плагин, — это идентичность, а не местоположение: она называет, что представляет собой сущность, и никогда — где она сейчас находится.
Идентичность голая и не содержит хоста. В ней нет хоста реестра; хост — это координата разрешения, которую задаёт конфигурация через default_registry и которая связывается во время разрешения. Перенос реестра или зеркалирование той же сущности в другом месте — это изменение конфигурации: ссылки, называющие сущность, остаются нетронутыми.
Идентичность также не содержит версии. Ссылка может нести необязательное закрепление версии (:<version> или :^<version>), ограничивающее, какие версии ей удовлетворяют, а каждая сущность Release записывает точную разрешённую версию как закрепление в своём lock-файле, но версия задаётся рядом с идентичностью, а не встраивается в неё.
Во время разрешения компилятор соединяет голую идентичность с настроенным хостом и закреплённой версией, чтобы получить конкретные байты. Поскольку и то и другое задаётся отдельно, одна и та же ссылка разрешается в другом реестре или в другую закреплённую версию без правки исходного текста, который её называет.
Вывод сокращённых OCI URI
Авторам не нужно записывать каждый URI как полностью квалифицированный OCI URI. Во время разрешения компилятор применяет четыре ортогональных правила вывода, которые разворачивают сокращённые авторские формы в канонические OCI URI. Правила:
Правило 1 — домен по умолчанию
К любому URI без домена добавляется префикс — настроенный default_registry из .aggrega-config.yaml (по умолчанию: hub.aggrega.ai/).
# Shorthandtype: core/postgres:1.0.0
# Equivalent canonical formtype: hub.aggrega.ai/component/core/postgres:1.0.0Правило 2 — контекстное раскрытие сущности
Компилятор добавляет нужный сегмент типа сущности в зависимости от позиции в схеме. Соответствие то же, что в приведённой выше таблице вывода по позиции (/component/, /aggregate/, /recipe/, /featurerecipe/, /feature/, /plugin/).
# Same string, two positions, two expansionsAggregate.spec.components.foo.type: core/postgres:1.0.0# → hub.aggrega.ai/component/core/postgres:1.0.0
Manifest.spec.mappings.components.type."core/postgres:1.0.0": helm/postgres:1.0.0# Key: hub.aggrega.ai/component/core/postgres:1.0.0# Value: hub.aggrega.ai/recipe/helm/postgres:1.0.0Правило 3 — трёхуровневый приоритет
Прежде чем применять вывод OCI, компилятор разрешает URI по трёхуровневой модели разрешения сущностей, описанной в architecture/13-catalog-and-registry.md:
- Локальный путь — для документов, которые называют Release и его Manifest.
aggregate,manifestилиextendsсущности Release либоextendsсущности Manifest, записанные с префиксом./или../, читаются как файл относительно собственного каталога Release; вывод OCI не выполняется. Никакая другая позиция не принимает путь:type, ключ или значение сопоставления Manifest,implementsилиpluginконвейера, записанные как./…, не называют никакой сущности и останавливают сборку. Сущность, созданная локально, размещается вcatalog/в корне рабочего пространства или в каталоге, перечисленном вworkspace.catalog_dirs, и разрешается по своему имени через уровень рабочего пространства и кэша. - Рабочее пространство и кэш — стек поиска по каталогам рабочего пространства, затем кэш. Каталоги
catalog_dirs:рабочего пространства.aggrega-config.yaml— или, для сущности Release, которой конфигурация задаёт собственные каталоги вworkspace.releases, каталоги этой сущности Release — просматриваются в указанном порядке, а каталогcatalog/в корне рабочего пространства просматривается последним — после всех перечисленных записей и только если этот каталог существует. Совпадение в любом месте стека отменяет вывод OCI. При промахе затем проверяетсяartifact_cache_dir, где хранится то, что получили предыдущие загрузки из реестра. - Реестр. Когда на уровне рабочего пространства и кэша совпадения нет, применяются правила вывода OCI, и ссылка загружается из удалённого реестра командой
aggrega pullлибо сборкой, запущенной с--auto-pullили с настройкой рабочего пространстваauto_pull; сборка без того и другого читает только то, что закрепляет её lock-файл.
Каскад позволяет проекту сочетать документы, которые Release называет по пути (уровень локального пути), с вендорированным и локальным для рабочего пространства содержимым каталога (уровень рабочего пространства и кэша) и содержимым, загруженным из удалённого реестра (уровень реестра), а ссылка на сущность записывается одинаково, на каком бы из двух последних уровней ни находилась сущность.
Если catalog_dirs: перечисляет более одного каталога, список образует упорядоченный стек приоритетов «побеждает первый»: идентичность сущности, присутствующая в нескольких перечисленных каталогах, разрешается в каталог, указанный раньше, а более позднее вхождение затеняется (переопределяется, а не считается ошибкой) — так проект может поместить собственный каталог перед общим и переопределять сущности по идентичности, тогда как остальные проходят дальше. Переопределение отражается в подробностях разрешения. Два файла, претендующие на одну и ту же идентичность внутри одного каталога, по-прежнему являются ошибкой автора, которая останавливает загрузку.
Каталог catalog/ в корне рабочего пространства находится в конце этого стека, а не в начале, поэтому всё, что перечисляет проект, побеждает его при коллизии, а перечисление одного постороннего каталога никогда не мешает его чтению. Он пропускается, если до него уже доходит одна из перечисленных записей: обход перечисленного каталога рекурсивен, поэтому стек, в котором указан корень рабочего пространства, его уже прочитал. Отсутствие catalog_dirs: и запись его как пустого списка означают разное: если ключ опущен, рабочее пространство всё равно читает catalog/; если записано [], оно не читает никакого локального каталога — так рабочее пространство сообщает, что у него его нет.
Правило 4 — обработка версий
URI может содержать сегмент версии или опускать его. Обработка версии зависит от позиции разрешения (разрешение уровней Manifest, сопоставление implements:, импорт вложенного агрегата) согласно собственным правилам потребления версий для этой позиции. Семантику версий для каждой сущности см. в разделе «Cross-entity version consumption» файла inheritance-and-interface.md.
Перечень форматов строк
Помимо строк URI, поверхность авторинга Aggrega использует несколько различных соглашений о форматах строк. Авторы, которые пишут или читают YAML-файлы, встречают в разных позициях следующие форматы:
| Формат | Где задаётся | Чем проверяется |
|---|---|---|
Шаблон Go ({{ .field }}) | Recipe valuesMapping: / workload: / artifacts: / provides: / locals: / source:; FeatureRecipe injectMapping: / with: конвейера; интерполяция parameters: в Aggregate; Release directory: / subDirectory: | Парсер шаблонов Go во время вычисления; правила доступности для каждого места — в templates/expansion-matrix.md |
Справочник функций Sprig ({{ default 1 .v }} и т. д.) | Те же места, что и для шаблонов Go | FuncMap Sprig v3, регистрируемый при инициализации движка шаблонов; полный список функций — в templates/sprig-functions.md |
| JSON Schema 2020-12 (компактная или полная форма) | Содержимое schema: в Component / Feature (или $ref: на запись SchemaLibrary) | Валидатор JSON Schema при загрузке сущности во время разрешения |
| JSON Pointer (RFC 6901) | Ключи Recipe locals.<*_path>: (volumes_path, containers_path и т. д.); ссылки на выходные данные шагов pipeline: в FeatureRecipe; полезные нагрузки JSONPatch Wasm-плагинов | Базовый уровень RFC 6901 согласно контракту Wasm-плагинов; объявлен в plugins/plugin-contract.md |
| Регулярное выражение SemVer | Поля metadata.version в каждой сущности | Регулярное выражение JSON Schema ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-...)?$ в схеме каждой сущности |
Закрепление версии (:<version>, :^<version>) | Сегмент версии в ссылке на сущность, во всех перечисленных выше позициях URI | Компилятор при разрешении ссылки: точное закрепление должно быть семантической версией, диапазон закрепления с крышкой должен разбираться, а некорректное закрепление отклоняется с собственным условием — см. форму URI выше |
| Путь в файловой системе | Пути относительно каталога (например, записи catalog_dirs: в .aggrega-config.yaml); пути к файлам $import: в Recipe внутри workload: / artifacts: / valuesMapping: | Читается как записано при разрешении — запись catalog_dirs: относительно файла конфигурации, который её объявляет, путь $import: относительно собственного каталога сущности; glob не раскрывается, поэтому * обозначает файл или каталог с таким именем |
| Выражение селектора меток | Component.spec.usesSchema.<socket>.selector; Feature appliesTo: / appliesToAnyOf: | Парсер селекторов Aggrega там, где вычисляется селектор; грамматика селекторов описана в vocabulary/modifier-system.md |
Форма ключа аннотации (<namespace>/<name>) | Ключи metadata.annotations; ключи features.annotations в Manifest; каскад граничных аннотаций | Регулярное выражение JSON Schema в каждой сущности; порядок использования зарезервированных префиксов — в vocabulary/labels-and-annotations.md |
Имя Provider, при необходимости с закреплённой версией (helm, helm:^1.0.0) | Recipe.spec.capability; FeatureRecipe.spec.capability | Поиск для диспетчеризации Provider; закрепление, которому не удовлетворяет ни одна версия плагина, останавливает сборку |
Ключ доставки inject (env.<KEY>, file.<path>, arg.<flag>) | Блоки inject: в Aggregate; выходные данные injectMapping: в FeatureRecipe | Схема inject в vocabulary/topology-triad.md |
У каждого формата своя грамматика, свой валидатор и своя форма сообщений об ошибках. Авторы, столкнувшиеся с ошибкой разбора строки формата, находят правила синтаксиса в справочнике по соответствующему формату.
Редактор сообщает об этих ошибках прямо во время написания: aggrega serve проверяет каждый полученный документ по схеме его вида и возвращает тот же вердикт, что дала бы сборка (см. cli/aggrega-serve.md, «Живая валидация»), а aggrega scaffold создаёт черновик начального документа любого вида.
Перекрёстные ссылки
entities/manifest.md— разрешение уровней сопоставления сущности Manifest + раздел о контекстно-зависимых сокращённых URI.entities/plugin.md— таксономия сокетов сущности Plugin + форма URIplugin/<socket>/<name>с закодированным сокетом.architecture/13-catalog-and-registry.md— трёхуровневая модель разрешения сущностей + каноническая таксономия OCI для распространения каталогов.vocabulary/inheritance-and-interface.md— привязка интерфейсаimplements:+ использование версий между сущностями.templates/expansion-matrix.md— правила доступности для каждого места шаблона для форматных строк Go template.templates/sprig-functions.md— перечень вспомогательных функций Sprig v3, подключённых к движку шаблонов.vocabulary/topology-triad.md— соглашения о ключах доставки inject; грамматика выражений селекторов описана вvocabulary/modifier-system.md.vocabulary/labels-and-annotations.md— форма ключей аннотаций и дисциплина зарезервированных префиксов.10-status.md— состояние готовности трёхформенного сопоставленияimplements:и команд CLI, разрешающих ссылки.