Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

appliesTo und Selektoren

Das Modifikatorsystem regelt, an welche Knoten ein Feature angebunden wird. Ein Feature deklariert Label-Selektoren; die native Label-Matching-Engine des Compilers wertet sie während der Stufe der statischen Analyse gegen die metadata.labels jeder Ziel-Component aus. Dieselbe Engine — und dieselbe Selektorgrammatik — wertet auch Socket-Selektoren usesSchema für knotenübergreifende Typsicherheit aus, sodass ein einziges Vokabular jeder Selektoroberfläche der Sprache dient.

Die zwei Hüllen

Eine Feature-Spec trägt bis zu zwei Selektorfelder:

  • appliesTo — die Oberfläche für AND-Komposition. Ein einzelner Label-Selektor-String im Kubernetes-Stil; jede kommagetrennte Anforderung muss erfüllt sein, damit die Anbindung gültig ist.
  • appliesToAnyOf — die Oberfläche für OR-Komposition. Eine Liste von Selektorelementen; ein einziges passendes Element erfüllt die Anbindung. Jedes Element ist entweder ein Selektor in String-Form (dieselbe Grammatik wie appliesTo, Anforderungen innerhalb des Strings werden per AND verknüpft) oder eine flache Schlüssel-Wert-Map, die nur auf Gleichheit geprüft wird.

Wenn ein Feature beide deklariert, werden die Ergebnisse über die Hüllen hinweg per AND verknüpft: Der String appliesTo muss erfüllt sein, und mindestens ein Element von appliesToAnyOf muss passen. Ein ausgelassener oder leerer Selektor deklariert keine Einschränkung und passt auf jede Label-Menge — ein Feature ohne eines der beiden Felder wird überall angebunden, wo der Entwickler es platziert.

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)"

Die String-Grammatik

Der Selektor-String folgt der Label-Selektor-Syntax, die kubectl get -l akzeptiert: kommagetrennte Anforderungen, per AND verknüpft, jede in einer von sechs Formen:

FormBedeutung
key=valuedas Label existiert mit genau diesem Wert
key!=valuedas Label fehlt oder ist mit einem anderen Wert vorhanden
key in (v1, v2)der Wert des Labels ist einer aus der Menge
key notin (v1, v2)das Label fehlt, oder sein Wert liegt außerhalb der Menge
keydas Label existiert (beliebiger Wert)
!keydas Label fehlt

Schlüssel können Präfixe im DNS-Stil tragen (team.aggrega.ai/owner). Das Operatorvokabular ist eine geschlossene Menge von sechs; die Engine unterstützt keine regulären Ausdrücke, keine Teilstrings und keine numerischen Vergleiche.

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

Eine Anforderung außerhalb der sechs Formen wird zurückgewiesen, nie erraten:

  • Eine leere Anforderung — ein führendes, abschließendes oder doppeltes Komma oder ein String, der nur aus Trennzeichen besteht. "tier=frontend," und " , , " werden zurückgewiesen, statt als weniger Anforderungen oder als gar keine gelesen zu werden.
  • Ein Schlüssel, der Leerraum oder eines der eigenen Zeichen der Grammatik enthält — =, !, (, ) und das Komma, die eine Form von einer anderen unterscheiden. ! benennt einen Label-Schlüssel und nichts anderes, daher wird !tier=frontend zurückgewiesen: Geschrieben, um Frontends auszuschließen, würde es sonst als „das Label namens tier=frontend fehlt“ gelesen, was jede Komponente erfüllt. tier!=frontend ist die Art, einen Wert auszuschließen. Ebenso wird tier in frontend zurückgewiesen — eine Menge wird tier in (frontend) geschrieben — und ebenso tier: frontend.
  • Eine nicht geschlossene Menge — in ( oder notin ( ohne ihr ).

Ein Wert ist an keinen Zeichensatz gebunden: Er ist der Text nach dem Operator, ohne umgebenden Leerraum, verglichen mit dem Wert des Labels, wie er geschrieben ist. So fragt tier==frontend nach einem Label, dessen Wert =frontend ist; == ist keine zweite Schreibweise der Gleichheit. Über die obige Schlüsselregel hinaus wird weder ein Schlüssel noch ein Wert beurteilt — Labels sind opake Strings, die die Engine vergleicht.

Wo die Validierung stattfindet

Zwei Ebenen prüfen einen Selektor, mit bewusst unterschiedlicher Strenge:

  • Das pattern des JSON Schema ist ein lockeres äußeres Tor. Das Feature-Schema deklariert appliesTo (und Elemente von appliesToAnyOf in String-Form) als Strings mit einem begrenzenden Muster, das nur offensichtlich fehlerhafte Formen zurückweist. Es ist bewusst nachsichtig — das Schema weist nie einen Selektor zurück, den die Engine auswerten würde.
  • Der Parser ist der Validator. Der Selektorparser des Compilers besitzt die Grammatik: Ein Selektor, den er zurückweist — eine der obigen Formen —, hält den Build mit einer Diagnose an, die den Selektor, das ihn deklarierende Feature, den Socket oder Slot sowie die Anforderung nennt, die er nicht lesen konnte. Parse-Fehler sind laut und konkret, nie stillschweigend übersprungen. In einem Build läuft der Parser dort, wo ein Selektor ausgewertet wird — für jede Anbindung eines Feature, jede über einen Socket verdrahtete Kante, jede Befüllung eines Slots. aggrega validate liest, über den ganzen Katalog oder über eine einzelne Component oder ein einzelnes Feature, zudem jeden Socket- und Slot-Selektor, den das Dokument der Entität deklariert, sodass ein fehlerhafter Selektor an einem Socket oder Slot, den nichts verwendet, dort zurückgewiesen wird, unter dem Code und mit den Worten, die ein Build verwendet. Ein fehlerhaftes appliesTo an einem Feature, das nichts anbindet, wird erst gemeldet, wenn etwas es tut.

Ein Selektor, der geparst wird, aber nicht passt, ist an sich kein Fehler — er ist eine unerfüllte Einschränkung. Bei der statischen Analyse erzeugt jede Feature-Anbindung, deren Ziel-Labels die Selektoren des Feature nicht erfüllen, eine Verletzungsdiagnose, die die Funktionsinstanz, den Zielknoten, seine Labels und die Einschränkung nennt; der Analysator sammelt jede Verletzung, bevor er anhält, sodass ein einziger Kompiliervorgang alle sichtbar macht.

Was der Compiler nicht tut

Der Compiler ist agnostisch gegenüber der Semantik von Labels. Er wertet alle Label-Strings aus, die er findet — er erkennt component.aggrega.ai/type nicht als besonders, prüft nicht, ob ein Kategoriewert zur geschlossenen Menge des Standardkatalogs gehört, und leitet keine Bedeutung aus Schlüsselnamen ab. Das Label-Vokabular selbst — der operative Typvertrag, die kognitive Kategorienachse, die rollenbezogenen Fähigkeits-Labels — ist eine Konvention der Standardbibliothek, die von Katalogautoren und dem Veröffentlichungs-Linter getragen wird, nicht vom Compiler. Unternehmen, die eigene Kataloge verfassen, können ihr eigenes Label-Vokabular definieren; die Selektor-Engine wertet es identisch aus. Zum Drei-Achsen-Label-Schema, das der Standardkatalog verwendet, siehe architecture/13-catalog-and-registry.md; zur Darstellung der einzelnen Labels siehe architecture/09-ai-features.md §1.2.

Verwandtschaft der Selektoren in der gesamten Sprache

Socket-Selektoren usesSchema (selector: "component.aggrega.ai/type=stateful-server") und die daraus synthetisierten Annotationen x-aggrega-selector: verwenden dieselbe Grammatik und dieselbe Engine wie das appliesTo eines Feature. Authoring-Wissen lässt sich eins zu eins übertragen: Ein String, der als Socket-Selektor funktioniert, funktioniert auch als Anbindungsselektor. Zur Darstellung auf der Socket-Seite siehe topology-triad.md und entities/component.md.

Zur Authoring-Oberfläche auf der Feature-Seite — den Spec-Feldern, ausgearbeiteten Anbindungsbeispielen und dem Zusammenspiel mit der Vererbung über extends — siehe entities/feature.md §Label-Based Attachment (Label-basierte Anbindung).