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.