appliesTo e selettori
Il sistema dei modificatori governa a quali nodi si associa una Feature. Una Feature dichiara selettori di etichette; il motore nativo di corrispondenza delle etichette del compilatore li valuta rispetto ai metadata.labels di ciascun Component di destinazione durante la fase di analisi statica. Lo stesso motore — e la stessa grammatica dei selettori — valuta anche i selettori di socket usesSchema per la sicurezza dei tipi tra nodi, così un unico vocabolario serve ogni superficie di selettore del linguaggio.
I due involucri
Lo spec di una Feature porta fino a due campi selettore:
appliesTo— la superficie di composizione AND. Una singola stringa di selettore di etichette in stile Kubernetes; ogni requisito separato da virgole deve essere soddisfatto perché l’associazione sia valida.appliesToAnyOf— la superficie di composizione OR. Un elenco di elementi selettore; un qualsiasi singolo elemento corrispondente soddisfa l’associazione. Ogni elemento è o un selettore in forma di stringa (stessa grammatica diappliesTo, con i requisiti all’interno della stringa combinati in AND) o una mappa chiave-valore piatta confrontata solo per uguaglianza.
Quando una Feature dichiara entrambi, i risultati si combinano in AND tra gli involucri: la stringa appliesTo deve essere soddisfatta e almeno un elemento di appliesToAnyOf deve corrispondere. Un selettore omesso o vuoto non dichiara alcun vincolo e corrisponde a qualsiasi insieme di etichette — una Feature senza nessuno dei due campi si associa ovunque lo sviluppatore la metta.
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)"La grammatica della stringa
La stringa del selettore segue la sintassi dei selettori di etichette che kubectl get -l accetta: requisiti separati da virgole, composti in AND, ciascuno in una di sei forme:
| Forma | Significato |
|---|---|
key=value | l’etichetta esiste con esattamente questo valore |
key!=value | l’etichetta è assente, oppure presente con un valore diverso |
key in (v1, v2) | il valore dell’etichetta è uno di quelli dell’insieme |
key notin (v1, v2) | l’etichetta è assente, oppure il suo valore è fuori dall’insieme |
key | l’etichetta esiste (qualsiasi valore) |
!key | l’etichetta è assente |
Le chiavi possono portare prefissi in stile DNS (team.aggrega.ai/owner). Il vocabolario degli operatori è un insieme chiuso di sei; il motore non supporta espressioni regolari, sottostringhe o confronti numerici.
appliesTo: "component.aggrega.ai/type in (server, worker), !legacy.aggrega.ai/exempt"Un requisito al di fuori delle sei forme viene rifiutato, mai interpretato per congettura:
- Un requisito vuoto — una virgola iniziale, finale o doppia, oppure una stringa composta solo da separatori.
"tier=frontend,"e" , , "vengono rifiutati anziché letti come un numero minore di requisiti, o come nessuno. - Una chiave che contiene spazi o uno dei caratteri propri della grammatica —
=,!,(,)e la virgola, che sono ciò che distingue una forma dall’altra.!nomina una chiave di etichetta e nient’altro, quindi!tier=frontendviene rifiutato: scritto per escludere i frontend, verrebbe altrimenti letto come «l’etichetta chiamatatier=frontendè assente», cosa che ogni componente soddisfa.tier!=frontendè il modo in cui si esclude un valore. Allo stesso modotier in frontendviene rifiutato — un insieme si scrivetier in (frontend)— e così anchetier: frontend. - Un insieme non chiuso —
in (onotin (senza la sua).
Un valore non è vincolato ad alcun insieme di caratteri: è il testo dopo l’operatore, privato degli spazi circostanti, confrontato con il valore dell’etichetta così come è scritto. Quindi tier==frontend chiede un’etichetta il cui valore è =frontend; == non è una seconda grafia dell’uguaglianza. Al di là della regola sulle chiavi qui sopra, né una chiave né un valore vengono giudicati — le etichette sono stringhe opache che il motore confronta.
Dove risiede la validazione
Due livelli controllano un selettore, con un rigore deliberatamente diverso:
- Il
patterndi JSON Schema è un controllo esterno permissivo. Lo schema della Feature dichiaraappliesTo(e gli elementi in forma di stringa diappliesToAnyOf) come stringhe con un pattern di delimitazione che rifiuta solo forme palesemente malformate. È deliberatamente permissivo — lo schema non rifiuta mai un selettore che il motore valuterebbe. - Il parser è il validatore. Il parser dei selettori del compilatore possiede la grammatica: un selettore che rifiuta — una qualsiasi delle forme sopra — arresta la build con una diagnostica che nomina il selettore, la Feature, il socket o lo slot che lo dichiara e il requisito che non è riuscito a leggere. I fallimenti di parsing sono evidenti e specifici, mai saltati in silenzio. In una build il parser viene eseguito dove un selettore viene valutato — per ogni associazione di una Feature, ogni arco collegato attraverso un socket, ogni riempimento di uno slot. Anche
aggrega validate, sull’intero catalogo o su un singolo Component o Feature, legge ogni selettore di socket e di slot che il documento dell’entità dichiara, quindi uno malformato su un socket o uno slot che nulla usa viene rifiutato lì, con il codice e con le parole che usa una build. UnappliesTomalformato su una Feature che nulla associa non viene segnalato finché qualcosa non lo fa.
Un selettore che viene analizzato ma non corrisponde non è di per sé un errore — è un vincolo non soddisfatto. All’analisi statica, ogni associazione di Feature le cui etichette di destinazione non soddisfano i selettori della Feature produce una diagnostica di violazione che nomina l’istanza della funzionalità, il nodo di destinazione, le sue etichette e il vincolo; l’analizzatore raccoglie ogni violazione prima di arrestarsi, così una sola compilazione le fa emergere tutte.
Che cosa non fa il compilatore
Il compilatore è agnostico rispetto alla semantica delle etichette. Valuta qualunque stringa di etichetta trovi — non riconosce component.aggrega.ai/type come speciale, non verifica che un valore di categoria appartenga all’insieme chiuso del catalogo standard e non deduce significato dai nomi delle chiavi. Il vocabolario delle etichette stesso — il contratto del tipo operativo, l’asse della categoria cognitiva, le etichette di capacità per ruolo — è una convenzione della libreria standard mantenuta dagli autori del catalogo e dal linter di pubblicazione, non dal compilatore. Le aziende che scrivono i propri cataloghi sono libere di definire il proprio vocabolario di etichette; il motore dei selettori lo valuta in modo identico. Per lo schema di etichette a tre assi che usa il catalogo standard, vedi architecture/13-catalog-and-registry.md; per la trattazione delle singole etichette, vedi architecture/09-ai-features.md §1.2.
Affinità dei selettori in tutto il linguaggio
I selettori di socket usesSchema (selector: "component.aggrega.ai/type=stateful-server") e le annotazioni x-aggrega-selector: sintetizzate a partire da essi usano la stessa grammatica e lo stesso motore dell’appliesTo di una Feature. La conoscenza di scrittura si trasferisce uno a uno: una stringa che funziona come selettore di socket funziona come selettore di associazione. Per la trattazione dal lato dei socket, vedi topology-triad.md e entities/component.md.
Per la superficie di scrittura dal lato della Feature — i campi dello spec, esempi di associazione svolti e l’interazione con l’ereditarietà extends — vedi entities/feature.md §Label-Based Attachment (Collegamento basato su etichette).