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

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.