Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

appliesTo e seletores

O sistema de modificadores governa a quais nós uma Feature se vincula. Uma Feature declara seletores de rótulos; o motor nativo de correspondência de rótulos do compilador os avalia em relação 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 — também avalia os seletores de socket usesSchema para a segurança de tipos entre nós, de modo que um único vocabulário serve a todas as superfícies de seletor da linguagem.

Os dois envelopes

Uma spec de Feature carrega até dois campos de seletor:

  • appliesTo — a superfície de composição AND. Uma única string de seletor de rótulos no estilo Kubernetes; cada requisito separado por vírgulas precisa ser atendido para que a vinculação seja válida.
  • appliesToAnyOf — a superfície de composição OR. Uma lista de itens de seletor; qualquer item correspondente satisfaz sozinho a vinculação. Cada item é ou um seletor em forma de string (a mesma gramática de appliesTo, com os requisitos dentro da string combinados em AND) ou um mapa plano de chave-valor comparado apenas por igualdade.

Quando uma Feature declara ambos, os resultados se combinam em AND entre os envelopes: a string appliesTo precisa ser atendida e pelo menos um item de appliesToAnyOf precisa corresponder. Um seletor omitido ou vazio não declara nenhuma restrição e corresponde a qualquer conjunto de rótulos — uma Feature sem nenhum dos dois campos se vincula onde quer que o desenvolvedor 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 string

A string do seletor segue a sintaxe de seletores de rótulos que kubectl get -l aceita: requisitos separados por vírgulas, compostos em AND, cada um em uma de seis formas:

FormaSignificado
key=valueo rótulo existe com exatamente este valor
key!=valueo rótulo está ausente, ou presente com um valor diferente
key in (v1, v2)o valor do rótulo é um dos do conjunto
key notin (v1, v2)o rótulo está ausente, ou seu valor está fora do conjunto
keyo rótulo existe (qualquer valor)
!keyo rótulo está ausente

As chaves podem carregar prefixos no estilo DNS (team.aggrega.ai/owner). O vocabulário de operadores é um conjunto fechado de seis; o motor não suporta expressões regulares, substrings 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 string 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 rótulo e nada mais, então !tier=frontend é recusado: escrito para excluir os frontends, ele seria lido de outra forma como “o rótulo chamado tier=frontend está ausente”, o que todo componente satisfaz. tier!=frontend é a forma de excluir um valor. Da mesma maneira, tier in frontend é recusado — um conjunto é escrito tier in (frontend) — e tier: frontend também.
  • Um conjunto que não está fechado — in ( ou notin ( 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 ao redor, comparado com o valor do rótulo tal como está escrito. Assim, tier==frontend pede um rótulo cujo valor é =frontend; == não é uma segunda grafia da igualdade. Além da regra sobre chaves acima, nem uma chave nem um valor são julgados — os rótulos são strings opacas que o motor compara.

Onde fica a validação

Duas camadas verificam um seletor, com rigor deliberadamente diferente:

  • O pattern do JSON Schema é uma barreira externa folgada. O schema da Feature declara appliesTo (e os itens de appliesToAnyOf em forma de string) como strings com um padrão delimitador que recusa apenas formas claramente malformadas. Ele é deliberadamente permissivo — o schema nunca recusa um seletor que o motor avaliaria.
  • O parser é o validador. O parser de seletores do compilador é dono da gramática: um seletor que ele recusa — qualquer uma das formas acima — interrompe o build com um diagnóstico que nomeia o seletor, a Feature, o socket ou o slot que o declara, e o requisito que ele não conseguiu ler. As falhas de parsing são explícitas e específicas, nunca ignoradas em silêncio. Em um build, o parser é executado onde um seletor é avaliado — para cada vinculação de uma Feature, cada aresta conectada por meio 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ê cada seletor de socket e de slot que o documento da entidade declara, então um seletor malformado em um socket ou slot que nada usa é recusado ali, com o código e nas palavras que um build usa. Um appliesTo malformado em uma Feature que nada vincula 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 vinculação de Feature cujos rótulos 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, seus rótulos e a restrição; o analisador coleta todas as violações antes de interromper, de modo que uma única compilação revela todas elas.

O que o compilador não faz

O compilador é agnóstico em relação à semântica dos rótulos. Ele avalia quaisquer strings de rótulo 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 rótulos — o contrato do tipo operacional, o eixo de categoria cognitiva, os rótulos 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 escrevem seus próprios catálogos são livres para definir seu próprio vocabulário de rótulos; o motor de seletores o avalia de forma idêntica. Para o esquema de rótulos de três eixos que o catálogo padrão usa, consulte architecture/13-catalog-and-registry.md; para a explicação rótulo a rótulo, consulte 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 autoria se transfere de um para um: uma string que funciona como seletor de socket funciona como seletor de vinculação. Para a explicação do lado do socket, consulte topology-triad.md e entities/component.md.

Para a superfície de autoria do lado da Feature — os campos da spec, exemplos de vinculação detalhados e a interação com a herança extends —, consulte entities/feature.md §Label-Based Attachment (Anexação baseada em labels).