Граматика 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:; інтерполяція Aggregate parameters:; Release directory: / subDirectory: | Парсер шаблонів Go під час обчислення; правила доступності для кожного місця — у templates/expansion-matrix.md |
Посилання на функції Sprig ({{ default 1 .v }} тощо) | Ті самі поверхні, що й для шаблонів Go | Sprig v3 FuncMap, зареєстрований під час ініціалізації рушія шаблонів; повний перелік допоміжних функцій — у 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 тощо); посилання на вихідні дані кроків FeatureRecipe pipeline:; корисні навантаження 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); шляхи до файлів Recipe $import: у workload: / artifacts: / valuesMapping: | Читається так, як записано, під час розв’язання — запис catalog_dirs: відносно файлу конфігурації, що його оголошує, шлях $import: відносно власного каталогу сутності; жоден glob не розгортається, тож * позначає файл або каталог із такою назвою |
| Вираз селектора міток | Component.spec.usesSchema.<socket>.selector; Feature appliesTo: / appliesToAnyOf: | Парсер селекторів Aggrega там, де обчислюється селектор; граматику селекторів описано в vocabulary/modifier-system.md |
Форма ключа анотації (<namespace>/<name>) | Ключі metadata.annotations; ключі Manifest features.annotations; каскад граничних анотацій | Регулярний вираз JSON Schema для кожної сутності; дисципліна зарезервованих префіксів — у vocabulary/labels-and-annotations.md |
Назва Provider, за потреби із закріпленою версією (helm, helm:^1.0.0) | Recipe.spec.capability; FeatureRecipe.spec.capability | Пошук для диспетчеризації Provider; закріплення, якому не відповідає жодна версія плагіна, зупиняє збирання |
Ключ доставки ін’єкції (env.<KEY>, file.<path>, arg.<flag>) | Блоки Aggregate inject:; вихідні дані FeatureRecipe injectMapping: | Схема ін’єкції в 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, що розв’язують посилання.