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

Potok kompilacji (widok ogólny)

Ten rozdział szczegółowo opisuje wewnętrzną fizykę kompilatora Go, definiując, jak abstrakcyjny YAML jest przekładany na fizyczne konfiguracje w potoku kompilacji, grafie reprezentacji pośredniej (IR) i gniazdach wykonawczych WebAssembly (Wasm).

Potok kompilacji i przepływ wykonania

Aggrega uruchamia ścisły potok kompilacji z wyprzedzeniem (AOT) o stałej kolejności zamiast zakodowanej na sztywno logiki orkiestracji. Uruchamiany przez aggrega build kompilator przekazuje płaski graf między odizolowanymi gniazdami WebAssembly (Wasm), aby ocenić architekturę przed wyrenderowaniem fizycznych artefaktów.

Gniazda Wasm działają na osadzonym hoście — zestawie narzędzi Extism na silniku Wazero — za zaporą czystości AOT, która odmawia wtyczce jakiejkolwiek zdolności dostępu w czasie wykonywania (sieć, system plików, zegar ścienny, środowisko, standardowe wejście/wyjście), więc wtyczka nie może naruszyć deterministycznej gwarancji kompilacji z wyprzedzeniem. Host uruchamia linter publikacji poza pasmem, poprzez aggrega lint. Opisane poniżej bramki wewnątrzpasmowe — rola label-transform gniazda nadzoru przy budowie topologii i jego rola werdyktu IR przy analizie statycznej, a także potok wtyczek zamykający renderowanie — działają w każdym buildzie: rola nadzoru wszędzie tam, gdzie przestrzeń robocza dołącza do niej wtyczkę, a potok wtyczek dla każdej encji Recipe, która deklaruje kroki. Status języka śledzi status każdej fazy potoku.

Potok wykonuje się w całości w pamięci, w ścisłej, stałej kolejności:

Rozwiązywanie — resolver i walidator składni

  • Mechanizm: scalanie dziedziczenia, interpolacja szablonów Go i walidacja JSON Schema 2020-12.
  • Działanie: CLI pobiera wszystkie żądane encje (Components, Features, Releases). Najpierw sprawdza w tych definicjach słowo kluczowe extends. W przypadku encji katalogowych głęboko scala metadane YAML, a oba rodzaje rozchodzą się w kwestii filarów danych: schema: encji Feature składa się ze schematem jej encji bazowej zgodnie z kompozycją JSON Schema 2020-12, natomiast rozszerzająca encja Component składa wyłącznie strukturę — swoje sloty dołączeń, gniazda topologii, listę dozwolonych samowstrzyknięć i nazwane asercje — i otrzymuje blok schema: swojej encji bazowej dokładnie w takiej postaci, w jakiej napisała go encja bazowa. Rozszerzająca encja Release jest składana według tej samej zasady: wartość potomka wygrywa klucz po kluczu, aż do pierwszej niepodzielnej wartości — skalara, listy, szablonu — która jest zastępowana w całości, a klucz zapisany przez potomka jako null zostaje usunięty. Dzięki temu przenoszona jest cała jej powierzchnia autorska — drzewo granic z dołączeniami infra i Feature dla poszczególnych komponentów, blok parameters, adnotacje i wskaźnik do encji Manifest — natomiast żadne pole metadata nie jest przenoszone, ponieważ tożsamość i pochodzenie są właściwe dla każdej encji Release osobno. Następnie wykonuje interpolację w pamięci w trzech podkrokach: walidację kontraktu parametrów względem typowanych deklaracji parameters: encji Aggregate; interpolację rozwiązanych wartości w otaczających ciągach values:; wycofanie mapy .parameters z każdego kontekstu szablonów wartości, tak że pozostaje ona czytelna wyłącznie dla szablonów ścieżek tworzonych przez operatora. Na koniec wstrzykuje rozwiązane bloki infra do ładunków komponentów docelowych. Gdy plan jest w pełni konkretny, kompilator używa ujednoliconej deklaracji schema: z katalogu (forma kompaktowa lub pełny JSON Schema 2020-12), aby lokalnie i ściśle zwalidować konfiguracje values i infra programisty.
    • Walidacja schematu Feature w Release: Encje Features dołączone poprzez Release (zarówno obejmujące całą granicę, jak i właściwe dla komponentu) są w tym kroku rozwiązywane względem ich encji katalogowych. Kompilator waliduje bloki infra dostarczone przez Release względem deklaracji schema: każdej encji Feature bezpośrednio po rozwiązaniu katalogu, zapewniając bezpieczeństwo typów przed zbudowaniem topologii.
    • Podfaza rozwijania encji Feature sterowanego adnotacjami: Po rozwiązaniu encji Manifest, powiązaniu Recipe/Provider i walidacji celów powiązań Manifest (ścieżki zadeklarowane w mappings.features.annotations.<key>.maps istnieją w spec.schema przywoływanej encji Feature) kompilator uruchamia podfazę rozwijania adnotacji przed konstruktorem topologii. Podfaza przechodzi granice encji Release od zewnętrznej do wewnętrznej i podsystemy encji Aggregate od zewnętrznego do wewnętrznego, obliczając efektywny zbiór adnotacji dla każdego komponentu przez scalanie kaskady + nadpisania + rezygnacji przez null; parsuje każdą wartość adnotacji jako YAML do skalara, wartości strukturalnej lub null; kieruje każdą wartość (skalarną lub strukturalną dla każdego podklucza) przez deklarację maps powiązania Manifest do docelowego filaru schematu Feature z egzekwowaniem zgodności strony z filarem (strona Aggregate uruchamia maps.values; strona Release uruchamia maps.infra); waliduje typy poszczególnych liści względem spec.schema encji Feature; i wstrzykuje syntetyczne dołączenia Feature, które graf IR oznacza jako origin: annotation. Schematy są kompilowane raz na kompilację i ponownie używane w kolejnych przejściach kaskady. Rozwijanie odbywa się po walidacji celów powiązań i przed budową topologii, więc kolejne etapy traktują syntetyczne dołączenia strukturalnie identycznie jak jawne (z wyjątkiem inspekcji pochodzenia). Zobacz 13-catalog-and-registry.md §„Rozwijanie Feature sterowane adnotacjami” oraz language-reference/providers/well-known-annotations.md, aby poznać kształt powiązania, semantykę kaskady i reguły kompozycji między stronami.

Budowa topologii — konstruktor topologii i bramka mutacji

  • Mechanizm: rozwijanie AST + rola label-transform gniazda nadzoru.
  • Działanie: Kompilator natywnie odczytuje jawnie zadeklarowane bloki uses ze zwalidowanych komponentów, aby deterministycznie wyznaczyć krawędzie topologiczne między węzłami grafu, pozostawiając blok values całkowicie nieprzejrzystym. Następnie ewaluuje bramkę mutacji, przekazując projekcję grafu — etykiety każdego węzła i values deklarowane przez jego instancję, które kompilator przekazuje bez odczytywania — wraz z nazwą i środowiskiem encji Release do wtyczki nadzoru dołączonej w roli label-transform. Wtyczka ocenia kontekst i zwraca obiekty JSONPatch, aby dynamicznie i automatycznie oznaczać graf (np. wstrzykując etykietę compliance.aggrega.ai/data-class: restricted na podstawie środowiska encji Release lub datastore.aggrega.ai/engine: vector na podstawie zadeklarowanych rozszerzeń bazy danych); poprawki dotyczą wyłącznie etykiet.

Finalizacja grafu

  • Mechanizm: normalizacja.
  • Działanie: Kompilator finalizuje płaski graf reprezentacji pośredniej (IR), zachowując jawne krawędzie topologiczne wyznaczone przez konstruktor topologii. Następnie normalizuje dołączone encje Features i ich ładunki values do płaskiego słownika indeksowanego identyfikatorem węzła, przygotowując niezależny od zdolności graf do walidacji.
    • Normalizacja ładunku IR: Strukturalny kształt IR wymusza jedno źródło prawdy dla konfiguracji: warstwa topologii przenosi wyłącznie strukturę grafu (tożsamość węzłów, krawędzie, etykiety metadanych), a znormalizowany stan konfiguracji znajduje się w osobnym słowniku w pamięci, który kompilator przekazuje kolejnym wtyczkom. Mutatory zmieniające konfigurację zmieniają ją w jednym miejscu; dostawca odczytuje znormalizowany stan bez ryzyka rozbieżności wynikającej z nadmiarowego przechowywania.

Analiza statyczna — analizator statyczny i bramka walidacji

  • Mechanizm: kontrole czystości topologicznej + rola ir-verdict gniazda nadzoru.
  • Działanie: Kompilator przeprowadza abstrakcyjną analizę statyczną grafu IR. Po pierwsze, wyodrębnia ciągi selector z definicji usesSchema i ewaluuje je za pomocą natywnego silnika dopasowywania etykiet w Go (obsługującego semantykę w stylu Kubernetes: AND, OR poprzez in() oraz NOT poprzez !=) na jawnie zdefiniowanych krawędziach grafu, aby zagwarantować bezpieczeństwo typów między węzłami w obrębie zadeklarowanych gniazd. Krawędź na gnieździe ad hoc — takim, które nazwał autor encji Aggregate, a którego katalog nie zadeklarował — nie ma wpisu w katalogu, a zatem nie ma selektora, więc ta kontrola nie ma czego ewaluować i niczego nie brakuje; każda krawędź zapisuje, którym z tych dwóch rodzajów jest, a to, co może przenosić krawędź ad hoc, jest zamiast tego ograniczone przez zadeklarowane provides celu. Ewaluuje także selektory appliesTo i appliesToAnyOf encji Feature, aby sprawdzić, czy dołączone funkcje są zgodne z etykietami komponentu docelowego, a także własny selector każdego wypełnionego slotu dołączenia względem etykiet encji Feature, która go wypełnia. Po drugie, ewaluuje każdy nakaz obecności, który deklaruje encja Component węzła — każdą adnotację features.aggrega.ai/requiredType.<label> — względem ostatecznego zbioru dołączeń tego węzła. Analizator jest właściwym miejscem dla tej kontroli, ponieważ jest pierwszym etapem, który ma obie połowy reguły: adnotacje rozwiązanej encji Component oraz zbiór dołączeń wytworzony przez 5-poziomową kaskadę, uwzględniający na równi dołączenia z encji Aggregate, z podsystemu, z encji Release i z rozwinięcia adnotacji. Nakaz, którego nie spełnia żadne dołączenie, zatrzymuje kompilację; nakaz o nieprawidłowo sformułowanej deklaracji zatrzymuje ją z odrębną diagnostyką, więc uszkodzona deklaracja nigdy nie jest odczytywana jako spełniony wymóg. Po trzecie, wykonuje bramkę walidacji, przekazując pełną strukturę grafu (w tym wszystkie węzły, krawędzie, dołączone funkcje i wstępnie obliczone ścieżki DFS) do wtyczki nadzoru dołączonej w roli ir-verdict. Niestandardowa polityka Wasm przedsiębiorstwa ocenia topologię. Jeśli wtyczka Wasm zwróci tablicę niepowodzeń (np. wykrywając ciągłą ścieżkę od węzła public do węzła restricted bez określonej funkcji proxy), kompilacja zostaje zatrzymana.

Renderowanie

  • Mechanizm: przechwytywanie przed renderowaniem (injectMapping), późne wiązanie (valuesMapping) i gniazda renderujące Wasm (pipeline).
  • Działanie: Końcowa faza generowania artefaktów jest podzielona na ścisłe podfazy czasowe, które działają w stałej kolejności, co utrzymuje deterministyczność wykonania:
    • Mapowanie wstrzyknięć (przechwytywanie przed renderowaniem): Kompilator Go rozwiązuje abstrakcyjny kontrakt .context.inject programisty. Następnie wykonuje szablony Go injectMapping ze wszystkich dołączonych FeatureRecipes zgodnie ze ścisłą kolejnością wykonania 5-poziomowego modelu cebuli (Sub-Aggregate — najpierw własne dołączenia komponentu modułu, potem te deklarowane przez podsystemy jego modułu, od zewnętrznych do wewnętrznych → komponent głównej encji Aggregate → podsystem głównej encji Aggregate → granica encji Release od zewnętrznej do wewnętrznej → część encji Release właściwa dla komponentu). Kompilator natywnie głęboko scala powstałe słowniki na potoku pamięci .context.inject wywołującego. Pozwala to bezpiecznie przepisać zmienne środowiskowe i ciągi połączeń dla wywołującego, zanim bazowa encja Recipe w ogóle je zobaczy. Mapowanie może przepisać to, co dostarczył własny blok inject: wywołującego lub jedno z jego połączeń; klucz, który dostarczyła już inna dołączona encja Feature — poprzez własne mapowanie lub własny blok inject: — zatrzymuje kompilację ze wskazaniem obu dołączeń, więc kolejność wykonania nigdy nie rozstrzyga między wartościami dwóch dołączeń.
    • Preambuła locals: Zanim zostanie uruchomiony jakikolwiek szablon provides, kompilator ewaluuje wpisy .locals encji Recipe w kolejności, w jakiej zostały zapisane, każdy względem samodzielnego kontekstu lokalnego dla węzła — .context.instance_id, .values, .infra oraz wpisów tego samego bloku rozwiązanych do tej pory, ale nie .context.inject ani .context.uses. Wpis może zatem odczytać sąsiedni wpis zdefiniowany nad nim i otrzymuje jego rozwiązaną wartość; kolejność autorska jest częścią kontraktu wszędzie tam, gdzie jeden wpis odczytuje inny, a blok nigdy nie jest przestawiany, aby odwołanie dało się rozwiązać. To wcześniejsze rozwiązanie locals pozwala szablonowi provides odczytać .locals. Szablon .source encji Recipe jest ewaluowany względem tego samego kontekstu po rozwiązaniu tych locals, co zachowuje .locals jako skrót wielokrotnego użytku we wszystkich szablonach encji Recipe i pozwala autorom parametryzować .source (wersję chartu, ścieżkę, rejestr) dla każdej granicy.
    • Renderowanie bazowe (valuesMapping bazowej encji Recipe): Kompilator ewaluuje szablon valuesMapping bazowej encji Recipe. Szablon odczytuje przechwycone ciągi z potoku .context.inject (przepisane podczas mapowania wstrzyknięć), a powstały słownik wartości jest przekazywany dostawcy wskazanemu przez capability encji Recipe — dostawcy helm i helm-chart renderują oba przez Helm — w celu wyrenderowania bazowych artefaktów infrastruktury.
    • Parsowanie i walidacja Workload: W przypadku encji Recipe deklarującej workload: — treść bloku inline albo workload: { $import: <path> } wskazujące plik — ten dokument jest ewaluowany jako szablon względem kontekstu renderowania węzła, następnie parsowany jako YAML do kształtu Workload i sprawdzany: wyrenderowane bajty są walidowane względem schematu Workload, zdekodowana wartość również jest względem niego walidowana (bajty zawierają klucze, które dekodowanie odrzuca, a dekodowanie pomija pole podane jako puste, więc każda z walidacji odrzuca to, czego druga nie widzi), każdy wpis attachments jest sprawdzany względem slotów zadeklarowanych przez featuresSchema powiązanej encji Component, a każde odwołanie do zasobu jest sprawdzane względem rozwiązanego provides slotu, który wskazuje. Niepowodzenie na tym etapie zatrzymuje kompilację. Sparsowana encja Workload jest umieszczana w kontekście szablonu jako .workload, dzięki czemu szablon ewaluowany później na tym samym węźle może ją odczytać.
    • Ewaluacja artefaktów: Każdy wpis, który encja Recipe deklaruje w artifacts: — treść inline lub plik wskazany przez własny $import: tego wpisu — jest odczytywany, parsowany jako szablon, ewaluowany względem pełnego kontekstu szablonu i opatrzony informacją o pochodzeniu kompilacji. Powstała projekcja jest przekazywana dostawcy, który decyduje o formacie wyjściowym, miejscu umieszczenia informacji o pochodzeniu, ścieżce wyjściowej i ostatecznych bajtach. Każdy emitowany plik zapisuje, z której formy autorskiej pochodzi, więc kolizja nazw plików może wskazać każdego współtwórcę.
    • Synteza Workload: Sparsowana encja Workload jest przekazywana dostawcy wskazanemu przez capability encji Recipe, który przekłada ją na natywne zasoby tego dostawcy. Encja Recipe, która nie deklaruje workload:, nie ma tu nic do syntezy; jej pliki pochodzą zamiast tego z renderowania źródła.
    • Renderowanie Feature (generowanie zasobów przez FeatureRecipe): Każde dołączenie na węźle, którego powiązana encja FeatureRecipe ma własne source, workload, artifacts i/lub valuesMapping — wzorzec generowania zasobów, używany dla pomocniczych manifestów, takich jak ServiceMonitor, NetworkPolicy, ConfigMap sidecara lub zasób dostarczający poświadczenia — jest ewaluowane w jednym przebiegu, w tej samej kolejności 5-poziomowego modelu cebuli, którą stosuje mapowanie wstrzyknięć. Istnieje jedna sekwencja nad jednym zbiorem dołączeń: operacyjna encja Feature i encja Feature poświadczeń przechodzą tę samą ścieżkę, a różni je to, co emituje ich FeatureRecipe. Dla każdego dołączenia .values i .infra są przełączane na jego własny zakres; dziedziczy ono ewaluowane .locals bazowej encji Recipe; .attachment_name nazywa renderowaną instancję, a .provides przenosi własne rozwiązane provides dołączenia, ten sam zbiór, który odczytuje konsument. Powstały słownik wartości jest przekazywany dostawcy wskazanemu przez własną zdolność encji FeatureRecipe, a wyrenderowane pliki są dołączane do wyjścia granicy z dwiema współrzędnymi — komponentem, do którego dołączona jest encja Feature, a następnie nazwą, pod którą jest dołączona — dzięki czemu jedna nazwa encji Feature dołączona do kilku komponentów utrzymuje każde dołączenie osobno. Postać tych współrzędnych wynika z własnego układu dostawcy hosta: katalog <component>--<instance>/ obok katalogu komponentu, gdy cel daje każdemu współtwórcy własną pozycję, oraz przedrostek nazwy pliku <component>--<instance>--, gdy cel odczytuje tylko pliki leżące bezpośrednio w katalogu. Encje FeatureRecipes służące wyłącznie wstrzykiwaniu — zawierające tylko injectMapping, już obsłużone podczas mapowania wstrzyknięć — są tutaj pomijane. Podobnie jak poprzednie podfazy, renderowanie funkcji działa dla jednego komponentu naraz, więc dołączenie jest zwykle ewaluowane zaraz po komponencie, do którego jest dołączone. Dołączenie, którego FeatureRecipe deklaruje readsCallerRenderFacts: true lub readsTargetRenderFacts: true, jest natomiast ewaluowane dopiero wtedy, gdy wyrenderowały się wszystkie komponenty i wszystkie dołączenia, które nie deklarują żadnej z tych opcji — tak że do tego czasu wyrenderował się każdy komponent łączący się z jego hostem i każdy, z którym jego host jest połączony — a jego wyjście trafia tam, gdzie trafiłoby w przeciwnym razie.
    • Potok wtyczek (wykonywanie kroków Wasm): Kompilator odczytuje tablicę pipeline encji Recipe i wykonuje jej kroki w zadeklarowanej kolejności. Uruchamia nazwaną wtyczkę Wasm każdego kroku na wyrenderowanych dokumentach węzła, stosuje operacje JSON Patch RFC 6902 zwrócone przez krok do dokumentów, których te operacje dotyczą, i emituje obok nich efekty uboczne kroku — to mechanizm stojący za precyzyjnymi mutacjami, takimi jak wstrzyknięcie sidecara Envoy lub zamontowanie sekretu przez VolumeMount. Krok, którego bramka when: renderuje się jako fałsz, jest pomijany jako przejście bez zmian, a zbiór dokumentów pozostaje niezmieniony dla następnego kroku. URI plugin każdego kroku jest przed wykonaniem rozwiązywany do zweryfikowanych bajtów artefaktu, które plik blokady przypina według skrótu. Kroki pipeline encji FeatureRecipe są wykonywane w ten sam sposób, na własnych wyrenderowanych dokumentach dołączenia oraz, w przypadku dołączenia o zakresie komponentu, obok nich na dokumentach komponentu hosta.

Wszystkie trzy rodzaje wejścia encji Recipe docierają do kompilatora: source: + valuesMapping: przez renderowanie bazowe, workload: przez parsowanie Workload i syntezę Workload, a artifacts: przez ewaluację artefaktów. To, które z nich można przekazać danemu dostawcy, nie jest rozstrzygane podetap po podetapie — jest ustalane raz na węzeł, przed jakimkolwiek wywołaniem renderowania, na podstawie własnego zadeklarowanego kontraktu dostawcy, więc encja Recipe, której rodzaju wejścia powiązany dostawca nie akceptuje, jest odrzucana w tym miejscu, a nie w trakcie renderowania. Zobacz 16-recipe-input-composition.md, aby poznać model kompozycji trzech rodzajów wejścia, rodzaj Workload i mechanizm artefaktów, oraz Status języka, aby sprawdzić, który dostawca akceptuje który rodzaj.

Wyjście natywne dla GitOps

Aby pozostać ściśle bez własnego zdania co do tego, jak stosowane jest jego wyjście, wtyczki renderujące zapisują wygenerowane artefakty w czystej strukturze katalogów odizolowanej według granic (np. dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). Pozwala to zewnętrznym kontrolerom GitOps (takim jak ArgoCD lub Flux) synchronizować i stosować infrastrukturę, a kompilator Aggrega nigdy nie potrzebuje poświadczeń do API działającego klastra.

graph TD
    subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
        direction TB
        A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
        
        B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
        
        C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
        
        D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
    end
graph LR
    E["Rendering"]
    E -->|"Stringified Artifacts"| F["Helm Charts"]
    E -->|"Stringified Artifacts"| G["Docker Compose"]
    E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
    E -->|"Stringified Artifacts"| I["Terraform Configuration"]
    E -->|"Stringified Artifacts"| J["CloudFormation Templates"]

Mapa źródeł infrastruktury

Aggrega kompiluje plik Aggregate.yaml liczący ok. 30 wierszy do tysięcy wierszy fizycznej konfiguracji JSON lub YAML. Bez sposobu na prześledzenie działającego zasobu z powrotem do jego źródła debugowanie awarii w „main.tf.json, wiersz 4032” zmusza programistów do ręcznego odtwarzania mapowania. Wtyczki renderujące Aggrega rozwiązują ten problem, scalając identyfikatory śledzenia z natywną powierzchnią metadanych dostawcy — metadata.labels i metadata.annotations dla Kubernetes, komentarzem o pochodzeniu dla Terraform i odpowiadającymi im konwencjami poszczególnych dostawców — dzięki czemu każdy wyrenderowany obiekt niesie wskaźnik do źródła, z którego powstał. Etykieta aggrega.ai/compiler-version (opisana w governance-and-compliance §5) jest jednym z kluczy śledzenia w tej rodzinie; obok niej znacznik zawiera aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri i aggrega.ai/environment, a emituje go każdy z dostawców helm, helm-chart, compose, terraform i cloudformation — dostawca helm-chart w plikach szablonów, które encja Recipe dodaje do chartu, ponieważ własne szablony chartu kopiuje bez zmian.

Znacznik nie zawiera żadnego klucza identyfikującego pochodzenie funkcji ani typ katalogowy.

Wraz z kompilatorem dostarczane są jeszcze dwa narzędzia debugowania. aggrega build --trace zapisuje stan pośredni każdego węzła, przebieg po przebiegu, do .trace/ obok dist/, dla autora encji Recipe sprawdzającego, co każdy etap otrzymał i wytworzył; a diagnostyka zatrzymująca build niesie kategorię powierzchni autorskiej, do której należy — DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR i pozostałe — wszędzie tam, gdzie awaria ją ma, więc wskazuje właściwego autora. Błędy, które śledzą nieprawidłowe pole wygenerowanego manifestu aż do wiersza szablonu, który je wytworzył, nie są częścią kompilatora.

Potok walidatorów

Faza walidacji schematów w rozwiązywaniu opiera się na potoku walidatorów, który przekształca treść specyfikacji encji (forma kompaktowa, JSON Schema w YAML lub forma mieszana) w ujednolicony dokument JSON Schema 2020-12 z pochodzeniem dla każdego liścia, a następnie waliduje względem niego treść instancji napisaną przez programistów. Pięć etapów wykonuje się kolejno jako czyste przekształcenia; każdy jest deterministyczną funkcją swoich zadeklarowanych wejść.

Etap 1 — Kompilacja formy kompaktowej. Kompilator przechodzi drzewo YAML treści schema:, parameters: i SchemaLibrary; rozdziela przetwarzanie per węzeł (liść w formie kompaktowej, JSON Schema w YAML, odwołanie $ref: albo kompozycja); emituje rozwiązany JSON Schema 2020-12. Forma kompaktowa i JSON Schema w YAML mogą się mieszać na dowolnej granicy węzła za pomocą ucieczki $jsonschema:; kompilator obsługuje przypadek mieszany, przechodząc drzewo i rozdzielając przetwarzanie per węzeł. Przekształcenie jest czystą funkcją: to samo wejście w formie kompaktowej zawsze daje to samo wyjście JSON Schema. Słownik słów kluczowych opisuje language-reference/vocabulary/compact-form-authoring.md.

Etap 2 — Rozwiązywanie spec.templates i $instantiate:. Dla wpisów SchemaLibrary napisanych jako odwołania do szablonów kompilator przechodzi każdy wpis biblioteki wywołujący $instantiate: z $args:, podstawia wartości parametrów jako zamianę literalnych skalarów i tworzy konkretne wpisy schematu. Podstawienie wykonuje się raz na każde załadowanie biblioteki; rozwiązane wpisy są buforowane. Kształt, w jakim pisze się encję biblioteki, opisuje language-reference/entities/schemalibrary.md.

Etap 3 — Rozwijanie $ref: między dokumentami. Dla odwołań do SchemaLibrary przez $ref: (forma tożsamościowa <Library>#/schemas/<entry>) kompilator przechodzi łańcuch odwołań w czasie kompilacji, przekazując stos rozwiązywania; treść, do której prowadzi odwołanie, zostaje wstawiona do schematu konsumenta. Rozwijanie zachowuje wykrywanie cykli (cykle zatrzymują build błędem wskazującym łańcuch), zabezpieczenie „tożsamość, nie lokalizacja” (odwołanie zawierające host rejestru zatrzymuje build ze wskazówką, by użyć formy tożsamościowej — odwołania adresują biblioteki przez tożsamość, nie przez fizyczną lokalizację) oraz kompozycję z jednego źródła (bloki $ref: przyjmują wyłącznie samo odwołanie; nadpisania po stronie konsumenta składa się przez allOf: z JSON Schema). Semantykę rozwiązywania opisuje language-reference/vocabulary/cross-document-ref.md.

Etap 4 — Synteza mostu dla featuresSchema:. Kompilator przechodzi treść featuresSchema: każdej encji w kolejności autora i emituje fragment JSON Schema opisujący kształt wypełnienia, które może związać każdy slot dołączenia, ze słowem kluczowym rozszerzenia x-aggrega-inject: na slocie deklarującym listę dozwolonych inject. Ten fragment jest kompilowany i sprawdzany osobno, względem napisanego bloku dołączeń, zamiast być włączany do treści schema: przeznaczonej dla programisty; słowo kluczowe rozszerzenia to metadane, które walidacja JSON Schema ignoruje, i żaden późniejszy etap nie odczytuje go z powrotem z fragmentu — sprawdzenie potrzebujące listy dozwolonych danego slotu czyta slot. Tablica gniazd usesSchema: nie jest rzutowana na żaden fragment: selector: i inject: gniazda są odczytywane jako typowany YAML, który napisał architekt, a valueSchema: / infraSchema: gniazda dla każdej krawędzi jest kompilowany osobno. Synteza jest czystą funkcją swoich wejść.

Etap 5 — Własny mechanizm scalania z pochodzeniem. Dla encji deklarujących extends: kompilator przechodzi łańcuch rodziców; rozwiązany JSON Schema rodzica staje się bazą; nadpisania dziecka nakłada się na wierzch. Każdy liść w rozwiązanym schemacie nosi znacznik pochodzenia (ścieżka pliku, numer wiersza, pochodzenie od rodzica lub dziecka). Wyjście mechanizmu scalania jest tym, co zużywa silnik walidatora; silnik walidatora to niezmodyfikowana zewnętrzna implementacja zgodna z JSON Schema 2020-12, otoczona deterministycznym mechanizmem przechodzenia, który emituje wyniki w ustalonej kolejności.

Pięć etapów wykonuje się, zanim silnik walidatora zobaczy schemat. Silnik otrzymuje jeden rozwiązany dokument JSON Schema 2020-12 oraz treść instancji programisty; tworzy raport walidacji. Formater błędów korzysta ze znaczników pochodzenia, aby emitować diagnostykę dla użytkownika, która jasno wskazuje pozycje w źródle — w tym plik źródłowy ograniczenia, które encja Feature odziedziczyła po swojej bazie, zamiast napisać je sama.

Potok walidatora działa tam, gdzie każdy ładunek po raz pierwszy jest kompletny — dla values i infra komponentu podczas rozwiązywania, dla komponentów podagregatu, gdy budowa topologii je włącza, oraz dla ładunku dołączenia przy finalizacji grafu — dzięki czemu ustalenie schematu zatrzymuje build, zanim analiza statyczna oceni jakikolwiek selektor, i przed ewaluacją asercji, co pozwala szablonom asercji polegać na zwalidowanych ładunkach.

Zachowanie determinizmu w całym potoku

Każdy etap potoku kompilacji zachowuje niezmiennik deterministycznego wyjścia: przy tych samych plikach źródłowych, tym samym lockfile i tej samej wersji kompilatora build daje bajtowo identyczne wyjście. Niezmiennik jest fundamentalny — adresowanie treścią w lockfile wymaga stabilnych skrótów artefaktów; powtarzalne buildy wymagają, aby release napisany na laptopie programisty A kompilował się do tego samego wyjścia na laptopie programisty B i w CI; możliwość przeglądania różnic wymaga, aby zmiany w źródle były jedynymi zmianami w skompilowanym wyjściu.

Determinizm zachowuje niewielka liczba zasad dyscypliny, których przestrzega każde przekształcenie:

  • Stała kolejność iteracji. Każde przejście po YAML w kształcie mapy iteruje w stałej kolejności, ponieważ natywna iteracja map w Go jest losowa. W większości etapów kompilator sortuje przed iteracją (kompilator formy kompaktowej, mechanizm scalania, resolver spec.templates, formater błędów, serializator YAML); rzutowanie slotów dołączeń przenosi natomiast kolejność autora, więc kolejność właściwości tablicy slotów jest kolejnością, w jakiej ją napisano.
  • Brak osadzania czasu. Kompilacja nie osadza znaczników czasu w wyjściu. Build o 14:00 daje ten sam artefakt co build o 2:00. Metadane pochodzenia mechanizmu scalania używają plik:wiersz, a nie plik:znacznik czasu.
  • Ścieżki względne wobec workspace. Wszystkie ścieżki w rozwiązanym wyjściu są względne wobec workspace; warstwa rozwiązywania ścieżek normalizuje je, zanim trafią do jakiegokolwiek wyjścia.
  • Brak losowych źródeł i stanu zewnętrznego. Przekształcenia są czystymi funkcjami swoich zadeklarowanych wejść (treść encji, łańcuch rodziców, lockfile). Stan zewnętrzny jest sprawdzany tylko podczas rozwiązywania (pobieranie artefaktów OCI), a rozwiązana treść jest adresowana treścią przez skrót.
  • Kanoniczna serializacja YAML. Dla jednego wejścia wyjście jest zapisywane w jednej stałej formie: ta sama kolejność kluczy na każdym poziomie zagnieżdżenia przy każdym uruchomieniu, przy czym tablice i tablice enum: zachowują kolejność wejściową; wcięcie 2 spacji; końce wierszy Unix LF; ciągi bez cudzysłowów tam, gdzie YAML na to pozwala; forma logiczna true/false; null pomijany dla nieobecnych pól.
  • Alfabetyczna kolejność $defs:. Wpisy $defs: schematu są emitowane w alfabetycznej kolejności kluczy w rozwiązanym JSON Schema. $defs: jest koncepcyjnie słownikiem, a nie uporządkowaną listą; kolejność alfabetyczna sprawia, że różnice są przewidywalne mimo reorganizacji źródła.
  • Równoległość nie przenika do wyjścia. Kompilator może zrównoleglać niezależne jednostki (różne encje mogą kompilować się współbieżnie). Wyniki równoległe są zbierane w deterministyczną strukturę (np. posortowaną według nazwy encji) przed serializacją.

Testy end-to-end kompilatora kompilują każdy fixture kilka razy w ramach jednego testu i sprawdzają, czy każde uruchomienie emituje te same pliki o identycznej co do bajtu zawartości. To właśnie powtarzanie kompilacji wychwytuje wyciek kolejności iteracji map lub iterację po nieposortowanym zbiorze, które w większości uruchomień dają stabilne wyjście, a tylko czasami się rozjeżdżają. Testy działają wraz z resztą zestawu testów kompilatora.

Niezmiennik deterministycznego wyjścia obowiązuje w czasie budowania: te same pliki źródłowe + ten sam lockfile + ta sama wersja kompilatora dają bajtowo identyczne wyjście. Towarzysząca mu właściwość w czasie blokowania (te same pliki źródłowe + ten sam stan rejestru dają ten sam lockfile) jest słabsza — rejestry są zmienne (można publikować nowe wersje; można dodawać sidecary; metadane poszczególnych komponentów mogą ewoluować), więc dwa wywołania blokowania dla tych samych plików źródłowych w różnym czasie mogą dać różne lockfile. Właśnie temu służy lockfile, zgodnie z konwencjami w npm, Cargo i Go. Ze świeżego lockfile build daje deterministyczne wyjście. Rozdzielenie tych dwóch momentów sprawia, że zmienność po stronie rejestru jest do zaakceptowania: sidecar opublikowany w czasie T2 zmienia kolejne wywołanie blokowania; nie zmienia buildów opartych na lockfile wygenerowanym w czasie T1.