Перейти к содержимому
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 inline — в компактной или полной форме — или $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, выполняющей рендеринг для провайдера, — как документированный контракт трансляции. Само тело 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, выполняющих рендеринг для провайдера, рабочее пространство разрешает неоднозначность с помощью привязки провайдера в .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.