Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

appliesTo y selectores

El sistema de modificadores rige a qué nodos se vincula una Feature. Una Feature declara selectores de etiquetas; el motor nativo de coincidencia de etiquetas del compilador los evalúa frente a los metadata.labels de cada Component de destino durante la etapa de análisis estático. El mismo motor — y la misma gramática de selectores — evalúa también los selectores de socket usesSchema para la seguridad de tipos entre nodos, de modo que un único vocabulario sirve a todas las superficies de selector del lenguaje.

Las dos envolturas

Una spec de Feature lleva hasta dos campos de selector:

  • appliesTo — la superficie de composición AND. Una única cadena de selector de etiquetas al estilo de Kubernetes; cada requisito separado por comas debe cumplirse para que la vinculación sea válida.
  • appliesToAnyOf — la superficie de composición OR. Una lista de elementos de selector; cualquier elemento que coincida satisface por sí solo la vinculación. Cada elemento es o bien un selector en forma de cadena (la misma gramática que appliesTo, con los requisitos dentro de la cadena combinados con AND) o bien un mapa plano de clave-valor que se compara solo por igualdad.

Cuando una Feature declara ambos, los resultados se combinan con AND entre las envolturas: la cadena appliesTo debe cumplirse y al menos un elemento de appliesToAnyOf debe coincidir. Un selector omitido o vacío no declara ninguna restricción y coincide con cualquier conjunto de etiquetas — una Feature sin ninguno de los dos campos se vincula en cualquier lugar donde la ponga el desarrollador.

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 gramática de la cadena

La cadena del selector sigue la sintaxis de selectores de etiquetas que acepta kubectl get -l: requisitos separados por comas, compuestos con AND, cada uno en una de seis formas:

FormaSignificado
key=valuela etiqueta existe con exactamente este valor
key!=valuela etiqueta está ausente, o presente con un valor distinto
key in (v1, v2)el valor de la etiqueta es uno del conjunto
key notin (v1, v2)la etiqueta está ausente, o su valor está fuera del conjunto
keyla etiqueta existe (cualquier valor)
!keyla etiqueta está ausente

Las claves pueden llevar prefijos al estilo DNS (team.aggrega.ai/owner). El vocabulario de operadores es un conjunto cerrado de seis; el motor no admite expresiones regulares, subcadenas ni comparaciones numéricas.

appliesTo: "component.aggrega.ai/type in (server, worker), !legacy.aggrega.ai/exempt"

Un requisito fuera de las seis formas se rechaza, nunca se adivina:

  • Un requisito vacío — una coma inicial, final o duplicada, o una cadena formada solo por separadores. "tier=frontend," y " , , " se rechazan en lugar de leerse como menos requisitos, o como ninguno.
  • Una clave que contiene espacios en blanco o uno de los caracteres propios de la gramática — =, !, (, ) y la coma, que son lo que distingue una forma de otra. ! nombra una clave de etiqueta y nada más, así que !tier=frontend se rechaza: escrito para excluir los frontends, de lo contrario se leería como «la etiqueta llamada tier=frontend está ausente», lo que satisface todo componente. tier!=frontend es la forma de excluir un valor. Del mismo modo se rechaza tier in frontend — un conjunto se escribe tier in (frontend) —, y también tier: frontend.
  • Un conjunto que no está cerrado — in ( o notin ( sin su ).

Un valor no está sujeto a ningún conjunto de caracteres: es el texto que sigue al operador, sin los espacios en blanco que lo rodean, comparado con el valor de la etiqueta tal como está escrito. Así, tier==frontend pide una etiqueta cuyo valor sea =frontend; == no es una segunda grafía de la igualdad. Más allá de la regla sobre las claves de arriba, no se juzga ni una clave ni un valor — las etiquetas son cadenas opacas que el motor compara.

Dónde reside la validación

Dos capas comprueban un selector, con un rigor deliberadamente distinto:

  • El pattern del JSON Schema es una barrera exterior holgada. El esquema de la Feature declara appliesTo (y los elementos de appliesToAnyOf en forma de cadena) como cadenas con un patrón delimitador que solo rechaza formas claramente mal construidas. Es deliberadamente permisivo — el esquema nunca rechaza un selector que el motor evaluaría.
  • El analizador es el validador. El analizador de selectores del compilador es dueño de la gramática: un selector que rechaza — cualquiera de las formas anteriores — detiene la compilación con un diagnóstico que nombra el selector, la Feature, el socket o el slot que lo declara, y el requisito que no pudo leer. Los fallos de análisis son explícitos y concretos, nunca se omiten en silencio. En una compilación, el analizador se ejecuta donde se evalúa un selector — para cada vinculación de una Feature, cada arista conectada a través de un socket, cada relleno de un slot. aggrega validate, sobre todo el catálogo o sobre un solo Component o Feature, también lee cada selector de socket y de slot que declara el documento de la entidad, así que uno mal formado en un socket o slot que nada usa se rechaza ahí, con el código y en los términos que usa una compilación. Un appliesTo mal formado en una Feature que nada vincula no se notifica hasta que algo lo hace.

Un selector que se analiza pero no coincide no es un error en sí mismo — es una restricción no satisfecha. En el análisis estático, cada vinculación de Feature cuyas etiquetas de destino no satisfacen los selectores de la Feature produce un diagnóstico de violación que nombra la instancia de la funcionalidad, el nodo de destino, sus etiquetas y la restricción; el analizador recopila todas las violaciones antes de detenerse, de modo que una sola compilación las muestra todas.

Lo que el compilador no hace

El compilador es agnóstico respecto a la semántica de las etiquetas. Evalúa cualquier cadena de etiqueta que encuentre — no reconoce component.aggrega.ai/type como especial, no valida que un valor de categoría pertenezca al conjunto cerrado del catálogo estándar y no infiere significado a partir de los nombres de las claves. El propio vocabulario de etiquetas — el contrato del tipo operativo, el eje de categoría cognitiva, las etiquetas de capacidad por rol — es una convención de la biblioteca estándar que mantienen los autores del catálogo y el linter de publicación, no el compilador. Las empresas que escriben sus propios catálogos son libres de definir su propio vocabulario de etiquetas; el motor de selectores lo evalúa de forma idéntica. Para el esquema de etiquetas de tres ejes que usa el catálogo estándar, consulta architecture/13-catalog-and-registry.md; para la explicación etiqueta por etiqueta, consulta architecture/09-ai-features.md §1.2.

Parentesco de los selectores en todo el lenguaje

Los selectores de socket usesSchema (selector: "component.aggrega.ai/type=stateful-server") y las anotaciones x-aggrega-selector: sintetizadas a partir de ellos usan la misma gramática y el mismo motor que el appliesTo de una Feature. El conocimiento de autoría se transfiere uno a uno: una cadena que funciona como selector de socket funciona como selector de vinculación. Para la explicación del lado del socket, consulta topology-triad.md y entities/component.md.

Para la superficie de autoría del lado de la Feature — los campos de la spec, ejemplos de vinculación desarrollados y la interacción con la herencia extends —, consulta entities/feature.md §Label-Based Attachment (Acoplamiento basado en etiquetas).