appliesTo dan selector
Sistem modifier menentukan node mana yang menjadi tempat sebuah Feature dilekatkan. Sebuah Feature
mendeklarasikan label selector; mesin pencocokan label bawaan compiler
mengevaluasinya terhadap metadata.labels milik setiap Component target selama
tahap analisis statis. Mesin yang sama — dan tata bahasa selector
yang sama — juga mengevaluasi selector socket usesSchema untuk keamanan tipe
lintas node, sehingga satu kosakata melayani setiap permukaan selector dalam
bahasa ini.
Dua amplop
Spec sebuah Feature memuat paling banyak dua field selector:
appliesTo— permukaan komposisi AND. Satu string label selector bergaya Kubernetes; setiap persyaratan yang dipisahkan koma harus terpenuhi agar pelekatan valid.appliesToAnyOf— permukaan komposisi OR. Sebuah daftar item selector; satu item yang cocok saja sudah memenuhi pelekatan. Setiap item berupa selector bentuk string (tata bahasa sama denganappliesTo, persyaratan di dalam string digabungkan dengan AND) atau map key-value datar yang dicocokkan hanya berdasarkan kesamaan.
Jika sebuah Feature mendeklarasikan keduanya, hasilnya digabungkan dengan AND antaramplop: string
appliesTo harus terpenuhi dan setidaknya satu item appliesToAnyOf harus
cocok. Selector yang dihilangkan atau kosong tidak mendeklarasikan batasan apa pun dan cocok dengan
setiap himpunan label — sebuah Feature tanpa kedua field tersebut dapat dilekatkan di mana pun
pengembang menempatkannya.
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)"Tata bahasa string
String selector mengikuti sintaks label selector yang diterima kubectl get -l:
persyaratan yang dipisahkan koma, digabungkan dengan AND, masing-masing dalam salah satu dari enam
bentuk:
| Bentuk | Arti |
|---|---|
key=value | label ada dengan nilai persis ini |
key!=value | label tidak ada, atau ada dengan nilai yang berbeda |
key in (v1, v2) | nilai label termasuk salah satu anggota himpunan |
key notin (v1, v2) | label tidak ada, atau nilainya di luar himpunan |
key | label ada (nilai apa pun) |
!key | label tidak ada |
Key dapat memiliki prefiks bergaya DNS (team.aggrega.ai/owner). Kosakata
operator adalah himpunan tertutup berisi enam; mesin tidak mendukung
regex, substring, maupun perbandingan numerik.
appliesTo: "component.aggrega.ai/type in (server, worker), !legacy.aggrega.ai/exempt"Persyaratan di luar keenam bentuk tersebut ditolak, tidak pernah ditebak:
- Persyaratan kosong — koma di awal, di akhir, atau ganda, atau
string yang hanya berisi pemisah.
"tier=frontend,"dan" , , "ditolak alih-alih dibaca sebagai persyaratan yang lebih sedikit, atau sebagai tidak ada persyaratan. - Key yang mengandung spasi atau salah satu karakter milik tata bahasa itu sendiri —
=,!,(,)dan koma, yang membedakan satu bentuk dari bentuk lainnya.!hanya menamai sebuah key label, sehingga!tier=frontendditolak: ditulis untuk mengecualikan frontend, string itu justru akan dibaca sebagai “label bernamatier=frontendtidak ada”, yang dipenuhi oleh setiap komponen.tier!=frontendadalah cara mengecualikan sebuah nilai. Dengan cara yang samatier in frontendditolak — himpunan ditulistier in (frontend)— begitu pulatier: frontend. - Himpunan yang tidak ditutup —
in (ataunotin (tanpa)-nya.
Nilai tidak dibatasi pada himpunan karakter apa pun: nilai adalah teks setelah
operator, dengan spasi di sekitarnya dihapus, dibandingkan dengan nilai label
sebagaimana tertulis. Jadi tier==frontend meminta label yang nilainya
=frontend; == bukan ejaan kedua untuk kesamaan. Di luar aturan key
di atas, baik key maupun nilai tidak dinilai — label adalah string opak
yang dibandingkan oleh mesin.
Tempat validasi dilakukan
Dua lapisan memeriksa selector, dengan tingkat keketatan yang sengaja dibuat berbeda:
patternJSON Schema adalah gerbang luar yang longgar. Schema Feature mendeklarasikanappliesTo(dan itemappliesToAnyOfbentuk string) sebagai string dengan pola pembatas yang hanya menolak bentuk yang jelas-jelas salah. Pola ini sengaja dibuat permisif — schema tidak pernah menolak selector yang akan dievaluasi oleh mesin.- Parser adalah validatornya. Parser selector milik compiler memegang tata bahasa: selector yang ditolaknya — salah satu bentuk di atas — menghentikan build dengan diagnostik yang menyebutkan selector tersebut, Feature, socket, atau slot yang mendeklarasikannya, serta persyaratan yang tidak dapat dibacanya. Kegagalan parse dilaporkan dengan jelas dan spesifik, tidak pernah dilewati secara diam-diam. Dalam sebuah build, parser dijalankan di tempat selector dievaluasi — untuk setiap pelekatan sebuah Feature, setiap edge yang dihubungkan melalui socket, setiap pengisian slot.
aggrega validate, atas seluruh katalog atau atas satu Component atau Feature, juga membaca setiap selector socket dan slot yang dideklarasikan dokumen entitas tersebut, sehingga selector yang salah bentuk pada socket atau slot yang tidak digunakan ditolak di sana, dengan kode dan kata-kata yang sama seperti yang digunakan build.appliesToyang salah bentuk pada Feature yang tidak dilekatkan di mana pun tidak dilaporkan sampai ada yang melekatkannya.
Selector yang berhasil di-parse tetapi tidak cocok bukanlah error dengan sendirinya — melainkan batasan yang tidak terpenuhi. Pada analisis statis, setiap pelekatan Feature yang label targetnya tidak memenuhi selector Feature tersebut menghasilkan diagnostik pelanggaran yang menyebutkan instans feature, node target, labelnya, dan batasannya; analyzer mengumpulkan setiap pelanggaran sebelum berhenti, sehingga satu kali kompilasi menampilkan semuanya.
Hal yang tidak dilakukan compiler
Compiler agnostik terhadap semantik label. Compiler mengevaluasi string label apa pun yang ditemukannya — compiler tidak menganggap component.aggrega.ai/type sebagai hal khusus, tidak memvalidasi bahwa nilai kategori termasuk dalam himpunan tertutup catalog standar, dan tidak menyimpulkan makna dari nama key. Kosakata label itu sendiri — kontrak tipe operasional, sumbu kategori kognitif, label kapabilitas per peran — adalah konvensi pustaka standar yang dijaga oleh penulis catalog dan linter publikasi, bukan oleh compiler. Perusahaan yang menulis catalog mereka sendiri bebas mendefinisikan kosakata label mereka sendiri; mesin selector mengevaluasinya dengan cara yang sama persis. Untuk skema label tiga sumbu yang digunakan catalog standar, lihat architecture/13-catalog-and-registry.md; untuk penjelasan per label, lihat architecture/09-ai-features.md §1.2.
Kekerabatan selector di seluruh bahasa
Selector socket usesSchema (selector: "component.aggrega.ai/type=stateful-server")
dan anotasi x-aggrega-selector: yang disintesis darinya menggunakan
tata bahasa dan mesin yang sama dengan appliesTo milik Feature. Pengetahuan
penulisan berlaku satu banding satu: string yang berfungsi sebagai selector socket
berfungsi pula sebagai selector pelekatan. Untuk penjelasan sisi socket,
lihat topology-triad.md dan
entities/component.md.
Untuk permukaan penulisan sisi Feature — field spec, contoh
pelekatan yang dikerjakan, dan interaksinya dengan pewarisan extends — lihat
entities/feature.md §Label-Based Attachment.