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

Kontrakt kontekstu szablonu

Ta strona opisuje widok środowiska uruchomieniowego, który kompilator wstrzykuje do szablonów Go encji Recipe i FeatureRecipe: kształt kontekstu szablonu, dostępność poszczególnych pól w kolejnych etapach potoku kompilacji oraz kanoniczny kontrakt potrzebny zaawansowanym autorom piszącym szablony, które korzystają ze stanu innych komponentów. Dostępność w poszczególnych miejscach szablonów (które pola są obecne w którym miejscu ewaluacji) opisano w expansion-matrix.md; ta strona opisuje kształty pól i ich semantykę.

Przegląd

Podczas renderowania kompilator składa kontekst szablonu dla każdego węzła i wstrzykuje go do każdego szablonu Go, który renderer ewaluuje dla tego węzła. Kontekst istnieje wyłącznie w pamięci — nigdy nie jest zapisywany na dysk i nigdy nie przechodzi przez Wasm ABI jako pojedynczy ładunek. Każde miejsce szablonu otrzymuje widok tego samego obiektu kontekstu; niektóre pola są wypełniane późno (.workload pojawia się podczas syntezy workloadu; .source podczas rozwiązywania źródła; .steps jest wypełniane przez wykonanie pipeline: w miarę ukończenia kolejnych kroków, zob. Status języka → Fazy potoku kompilacji).

Schematem kształtu w czasie wykonania jest template-context-v1beta1.schema.json (dostarczany wraz z dystrybucją schematów Aggrega).

Pola najwyższego poziomu

Pola najwyższego poziomu znajdują się w korzeniu kontekstu szablonu — wewnątrz szablonu odwołuje się do nich jako .field.

  • .values (mapa). Ładunek poznawczy tworzony przez programistę, pochodzący z encji Aggregate. Wartości poszczególnych komponentów trafiają w tym polu do wyrenderowanej encji Recipe. Walidowane podczas rozwiązywania przez schema: katalogu (deklarację JSON Schema 2020-12 encji Component lub Feature). Gdy zapisane przez autora zero / pusta wartość / false ma inne znaczenie niż brak pola, należy użyć optional (zob. sprig-functions.md) zamiast default.
  • .infra (mapa). Fizyczne wymiarowanie tworzone przez zespół operacyjny, pochodzące z encji Release. Walidowane podczas rozwiązywania przez schema: katalogu (deklarację JSON Schema 2020-12 encji Component lub Feature). Obowiązują te same wskazówki dotyczące optional i default co dla .values — należy preferować optional, gdy zapisane zero lub false jest uprawnioną intencją (skalowanie do zera, brak ponowień, wyłączona flaga funkcji).
  • .locals (mapa wartości tekstowych). Prywatny stan encji Recipe — nazwy zadeklarowane w bloku locals: encji Recipe, rozwiązywane w preambule locals i publikowane w tym filarze podczas rozwiązywania źródła. Wpisy są rozwiązywane w kolejności zapisu przez autora, a wpis może odczytać wpis sąsiedni zdefiniowany nad nim, więc kolejność ma znaczenie wszędzie tam, gdzie jeden wpis odczytuje inny. Dostępne wyłącznie w szablonach danej encji Recipe; nigdy nie są udostępniane wywołującym.
  • .provides (mapa wartości tekstowych). Publiczne ciągi wyjściowe encji Recipe — kontrakt, względem którego bloki inject: wywołujących rozwiązują odwołania from:. Wypełniane podczas ewaluacji provides.
  • .features (mapa dołączeń). Iteruje po encjach Features dołączonych do tej encji Component (na poziomie encji Aggregate + podsystemu + encji Release + sterowanych adnotacjami encji Manifest, zgodnie z 5-warstwowym modelem cebuli), indeksowanych nazwą instancji nadaną dołączeniu przez autora. Każdy wpis zawiera te same pola — zob. kształt dołączenia poniżej. Dołączenie zapisane na jednym z połączeń encji Component nie należy do nich: odczytuje się je w ramach tego połączenia, w .context.uses.<alias>.features.<slot>, więc szablon iterujący po .features napotyka wyłącznie własne dołączenia encji Component.
  • .metadata (struktura). Tożsamość encji Release na potrzeby deterministycznego nazewnictwa: release_name, release_version, environment, aggregate_name. Wypełniane przy każdym renderowaniu; wartości pochodzą z bloku metadata: encji Release.
  • .source. source: encji Recipe, rozwiązane przez ewaluację szablonu rozwiązywania źródła. nil dla encji Recipes bez źródła; nil przed uruchomieniem rozwiązywania źródła. W szablonach encji FeatureRecipe jest to własne source: tej encji FeatureRecipe, nigdy komponentu hosta — zob. Miejsce załącznika FeatureRecipe.
  • .workload. Sparsowany obiekt Workload, wypełniany, gdy wyrenderowany dokument workload: zostanie zdekodowany i przejdzie walidację, która go warunkuje: schemat encji Workload, featuresSchema encji Component dla każdego dołączenia deklarowanego przez jej kontenery oraz rozwiązywalność tego, do czego odwołuje się każde dołączenie. nil dla encji Recipes niesyntetyzowanych; nil przed uruchomieniem syntezy workloadu.
  • .steps (mapa wyników kroków). Wypełniane przez wykonanie pipeline: w miarę działania pluginów Wasm; udostępnia zwrócone wyniki ukończonego kroku kolejnym krokom przez .steps.<id>.outputs. Krok odczytuje wyniki poprzedniego kroku ze swojego szablonu with; outputs kroku stają się widoczne tylko dla kroków zadeklarowanych po nim. Puste, gdy węzeł nie deklaruje potoku, oraz przed ukończeniem pierwszego kroku węzła.

Pole najwyższego poziomu, które dla tego węzła nie zawiera niczego — .workload w encji Recipe, która żadnego nie syntetyzuje, .source w encji Recipe bez źródła, .features w encji Component bez załączników — w szablonie wartości odczytuje się jako puste, dokładnie tak jak nieustawiony klucz pod .values: {{ .workload }} nie renderuje niczego, default nałożone na nie dostarcza swoją wartość zastępczą, a if lub with nałożone na nie wybiera gałąź fałszu. range po nim nie iteruje po niczym. Odczyt poniżej niego — {{ .workload.containers }} — nadal zatrzymuje kompilację, ponieważ nie ma do czego zejść. A szablon, który zarówno wypisuje takie pole tam, gdzie zawsze się wykonuje — poza każdym if, with i range — jak i iteruje po nim, zatrzymuje kompilację, wskazując to pole, tak jak dla każdej ścieżki niezawierającej niczego, która jest odczytywana na oba sposoby, ponieważ żadna wartość nie jest jednocześnie wypisywana jako nic i iterowana jako nic: zob. A template reads and iterates a path that holds nothing (Szablon odczytuje i iteruje ścieżkę, która nie zawiera niczego).

Kształt dołączenia

.features.<name> i .features.<slot> mają ten sam kształt — jedno dołączenie, odczytywane w jeden sposób:

  • .type (string). URI katalogowy dołączonej encji Feature.
  • .resolved_version (string). Wersja dołączonej encji Feature po rozwiązaniu Manifest — wersja faktycznie powiązana w tej kompilacji, a nie przypięcie powtórzone po stronie konsumenta. Odpowiada .context.uses.<alias>.resolved_version. Pusta, gdy type dołączenia nie wskazuje żadnej encji katalogowej.
  • .labels (mapa wartości string). Etykiety katalogowe dołączonej encji Feature, przenoszone dosłownie w kolejności, w jakiej Feature je deklaruje — nic nie jest filtrowane, przemianowywane ani pozbawiane prefiksu, więc szablon odczytuje dokładnie to, co napisał autor encji Feature. Odpowiada .context.uses.<alias>.labels. Nieobecne, gdy Feature nie deklaruje etykiet oraz gdy type dołączenia nie wskazuje żadnej encji katalogowej.
  • .values (mapa). Własny filar intencji dewelopera dołączenia, zapisany w deklaracji dołączenia w encji Aggregate. Różny od .values najwyższego poziomu komponentu-gospodarza.
  • .infra (mapa). Własny filar wymiarowania operacyjnego dołączenia, zapisany w deklaracji dołączenia w encji Release. Różny od .infra najwyższego poziomu komponentu-gospodarza.
  • .provides (mapa wartości string). Rozwiązany publiczny kontrakt encji FeatureRecipe powiązanej z tym dołączeniem — nazwa emitowanego zasobu, jego klucz danych, tożsamość chmurowa oraz wszelkie dodatkowe klucze publikowane przez FeatureRecipe. Odczytywany jako .features.<name>.provides.<key>, analogicznie do .context.uses.<alias>.provides: konsument odczytuje to, co opublikował producent, zamiast wyprowadzać to ponownie. Dołączenie, którego powiązana FeatureRecipe niczego nie publikuje, nie ma w ogóle klucza provides zamiast pustej mapy, dlatego przed odwołaniem do pojedynczego klucza należy to sprawdzić.

.provides sprawia, że dołączenie jest możliwe do skonsumowania, a nie tylko obecne. Encja Feature deklarująca kontrakt schema.provides ma ten kontrakt egzekwowany wobec realizującej ją encji FeatureRecipe — FeatureRecipe musi opublikować każdy zadeklarowany klucz — a konsument odczytuje wynik tutaj. Dzięki temu encja Feature tożsamości, która emituje ServiceAccount i publikuje jego nazwę, pozwala konsumującej encji Recipe się z nim powiązać:

workload: |
serviceAccount: "{{ .features.identity.provides.name }}"

Emitowana nazwa jest podawana raz, przez producenta, i konsumowana — nigdy nie jest powtarzana po stronie konsumenta, gdzie obie mogłyby się rozejść. Przykład workload-identity-binding renderuje to od początku do końca.

.labels pozwala szablonowi dostosować się do tego, czym jest dołączenie, bez dopasowywania jego nazwy ani parsowania URI. Kompilator nie odczytuje żadnej z nich — przenosi ciągi znaków, a o ich znaczeniu decyduje autor szablonu.

Encja Feature, która nie deklaruje etykiet, nie ma w ogóle .labels zamiast pustej mapy, dlatego przed odwołaniem do pojedynczej etykiety należy to sprawdzić — sięgnięcie po nieistniejący klucz zatrzymuje kompilację. Etykietę, której Feature może nie deklarować, należy odczytywać przez optional, ponieważ index zatrzymuje kompilację, podając nazwę klucza, gdy mapa go nie zawiera:

{{ if .features.db.labels }}
{{ if eq (optional .features.db.labels "feature.aggrega.ai/kind" "") "secret" }}...{{ end }}
{{ end }}

Ponieważ etykiety docierają dosłownie, własna przestrzeń nazw autora katalogu trafia do szablonu bez zmian, a encja Recipe odczytuje ten sam klucz, który deklaruje Feature.

Blok .context

.context to kontekst wykonania pojedynczego węzła składany przez kompilator — dane tożsamości, topologii i potoku dostarczania, które renderer przekazuje do każdego miejsca szablonu. Jego pola:

  • .context.instance_id (string). Tożsamość węzła jako nazwa — wartość, której sama kompilacja używa do nazywania i etykietowania tego, co emituje, dzięki czemu szablon składający z niej nazwę zasobu lub adres wewnątrzklastrowy przewiduje nazwę, którą kompilacja faktycznie wytwarza. Dla węzła deklarowanego przez własną encję Aggregate jest to nazwa nadana węzłowi przez autora. Dla węzła wnoszonego przez importowaną encję Aggregate jest to spłaszczona tożsamość z rozpisanym separatorem modułu (data-layer.main-db staje się data-layer-zdmain-db), ponieważ kropka nie jest znakiem, który może zawierać nazwa zasobu, a w adresie klastra oddziela usługę od jej przestrzeni nazw. Postać z kropkami służy w dokumentach i diagnostykach kompilacji do adresowania tego węzła; zob. Konwencje nazewnictwa.
  • .context.rendered_name (string). Nazwa, którą provider węzła nadaje zasobom renderowanym dla węzła — ze źródła dostarczonego przez autora, takiego jak nazwa wydania odczytywana przez chart, oraz z syntetyzowanego workloadu, gdy provider nazywa zasoby tego workloadu według własnej nazwy, jak robi to helm z tą samą nazwą wydania. Występuje tylko tam, gdzie provider ją wyprowadza. W szablonach dołączenia encji Feature jest to nazwa komponentu-gospodarza, tak jak .context.instance_id jest tam tożsamością gospodarza; zob. Nazywanie renderowanego zasobu.
  • .context.labels (mapa wartości string). Etykiety zdefiniowane w katalogu oraz wszelkie dodatki label-transform wprowadzone podczas budowy topologii.
  • .context.annotations (trzy kubełki, zob. niżej). Kaskadowe adnotacje pogrupowane według pochodzenia.
  • .context.inject (mapa mechanizmów, zob. niżej). Wstępnie wypełniony, przechwycony potok dostarczania — standardowa powierzchnia, z której szablony encji Recipe odczytują wartości międzykomponentowe.
  • .context.uses (mapa połączeń, zob. niżej). Projekcja JOIN nad wychodzącymi krawędziami topologicznymi.
  • .context.self_inject (mapa mechanizmów, zob. niżej). Dla każdej nazwy, którą programista zapisał we własnym bloku inject: komponentu — własny klucz provides dostarczany przez ten wpis albo jedyna własna wartość odczytywana przez jego szablon.
  • .context.used_by (lista, zob. niżej). Komponenty, których wpisy uses wskazują na ten komponent. Odczytywana przez encję FeatureRecipe dołączoną do komponentu, w szablonach wytwarzających własne zasoby dołączenia; wszędzie indziej pusta.
  • .context.render_facts (mapa list, zob. niżej). To, co provider komponentu zgłosił o wyrenderowanym wyniku, kluczowane nazwą faktu. Odczytywana przez encję FeatureRecipe dołączoną do komponentu, w każdym jej szablonie uruchamianym po wyrenderowaniu komponentu; wszędzie indziej nieobecna.

.context.annotations — trzy kubełki

Adnotacje spływają kaskadowo do trzech kubełków kluczowanych pochodzeniem:

  • .context.annotations.release — adnotacje granicy Release (Domena 4). Służą do zarządzania realiami fizycznymi; renderery kierują je w odpowiednich przypadkach do pól infra:. W tym kubełku znajdują się dobrze znane adnotacje aggrega.ai/*.
  • .context.annotations.catalog — adnotacje metadanych encji Component z Domeny 2. Niezmienne cechy wewnętrzne definiowane przez architekta; konsumowane głównie przez plugins polityk Wasm.
  • .context.annotations.aggregate — adnotacje podsystemu Aggregate z Domeny 1. Metadane poznawcze; renderery kierują je w odpowiednich przypadkach do ładunków values:.

Każdy kubełek jest płaską mapą string-do-string. Zgodnie z zasadami separacji architektury kubełki są przeznaczone do odrębnych zastosowań; silnik nie wymusza tej separacji, więc to dyscyplina autorów utrzymuje kubełki zgodne z zamierzoną semantyką. Projekt kaskadowych adnotacji opisano w rozdziale 6 §2, przepływ 5.

.context.inject — potok dostarczania

Potok to wstępnie rozwiązana mapa dostarczania kompilatora. Zanim szablon encji Recipe zostanie uruchomiony w renderowaniu bazowym, każde źródło inject (literały self-inject zdefiniowane przez programistę, referencje self-inject from: rozwiązywane względem własnych provides, międzykomponentowe referencje uses[].inject rozwiązywane względem provides celu, przechwycenia injectMapping encji FeatureRecipe) zostało rozwiązane do końcowej wartości string i scalone z tą mapą.

Pola:

  • .context.inject.env — mapa wartości string: nazwa zmiennej środowiskowej → rozwiązana wartość.
  • .context.inject.file — mapa wartości string: ścieżka pliku → rozwiązana wartość.
  • .context.inject.arg — mapa wartości string: flaga argumentu → rozwiązana wartość.
  • .context.inject.all — mapa wartości string łącząca mechanizmy env/file/arg/niestandardowe w jeden płaski słownik; przydatna do serializacji całego potoku ({{ toJson .context.inject.all }}).

Mechanizm jest obecny w potoku tylko wtedy, gdy coś jest przez niego dostarczane. Szablon odczytujący mechanizm, przez który nic nie jest dostarczane — .context.inject.file przy braku dostarczania plików — odczytuje go jako pusty, tak jak szablon wartości odczytuje każdy nieobecny klucz, a range po nim nic nie renderuje; ten odczyt dostarcza pustą wartość dla całego szablonu, więc {{ toJson .context.inject }} w tym samym szablonie pokazuje "file": "". To, czy cokolwiek jest przez niego dostarczane, pokazuje hasKey .context.inject "file".

  • Mechanizmy niestandardowe (np. ssm_param) — odczytywane pod własną nazwą pola, .context.inject.<mechanism>.<key>, dokładnie tak jak trzy podstawowe. Wartości mechanizmu niestandardowego trafiają do potoku z self-inject na poziomie komponentu, z krawędzi uses[].inject, z mapowania inject: dołączenia encji Feature oraz z wyniku injectMapping encji FeatureRecipe. W przypadku self-inject na poziomie komponentu lista dozwolonych spec.inject encji Component musi wymieniać dany mechanizm, a mechanizm, którego lista nie wymienia, zatrzymuje kompilację. Wpisy mechanizmu niestandardowego pojawiają się także w .context.inject.all obok trzech podstawowych. Mechanizm niestandardowy może mieć dowolną nazwę poza all: ta nazwa jest samym scalonym widokiem, więc mechanizmu o tej nazwie nigdy nie dałoby się odczytać osobno. Blok inject wymieniający mechanizm all oraz lista dozwolonych encji Component lub encji Feature (spec.inject, inject gniazda), która go wymienia, zatrzymują kompilację podczas wczytywania dokumentu, a odmowa wyjaśnia, że ta nazwa należy do tego scalonego widoku. W nazwach rozróżniana jest wielkość liter, więc ALL jest zwykłym mechanizmem niestandardowym.

Potok to stan po przechwyceniu — zanim szablony encji Recipe go odczytają, bloki injectMapping encji FeatureRecipe już podczas mapowania inject głęboko scaliły swoje nadpisania z tym potokiem. Mapowanie może zastąpić klucz dostarczony przez własny blok inject: komponentu, blok inject: jednego z jego połączeń lub blok inject: jego własnego dołączenia; klucz dostarczany przez dwie dołączone encje Features, czy to przez bloki inject:, czy przez mapowania, zatrzymuje kompilację, zamiast trafić do potoku z jedną z dwóch wartości. Encja Feature dołączona do granicy Release dociera do komponentu w ten sam sposób — przez injectMapping swojej encji FeatureRecipe, które działa we własnym kontekście komponentu niezależnie od executionScope encji FeatureRecipe; przepisanie przez most compose zmiennej hosta konsumenta jest jednym z takich mapowań i podlega tej samej zasadzie.

.context.self_inject — którą własną wartość dostarcza każda z nazw programisty

Gdy encja Component deklaruje spec.inject, programista może zapisać blok inject: na samym komponencie i wybrać nazwy, pod którymi dostarczane są własne wartości i provides komponentu. .context.inject zawiera to, do czego zostały rozstrzygnięte te wpisy, a .inject_raw zawiera je w postaci zapisanej; .context.self_inject wskazuje dla każdego z nich własny klucz provides komponentu, który dostarcza, albo jedyną własną wartość, którą odczytuje jego szablon. Ma ten sam kształt co .context.uses.<alias>.inject połączenia — mechanizm, potem nazwa programisty, potem klucz — przy czym klucz wskazuje jeden z własnych provides lub własnych wartości komponentu:

  • provides.<key> — wpis zapisany z from: <key>, dostarczający jeden z własnych provides komponentu.
  • values.<key> — wpis, którego szablon value: odczytuje dokładnie jedną z własnych wartości komponentu i nic poza nią, przy czym <key> jest kluczem najwyższego poziomu tej wartości. Tekst ani funkcje wokół odczytu nie mają znaczenia, podobnie jak to, jak głęboko szablon sięga w wartość: '{{ .values.role }}', 'role={{ .values.role | upper }}' i '{{ with .values.role }}{{ . }}{{ end }}' są wszystkie odwzorowywane na values.role, a '{{ .values.config.port }}', '{{ index .values.config "port" }}' i '{{ (default dict .values.config).port }}' są wszystkie odwzorowywane na values.config.
  • pusty ciąg — każdy inny wpis: literał, szablon odczytujący dwie wartości, szablon odczytujący cokolwiek poza wartościami (.infra, .metadata, .context) oraz szablon, którego odczytu wartości tekst nie przypisuje do jednego klucza najwyższego poziomu — wartości przekazane funkcji przez ich korzeń (index .values "role"), wartości odczytane w całości (toJson .values albo pole odczytane wewnątrz {{ with .values }} lub przez zmienną powiązaną z .values) albo cały kontekst przekazany dalej (toJson .).
# The developer's block on the component, in the Aggregate
inject:
env:
- { in: SERVICE_HOST, from: host }
- { in: AGENT_ROLE, value: '{{"{{"}} .values.role }}' }
- { in: MODE, value: batch }
- { in: ROLE_AND_GOAL, value: '{{"{{"}} .values.role }}-{{"{{"}} .values.goal }}' }
ssm_param:
- { in: /app/goal, value: '{{"{{"}} .values.goal }}' }
# What the Recipe reads at .context.self_inject
env:
SERVICE_HOST: provides.host
AGENT_ROLE: values.role
MODE: ""
ROLE_AND_GOAL: ""
ssm_param:
/app/goal: values.goal

W encji Aggregate każdy szablon value: zaczyna się od {{"{{"}} zamiast {{, ponieważ cały tekst encji Aggregate jest raz odczytywany jako szablon, na potrzeby interpolacji parametrów, zanim zostaną przetworzone własne szablony bloku; szablony przytoczone na powyższej liście pokazano w postaci, jaką mają po tym escapowaniu. Zob. Tekst zawierający własne podwójne nawiasy klamrowe.

To właśnie pozwala encji Recipe, która uruchamia własny obraz programisty, traktować własne nazwy zmiennych dla własnych wartości komponentu jako domyślne — to konwencja katalogu biblioteki standardowej, a katalog przedsiębiorstwa może wybrać inaczej. Zanim taka encja Recipe dostarczy własną wartość pod własną nazwą, sprawdza, czy blok programisty już dostarcza tę wartość, i pomija swoją wartość domyślną, jeśli tak jest — dzięki temu programista, który zmienia nazwę jednej wartości, zachowuje wszystkie pozostałe wartości domyślne:

workload: |
containers:
main:
variables:
{{- range $name, $value := .context.inject.env }}
{{ $name }}: {{ $value | quote }}
{{- end }}
{{- $named := dict }}
{{- with .context.self_inject.env }}{{ range $name, $key := . }}{{ $_ := set $named $key true }}{{ end }}{{ end }}
{{- if not (hasKey $named "values.role") }}
APP_ROLE: {{ .values.role | quote }}
{{- end }}

.context.self_inject jest obecne przy każdym renderowaniu i puste tam, gdzie programista nie zapisał żadnego bloku. Mechanizm pojawia się tylko wtedy, gdy blok go nazywa, dlatego odczyt mechanizmu, którego blok może nie nazywać, należy zabezpieczyć, tak jak robi to powyższe with. Szablon otrzymuje nazwy posortowane, niezależnie od sposobu ich odczytu, tak jak każdą mapę. Mapa jest odczytywana z tekstu zapisanego przez programistę; nic w niej nie jest rozstrzygniętą wartością, a kompilator nie przypisuje nazwom ani kluczom żadnego znaczenia.

.context.uses — projekcja JOIN

.context.uses to wzbogacony przez kompilator widok każdej wychodzącej krawędzi topologicznej bieżącego węzła. Każdy wpis mapy ma jako klucz lokalny alias gniazda (np. databases.primary staje się .context.uses.primary, gdy encja Aggregate zawiera uses: { databases: { primary: { target: ... } } }) i niesie projekcję JOIN rozwiązanego stanu celu oraz kontrakt dostarczania po stronie wywołującego:

  • .target (string) — identyfikator instancji węzła docelowego.
  • .socket (string) — nazwa gniazda po stronie wywołującego (klucz usesSchema).
  • .provides (mapa wartości tekstowych) — rozwiązane klucze provides: celu (publiczne ciągi wyjściowe, które docelowa encja Recipe wyeksportowała podczas ewaluacji provides).
  • .inject (mapa mechanizm → mapa klucz → wartość) — dyrektywy inject po stronie wywołującego dla tej krawędzi (blok inject: w deklaracji uses[].inject). Kluczami mechanizmów są env/file/arg/niestandardowe; wpisy map poszczególnych mechanizmów to odwołania klucz lokalny → klucz provides celu.
  • .labels (mapa wartości tekstowych) — etykiety celu, nigdy komponentu konsumującego: zestaw, który niesie własne .context.labels celu, czyli jego etykiety zdefiniowane w katalogu oraz wszelkie dodatki label-transform wprowadzone podczas budowania topologii.
  • .annotations (trzy kubełki) — kubełki adnotacji release/catalog/aggregate celu.
  • .component (string) — URI typu encji Component celu.
  • .resolved_version (string) — wersja encji Component celu po rozwiązaniu w encji Manifest.
  • .boundary_path (string) — ścieżka granicy Release celu, ustawiana niezależnie od tego, czy cel znajduje się w granicy wywołującego, czy w innej.
  • .origin_feature (string) — ustawiane, gdy krawędź została zsyntetyzowana przez dołączenie Feature (np. Feature typu sidecar dodający krawędź uses do Feature z poświadczeniami).
  • .values (mapa) — rozwiązana konfiguracja deweloperska dla tego połączenia, zdefiniowana we wpisie uses encji Aggregate. Obecne tylko wtedy, gdy krawędź niesie własne wartości.
  • .infra (mapa) — rozwiązana konfiguracja operatora dla tego połączenia, zdefiniowana we wpisie uses encji Release. Obecne tylko wtedy, gdy krawędź niesie własne infra.
  • .origin_release (boolean) — true, gdy to połączenie zostało podpięte przez encję Release, a nie zadeklarowane przez encję Aggregate; nieobecne dla połączenia deklarowanego przez encję Aggregate.
  • .features (mapa dołączeń) — dołączenia zapisane na tym połączeniu, z kluczem w postaci nazwy slotu deklarowanego przez gniazdo; zob. niżej. Obecne tylko wtedy, gdy połączenie niesie dołączenie.
  • .render_facts (mapa list) — to, co renderowania celu zgłosiły o wyemitowanym wyjściu, z kluczem w postaci nazwy faktu, w tym samym kształcie co .render_facts wywołującego w .context.used_by: każdy fakt jest listą, najpierw wywołania własnego dostawcy celu, a następnie każdego z jego Features w kolejności renderowania, przy czym listy otrzymane dla jednej nazwy z każdego źródła są łączone w jedną. Obecne tylko dla encji FeatureRecipe ustawiającej readsTargetRenderFacts: true — jej dołączenia renderują się, gdy wszystkie komponenty zostały już wyrenderowane, więc renderowanie każdego celu jest kompletne — i wtedy na każdym połączeniu, puste dla celu, którego dostawcy nic nie zgłaszają. Odczytywane tylko w valuesMapping:, workload: i artifacts: tej encji FeatureRecipe; nieobecne we własnych szablonach Recipe komponentu, w injectMapping:, w with: i when: kroku pipeline: oraz w każdej encji FeatureRecipe, która nie ustawia tego klucza — szablon takiej encji, który je odczytuje, zatrzymuje kompilację, zanim cokolwiek zostanie wyrenderowane.

Obie mapy konfiguracji krawędzi mają zakres konsumenta: trafiają wyłącznie do kontekstu renderowania węzła konsumującego, nigdy do kontekstu celu.

Udostępnioną wartość odczytuje się w .provides.<name> — udostępnione nazwy są zagnieżdżone pod .provides, zamiast znajdować się bezpośrednio na krawędzi, więc .context.uses.<alias>.<name> nie wskazuje żadnego pola i nic nie zwraca.

Na połączeniu, którego dwa końce renderują się do różnych wyjść, .provides zawiera zastępniki zamiast wartości. Gdy provider łączy takie połączenie własnym odwołaniem po złożeniu obu wyjść — na przykład stos CloudFormation odczytuje wartość innego stosu — każda wartość, którą niesie .context.uses.<alias>.provides, jest symbolem zastępczym, który provider później zastępuje odwołaniem między stosami lub samą wartością, jak opisuje jego własna strona. Taką wartość należy kopiować, a nie porównywać — to ta sama zasada, której podlega wartość dostarczana przez takie połączenie w potoku inject, będąca symbolem zastępczym tego samego rodzaju. Należy ją zapisać w całości, wewnątrz dłuższego ciągu lub przez funkcję, która pozostawia ją bez zmian, taką jak quote. Szablon, który porównuje wartość odczytaną z .provides, rozgałęzia się według niej, mierzy ją lub ją zmienia, podejmowałby decyzję na podstawie symbolu zastępczego, więc zamiast tego kompilacja zostaje zatrzymana, ze wskazaniem szablonu i każdej odczytanej przez niego wartości; rozgałęzienie należy oprzeć na własnej wartości komponentu konsumującego. Zatrzymanie obejmuje każdy szablon odczytujący .provides połączenia, w tym injectMapping: dołączonej encji FeatureRecipe, oraz encję FeatureRecipe o zakresie granicy odczytującą te same połączenia pod .boundary. Połączenie, którego oba końce renderują się do jednego wyjścia, niesie swoje wartości bez zmian.

Jeden alias nazywa jedno połączenie, więc mapa zawiera wpis dla każdego połączenia komponentu. Kluczem mapy jest wyłącznie alias, niezależnie od gniazda, do którego połączenie jest podpięte, i żadne dwa połączenia jednego komponentu nie dzielą aliasu — ani na jednym gnieździe, ani na dwóch, niezależnie od tego, który dokument lub dołączenie utworzyło każde z nich. Kompilacja odrzuca taką parę, wskazując oba połączenia i miejsce zapisania każdego z nich, zanim cokolwiek zostanie wyrenderowane. Lista wskazująca jeden cel dwukrotnie jest taką parą, ponieważ aliasem wpisu listy jest jego cel; podobnie połączenie local na gnieździe models obok połączenia local na gnieździe databases.

Szablony Recipe korzystają z tej projekcji, aby odczytać stan po stronie celu bez przechodzenia grafu IR. Szablony injectMapping encji FeatureRecipe używają jej, aby sięgać do adnotacji celu przy decyzjach o routingu między granicami (wzorzec resolvera DNS K8s opisany w entities/featurerecipe.md jest kanonicznym przykładem).

Szablon iterujący po .context.uses widzi połączenia w kolejności kluczy — posortowane według aliasu — a nie w kolejności zapisania w encji Aggregate. W ten sposób odwiedzana jest każda mapa, po której iteruje szablon, w tym .features i .features połączenia, więc szablon nigdy nie odtworzy kolejności zapisu, iterując po mapie; tam, gdzie kolejność ma znaczenie, powierzchnia autorska modeluje ją jako listę. W obu przypadkach wyrenderowane wyjście jest identyczne bajt w bajt między kompilacjami tych samych danych wejściowych.

Dołączenia połączenia — .context.uses.<alias>.features

Dołączenie zapisane na połączeniu — pod features: we wpisie uses komponentu w encji Aggregate lub we wpisie encji Release dla tego połączenia — wypełnia slot deklarowany przez gniazdo. Jest ono dołączeniem komponentu konsumującego we wszystkim, co kompilacja z nim robi: encja Manifest wiąże jego realizację, jego encja FeatureRecipe renderuje się po stronie konsumenta, a jego kontrakt provides jest egzekwowany. Szablon odczytuje je pod połączeniem, na którym zostało zapisane:

{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
api_base: {{ $edge.provides.endpoint }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
api_key_key: {{ .provides.key }}
{{- end }}{{ end }}
{{- end }}
  • Klucz według slotu. .context.uses.<alias>.features.<slot> wskazuje slot deklarowany przez gniazdo połączenia — powyżej credential — więc konsument sięgający do kilku celów odczytuje poświadczenie każdego celu pod aliasem tego celu. Połączenie bez dołączenia nie ma .features, dlatego odczyt jest zabezpieczony.
  • Kształt dołączenia. Każdy wpis niesie dokładnie to, co .features.<name> niesie dla jednego z własnych dołączeń komponentu — .type, .resolved_version, .labels, .values, .infra oraz rozwiązane .provides powiązanej z nim encji FeatureRecipe — zob. kształt dołączenia. Odczytywane tu provides to te, względem których renderuje się własna encja FeatureRecipe dołączenia, więc nazwa, do której odwołuje się konsument, i nazwa zasobu emitowanego przez tę encję FeatureRecipe są jedną obliczoną wartością.
  • Nigdy w .features. Własne .features komponentu zawiera wyłącznie dołączenia zapisane w jego własnym bloku. Encja Recipe, która iteruje po .features i wybiera dołączenia według typu — {{ range $name, $f := (default dict .features) }}{{ if eq $f.type "core/referenced-secret" }}… — nigdy więc nie natrafi na poświadczenie połączenia, nawet tego samego Feature: szablon sięga do dołączenia połączenia przez to połączenie, nigdy przez .features. To samo dotyczy każdej powierzchni pokazującej dołączenia komponentu, w tym kontekstu assertions.

Komponenty, które używają tego komponentu — .context.used_by

.context.uses patrzy na zewnątrz, na połączenia, które tworzy komponent. .context.used_by patrzy do wewnątrz, na komponenty, których wpisy uses wskazują na ten komponent. Odczytuje go FeatureRecipe dołączona do komponentu i właśnie tam należy zasób opisujący lub ograniczający te połączenia — na przykład polityka sieciowa dopuszczająca wyłącznie komponenty zadeklarowane jako wywołujące ten komponent:

artifacts:
callers.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ .context.rendered_name }}-{{ .attachment_name }}
data:
callers: |
{{- range .context.used_by }}
- component: {{ .component_id }}
socket: {{ .socket }}
selector: {{ .provides.selector }}
{{- with .source_namespace }}
namespace: {{ . }}
{{- end }}
{{- end }}

Każdy wpis zawiera:

  • .component_id (string) — identyfikator instancji łączącego się komponentu w postaci spłaszczonej (frontend, data-layer.etl), czyli wartość, którą szablon ścieżki subDirectory: odczytuje jako .component_id.
  • .socket (string) — gniazdo, które połączenie wypełnia w łączącym się komponencie (jego klucz usesSchema).
  • .provides (mapa wartości typu string) — to, co publikuje łączący się komponent, zawężone do kluczy deklarowanych przez jego encję Component: te same wartości, które konsument tego komponentu odczytuje w .context.uses.<alias>.provides. Klucz publikowany przez Recipe komponentu, którego jego encja Component nie deklaruje, nie należy do nich.
  • .source_namespace (string) — przestrzeń nazw, w której umieszczony jest łączący się komponent: obowiązująca go adnotacja aggrega.ai/namespace, kaskadowo przekazywana w dół jego granic, przy czym pierwszeństwo ma jego własny wpis w encji Release. Komponent, którego wpis w encji Release ustawia przestrzeń nazw lub czyści ją wartością null, ma własne ustawienie zamiast ustawienia swojej granicy, więc wartość wskazuje przestrzeń nazw, do której renderowane są własne zasoby komponentu. Pole jest nieobecne, gdy komponentu nie obejmuje żadna przestrzeń nazw; należy je odczytywać przez with lub if, jak w przykładzie, a nie wypisywać bezpośrednio.
  • .source_boundary_path (string) — ścieżka granicy encji Release zawierającej łączący się komponent, z zagnieżdżonymi granicami połączonymi znakiem / (edge, edge/inner).
  • .render_facts (mapa list) — to, co renderowania łączącego się komponentu zgłosiły o wygenerowanym wyniku, z kluczami w postaci nazw faktów, w tym samym kształcie co .context.render_facts. Każdy fakt jest listą, więc szablon zawsze iteruje po nim, nawet gdy zawiera jeden wpis. Wpisy mogą pochodzić z własnego renderowania łączącego się komponentu oraz z renderowań dołączonych do niego Features: listy, które jedna nazwa otrzymuje z każdego z nich, są łączone w jedną — najpierw własne wywołania providera komponentu, potem każda z jego Features w kolejności renderowania. Pole jest obecne tylko dla FeatureRecipe, która ustawia readsCallerRenderFacts: true — jej dołączenia renderują się, gdy wszystkie komponenty zostaną wyrenderowane, więc renderowanie każdego wywołującego jest kompletne — i wtedy na każdym wpisie, puste dla wywołującego, którego providery niczego nie zgłaszają. FeatureRecipe, która nie ustawia tego klucza, nie widzi .render_facts na żadnym wpisie, a jej szablon, który je odczytuje, zatrzymuje kompilację, zanim cokolwiek zostanie wyrenderowane.

Obie wartości rozmieszczenia to te same, które FeatureRecipe o zakresie granicy odczytuje jako source_namespace i source_boundary_path we wpisie tego samego połączenia na swoich listach krawędzi .boundary: oba widoki odczytują rozmieszczenie komponentu w ten sam sposób, więc nigdy się w tej kwestii nie różnią. Krawędź na tych listach niesie też ścieżkę składania każdego punktu końcowego — source_assembly_path i target_assembly_path, katalog w katalogu wyjściowym kompilacji, do którego składa go provider punktu końcowego — czego wpis .context.used_by nie zawiera.

FeatureRecipe, która ustawia readsCallerRenderFacts: true, odczytuje fakty każdego wywołującego tak samo jak fakty hosta. Dla providera dokumentującego fakt o nazwie ports, którego każdy wpis zawiera port:

artifacts:
callers.yaml: |
callers:
{{- range .context.used_by }}
- component: {{ .component_id }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

Wywołujący, którego provider nie zgłasza ports, renderuje puste ports: zamiast zakończyć się błędem, ponieważ nazwa, której nikt nie zgłosił, odczytywana jest jako nic.

Zachowanie listy:

  • W kolejności zapisu. Wpisy następują w kolejności, w jakiej zapisano łączące się komponenty, a następnie w kolejności własnych wpisów uses każdego z nich. Komponent łączący się dwukrotnie występuje dwa razy, raz na każde połączenie. Ponieważ jest to lista, a nie mapa, range napotyka wywołujących w tej kolejności — nic nie jest sortowane.
  • Tylko tam, gdzie dołączenie renderuje własne zasoby. Odczytują ją valuesMapping:, workload: i artifacts: encji FeatureRecipe. Jest pusta we własnych szablonach Recipe komponentu, w injectMapping: oraz w with: i when: kroku pipeline:, ponieważ to, co każdy z nich produkuje, może trafić do własnego wyrenderowanego wyniku komponentu: injectMapping: zapisuje potok dostarczania komponentu, a krok potoku może przepisać dokumenty komponentu. Dzięki temu własny wynik komponentu pozostaje taki sam niezależnie od tego, kto go używa — podłączenie kolejnego wywołującego do komponentu zmienia wynik dołączonej do niego Feature, która odczytuje jego wywołujących, i nic z tego, co renderuje sam komponent.
  • Nic o samym połączeniu. Wpis nie zawiera values ani infra danego połączenia ani żadnych dołączeń połączenia; pozostają one przy konsumującym komponencie, w jego .context.uses.<alias>.
  • Pusta, gdy nic nie używa komponentu. range po niej nie renderuje wtedy niczego.
  • Przekazywane, nigdy interpretowane. Tożsamość, gniazdo, opublikowane wartości i rozmieszczenie to ciągi znaków, które kompilator przekazuje dalej, a fakty renderowania to to, co zgłosiły providery każdego wywołującego, z kluczami w postaci nazw. Kompilator niczego nie wnioskuje z nazwy, niczego nie pobiera i niczego nie rozstrzyga o tym, których wywołujących zasób powinien dopuścić; decyduje szablon.

Co provider zgłosił o renderowaniu — .context.render_facts

Provider komponentu może zgłaszać fakty o wyrenderowanym wyniku — właściwości zapisanych dokumentów, które dostrzec może tylko jego własna znajomość swojego formatu. To, jakie fakty provider zgłasza, pod jakimi nazwami i co zawiera każdy wpis, stanowi jego własny udokumentowany kontrakt; stronę providera opisano w Reporting facts about what a guest emitted. Provider helm na przykład zgłasza etykiety wygenerowanych szablonów podów, selektory swoich kontrolerów i obiektów Service oraz porty swoich kontenerów — zob. jego fakty renderowania. FeatureRecipe dołączona do komponentu odczytuje to, co zgłosił provider komponentu, w .context.render_facts, z kluczami w postaci nazw faktów. Dla providera dokumentującego fakt o nazwie ports, którego każdy wpis zawiera name i port:

artifacts:
ports.yaml: |
ports:
{{- range .context.render_facts.ports }}
- name: {{ .name }}
port: {{ .port }}
{{- end }}
  • Każdy fakt jest listą. Provider zgłasza każdy fakt jako listę, nawet gdy zawiera jeden wpis, więc szablon zawsze iteruje po nim — nie ma pojedynczej wartości do odczytania samodzielnie.
  • Jedna lista na nazwę, łączona w ramach renderowania komponentu. Renderowanie komponentu może wymagać więcej niż jednego wywołania jego providera — na przykład renderowania chartu i umieszczenia artefaktów — a każde wywołanie zgłasza fakty za siebie. Listy, które jedna nazwa otrzymuje z tych wywołań, są łączone w jedną, w kolejności wykonania wywołań. To, co wyrenderowały dołączone do komponentu Features, nie należy tu do nich: Feature odczytuje w .context.render_facts wyłącznie własne renderowanie komponentu, niezależnie od tego, co wygenerowały inne Features komponentu.
  • W każdym szablonie dołączonej FeatureRecipe. Odczytują go jej valuesMapping:, workload: i artifacts:, a także with: i when: jej kroków pipeline: — fakty pochodzą z własnego renderowania komponentu, więc ich odczytanie nie uzależnia niczego od tego, kto łączy się z komponentem. Jest nieobecny we własnych szablonach Recipe komponentu oraz w injectMapping:, które są wykonywane, zanim komponent zostanie wyrenderowany.
  • Pusta zamiast brakującej. Gdy provider komponentu niczego nie zgłasza, .context.render_facts jest pustą mapą, a nazwa, której nikt nie zgłosił, odczytywana jest jako nic, więc range po niej nie renderuje niczego zamiast zakończyć się błędem.
  • Kolejność. Lista zachowuje wpisy w kolejności, w jakiej zgłosił je provider. Wpis będący obiektem jest mapą z kluczami jak każda inna w kontekście, więc szablon iterujący po nim napotyka klucze w kolejności kluczy.
  • Przekazywane, nigdy interpretowane. Kompilator sprawdza jedynie, czy wartość każdego faktu jest listą. Nie odczytuje niczego z tego, co oznacza nazwa lub wpis; o tym, co z nimi zrobić, decyduje szablon.

.uses asercji — kluczowane gniazdem, a następnie aliasem

Szablon assertions: odczytuje te same połączenia przez własny, węższy widok: .uses w korzeniu, a nie pod .context, bez niczego, co opublikował cel połączenia, ponieważ obie fazy asercji są obliczane przed renderowaniem. Odzwierciedla on formę autorską uses: <socket>: <alias>: { target: … } — jest kluczowany gniazdem, a pod każdym gniazdem aliasem każdego połączenia w nim, przy czym połączenie zapisane jako element listy przyjmuje swój cel jako alias. Wpis każdego połączenia zawiera target, alias oraz, dla połączenia utworzonego przez dołączenie encji Feature, origin_feature, a także trzy z faktów, które zawiera .context.uses, pod tymi samymi nazwami i z tymi samymi wartościami: .labels, etykiety celu; .values, wartości zapisane w połączeniu; oraz .features, dołączenia zapisane w nim, kluczowane slotem. Każdy z tych trzech jest obecny w każdym wpisie i pusty tam, gdzie połączenie żadnych nie zawiera. Dołączenie pod .features zawiera wyłącznie swoje type, resolved_version i values — kształt, w jakim asercja odczytuje każde dołączenie, łącznie z własnymi dołączeniami komponentu, ponieważ FeatureRecipe dołączenia nie rozwiązała jeszcze swojego provides, gdy asercja jest wykonywana.

Gniazdo z jednym połączeniem i gniazdo z kilkoma mają ten sam kształt, więc asercja odczytuje oba w ten sam sposób. Dla komponentu, którego wpis w encji Aggregate zapisuje uses: { models: { local: { target: llama }, fast: { target: turbo } } }:

assertions:
two-models-wired: |
{{- if lt (len (optional .uses "models" dict)) 2 -}}
{{- fail "wire two models to the models socket" -}}
{{- end -}}
local-is-llama: |
{{- if and (hasKey .uses "models") (hasKey .uses.models "local") (ne .uses.models.local.target "llama") -}}
{{- fail (printf "the local connection must point at llama; it points at %s" .uses.models.local.target) -}}
{{- end -}}

hasKey .uses "models" sprawdza, czy gniazdo jest podłączone, len liczy jego połączenia, range po nim odwiedza każde z nich w kolejności alfabetycznej aliasów, a .uses.models.local.target odczytuje jedno połączenie. .uses.models.target nie wskazuje żadnego połączenia i zatrzymuje kompilację przy missingkey=error obowiązującym w szablonach asercji. Każde połączenie ma własny wpis z tego samego powodu co w mapie kontekstu renderowania: dwa połączenia jednego komponentu nigdy nie mają wspólnego aliasu, ponieważ kompilacja odrzuca taki przypadek, zanim zostanie wykonana jakakolwiek asercja. Pełny kontekst asercji opisano w assertions-block.md.

Kontekst szablonu zawiera te pola o kształcie inject, każde z własną semantyką. Autorzy encji Recipe i FeatureRecipe powinni wiedzieć, które miejsce odczytywać.

MiejsceTypWypełniane, gdyZastosowanie
.context.injectmapa mechanizmów (zawsze obecna)Przy każdym renderowaniuStandardowy, wstępnie wypełniony potok dostarczania — należy go odczytywać w szablonach valuesMapping:/workload:/artifacts: oraz w każdym miejscu szablonu encji FeatureRecipe.
.inject (najwyższego poziomu)mapa mechanizmów (może mieć wartość null)Renderowanie encji FeatureRecipe dołączenia, gdy dołączenie zawiera blok inject:Własne wpisy inject: dołączenia, pod każdym mechanizmem, który wymienia jego blok — env, file, arg lub niestandardowym, takim jak vault_ref — przy czym każda nazwa lokalna jest mapowana na klucz wskazany przez jej from:. Ten klucz to albo klucz, który encja FeatureRecipe publikuje w swoich provides: i który kompilator dostarcza także do .context.inject komponentu, albo klucz, który sama konsumuje encja FeatureRecipe odczytująca .inject: wpis wskazujący klucz, którego encja FeatureRecipe nie publikuje, zatrzymuje budowanie, chyba że szablon, który encja FeatureRecipe oblicza względem tego kontekstu — jej valuesMapping:, workload:, artifacts:, omits: albo with: lub when: kroku potoku — odczytuje .inject przez ścieżkę wskazaną w szablonie: .inject, .inject.env, {{ with .inject }} i podobne, a nie przez przekazanie całego kontekstu, takie jak toJson .. Jej injectMapping: się nie liczy, ponieważ jest obliczane względem kontekstu komponentu, w którym .inject nie występuje. Blok dołączenia nie zawiera literałów: wpis value: w nim zatrzymuje budowanie, a literał potrzebny komponentowi zapisuje się we własnym bloku inject: komponentu. Mechanizm niestandardowy odczytuje się pod .inject.<mechanism> dokładnie tak jak .inject.env, a jego wpisy pojawiają się w .inject.all obok trzech podstawowych. Odczyt z kropką mechanizmu, którego dołączenie nie definiuje, zatrzymuje budowanie jako nieznany klucz, nawet wewnątrz if lub with, gdzie .context.inject.<mechanism> odczytuje się jako puste; mechanizm, którego dołączenie może nie definiować, należy odczytywać przez {{ with .inject }}{{ if hasKey . "<mechanism>" }}{{ index . "<mechanism>" "<key>" }}{{ end }}{{ end }}, co buduje się niezależnie od tego, czy dołączenie definiuje dany mechanizm lub jakikolwiek blok inject:. Nieobecne w szablonach bazowej encji Recipe oraz w dołączeniu, które nie definiuje żadnego bloku inject:.
.inject_raw (najwyższego poziomu)mapa mechanizmów (może mieć wartość null)Ustawiane, gdy programista napisał blok inject: w komponencie nadrzędnymNiezmieniona intencja programisty sprzed jakiegokolwiek przechwycenia przez mapowanie inject. Każdy mechanizm wskazany w bloku — env, file, arg lub niestandardowy, taki jak ssm_param — znajduje się pod własną nazwą i zawiera wpisy dokładnie w zapisanej postaci (in z from lub value), w zapisanej kolejności: .inject_raw.ssm_param odczytuje mechanizm niestandardowy tak samo, jak .inject_raw.env odczytuje mechanizm podstawowy. Służy do sprawdzeń logicznych typu „czy programista pierwotnie zażądał tego klucza dostarczania?”; odporne na przepisywanie przez injectMapping encji FeatureRecipe. nil, jeśli programista pominął blok inject:.
.context.self_injectmapa mechanizmów (zawsze obecna)Każde renderowanie; puste tam, gdzie programista nie zapisał bloku inject: na komponencieKażda nazwa z własnego bloku inject: komponentu odwzorowana na własny klucz, który dostarcza jej wpis — provides.<key>, values.<key> albo pusty. Służy do pominięcia nazwy domyślnej dla własnej wartości, którą programista już dostarcza; zob. wyżej.

Autorzy potrzebujący rozwiązanego dostarczania po przechwyceniu powinni odczytywać .context.inject. Autorzy potrzebujący niezmiennej pierwotnej intencji (np. aby wykryć przechwycenie lub zastosować zachowanie zastępcze, gdy programista pominął blok inject) powinni odczytywać .inject_raw. Autorzy, którzy muszą wiedzieć, które z własnych wartości komponentu programista już nazwał, powinni odczytywać .context.self_inject.

Miejsce załącznika FeatureRecipe

Gdy renderer ewaluuje szablony załącznika FeatureRecipe, ustawiane jest dodatkowe pole najwyższego poziomu:

  • .attachment_name (string) — nazwa instancji załącznika: slot, który wypełnia w featuresSchema encji będącej właścicielem, lub dowolna nazwa nadana mu przez autora. Sekcje locals:, provides:, injectMapping:, valuesMapping: i artifacts: encji FeatureRecipe odczytują je, aby wyprowadzić deterministyczny identyfikator zasobu — {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }} tam, gdzie provider hosta zgłasza wyrenderowaną nazwę, jak robi to helm, oraz {{ .context.instance_id }}-{{ .attachment_name }} tam, gdzie nie zgłasza żadnej — a także aby nazwać przetwarzany załącznik.

Własne szablony bazowej encji Recipe nie rozwiązują załącznika, więc to pole nie należy do ich kontekstu: szablon provides:, locals: lub source: encji Recipe, który się do niego odwołuje, zatrzymuje kompilację ze wskazaniem tego odwołania, zamiast wyrenderować pustą wartość. Encja FeatureRecipe z executionScope: boundary renderuje się raz dla granicy, a nie raz na komponent, więc to pole nie jest dostępne również dla szablonów uruchamianych dla granicy; jej injectMapping: działa dla każdego komponentu, do którego dociera załącznik, i tam je odczytuje.

W szablonach, które tworzą własne zasoby załącznika — jego valuesMapping:, workload: i artifacts: — kontekst załącznika zawiera też listę komponentów korzystających z jego hosta, w .context.used_by, a tam, gdzie jego FeatureRecipe ustawia readsTargetRenderFacts: true, niesie to, co wyrenderował każdy komponent, z którym połączony jest jego host, w .context.uses.<alias>.render_facts. Te szablony oraz jego kroki pipeline: odczytują również to, co provider hosta zgłosił o renderowaniu hosta, w .context.render_facts. Encja FeatureRecipe o zasięgu granicy renderuje swoje zasoby bez komponentu hosta i bez .context; zamiast tego odczytuje każde połączenie wchodzące do jej granicy w .boundary.internal_uses_edges i .boundary.incoming_cross_boundary_uses_edges. Jej injectMapping: to jedyny zapisany przez nią szablon, który działa w kontekście komponentu — każdego komponentu, do którego dociera załącznik, łącznie z .context.* — a odwołanie do .boundary w nim zatrzymuje kompilację.

To pole jest jedyną drogą do nazwy instancji załącznika. .context.instance_id to komponent hosta, dla którego załącznik jest rozwiązywany — oznacza hosta w każdym miejscu szablonów ewaluowanym przez kompilator, w tym we własnych locals: encji FeatureRecipe — więc te dwie nazwy nie są wymienne i żadna nie zastępuje drugiej.

.source należy do samego dołączenia. Szablon source: encji FeatureRecipe jest obliczany przed jej valuesMapping:, tak jak szablon encji Recipe przed jej własnym, a to, co wytworzył, jest tym, co .source zawiera w szablonach wytwarzających zasoby dołączenia — jej valuesMapping:, omits:, workload: i artifacts: — oraz w jej krokach pipeline:. Nigdy nie jest to źródło komponentu hosta: encja FeatureRecipe, która nie deklaruje source: albo której szablon nic nie wytwarza, niczego tam nie odczytuje, nawet na hoście, którego encja Recipe je deklaruje. Encja FeatureRecipe o zakresie granicy odczytuje własne źródło w tych samych szablonach. Jedynym wyjątkiem jest injectMapping:, który działa przed obliczeniem źródła dołączenia i odczytuje .source tak, jak robi to własna encja Recipe komponentu hosta.

.context.rendered_name również należy do komponentu hosta: w każdym szablonie załącznika per komponent niesie nazwę, jaką własny provider hosta zgłasza dla hosta — wartość odczytywaną przez własną encję Recipe hosta — więc załącznik nazywa zasób od swojego hosta za pomocą {{ .context.rendered_name }}-{{ .attachment_name }} i otrzymuje nazwę akceptowaną przez platformę nawet wtedy, gdy tożsamość hosta zawiera podkreślenie lub wielką literę. Jest obecne wszędzie tam, gdzie provider hosta zgłasza nazwę, i nieobecne tam, gdzie nie zgłasza żadnej, a jego odczyt na takim hoście zatrzymuje kompilację z każdego szablonu, który FeatureRecipe zapisuje inline, z wyjątkiem jego injectMapping:; zob. Nazywanie wyrenderowanego zasobu.

Dostępność w poszczególnych miejscach

Dostępność pól zależy od miejsca szablonu. Szablony provides: encji Recipe są wykonywane podczas ewaluacji provides z samowystarczalnym kontekstem (bez .context.inject/.context.uses); valuesMapping: encji Recipe jest wykonywane podczas renderowania bazowego z pełnym kontekstem szablonu; injectMapping: encji FeatureRecipe jest wykonywane podczas mapowania inject z pełnym kontekstem szablonu, łącznie z przechwytywanym potokiem inject. Pełna tabela dostępności dla poszczególnych miejsc znajduje się w expansion-matrix.md; ta strona dokumentuje kształty pól, na które wskazuje kolumna „dostępne odwołania” tej macierzy.

Odsyłacze