appliesTo e seletores
O sistema de modificadores rege a que nós uma Feature se anexa. Uma Feature declara seletores de etiquetas; o motor nativo de correspondência de etiquetas do compilador avalia-os face aos metadata.labels de cada Component de destino durante a etapa de análise estática. O mesmo motor — e a mesma gramática de seletores — avalia também os seletores de socket usesSchema para a segurança de tipos entre nós, pelo que um único vocabulário serve todas as superfícies de seletor da linguagem.
Os dois envelopes
Uma spec de Feature transporta até dois campos de seletor:
appliesTo— a superfície de composição AND. Uma única cadeia de seletor de etiquetas ao estilo do Kubernetes; cada requisito separado por vírgulas tem de ser cumprido para que o anexo seja válido.appliesToAnyOf— a superfície de composição OR. Uma lista de itens de seletor; qualquer item correspondente satisfaz sozinho o anexo. Cada item é ou um seletor em forma de cadeia (a mesma gramática deappliesTo, com os requisitos dentro da cadeia combinados em AND) ou um mapa plano de chave-valor comparado apenas por igualdade.
Quando uma Feature declara ambos, os resultados combinam-se em AND entre os envelopes: a cadeia appliesTo tem de ser cumprida e pelo menos um item de appliesToAnyOf tem de corresponder. Um seletor omitido ou vazio não declara qualquer restrição e corresponde a qualquer conjunto de etiquetas — uma Feature sem nenhum dos dois campos anexa-se onde quer que o programador a coloque.
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)"A gramática da cadeia
A cadeia do seletor segue a sintaxe de seletores de etiquetas que kubectl get -l aceita: requisitos separados por vírgulas, compostos em AND, cada um numa de seis formas:
| Forma | Significado |
|---|---|
key=value | a etiqueta existe com exatamente este valor |
key!=value | a etiqueta está ausente, ou presente com um valor diferente |
key in (v1, v2) | o valor da etiqueta é um dos do conjunto |
key notin (v1, v2) | a etiqueta está ausente, ou o seu valor está fora do conjunto |
key | a etiqueta existe (qualquer valor) |
!key | a etiqueta está ausente |
As chaves podem ter prefixos ao estilo DNS (team.aggrega.ai/owner). O vocabulário de operadores é um conjunto fechado de seis; o motor não suporta expressões regulares, subcadeias nem comparações numéricas.
appliesTo: "component.aggrega.ai/type in (server, worker), !legacy.aggrega.ai/exempt"Um requisito fora das seis formas é recusado, nunca adivinhado:
- Um requisito vazio — uma vírgula inicial, final ou duplicada, ou uma cadeia formada apenas por separadores.
"tier=frontend,"e" , , "são recusadas em vez de lidas como menos requisitos, ou como nenhum. - Uma chave que contém espaços em branco ou um dos caracteres próprios da gramática —
=,!,(,)e a vírgula, que são o que distingue uma forma da outra.!nomeia uma chave de etiqueta e nada mais, pelo que!tier=frontendé recusado: escrito para excluir os frontends, seria de outro modo lido como «a etiqueta chamadatier=frontendestá ausente», o que todo o componente satisfaz.tier!=frontendé a forma de excluir um valor. Do mesmo modo,tier in frontendé recusado — um conjunto escreve-setier in (frontend)— etier: frontendtambém. - Um conjunto que não está fechado —
in (ounotin (sem o seu).
Um valor não está sujeito a nenhum conjunto de caracteres: é o texto após o operador, sem os espaços em branco à volta, comparado com o valor da etiqueta tal como está escrito. Assim, tier==frontend pede uma etiqueta cujo valor é =frontend; == não é uma segunda grafia da igualdade. Para além da regra sobre chaves acima, nem uma chave nem um valor são julgados — as etiquetas são cadeias opacas que o motor compara.
Onde reside a validação
Duas camadas verificam um seletor, com um rigor deliberadamente diferente:
- O
patterndo JSON Schema é uma barreira exterior folgada. O schema da Feature declaraappliesTo(e os itens deappliesToAnyOfem forma de cadeia) como cadeias com um padrão delimitador que recusa apenas formas claramente malformadas. É deliberadamente permissivo — o schema nunca recusa um seletor que o motor avaliaria. - O parser é o validador. O parser de seletores do compilador detém a gramática: um seletor que recusa — qualquer uma das formas acima — interrompe a compilação com um diagnóstico que nomeia o seletor, a Feature, o socket ou o slot que o declara, e o requisito que não conseguiu ler. As falhas de parsing são explícitas e específicas, nunca ignoradas em silêncio. Numa compilação, o parser é executado onde um seletor é avaliado — para cada anexo de uma Feature, cada aresta ligada através de um socket, cada preenchimento de um slot.
aggrega validate, sobre o catálogo inteiro ou sobre um único Component ou Feature, também lê todos os seletores de socket e de slot que o documento da entidade declara, pelo que um seletor malformado num socket ou slot que nada usa é recusado aí, com o código e nas palavras que uma compilação usa. UmappliesTomalformado numa Feature que nada anexa não é reportado até que algo o faça.
Um seletor que é analisado mas não corresponde não é um erro em si — é uma restrição não satisfeita. Na análise estática, cada anexo de Feature cujas etiquetas de destino não satisfazem os seletores da Feature produz um diagnóstico de violação que nomeia a instância da funcionalidade, o nó de destino, as suas etiquetas e a restrição; o analisador recolhe todas as violações antes de interromper, pelo que uma única compilação as revela todas.
O que o compilador não faz
O compilador é agnóstico em relação à semântica das etiquetas. Avalia quaisquer cadeias de etiqueta que encontre — não reconhece component.aggrega.ai/type como especial, não valida se um valor de categoria pertence ao conjunto fechado do catálogo padrão e não infere significado a partir dos nomes das chaves. O próprio vocabulário de etiquetas — o contrato do tipo operacional, o eixo de categoria cognitiva, as etiquetas de capacidade por papel — é uma convenção da biblioteca padrão mantida pelos autores do catálogo e pelo linter de publicação, não pelo compilador. As empresas que criam os seus próprios catálogos são livres de definir o seu próprio vocabulário de etiquetas; o motor de seletores avalia-o de forma idêntica. Para o esquema de etiquetas de três eixos que o catálogo padrão usa, ver architecture/13-catalog-and-registry.md; para a explicação etiqueta a etiqueta, ver architecture/09-ai-features.md §1.2.
Parentesco dos seletores em toda a linguagem
Os seletores de socket usesSchema (selector: "component.aggrega.ai/type=stateful-server") e as anotações x-aggrega-selector: sintetizadas a partir deles usam a mesma gramática e o mesmo motor que o appliesTo de uma Feature. O conhecimento de criação transfere-se de um para um: uma cadeia que funciona como seletor de socket funciona como seletor de anexo. Para a explicação do lado do socket, ver topology-triad.md e entities/component.md.
Para a superfície de criação do lado da Feature — os campos da spec, exemplos de anexo detalhados e a interação com a herança extends —, ver entities/feature.md §Label-Based Attachment (Anexação baseada em etiquetas).