Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

appliesTo и селекторы

Система модификаторов определяет, к каким узлам присоединяется Feature. Feature объявляет селекторы меток; встроенный механизм сопоставления меток компилятора вычисляет их по metadata.labels каждой целевой сущности Component на этапе статического анализа. Тот же механизм — и та же грамматика селекторов — вычисляет также селекторы сокетов usesSchema для межузловой типобезопасности, так что один словарь служит всем местам языка, где используются селекторы.

Две оболочки

Спецификация Feature содержит до двух полей селекторов:

  • appliesTo — поверхность композиции через И. Одна строка селектора меток в стиле Kubernetes; для допустимости присоединения должно выполняться каждое требование, разделённое запятыми.
  • appliesToAnyOf — поверхность композиции через ИЛИ. Список элементов селектора; присоединение удовлетворяется любым одним совпавшим элементом. Каждый элемент — либо селектор в строковой форме (та же грамматика, что у appliesTo, требования внутри строки объединяются через И), либо плоское отображение ключ–значение, сопоставляемое только на равенство.

Если Feature объявляет оба поля, результаты оболочек объединяются через И: строка appliesTo должна выполняться и хотя бы один элемент appliesToAnyOf должен совпасть. Опущенный или пустой селектор не объявляет ограничений и совпадает с любым набором меток — Feature без обоих полей присоединяется везде, куда её поместит разработчик.

spec:
appliesTo: "compliance.aggrega.ai/scope in (pci), tier notin (dev, staging)"
appliesToAnyOf:
- { component.aggrega.ai/type: stateful-server }
- "datastore.aggrega.ai/engine in (relational, document, vector)"

Грамматика строки

Строка селектора следует синтаксису селекторов меток, который принимает kubectl get -l: требования через запятую, объединённые через И, каждое в одной из шести форм:

ФормаЗначение
key=valueметка существует и имеет ровно это значение
key!=valueметка отсутствует или имеет другое значение
key in (v1, v2)значение метки входит в множество
key notin (v1, v2)метка отсутствует или её значение не входит в множество
keyметка существует (с любым значением)
!keyметка отсутствует

Ключи могут иметь префиксы в стиле DNS (team.aggrega.ai/owner). Словарь операторов — закрытый набор из шести; механизм не поддерживает регулярные выражения, сравнение подстрок или числовое сравнение.

appliesTo: "component.aggrega.ai/type in (server, worker), !legacy.aggrega.ai/exempt"

Требование вне шести форм отклоняется, а не угадывается:

  • Пустое требование — запятая в начале, в конце или сдвоенная, либо строка из одних разделителей. "tier=frontend," и " , , " отклоняются, а не читаются как меньшее число требований или их отсутствие.
  • Ключ, содержащий пробельный символ или один из символов самой грамматики — =, !, (, ) и запятую, по которым одна форма отличается от другой. ! указывает на ключ метки и ни на что иное, поэтому !tier=frontend отклоняется: написанное ради исключения фронтендов, иначе оно читалось бы как «метка с именем tier=frontend отсутствует», чему удовлетворяет любой компонент. Значение исключается так: tier!=frontend. Точно так же отклоняется tier in frontend — множество записывается как tier in (frontend), — а также tier: frontend.
  • Незакрытое множество — in ( или notin ( без ).

Значение не ограничено никаким набором символов: это текст после оператора без окружающих пробелов, сравниваемый со значением метки в том виде, как оно записано. Поэтому tier==frontend запрашивает метку со значением =frontend; == не является вторым написанием равенства. Помимо правила для ключей выше, ни ключ, ни значение не оцениваются — метки являются непрозрачными строками, которые механизм сравнивает.

Где выполняется проверка

Селектор проверяют два уровня с намеренно разной строгостью:

  • pattern в JSON Schema — нестрогий внешний фильтр. Схема Feature объявляет appliesTo (и элементы appliesToAnyOf в строковой форме) как строки с ограничивающим шаблоном, который отклоняет только явно некорректные формы. Он намеренно снисходителен — схема никогда не отклоняет селектор, который вычислил бы механизм.
  • Валидатором является парсер. Грамматикой владеет парсер селекторов компилятора: отклонённый им селектор — любая из форм выше — останавливает сборку с диагностикой, в которой указаны селектор, объявившие его Feature, сокет или слот, а также требование, которое не удалось прочитать. Ошибки разбора выводятся явно и конкретно и никогда не пропускаются молча. При сборке парсер запускается там, где селектор вычисляется, — для каждого присоединения Feature, каждого ребра, проведённого через сокет, каждого заполнения слота. aggrega validate — для всего каталога или для одной сущности Component или Feature — также читает каждый селектор сокета и слота, который объявляет документ сущности, поэтому некорректный селектор в сокете или слоте, которые ничто не использует, отклоняется там с тем же кодом и в тех же формулировках, что и при сборке. О некорректном appliesTo в сущности Feature, которую ничто не присоединяет, не сообщается, пока что-нибудь её не присоединит.

Селектор, который разбирается, но не совпадает, сам по себе не является ошибкой — это невыполненное ограничение. При статическом анализе каждое присоединение Feature, метки цели которого не удовлетворяют селекторам Feature, порождает диагностику нарушения с указанием экземпляра функции, целевого узла, его меток и ограничения; анализатор собирает все нарушения перед остановкой, так что одна компиляция выявляет их все.

Чего компилятор не делает

Компилятор агностичен по отношению к семантике меток. Он вычисляет любые найденные строки меток — он не считает component.aggrega.ai/type особой, не проверяет, что значение категории входит в закрытый набор стандартного каталога, и не выводит смысл из имён ключей. Сам словарь меток — операционный контракт типов, когнитивная ось категорий, метки возможностей для каждой роли — это соглашение стандартной библиотеки, которое поддерживают авторы каталогов и линтер публикации, а не компилятор. Предприятия, создающие собственные каталоги, вольны определять собственный словарь меток; механизм селекторов вычисляет его точно так же. О трёхосевой схеме меток стандартного каталога см. architecture/13-catalog-and-registry.md; об отдельных метках см. architecture/09-ai-features.md §1.2.

Родство селекторов в языке

Селекторы сокетов usesSchema (selector: "component.aggrega.ai/type=stateful-server") и синтезированные из них аннотации x-aggrega-selector: используют ту же грамматику и тот же механизм, что и appliesTo в Feature. Знания об авторинге переносятся один к одному: строка, работающая как селектор сокета, работает и как селектор присоединения. О стороне сокетов см. topology-triad.md и entities/component.md.

Об авторинге со стороны Feature — полях спецификации, разобранных примерах присоединения и взаимодействии с наследованием extends — см. entities/feature.md §Label-Based Attachment.