Aggregate
Koncepcyjna rola encji Aggregate (Domena 1 — deklaratywny plan topologii tworzony przez programistę) jest opisana w architecture/04-entity-taxonomy.md. Wzorce kompozycji (podsystemy, zagnieżdżone agregaty, Zero-Port Convention, Parameter Hoisting) są opisane w architecture/06-data-taxonomy-and-composition.md. Ta strona omawia sposób tworzenia encji Aggregate na potrzeby katalogu — w szczególności tworzenie wielokrotnego użytku modułów Aggregate przeznaczonych do dystrybucji w katalogu.
Zakres encji Component: domyślny podsystem
Encja Aggregate organizuje komponenty w podsystemy — nazwane grupy dla zagadnień przekrojowych (warstwa danych, warstwa brzegowa), które mają własną kaskadę adnotacji. Większość encji Aggregates ma jedną grupę, więc nie wymaga ona żadnej ceremonii.
Pojedynczy zakres (domyślnie). Komponenty należy definiować bezpośrednio pod spec.components: i pominąć blok subsystems::
spec: components: api: type: core/server:1.0.0 worker: type: core/worker:1.0.0Kompilator włącza je do syntetyzowanego podsystemu default. Tożsamość węzłów się nie zmienia — api pozostaje api, nigdy default.api — dlatego encja Aggregate zdefiniowana w ten sposób jest wymienna z jawną postacią z jednym podsystemem, a odwołania do niej (w celach uses:, w diagnostyce) używają samej ścieżki spec.components.<name>. Syntetyzowany zakres jest rzetelnie zapisywany w eksportowanym IR (ze znacznikiem syntetyzowanego podsystemu), ale nigdy nie pojawia się w ścieżkach, które autor zapisuje lub odczytuje.
Wiele zakresów. Gdy komponenty dzielą się na odrębne grupy przekrojowe, należy zadeklarować nazwane podsystemy pod subsystems:. Każdy podsystem ma własne komponenty i kaskadę adnotacji oraz może zawierać kolejne zagnieżdżone podsystemy.
Wzajemne wykluczanie. spec.components: i spec.subsystems: wykluczają się wzajemnie na poziomie głównym encji Aggregate — należy użyć jednego albo drugiego, nigdy obu. Dokument deklarujący oba zatrzymuje się przy wczytywaniu z błędem koperty. (Podsystem, któremu programista jawnie nada nazwę default, jest zwykłym zadeklarowanym podsystemem, adresowanym pełną ścieżką spec.subsystems.default.components.<name> — pomijanie syntetyzowanego zakresu zależy od pochodzenia, a nie od nazwy.)
Moduły Aggregate wielokrotnego użytku
Encje Aggregates pełnią zarówno rolę głównej encji Aggregate budowanej przez encję Release, jak i modułów wielokrotnego użytku. Nadrzędna encja Aggregate może zadeklarować podrzędną encję Aggregate dokładnie tak jak komponent, przekazując do niej parameters. Aby uniknąć ścisłego powiązania, podrzędne encje Aggregates udostępniają kontrakt exportedComponents:, ustanawiający stabilną nazwę interfejsu publicznego. Element nadrzędny dociera do komponentów modułu wyłącznie przez ten interfejs: cel uses: to nazwa modułu, kropka i jeden z jego wyeksportowanych aliasów, a kompilator podłącza krawędź do wewnętrznego komponentu wskazanego przez alias. Cel, który sięga do modułu pod jakąkolwiek inną nazwą — nazwą komponentu wewnątrz modułu albo ścieżką do modułu zagnieżdżonego w nim — zatrzymuje kompilację, wskazując moduł i eksportowane przez niego aliasy; zob. A uses target names a module’s component the module does not export (Cel wskazuje komponent modułu, którego moduł nie eksportuje).
Dlaczego jawna lista exportedComponents:. Autorzy modułu decydują, które z jego komponentów tworzą interfejs publiczny, a które pozostają szczegółem implementacji. Ponieważ element nadrzędny może wskazać tylko to, co lista publikuje, wnętrze modułu można refaktoryzować — zmienić nazwę komponentu, podzielić jeden komponent na dwa, zastąpić workera usługą zarządzaną — nie psując żadnego elementu nadrzędnego, o ile każda opublikowana nazwa nadal wskazuje komponent. Lista kosztuje jeden wpis na każdy publikowany komponent, a komponent można opublikować pod jego własną nazwą (store: store), jeśli to tej nazwy mają używać importujący. Ta sama reguła obowiązuje wewnątrz kompozycji: moduł dociera do importowanego modułu przez wyeksportowane aliasy tego modułu. Encja Release może połączyć ze sobą dwa komponenty jednego modułu, ponieważ takie połączenie nie przekracza interfejsu żadnego modułu.
Ponowny eksport interfejsu zagnieżdżonego modułu. Wpis exportedComponents: może wskazywać na eksportowany alias zagnieżdżonego podagregatu zamiast na bezpośrednio zadeklarowany komponent — moduł ponownie publikuje wtedy część importowanego modułu pod nazwą własnego interfejsu, opcjonalnie pod nową nazwą. Krawędź uses: kierowana na taki ponownie eksportowany alias rozwiązuje się przechodnio przez łańcuch aż do konkretnego węzła wewnętrznego, dzięki czemu moduł włącza głębsze moduły do własnego interfejsu publicznego bez ujawniania ich wewnętrznego układu, a konsument nigdy nie musi wiedzieć, jak głęboko zagnieżdżony jest cel. Dyscyplina stabilnego interfejsu obowiązuje na każdym kroku: każdy moduł ponownie eksportuje tylko to, co sam zdecyduje się opublikować. Ponownie eksportowany cel, który nie rozwiązuje się do żadnego węzła wewnętrznego, zatrzymuje kompilację z wyraźnym błędem tak samo jak bezpośredni wiszący cel, a łańcuch ponownych eksportów zamykający się na sobie jest odrzucany, a nie śledzony w nieskończoność.
Deklaracje modułu są sprawdzane tak samo jak deklaracje encji Aggregate. Dokument modułu jest odczytywany dopiero wtedy, gdy budowana jest kompozycja, która go importuje, a jego deklaracje są od tego momentu sprawdzane na dowolnej głębokości zagnieżdżenia. Własny blok inject: komponentu modułu podlega liście dozwolonych spec.inject jego typu oraz regułom zakazującym dwukrotnego zajęcia jednego klucza dostarczania i odczytywania klucza, którego typ nie publikuje. Dołączenie zapisane w jednym z własnych podsystemów modułu może wskazywać tylko gniazdo deklarowane przez jego encję Feature; to samo dotyczy dołączenia, które encja Release zapisuje względem komponentu wniesionego przez moduł.
Dołączenia podsystemów modułu docierają do jego komponentów. Encja Feature, którą moduł dołącza w jednym z własnych podsystemów, kaskadowo obejmuje każdy komponent deklarowany przez moduł pod tym podsystemem, łącznie z zagnieżdżonymi podsystemami, dokładnie tak jak dołączenie podsystemu w encji Aggregate — i tylko te komponenty, nigdy komponent importującej encji Aggregate znajdujący się pod podsystemem o tej samej nazwie. Jest ono wartościowane bezpośrednio po własnych dołączeniach komponentu, podsystemy zewnętrzne przed wewnętrznymi. W polu zapisanym przez oba wygrywa własne dołączenie komponentu o tej samej nazwie, a pola, które ono pomija, zachowują wartości podsystemu. Każdy komponent, do którego dociera, sprawdza je względem appliesTo encji Feature. Ustalenie dotyczące własnych deklaracji modułu wskazuje moduł i klucz w jego dokumencie — na przykład .spec.subsystems.<subsystem>.features.<attachment> — więc poprawkę wprowadza się w module, w którym znajduje się deklaracja, a nie w importującej go encji Aggregate.
Położenie w katalogu
Moduł Aggregate wielokrotnego użytku znajduje się w katalogu rodzaju aggregate/ pod ścieżką, którą segment po segmencie wyznacza jego metadata.name, z katalogiem wersji na końcu:
aggrega-catalog/└── aggregate/ └── {module-name}/ # the module's metadata.name, segment for segment └── {version}/ # the module's metadata.version └── aggregate.yaml # The module definitionNazwa modułu może zaczynać się od segmentu {publisher} określającego dostawcę lub autora — core dla biblioteki standardowej, acme dla przedsiębiorstwa — i tak właśnie nazwane są opublikowane moduły biblioteki standardowej: core/agenta znajduje się w aggregate/core/agenta/1.0.0/aggregate.yaml. Nazwa złożona z jednego tokenu leży o jeden poziom płycej, w aggregate/{module-name}/{version}/aggregate.yaml. Obie formy są poprawne; nazwę zapisuje autor, a katalog ją odzwierciedla. To odzwierciedlenie jest konwencją katalogu, a nie czymś, co sprawdza kompilator — moduł jest odnajdywany po deklarowanej nazwie, a nie po położeniu pliku.
URI OCI: hub.aggrega.ai/aggregate/{module-name}:{version}, małymi literami — moduł o nazwie core/agenta jest więc publikowany pod hub.aggrega.ai/aggregate/core/agenta:1.0.0, a moduł o nazwie db-module pod hub.aggrega.ai/aggregate/db-module:1.0.0.
Wzorzec modułu
Moduł podrzędny (aggregate/child-database-module/1.0.0/aggregate.yaml, opublikowany jako hub.aggrega.ai/aggregate/child-database-module:1.0.0):
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: components: internal-pg-primary: type: core/postgres:1.0.0
exportedComponents: # The Public Contract (Written once by the module author) primary_db: "internal-pg-primary"Nadrzędna encja Aggregate:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_dbEtykiety modułu
Gdy encja Aggregate jest publikowana w katalogu jako moduł wielokrotnego użytku, może nosić metadata.labels w swojej kopercie YAML — na przykład aggregate.aggrega.ai/tier: infrastructure lub aggregate.aggrega.ai/compliance: pci-dss. Etykiety te opisują tożsamość modułu i są przenoszone w opublikowanym dokumencie modułu; żadne polecenie jeszcze ich nie odczytuje. Wyszukiwanie w katalogu nie indeksuje encji Aggregates, a graf kompilacji nie przenosi ani etykiet modułu, ani jego nazwy katalogowej, więc polityka zarządcza nie może wybierać komponentów według modułu, z którego pochodzą.
Kluczowe rozróżnienie. Etykiety encji Aggregate opisują tożsamość modułu wielokrotnego użytku w katalogu. Nie przechodzą kaskadowo na podrzędne węzły komponentów. Etykiety komponentów pochodzą wyłącznie z encji katalogowej Component w Domenie 2. Jeśli programista importuje moduł oznaczony aggregate.aggrega.ai/tier: infrastructure, poszczególne komponenty w tym module zachowują tylko własne etykiety zdefiniowane w katalogu (np. component.aggrega.ai/type: stateful-server). Etykieta encji Aggregate nigdy nie jest wstawiana do słownika labels węzła IR.
Pełne omówienie złożonych Aggregates i wzorca modułu (w tym zasady braku podkomponentów dla Components) oraz mechanizmu przekrojowego grupowania subsystems zawiera architecture/06-data-taxonomy-and-composition.md §6. Powierzchnię tworzenia typowanego kontraktu parameters opisuje vocabulary/data-pillars.
Typowane kontrakty parametrów
Blok spec.parameters: encji Aggregate deklaruje typowany kontrakt dla parametrów, które wypełnia encja Release. Każdy slot parametru ma zadeklarowany type, opcjonalny description, opcjonalny default, opcjonalne ograniczenia przestrzeni wartości oraz (w slotach typu obiektowego) zagnieżdżoną strukturę. Kompilator podczas rozwiązywania sprawdza każdą wartość dostarczoną przez encję Release względem kontraktu, zanim nastąpi interpolacja parametrów.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: web-app version: 1.0.0spec: parameters: region: type: string description: Cloud region the deployment targets enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1] default_locale: type: string description: Default UI locale presented to end users enum: [en-US, en-GB, fr-FR, ja-JP] default: en-US enable_debug: type: boolean description: Toggle verbose request logging default: false feature_flags: type: object description: Per-feature enablement map valuesType: { type: boolean } default: {} allowed_hosts: type: array description: Hostnames the ingress accepts items: { type: string, format: hostname } min: 1 default: ["web-app.example.com"]
components: web: type: core/web-server:1.0.0 values: default_locale: "{{ .parameters.default_locale }}" region: "{{ .parameters.region }}" debug: {{ .parameters.enable_debug }}Cudzysłowy w każdym odwołaniu są celowe: to one decydują o typie, z jakim dociera wyniesiona wartość. Zob. templates/parameters-context.md.
Słownik slotów parametrów
Typowany blok parameters: przyjmuje słownik formy kompaktowej: type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate i validateMessage (niestandardowe sprawdzenie i komunikat, który zgłasza), items (dla tablic), properties (dla obiektów), valuesType (dla map wartości typowanych) oraz required: true (znacznik na poziomie slotu). Trzy z tych słów kluczowych przyjmują jako wartość kontrakt, a nie zwykłe ustawienie — items, valuesType i każdy wpis w properties — a w slocie parametru taki zagnieżdżony kontrakt zapisuje się w tej samej typowanej formie co otaczający go slot: valuesType: { type: boolean }, a nie valuesType: boolean. Przed interpolacją kompilator sprawdza scaloną mapę parametrów bezpośrednio względem tych deklaracji: parametr niezadeklarowany w żadnym slocie jest odrzucany, slot oznaczony required: true, którego nie wypełnia encja Release ani nie dostarcza default, zatrzymuje kompilację, a każda dostarczona wartość jest sprawdzana względem zadeklarowanego type slotu, przynależności do enum, granic minLength i maxLength, wyrażenia regularnego pattern i format w slocie tekstowym oraz granic min i max — wartości slotu liczbowego, długości slotu tekstowego i liczby elementów slotu tablicowego. Sloty obiektowe i tablicowe są sprawdzane rekurencyjnie: każdy wpis w properties i każdy element względem items sprawdza się tak samo, kontrakt valuesType obejmuje klucze, których properties nie wymienia, a zagnieżdżony klucz niewymieniony w żadnej deklaracji jest odrzucany. Pełny słownik słów kluczowych, w tym miejsca, w których filar schema: zapisuje te słowa kluczowe inaczej, opisuje vocabulary/compact-form-authoring.md.
Poniższe słowa kluczowe są sprawdzane także w samej deklaracji, zanim zostanie odczytana jakakolwiek wartość encji Release, więc slot, który nie mógłby niczego ograniczać, zatrzymuje kompilację nawet wtedy, gdy żadna encja Release go nie wypełnia:
- Granice długości są równe zero lub większe. Ujemny
minLengthlubmaxLengthwe własnej deklaracji parametru jest odrzucany przez schemat encji Aggregate podczas jej ładowania, z podaniem parametru i klucza. Wewnątrz zagnieżdżonego kontraktu — witems,propertieslubvaluesType— granica długości jest odczytywana tak, jak ją zapisano, i podczas ładowania encji Aggregate nie jest sprawdzana względem tego minimum, dlatego również tam należy zapisywać ją jako zero lub więcej: ujemnyminLengthniczego nie narzuca, a ujemnymaxLengthodrzuca każdą wartość. minimaxmuszą coś ograniczać. W slocie logicznym lub obiektowym ta para niczego nie ogranicza, więcminlubmaxzapisane w nim są odrzucane podczas wczytywania encji Aggregate, ze wskazaniem parametru i klucza.- Wzorzec musi się kompilować. Każdy
patternjest kompilowany jako wyrażenie regularne podczas odczytu kontraktu parametrów — w samym slocie i w każdym zagnieżdżonym kontrakcie, na dowolnej głębokości — a taki, który się nie kompiluje, jest odrzucany z podaniem parametru, wzorca i przyczyny. Kontrakt jest odczytywany przy każdej kompilacji, pobraniu i walidacji encji Release, która dociera do encji Aggregate, niezależnie od tego, czy jest to własna encja Aggregate tej encji Release, czy moduł przez nią importowany. Sprawdzenie wartości dopasowuje następnie każdą dostarczoną wartość do tego samego skompilowanego wyrażenia. - Format musi być jednym z tych, które sprawdza kompilator.
formatwskazuje jedną z nazwemail,uri,hostname,ipv4,ipv6,uuid,date-timeidate, zapisanych tak jak w JSON Schema. Każda inna nazwa — literówka, np.emial, lub nazwa niezdefiniowana w JSON Schema, np.password— jest odrzucana podczas ładowania encji Aggregate, z podaniem parametru i listy obsługiwanych nazw: w samym slocie przez schemat encji Aggregate, a wewnątrz zagnieżdżonego kontraktu, na dowolnej głębokości, podczas odczytu kontraktu parametrów. Dostarczony ciąg, który nie ma wskazanego formatu, jest następnie odrzucany z podaniem parametru, wartości i formatu. Co sprawdza każda nazwa, opisujevocabulary/compact-form-authoring.md.
Parametry typu obiektowego i tablicowego
Sloty parametrów przyjmują każdy typ obsługiwany przez formę kompaktową, w tym zagnieżdżone obiekty i tablice typowanych elementów:
spec: parameters: database_config: type: object description: Database connection configuration properties: host: { type: string, required: true } port: { type: integer, min: 1, max: 65535, default: 5432 } ssl_mode: { type: string, enum: [disable, require, verify-full], default: require } pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels: type: array description: Custom Prometheus labels to attach to scraped metrics items: type: object properties: name: { type: string, required: true } value: { type: string, required: true }Encja Release wypełnia parametry typu obiektowego strukturalnym YAML; kompilator przed interpolacją sprawdza strukturę względem zadeklarowanego schematu. Szablony odwołujące się do pól obiektu używają standardowej składni szablonów Go: {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }} itd.
Walidacja kontraktu parametrów
Najpierw, w chwili odczytu, sprawdzany jest sam kontrakt — kontrole ograniczeń długości i wzorców opisane powyżej w sekcji „Parameter slot vocabulary”. Następnie kompilator wykonuje podczas przetwarzania parametrów trzy kroki:
- Uzupełnianie wartości domyślnych — sloty ze zdefiniowanym
default:, dla których encja Release nie dostarcza wartości, otrzymują wartość domyślną. Parametry będące zagnieżdżonymi obiektami mają trzyprzypadkową semantykę dla pominiętych, jawnie pustych i częściowo wypełnionych slotów nadrzędnych: pominięcie slotu nadrzędnego uzupełnia wartości domyślne slotów podrzędnych, zapisanie slotu nadrzędnego jako{}zachowuje jawną pustą wartość (wyłącza wartości domyślne slotów podrzędnych), a zapisanie slotu nadrzędnego jako niepustej mapy uzupełnia tylko te sloty podrzędne, których encja Release nie dostarczyła. Przykłady YAML i przewodnik „kiedy używać której formy” zawieratemplates/parameters-context.md. - Walidacja kontraktu — każda wartość w scalonej mapie, niezależnie od tego, czy dostarczyła ją encja Release, czy uzupełniło ją
default:, jest sprawdzana względem zadeklarowanych ograniczeńtype/enum/min/max/pattern/ struktury zagnieżdżonej. Błędy walidacji zatrzymują kompilację z czytelnym komunikatem wskazującym błędny slot, dostarczoną wartość i naruszone ograniczenie. Brak wymaganego parametru bezdefault:powoduje podobne zatrzymanie z nazwą slotu. - Interpolacja — kompilator przetwarza cały tekst encji Aggregate jako szablon, zanim odczyta go jako YAML, i zastępuje każde odwołanie
{{ .parameters.<slot> }}— zwykle w ciągachvalues:komponentów / funkcji / podagregatów — rozstrzygniętą wartością; każde inne{{w tekście również jest odczytywane jako składnia szablonu, więc wartość zawierająca własne podwójne nawiasy klamrowe — na przykład wyeksportowana definicja platformy przepływów — zapisuje każde{{jako{{"{{"}}, jak opisano w sekcji Tekst zawierający własne podwójne nawiasy klamrowe. Po tym przebiegu powierzchnie szablonów wartości otrzymują już zinterpolowane literały i nie dostają.parametersw swoim kontekście szablonu.
Scalona mapa parametrów pozostaje dostępna przez całe renderowanie, aby umożliwić ewaluację szablonów ścieżek. Tworzone przez operatora szablony directory: i subDirectory: na granicach encji Release odczytują .parameters.<slot> bezpośrednio w czasie renderowania, w ramach zamkniętej listy dozwolonych zmiennych; generowanie ścieżek wymaga słownictwa regionu / środowiska do układu artefaktów per środowisko, a asymetryczne uprawnienie utrzymuje tę kwestię operatora w obrębie powierzchni operatora bez przechodzenia przez values encji Aggregate. Mapa pozostaje czytelna do zakończenia wszystkich faz renderowania i jest osiągalna tylko z kompilacji, dla której została rozstrzygnięta; recepty korzystające z tworzonych przez programistę values: widzą ciągi po interpolacji, natomiast szablony ścieżek widzą bieżące dane .parameters przez całe renderowanie. Macierz dostępności szablonów ścieżek zawiera wiersz 3 w templates/expansion-matrix.md, a listę dozwolonych zmiennych szablonów ścieżek — path-template-variables.md.
Szerszą listę kontrolną przenoszenia parametrów (deklaracja w encji Aggregate → odwołanie w values → wypełnienie w encji Release → użycie w encji Recipe) oraz mechanikę między filarami opisuje vocabulary/data-pillars.md §“Parameters” i §“The parameter-hoisting checklist”. Pola kontekstu szablonu udostępniane podczas interpolacji oraz wyjątek dla szablonów ścieżek opisuje templates/parameters-context.md.
Krawędź uses to wywołanie deklarowane przez encję Aggregate
Krawędź uses to deklaracja encji Aggregate, że jeden komponent wywołuje inny. Kompilator przekazuje do wywołującego wartości publikowane przez cel i niczego nie ogranicza: sama krawędź ani nie wpuszcza wywołującego, ani nie odmawia nikomu innemu, a obciążenie, które dociera pod adres celu bez krawędzi, i tak do niego dociera.
Ograniczenie, kto może wywoływać komponent i co ten komponent może wywoływać, jest decyzją operatora, podejmowaną dla każdego środowiska w encji Release. Gdy encja Release dołącza do komponentu Feature core/caller-allowlist z katalogu biblioteki standardowej, kompilacja zapisuje politykę sieciową wpuszczającą dokładnie te komponenty, których krawędzie uses na niego wskazują, własne pody tego komponentu oraz źródła wskazane w dołączeniu. Jego odpowiednik dla ruchu wychodzącego, core/egress-allowlist, pozwala komponentowi, do którego jest dołączony, docierać wyłącznie do komponentów, na które wskazują jego własne krawędzie uses, do własnych podów, do DNS klastra oraz do zakresów adresów wymienionych w encji Release. Wywołanie, którego encja Aggregate nie deklaruje jako krawędzi, może wtedy zostać odrzucone przez klaster na dowolnym z końców, wszędzie tam, gdzie jego wtyczka sieciowa egzekwuje polityki sieciowe. Dlatego należy zapisać krawędź dla każdego wywołania wykonywanego przez komponenty, także takiego, które nie wstrzykuje żadnej wartości: brakująca krawędź to wywołanie, które odgrodzony komponent może odrzucić. model-server-caller-allowlist pokazuje serwer modelu osiągalny wyłącznie przez stojącą przed nim bramę.
Własne załączniki połączenia: features we wpisie uses
Połączenie, które komponent definiuje w rozwiniętej formie uses:, jest osobnym wpisem i obok target, inject i values może zawierać załączniki w kluczu features:. Każdy z nich jest kluczowany slotem zadeklarowanym przez gniazdo: konsumująca encja Component wymienia w featuresSchema gniazda sloty, które może wypełnić każde połączenie podpięte przez to gniazdo (zob. Gniazda topologii). W ten sposób jeden komponent przechowuje inne poświadczenie dla każdego komponentu, do którego sięga — brama wywołująca dwa modele z dwoma kluczami albo agent przedstawiający modelowi własny klucz.
spec: parameters: openai_key_secret: { type: string } components: router: type: core/gateway/litellm # its `models` socket declares a `credential` slot values: { model: gpt } # the alias it publishes as its model uses: models: gpt: target: gpt features: credential: type: core/referenced-secret values: origin: "{{ .parameters.openai_key_secret }}" key: api-key plain: target: plain # this connection carries no attachment gpt: type: core/ai-model/openai values: { model: gpt-4o-mini } plain: type: core/ai-model/ollama values: { model: llama3.1 }Załącznik połączenia zawiera type (wymagane), opcjonalny description oraz values dla encji Feature. Nie zawiera uses ani inject: załącznik połączenia nie jest zagnieżdżany, a o tym, jak jego materiał trafia do konsumenta, decyduje encja Recipe konsumującego komponentu, a nie blok inject. Dokument zawierający którykolwiek z tych kluczy jest odrzucany przy wczytywaniu z podaniem nazwy klucza.
Tylko sloty zadeklarowane przez gniazdo. Załącznik pod nazwą, której featuresSchema gniazda nie wymienia, zatrzymuje kompilację przy wczytywaniu, z podaniem połączenia, gniazda, komponentu i slotów, które gniazdo deklaruje — a jeśli nazwa różni się o jedną edycję od któregoś z nich, także tego slotu jako prawdopodobnie zamierzonej pisowni. Wypełniony slot podlega następnie własnej deklaracji slotu na każdym połączeniu: selector, którego etykiety encji Feature nie spełniają, zatrzymuje kompilację na tym wpisie, a slot required pozostawiony pusty na dowolnym połączeniu zatrzymuje ją z podaniem tego połączenia. Gniazdo, które nie deklaruje slotów, nie dopuszcza żadnego załącznika na swoich połączeniach; podobnie gniazdo ad hoc — takie, które encja Aggregate podpina bez deklaracji w encji Component — ponieważ nie deklaruje żadnych slotów. Komponent wniesiony przez podmoduł podlega tej samej regule, a komunikat wskazuje na własny dokument podmodułu. Zob. A connection carries an attachment under a name its socket declares no slot for (Połączenie zawiera załącznik pod nazwą, dla której jego gniazdo nie deklaruje slotu).
Połączenie definiowane przez encję Feature nie zawiera żadnych załączników. Własny blok uses: dołączonej encji Feature — na komponencie lub na podsystemie — ma ten sam kształt, ale przy wczytywaniu dokumentu odrzuca features:. Poświadczenie potrzebne takiemu połączeniu wypełnia slot, który encja Feature deklaruje we własnym featuresSchema, dołączony obok encji Feature; zob. Własne poświadczenie encji Feature.
Nazwa załącznika. Każdy załącznik połączenia staje się załącznikiem komponentu konsumującego o nazwie <alias>.<slot> — alias, pod którym zapisano połączenie, kropka i slot: powyżej gpt.credential. Kropka jest separatorem zarezerwowanym dla nazw składanych przez kompilator, której nie może zawierać żaden alias, slot ani nazwa załącznika w encji Aggregate, więc złożona nazwa nigdy nie jest równa nazwie zapisanej we własnym bloku features: komponentu; encja Release zapisująca ją na komponencie lub granicy jest odrzucana (zob. Konfiguracja połączeń dla poszczególnych krawędzi). Pod tą nazwą warstwa per instancja encji Manifest kluczuje załącznik (zob. Płaskie mapowanie URI), pod nią raportują go diagnostyka i graf IR, i tę wartość FeatureRecipe załącznika odczytuje jako .attachment_name (zob. Nazwy wyprowadzane z załącznika połączenia).
Dalej jest rozwiązywany jak każdy załącznik: encja Manifest wiąże jego typ Feature z encją FeatureRecipe, jego values są walidowane względem schematu encji Feature — błąd jest zgłaszany przy wpisie połączenia, który je zapisał — a jego FeatureRecipe renderuje się względem własnych values i infra załącznika. Od własnych załączników komponentu odróżniają go dwie rzeczy:
- Nie ma go w
.featureskonsumującej encji Recipe. Ten filar zawiera tylko załączniki zapisane we własnym bloku komponentu, więc encja Recipe przeszukująca.featurespod kątem własnych załączników według typu nigdy nie otrzyma poświadczenia połączenia. Encja Recipe odczytuje załącznik połączenia z samego połączenia, pod.context.uses.<alias>.features.<slot>, w kształcie, jaki ma.features— łącznie z rozwiązanymprovides(zob. Załączniki połączenia). - Trafia wyłącznie do konsumenta. Wyrenderowany wynik celu jest taki sam niezależnie od tego, co zawierają docierające do niego połączenia.
Kopia autorskiego bloku w grafie. Graf IR zachowuje blok uses: każdego komponentu w postaci zapisanej przez autora i tam załącznik połączenia zachowuje swoje type i description, ale żadnej ze swoich values. Wartości pojawiają się raz, w załączniku, który ma konsument, gdzie wartość zadeklarowana przez encję Feature jako wrażliwa jest ukrywana.
Encja Release może określić rozmiar zadeklarowanego tu załącznika za pomocą infra lub dołączyć własny załącznik do połączenia, do którego sięga — zob. Konfiguracja połączeń dla poszczególnych krawędzi.
Wyłączanie komponentu lub modułu: active:
Instancja komponentu i moduł podagregatu przyjmują przełącznik active:, który decyduje, czy dana encja w ogóle należy do skompilowanej topologii. Jeśli go pominąć, encja jest obecna; jest to wartość domyślna i zwykły przypadek.
spec: parameters: enable_cache: type: boolean default: false components: api: type: core/server:1.0.0 redis: type: core/redis:1.0.0 active: "{{ .parameters.enable_cache }}" aggregates: reporting: type: my-catalog/reporting-module:1.0.0 active: falseMożna wpisać wartość logiczną bezpośrednio albo szablon nad .parameters, który się do niej rozwiązuje. Forma szablonu jest powodem istnienia przełącznika: pozwala encji Release decydować o obecności encji przez wypełnienie parametru, dzięki czemu jedna encja Aggregate obejmuje środowiska różniące się tym, które elementy wdrażają — bez deklarowania przez encję Release niczego, czego nie zadeklarowała encja Aggregate.
Co usuwa przełącznik o wartości false. Encja jest przycinana przed zbudowaniem grafu, a przycięcie działa kaskadowo: komponent zabiera ze sobą własne krawędzie uses: i dołączone encje Features, a moduł zabiera wszystko, co wniósł — swoje komponenty, ich krawędzie i ich dołączenia. Nic, co wniosła przycięta encja, nie jest renderowane. Przycięcie nie obejmuje natomiast odwołania do niej z miejsca, które przetrwało, o czym mowa w następnym akapicie.
Komponent, który przetrwał i nadal wskazuje na przycięty, zatrzymuje kompilację. Jeśli api deklaruje krawędź uses: do redis, a redis jest wyłączony, kompilacja zatrzymuje się, zamiast pozwolić krawędzi zniknąć, co pozostawiłoby wstrzyknięte wartości api po cichu puste w czasie wdrożenia. Należy zdecydować, który z nich należy do tego środowiska: ponownie włączyć cel, uzależnić konsumenta od tego samego parametru, tak aby para znikała razem, albo usunąć krawędź z bloku uses: konsumenta.
Zapisany przełącznik musi dawać wartość logiczną, a pusta wartość nią nie jest. Przełącznik jest odczytywany ściśle po rozwiązaniu jego szablonu, a literał, którego nie da się sparsować jako wartości logicznej, zatrzymuje kompilację, zamiast przyjmować jakąkolwiek wartość domyślną. Przypadek, na który warto uważać, to przełącznik odczytujący parametr bez wartości: rozwiązuje się on do niczego, a odczytanie niczego jako „obecny” wdrożyłoby właśnie tę encję, którą uzależniono od tego parametru. Dlatego zapisanie active: bez niczego po nim nie jest tym samym co pominięcie klucza — tylko przełącznik, którego nikt nie zapisał, domyślnie oznacza obecność. Należy nadać parametrowi default: w spec.parameters, aby każde środowisko miało odpowiedź, albo wypełnić go w encji Release. Aby encja była obecna bezwarunkowo, należy usunąć klucz active:, a nie opróżniać go. Zatrzymanie opisano pod hasłem „An active: toggle does not resolve to true or false (Przełącznik active: nie rozwiązuje się do true ani false)” w opisie warunków zatrzymania.
Wyłączony komponent nadal można nazwać z encji Release. Encja Release może nadal wymienić go w granicy, i jest to zamierzone: wyłączenie komponentu jest czynnością autorską, a od encji Release, która go konfiguruje, nie oczekuje się przepisania w tej samej edycji.
Adnotacje w podsystemach i komponentach
Zarówno podsystemy, jak i instancje komponentów mają pole annotations:. Adnotacje tworzone przez programistów w encji Aggregate sterują kaskadą adnotacji po stronie Aggregate — adnotacja podsystemu propaguje się do każdego zagnieżdżonego podsystemu i każdego zawartego komponentu, przy czym nadpisania na bliższym poziomie działają z granulacją pojedynczego klucza. Mapa mappings.features.annotations w encji Manifest deklaruje powiązania, które w czasie budowania przekładają klucze adnotacji na syntetyczne dołączenia encji Feature. Niezmiennik Aggregate-as-Authoring-Surface ogranicza te adnotacje do routingu przez ścieżki maps.values powiązania; powiązanie deklarujące wyłącznie ścieżki maps.infra uruchamia się po stronie Release, a nie po stronie Aggregate.
Kształty wartości
Każdy klucz adnotacji przyjmuje jedną z czterech form, odróżniając „milczę” od „deklaruję wartość” — skalarną lub obiekt strukturalny — i od „rezygnuję”:
- Brak klucza — zakres nie deklaruje wartości dla tej adnotacji. Zagnieżdżone podsystemy i zawarte komponenty dziedziczą powiązanie z zakresu nadrzędnego.
- Skalarny ciąg znaków — pojedyncza wartość. Powiązanie w encji Manifest musi deklarować łącznie dokładnie jedną ścieżkę; wartość skalarna jest kierowana do tej ścieżki.
- Obiekt strukturalny — mapa podkluczy na podwartości. Każdy podklucz obiektu jest kierowany przez
mapspowiązania w encji Manifest do odpowiedniego pola schematu encji Feature w zadeklarowanym filarze. - Jawne YAML
null— zakres usuwa ze swojego poddrzewa każde odziedziczone powiązanie dla tego klucza. Sąsiednie komponenty i sąsiednie podsystemy zachowują dziedziczenie; powiązanie traci tylko zakres, który zrezygnował.
spec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker components: api: type: core/server:1.0.0 # inherits feature.myco/db-pool: "shared-pool" worker: type: core/server:1.0.0 annotations: feature.myco/db-pool: null # opts out for this component only special: type: core/server:1.0.0 annotations: feature.myco/db-pool: "vip-pool" # closer-level overrideWartości strukturalne dla wielopolowych encji Features
Encja Feature z wieloma konfigurowalnymi polami skłania do użycia strukturalnej wartości adnotacji: jeden klucz adnotacji niesie wartości dla kilku pól schematu encji Feature w jednej deklaracji. Strona Aggregate uruchamia tylko te podklucze, których filarem w mapie powiązania jest values; podklucze kierowane do infra należą do adnotacji po stronie Release.
spec: subsystems: data: annotations: feature.myco/db-pool: db_name: "prod-db" read_replicas: 5 components: api: type: core/server:1.0.0 annotations: feature.myco/db-pool: db_name: "api-override" # closer-level override at subkey granularity # read_replicas not listed → inherits 5 from parent analytics: type: core/server:1.0.0 annotations: feature.myco/db-pool: read_replicas: null # per-subkey opt-outWartości strukturalne kaskadują się z głębokim scalaniem na poziomie podkluczy: podklucze z bliższego poziomu nadpisują podklucze nadrzędne; jawne null przy podkluczu wyłącza odziedziczony podklucz dla danego zakresu, a sąsiednie podklucze pozostają. Pełny opis wartości strukturalnych — kompozycja między stronami z podkluczami infra po stronie Release, walidacja typów dla poszczególnych podkluczy, złagodzona dyscyplina wartości domyślnych dla pól schematu bez zadeklarowanego type — znajduje się w providers/well-known-annotations.md §„Structured annotation values”.
Niezależność poszczególnych kluczy
Każdy klucz adnotacji jest dziedziczony, nadpisywany i wyłączany niezależnie. Komponent deklarujący annotations.feature.myco/db-pool: null rezygnuje tylko z tego klucza; pozostałe klucze odziedziczone z otaczającego podsystemu nadal propagują się do tego komponentu. Sąsiednie komponenty w tym samym podsystemie niezależnie zachowują własne mapy adnotacji — rezygnacja jednego komponentu nie wpływa na sąsiednie.
Adnotacje komponentów najwyższego poziomu
Komponenty najwyższego poziomu (zadeklarowane bezpośrednio w spec.components, a nie wewnątrz podsystemu) nie mają odziedziczonej kaskady. Ich pole annotations: deklaruje wartości bezpośrednio w zakresie komponentu; rozwinięcie syntetyzuje dołączenia encji Feature z każdej zadeklarowanej adnotacji, dla której encja Manifest zawiera pasujące powiązanie.
Regułę kaskady po stronie Aggregate stosowaną do powiązań, podział strona–filar oraz kompletny przykład pokazujący, jak powiązania przekładają adnotacje na syntetyczne dołączenia encji Feature, opisano w providers/well-known-annotations.md §„Aggregate-side annotation cascade”.
Wzorce kotwic YAML (blok defs:)
Schemat encji Aggregate akceptuje opcjonalny blok defs: na poziomie głównym — listę ciągów YAML służącą wyłącznie jako miejsce na standardowe kotwice YAML (&anchor) i odwołania (*anchor). Kompilator nigdy nie odczytuje zawartości tego bloku; istnieje on po to, aby autorzy mogli zadeklarować definicje kotwic w jednym miejscu i odwoływać się do nich w pozostałej części encji Aggregate, zachowując powtarzane wartości zgodnie z zasadą DRY bez utraty płaskiego słownika O(1), po którym iteruje kompilator. Mechanizm odpowiada analogicznemu blokowi defs: w encji Manifest.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: anchored-app version: 1.0.0defs: - &default_log_level "info"spec: components: primary: type: core/compute/api-server:1.0.0 values: log_level: *default_log_level secondary: type: core/compute/python:1.0.0 values: log_level: *default_log_levelKotwice są rozwiązywane w czasie parsowania YAML, więc *default_log_level jest już ciągiem "info" w chwili, gdy kompilator odczytuje blok wartości. Blok defs: jest zgodnym z konwencją miejscem na definicje kotwic; YAML pozwala deklarować kotwice w dowolnym miejscu, ale zgrupowanie ich zachowuje czytelność pozostałej części encji Aggregate. Blok jest opcjonalny — encje Aggregates, które nie potrzebują kotwic, całkowicie go pomijają.