Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

appliesTo i selektory

System modyfikatorów określa, do których węzłów dołącza się encja Feature. Encja Feature deklaruje selektory etykiet; natywny silnik dopasowywania etykiet kompilatora ocenia je względem metadata.labels każdej docelowej encji Component na etapie analizy statycznej. Ten sam silnik — i ta sama gramatyka selektorów — ocenia również selektory gniazd usesSchema na potrzeby bezpieczeństwa typów między węzłami, dzięki czemu jedno słownictwo obsługuje każde miejsce w języku, w którym występują selektory.

Dwie koperty

Specyfikacja encji Feature zawiera maksymalnie dwa pola selektorów:

  • appliesTo — powierzchnia składania przez AND. Pojedynczy ciąg selektora etykiet w stylu Kubernetes; każde wymaganie oddzielone przecinkiem musi być spełnione, aby dołączenie było prawidłowe.
  • appliesToAnyOf — powierzchnia składania przez OR. Lista elementów selektora; dowolny pojedynczy pasujący element spełnia warunek dołączenia. Każdy element jest albo selektorem w postaci ciągu (ta sama gramatyka co appliesTo, wymagania wewnątrz ciągu łączone przez AND), albo płaską mapą klucz-wartość dopasowywaną wyłącznie przez równość.

Gdy encja Feature deklaruje oba pola, wyniki obu kopert łączone są przez AND: ciąg appliesTo musi być spełniony i co najmniej jeden element appliesToAnyOf musi pasować. Pominięty lub pusty selektor nie deklaruje żadnego ograniczenia i pasuje do każdego zestawu etykiet — encja Feature bez żadnego z tych pól dołącza się wszędzie tam, gdzie umieści ją programista.

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

Gramatyka ciągu

Ciąg selektora stosuje składnię selektorów etykiet akceptowaną przez kubectl get -l: wymagania oddzielone przecinkami, łączone przez AND, każde w jednej z sześciu postaci:

FormaZnaczenie
key=valueetykieta istnieje i ma dokładnie tę wartość
key!=valueetykieta nie istnieje lub ma inną wartość
key in (v1, v2)wartość etykiety należy do zbioru
key notin (v1, v2)etykieta nie istnieje lub jej wartość nie należy do zbioru
keyetykieta istnieje (dowolna wartość)
!keyetykieta nie istnieje

Klucze mogą mieć prefiksy w stylu DNS (team.aggrega.ai/owner). Słownik operatorów jest zamkniętym zbiorem sześciu elementów; silnik nie obsługuje wyrażeń regularnych, dopasowania podciągów ani porównań liczbowych.

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

Wymaganie spoza sześciu postaci jest odrzucane, a nie zgadywane:

  • Puste wymaganie — przecinek na początku, na końcu lub podwojony albo ciąg składający się wyłącznie z separatorów. "tier=frontend," i " , , " są odrzucane, a nie odczytywane jako mniejsza liczba wymagań lub ich brak.
  • Klucz zawierający białe znaki lub jeden ze znaków samej gramatyki — =, !, (, ) i przecinek, które odróżniają jedną postać od drugiej. ! poprzedza wyłącznie klucz etykiety, dlatego !tier=frontend jest odrzucane: zapisane w celu wykluczenia frontendów, zostałoby w przeciwnym razie odczytane jako „etykieta o nazwie tier=frontend nie istnieje”, co spełnia każdy komponent. Wartość wyklucza się zapisem tier!=frontend. W ten sam sposób odrzucane jest tier in frontend — zbiór zapisuje się jako tier in (frontend) — oraz tier: frontend.
  • Niezamknięty zbiór — in ( lub notin ( bez zamykającego ).

Wartość nie podlega żadnemu ograniczeniu zestawu znaków: jest to tekst po operatorze, z usuniętymi otaczającymi białymi znakami, porównywany z wartością etykiety w zapisanej postaci. Zatem tier==frontend wymaga etykiety o wartości =frontend; == nie jest drugim zapisem równości. Poza powyższą regułą dotyczącą kluczy ani klucz, ani wartość nie są oceniane — etykiety są nieprzezroczystymi ciągami, które silnik porównuje.

Gdzie odbywa się walidacja

Selektor sprawdzają dwie warstwy o celowo różnym stopniu rygoru:

  • pattern w JSON Schema to luźna bramka zewnętrzna. Schemat encji Feature deklaruje appliesTo (oraz elementy appliesToAnyOf w postaci ciągu) jako ciągi ze wzorcem ograniczającym, który odrzuca tylko oczywiście błędne kształty. Jest celowo pobłażliwy — schemat nigdy nie odrzuca selektora, który silnik by ocenił.
  • Parser jest walidatorem. Parser selektorów kompilatora odpowiada za gramatykę: selektor, który odrzuca — dowolny z powyższych kształtów — zatrzymuje kompilację z diagnostyką wskazującą selektor, deklarującą go encję Feature, gniazdo lub slot oraz wymaganie, którego nie udało się odczytać. Błędy parsowania są głośne i konkretne, nigdy nie są po cichu pomijane. Podczas kompilacji parser działa tam, gdzie selektor jest oceniany — przy każdym dołączeniu encji Feature, każdej krawędzi połączonej przez gniazdo, każdym wypełnieniu slotu. aggrega validate, uruchomione dla całego katalogu albo dla pojedynczej encji Component lub Feature, odczytuje też każdy selektor gniazda i slotu zadeklarowany w dokumencie encji, więc błędny selektor w gnieździe lub slocie, z którego nic nie korzysta, jest tam odrzucany, z tym samym kodem i w tych samych słowach, których używa kompilacja. Błędne appliesTo w encji Feature, której nic nie dołącza, nie jest zgłaszane, dopóki coś tego nie zrobi.

Selektor, który się parsuje, ale nie pasuje, nie jest sam w sobie błędem — jest niespełnionym ograniczeniem. Podczas analizy statycznej każde dołączenie encji Feature, którego etykiety docelowe nie spełniają selektorów tej encji Feature, generuje diagnostykę naruszenia wskazującą instancję funkcji, węzeł docelowy, jego etykiety oraz ograniczenie; analizator zbiera wszystkie naruszenia przed zatrzymaniem, więc jedna kompilacja ujawnia je wszystkie.

Czego kompilator nie robi

Kompilator jest agnostyczny wobec semantyki etykiet. Ocenia dowolne napotkane ciągi etykiet — nie traktuje component.aggrega.ai/type jako szczególnego, nie sprawdza, czy wartość kategorii należy do zamkniętego zbioru standardowego katalogu, i nie wnioskuje znaczenia z nazw kluczy. Samo słownictwo etykiet — kontrakt typu operacyjnego, oś kategorii poznawczej, etykiety możliwości dla poszczególnych ról — jest konwencją biblioteki standardowej, przestrzeganą przez autorów katalogów i linter publikacji, a nie przez kompilator. Przedsiębiorstwa tworzące własne katalogi mogą swobodnie definiować własne słownictwo etykiet; silnik selektorów ocenia je identycznie. Trójosiowy schemat etykiet stosowany przez standardowy katalog opisano w architecture/13-catalog-and-registry.md; omówienie poszczególnych etykiet znajduje się w architecture/09-ai-features.md §1.2.

Pokrewieństwo selektorów w całym języku

Selektory gniazd usesSchema (selector: "component.aggrega.ai/type=stateful-server") oraz syntetyzowane z nich adnotacje x-aggrega-selector: używają tej samej gramatyki i tego samego silnika co appliesTo encji Feature. Wiedza autorska przenosi się jeden do jednego: ciąg działający jako selektor gniazda działa jako selektor dołączenia. Omówienie strony gniazd znajduje się w topology-triad.md i entities/component.md.

Powierzchnię autorską po stronie encji Feature — pola specyfikacji, przykłady dołączeń oraz współdziałanie z dziedziczeniem extends — opisano w entities/feature.md §Label-Based Attachment.