appliesTo і селектори
Система модифікаторів визначає, до яких вузлів приєднується Feature. Feature
оголошує селектори міток; вбудований рушій зіставлення міток компілятора
обчислює їх щодо metadata.labels кожного цільового Component на
етапі статичного аналізу. Той самий рушій — і та сама граматика
селекторів — обчислює також селектори сокетів usesSchema для
типобезпеки між вузлами, тож один словник слугує всім поверхням
селекторів у мові.
Дві оболонки
Специфікація Feature містить до двох полів селекторів:
appliesTo— поверхня AND-композиції. Один рядок селектора міток у стилі Kubernetes; кожна вимога, відокремлена комою, має виконуватися, щоб приєднання було дійсним.appliesToAnyOf— поверхня OR-композиції. Список елементів селектора; будь-який один збіжний елемент задовольняє приєднання. Кожен елемент — це або селектор у рядковій формі (та сама граматика, що йappliesTo, вимоги всередині рядка поєднуються через AND), або плоска мапа ключ-значення, що зіставляється лише за рівністю.
Коли Feature оголошує обидва, результати поєднуються через AND між оболонками:
рядок 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:
вимоги, відокремлені комами, поєднані через AND, кожна в одній із шести
форм:
| Форма | Значення |
|---|---|
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.