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

Поверхня валідації

Aggrega валідує авторський вміст на чотирьох окремих рівнях схем. Кожен рівень охоплює власну область, виконується в іншій точці конвеєра компіляції та видає помилки іншої форми. Авторам, які отримали помилку валідації, корисно знати, який саме рівень відхилив вхідні дані: те саме поле може регулюватися кількома рівнями, і від рівня, що спрацював, залежить, що і де виправляти.

На цій сторінці описано чотири рівні, їхнє місце в конвеєрі, домовленість щодо форми помилок, якої дотримується кожен рівень, а також те, як рівні взаємодіють, коли до одного поля застосовується більше ніж один із них.

Чотири рівні

Рівень 1 — оболонка JSON Schema

Область. Структурна форма кожного YAML-файлу каталогу: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, блок верхнього рівня spec: і обов’язкові поля кожної сутності, які оголошує схема. Кожен вид сутності (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) має власну JSON Schema, описану в довіднику схем. Workload також має там схему, і це єдиний вид у цьому наборі, який автор пише всередині іншої сутності — у блоці workload: сутності Recipe чи FeatureRecipe або в записі WorkloadLibrary, — а не як окремий файл каталогу; та сама перевірка оболонки застосовується до нього, де б його не було написано, а aggrega validate приймає файл Workload безпосередньо як ціль з однією сутністю.

Коли виконується валідація. Під час розв’язання (resolver / load), для кожного файлу. Кожен документ під час завантаження перевіряється за JSON Schema свого виду; ключ поза полями, які оголошує схема, відхиляється вже на цьому етапі, до будь-якої подальшої валідації.

Форма помилки. Невідповідність схемі повідомляється як збій оболонки документа. Її заголовок несе категорію документа, у якому помилка, — [CATALOG_ERROR E0215] для сутності каталогу, [DEVELOPER_ERROR E0215] для Aggregate, [OPS_ERROR E0215] для Release, — а повідомлення називає вид, файл, рядок і стовпець, шлях до поля та порушене обмеження:

[CATALOG_ERROR E0215] <path>
document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schema

Пропуски обов’язкових полів і невідповідності типів проявляються в тій самій формі — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".

Рівень 2 — схеми стовпів (schema: / featuresSchema / usesSchema)

Область. Стовпи даних, які несе сутність, — values, infra, parameters, а також блок прикріплень features:, слоти якого оголошує featuresSchema, і блок uses:, яким керує usesSchema. Сутності домену 2 (Component, Feature) вбудовують оголошення JSON Schema 2020-12 у свою YAML-оболонку (spec.schema безпосередньо — у компактній або повній формі — або $ref: на спільний запис SchemaLibrary); сутності домену 3 (Recipe, FeatureRecipe) використовують розв’язані схеми під час власного проходу валідації.

Коли виконується валідація. Під час розв’язання, після успішної перевірки оболонки JSON Schema. Компілятор поєднує написану для сутності schema: з автоматично згенерованими базами, виведеними з оголошень usesSchema і featuresSchema; об’єднана схема перевіряє надані розробником блоки values: / infra: / features: / uses: у кожному екземплярі компонента в Aggregate.

Форма помилки. Порушення обмежень проявляються як повідомлення, що називають сутність, шлях усередині стовпа і правило, яке відхилило значення, — наприклад, коли розробник задає порт 80 всупереч правилу схеми, що вимагає >=1024.

Повторно оголошений запис usesSchema чи featuresSchema не спричиняє помилки поєднання. Ці дві поверхні накладаються за іменем: запис нащадка повністю замінює запис бази, разом зі схемою та селектором, тож конфлікту між записом бази й нащадка, про який слід повідомляти, немає.

Рівень 3 — здатність Provider до синтезованого режиму

Область. Визначається перевіркою здатності прив’язаного провайдера до синтезованого режиму:

  • Підтримка синтезованого режиму (workload:) залежить від здатності прив’язаного провайдера, а не від наявності workloadSchema: сутність Recipe з workload:, прив’язану до провайдера, що не вміє синтезувати, тут відхиляють. Каталог стандартної бібліотеки за домовленістю оголошує workloadSchema для провайдерів, здатних до синтезу, — у spec.provider.workloadSchema сутності Plugin, що виконує Provider-рендеринг, — як задокументований контракт трансляції. Саме тіло workloadSchema компілюється в JSON Schema 2020-12 під час завантаження Plugin; це структурна перевірка прийняття, яка відхиляє некоректну схему під час завантаження, а не під час рендерингу.

Коли виконується валідація. Під час базового рендерингу, після розв’язання власного valuesMapping сутності Recipe. Рівень 3 обумовлює диспетчеризацію синтезованого режиму здатністю провайдера.

Форма помилки. Відмову через здатність відносять до домену створення каталогу, тому звіт про неї починається із заголовка у квадратних дужках з цією категорією та екземпляром, у якому виникла проблема. Повідомлення починається з фіксованого речення, що описує умову, а далі називає вузол, провайдера і види, які цей провайдер підтримує:

[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesized

Заголовок [CATALOG_ERROR] сигналізує, що помилка в сутності каталогу, а не в Aggregate розробника. У терміналі заголовок також містить короткий код умови — E0265 для цієї, який розшифровує таблиця всіх умов, — а повідомлення переходить на окремий рядок із відступом; однорядкова форма вище — це те, що потрапляє в журнал. Початкове речення фіксоване для кожної умови, тож саме за ним слід шукати збіг, коли ви працюєте з текстом; усе, що йде після нього, залежить від вузла з помилкою.

Пов’язаний запобіжник захищає саму диспетчеризацію провайдерів: коли одну ціль обслуговує більше ніж один Plugin, що виконує Provider-рендеринг, робочий простір усуває неоднозначність через прив’язку провайдера в .aggrega-config.yaml, обрану під час aggrega pull і записану в lock-файл. Якщо прив’язки немає і кандидат Plugin рівно один, використовується цей кандидат; якщо прив’язки немає, а кандидатів більше одного, збірка явно зупиняється, називаючи плагіни-кандидати. Неоднозначність усувається для кожного робочого простору в місці використання, а не правилом унікальності для всього каталогу.

Валідація вмісту Workload для кожного провайдера. spec.provider.workloadSchema сутності Plugin, що рендерить провайдер, документує, як провайдер перетворює Workload, і позначає провайдер як здатний його синтезувати; вона нічого не валідує. Кожне тіло Workload валідується за схемою Workload платформи, хоч би який був провайдер.

Рівень 4 — валідація значень прив’язок анотацій

Область. Значення анотацій, написані на межах Release / компонентах меж або підсистемах Aggregate / екземплярах компонентів, коли прив’язка Manifest у mappings.features.annotations.<key> оголошує маршрутизацію через списки шляхів із крапками maps.infra та/або maps.values. Кожен оголошений шлях проходить spec.schema.<pillar> цільової сутності Feature до листкової властивості; внесок значення анотації в цей листок перевіряється за оголошеним типом схеми Feature. Валідація відбувається через власне оголошення JSON Schema 2020-12 сутності Feature — прив’язки оголошують лише маршрутизацію, а не фрагменти валідації.

Коли виконується валідація. На підфазі розгортання анотацій у межах розв’язання, після валідації цілей прив’язок Manifest (перевірки під час завантаження каталогу, яка підтверджує, що кожен оголошений шлях існує в схемі сутності Feature, на яку є посилання) і паралельно з валідацією схем рівня 2 для явних прикріплень. Для кожної чинної анотації компонента: розібрати значення як скаляр, структуровану мапу або явний null; спрямувати кожен підключ через згруповане за стовпами оголошення maps прив’язки з перевіркою відповідності сторони й стовпа (сторона Aggregate задіює maps.values; сторона Release задіює maps.infra); перевірити значення кожного листка під час виконання за оголошеним типом схеми Feature у визначеному маршрутом стовпі. Помилки кількох підключів збираються й виводяться всі разом перед зупинкою.

Форма помилки. Помилки валідації схеми на цьому рівні мають форму рівня 2 — сутність, шлях (ключ анотації плюс маршрут підключа), деталі обмеження. Порушення розподілу між стороною і стовпом та помилки неоднозначної маршрутизації відносять до документа, у якому написано значення анотації, тож помилка з Aggregate починається із заголовка [DEVELOPER_ERROR], а з Release — із заголовка [OPS_ERROR], і обидві називають ключ анотації, визначений маршрутом стовп, сторону автора та місце в джерелі.

Одна домовленість щодо форматування помилок для всіх шарів

Чотири шари мають одну спільну видиму домовленість: кожна помилка валідації, яку можна приписати Aggrega, має форму «шлях плюс обґрунтування», що називає проблемне поле й обмеження, яке його відхилило.

  • Помилки рівня 1 (оболонка) і рівня 2 (схеми стовпів) починаються з однакового заголовка у квадратних дужках — категорії документа, у якому помилка, і короткого коду умови, наприклад [CATALOG_ERROR E0215] для невідповідності оболонки в сутності каталогу та [DEVELOPER_ERROR E0168] для значення Aggregate, яке відхиляє схема стовпа, — після якого йдуть шлях до поля та порушене правило схеми.
  • Помилки шару 3 (джерело Provider / Workload) за визначенням приписуються сутності каталогу: саме пара Recipe + Provider створила схему, яка відхилила введені розробником дані. Їх приписують домену авторства каталогу, і це приписування доходить до вас у заголовку діагностики у квадратних дужках, а не як слово, вписане в повідомлення: звіт про зупинку починається з [CATALOG_ERROR E0nnn], де категорія називає домен, а короткий код — умову. Зіставляйте за коротким кодом, який після призначення не змінюється.
  • Помилки шару 4 (валідація значень прив’язок анотацій) мають форму шару 2: схема Feature, що виконує валідацію, міститься в spec.schema відповідної сутності Feature, а значення часу виконання проходять через маршрутизацію maps прив’язки Manifest у цю схему для перевірки типів на рівні кожного листка.

Повний перелік сентинелів із префіксом Aggrega та поверхонь, що їх породжують, див. у errors/error-translation.md. Каталог окремих помилок (правила форми Recipe для [CATALOG_ERROR], умова за умовою) див. у errors/fatal-halts.md.

Взаємодія рівнів, коли поля перекриваються

Те саме написане поле може підлягати більш ніж одному рівню. containers.<name>.ports.<port> у Workload перевіряється рівнем 1 як частина структурної форми схеми Workload; рівень 2 до нього не сягає, оскільки вміст Workload — це внутрішня структура Recipe, а не стовп Component; а workloadSchema провайдера нічого не перевіряє — тож обмеження на кшталт відхилення порту нижче 1024 слід розміщувати в схемі Component або в твердженні, де його назве рівень, що спрацював.

Підсумок розміщення в конвеєрі

РівеньОбласть застосуванняКоли виконуєтьсяПрефікс помилки
1 — оболонка JSON SchemaСтруктурна форма (apiVersion, kind, metadata, spec верхнього рівня)Розв’язання (завантаження)категорія документа з E0215 — [CATALOG_ERROR E0215] для сутності каталогу
2 — Схеми стовпів (schema: / featuresSchema / usesSchema)Валідація даних для кожного стовпа (values, infra, secrets, uses)Розв’язання (після оболонки)категорія документа-джерела з коротким кодом умови — [DEVELOPER_ERROR E0168] для значення Aggregate
3 — Шлюз можливостей ProviderПідтримка синтезованого режиму (можливість провайдера)Базовий рендеринг[CATALOG_ERROR]
4 — Валідація значень прив’язок анотаційВнески значень анотацій, спрямовані в spec.schema цільової сутності Feature через шляхи maps прив’язки сутності ManifestПідфаза розгортання анотацій під час розв’язання, поряд із рівнем 2помилка валідації схеми; поверхні «бічна сторона проти стовпа» / неоднозначної маршрутизації відкривають власний домен документа-автора — [DEVELOPER_ERROR] від сутності Aggregate, [OPS_ERROR] від сутності Release

Перехресні посилання

  • errors/error-translation.md — перелік сигнальних помилок із префіксом Aggrega та поверхонь, які їх породжують.
  • errors/fatal-halts.md — каталог усіх фатальних зупинок, які видає компілятор, з окремим записом для кожної помилки.
  • vocabulary/data-pillars.md — стовпи даних (values, infra, parameters, locals, features:, uses: і provides), які валідує рівень 2.
  • entities/component.md — поверхня написання сутності Component для schema: / featuresSchema / usesSchema.
  • entities/plugin.md — поверхня написання сутності Plugin для рендерингу провайдера для spec.provider.workloadSchema.
  • entities/manifest.md — поверхня прив’язки features.annotations сутності Manifest (рівень 4).
  • providers/well-known-annotations.md — розбір значень анотацій, маршрутизація підключів структурованих значень, відмова через null для окремого підключа та міжсторонна композиція, які валідує рівень 4.