Tworzenie providera: przykład krok po kroku
Ta strona przeprowadza przez całe zadanie tworzenia gościa providera, od pustego katalogu do kompilacji, która zapisuje pliki wyrenderowane przez providera. Stanowi praktyczne uzupełnienie przewodnika dla twórców pluginów, który opisuje encję i cykl życia, oraz kontraktu pluginu, który opisuje gniazda.
Budowany tu provider jest na tyle mały, że można go przeczytać za jednym razem, a przy tym wykonuje rzeczywistą pracę: renderuje pliki środowiskowe. Taki cel dobrze nadaje się na pierwszego providera, ponieważ jego translacja jest naprawdę specyficzna dla formatu — plik środowiskowy ma własną gramatykę kluczy, własne reguły cytowania i nie ma bloku metadanych, w którym można by umieścić pochodzenie kompilacji — więc gość musi podjąć każdą decyzję, którą podejmuje większy provider, bez dużej ilości kodu, która by je ukrywała.
O blokach na tej stronie. Każdy blok z wynikiem skopiowano z rzeczywistego wykonania poniższych kroków, w kolejności, w jakiej występują, zgodnie z konwencją dotyczącą wyników: blok jest albo kompletny, albo jest fragmentem oznaczającym miejsca, w których pominięto wiersze. To przykład, który składa się samodzielnie, a nie przestrzeń robocza do sklonowania, więc bloki źródłowe są plikami do utworzenia, a nie plikami do pobrania.
Czego potrzeba
- Zestaw narzędzi Go, który kompiluje do WebAssembly bez dodatkowych narzędzi.
- Kopia robocza zestawu do tworzenia pluginów, który przedstawia przewodnik dla twórców pluginów, oraz pakietu ABI, na którym ten zestaw się opiera: plik
go.modgościa poniżej wskazuje na oba. - Plik binarny
aggrega.
Kształt gotowego rozwiązania
Provider to dwa artefakty: gość .wasm oraz encja Plugin, która wnosi
go do katalogu. Nic poza tym — żadnej zmiany hosta, żadnej rejestracji, żadnej kompilacji
kompilatora. Dodanie providera polega na umieszczeniu tych dwóch plików tam, gdzie kompilacja może je zobaczyć.
Obszar roboczy, którym kończy się ten przewodnik:
dotenv-walkthrough/ guest/ the Go module that compiles to the .wasm go.mod go.sum main.go catalog/ the Component and Recipe you author component/example/compute/checkout/1.0.0/component.yaml recipe/dotenv/checkout/1.0.0/recipe.yaml dev-catalog/ the generated Plugin entity, with the .wasm beside it plugin/provider/dotenv/0.1.0/plugin.yaml plugin/provider/dotenv/0.1.0/provider--dotenv.wasm dotenv.wasm the compiled guest overlay.yaml the identity you supply to the entity generator aggregate.yaml manifest.yaml release.yaml .aggrega-config.yaml1. Samoopis gościa
Każdy plugin eksportuje describe(). Host wywołuje tę funkcję raz, gdy ładuje
gościa, i odczytuje odpowiedź jako własny opis gościa, mówiący, czym on jest. W przypadku
providera znaczenie mają cztery części tej odpowiedzi.
Należy utworzyć guest/main.go:
// A provider guest that renders environment-file artifacts.package main
import ( "bytes" "fmt" "sort" "strings"
pdk "github.com/extism/go-pdk"
"github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega")
func descriptor() aggrega.PluginDescriptor { return aggrega.PluginDescriptor{ AbiVersion: aggrega.APIVersion, PluginType: "provider", Description: "Render artifact bodies into environment files, quoting and escaping each value as the format requires.", Capabilities: []string{"dotenv"}, Exports: []aggrega.PluginExport{ {Name: "render_node"}, }, Metadata: &aggrega.PluginDescriptorMeta{License: "Apache-2.0"}, }}
//go:wasmexport describefunc describe() int32 { out, err := aggrega.MarshalDescriptor(descriptor()) if err != nil { pdk.SetError(err) return 1 } pdk.Output(out) return 0}PluginType określa, które gniazdo obsługuje ten gość. Capabilities to lista, względem której
rozwiązywana jest encja Recipe: encja Recipe, której spec.capability ma wartość dotenv, zostanie
skierowana do tego gościa. Exports wymienia punkty wejścia, do których host może kierować
wywołania; render_node to ten, który musi mieć każdy provider.
Ten deskryptor jest celowo niekompletny, tak jak zwykle bywa pierwsza wersja robocza. Ujawni się to w pierwszej kompilacji opisanej poniżej.
2. Renderowanie węzła
render_node jest wywoływana raz dla każdego komponentu, który kompilacja renderuje za pośrednictwem tego
providera. Otrzymuje tożsamość węzła, kontekst renderowania oraz te
wstępnie obliczone dane wejściowe, które zadeklarowała powiązana encja Recipe — tutaj zestaw artefaktów, który host
już odczytał i obliczył jako szablon.
Całe zadanie gościa polega na zdecydowaniu, jakie bajty powstaną na wyjściu. Do guest/main.go należy dodać:
// needsQuoting reports whether a value cannot be written bare in an// environment file. A bare value ends at the first space, so anything// carrying whitespace has to be quoted; the quote characters, the comment// introducer and the expansion introducer would each be read as syntax.func needsQuoting(v string) bool { if v == "" { return true } return strings.ContainsAny(v, " \t\n\r\"'#$\\")}
// quote wraps a value in double quotes and escapes what the format reads as// syntax inside them. Order matters: the backslash is escaped first, or the// escapes introduced afterwards would be escaped a second time.func quote(v string) string { v = strings.ReplaceAll(v, `\`, `\\`) v = strings.ReplaceAll(v, `"`, `\"`) v = strings.ReplaceAll(v, "\n", `\n`) v = strings.ReplaceAll(v, "\r", `\r`) v = strings.ReplaceAll(v, "\t", `\t`) return `"` + v + `"`}
// normaliseKey maps an authored key into the environment-variable grammar:// upper case, with the separators an author reaches for folded to// underscores. It reports an error rather than correcting a key that still// does not fit, because a silently-renamed variable is one the application// never reads.func normaliseKey(k string) (string, error) { n := strings.ToUpper(k) n = strings.NewReplacer("-", "_", ".", "_", "/", "_").Replace(n) if n == "" { return "", fmt.Errorf("empty key") } for i, r := range n { switch { case r >= 'A' && r <= 'Z', r == '_': case r >= '0' && r <= '9' && i > 0: default: return "", fmt.Errorf("key %q maps to %q, which is not a valid environment-variable name", k, n) } } return n, nil}Trzy decyzje w tym fragmencie należą do samego providera i żadna inna warstwa nie mogłaby ich podjąć. To, które znaki wymuszają cytowanie, jest właściwością plików środowiskowych. Podobnie gramatyka nazw zmiennych oraz decyzja, by odrzucić klucz, który do niej nie pasuje, zamiast zmieniać jego nazwę — zmienna o zmienionej nazwie to taka, której aplikacja będzie szukać i jej nie znajdzie, co jest gorsze niż przerwana kompilacja.
Pozostały jeszcze dwa elementy: miejsce na informacje o pochodzeniu oraz sam eksport.
// provenanceComment renders the build-provenance key set the host computed as// comment lines. An environment file has no metadata block, so a comment// header is where provenance can go; the keys are emitted in sorted order so// the bytes are identical across runs of identical input.func provenanceComment(annotations map[string]string) []byte { if len(annotations) == 0 { return nil } keys := make([]string, 0, len(annotations)) for k := range annotations { keys = append(keys, k) } sort.Strings(keys) var out bytes.Buffer for _, k := range keys { fmt.Fprintf(&out, "# %s=%s\n", k, annotations[k]) } out.WriteByte('\n') return out.Bytes()}
// renderBody translates one artifact body into environment-file lines. A// blank line and a comment pass through untouched; every other line is// KEY=value, and a line carrying no separator is a loud failure rather than a// line the guest guesses at.func renderBody(name string, body []byte) ([]byte, error) { var out bytes.Buffer for i, raw := range strings.Split(string(body), "\n") { line := strings.TrimSpace(raw) if line == "" || strings.HasPrefix(line, "#") { continue } k, v, found := strings.Cut(line, "=") if !found { return nil, fmt.Errorf("%s line %d: %q declares no value; an entry is KEY=value", name, i+1, line) } key, err := normaliseKey(strings.TrimSpace(k)) if err != nil { return nil, fmt.Errorf("%s line %d: %w", name, i+1, err) } val := strings.TrimSpace(v) if needsQuoting(val) { val = quote(val) } fmt.Fprintf(&out, "%s=%s\n", key, val) } return out.Bytes(), nil}
//go:wasmexport render_nodefunc render_node() int32 { var in aggrega.RenderNodeInput if err := in.DecodeCBOR(pdk.Input()); err != nil { pdk.SetError(fmt.Errorf("dotenv: decode RenderNodeInput: %w", err)) return 1 }
if in.ArtifactsProjection == nil || len(in.ArtifactsProjection.Entries) == 0 { pdk.SetError(fmt.Errorf("dotenv: node %q supplied no artifacts to render", in.Node.ID)) return 1 }
var files []aggrega.RenderedFile for _, e := range in.ArtifactsProjection.Entries { body, err := renderBody(e.Name, e.Content) if err != nil { pdk.SetError(fmt.Errorf("dotenv: %w", err)) return 1 } files = append(files, aggrega.RenderedFile{ Path: e.Name, Content: append(provenanceComment(e.Annotations), body...), Format: "text", }) }
outputBytes, err := aggrega.RenderNodeOutput{Files: files}.EncodeCBOR() if err != nil { pdk.SetError(fmt.Errorf("dotenv: encode RenderNodeOutput: %w", err)) return 1 } pdk.Output(outputBytes) return 0}
func main() {}Dane przechodzą w kodowaniu binarnym, a zestaw narzędzi je odczytuje i zapisuje.
Host przekazuje render_node dane wejściowe w kanonicznym CBOR i odczytuje odpowiedź
w tym samym kodowaniu, więc gość dekoduje za pomocą DecodeCBOR typu wejściowego
i koduje za pomocą EncodeCBOR typu wyjściowego — bez biblioteki CBOR i bez niczego
parsowanego ręcznie. Content pliku to wycinek bajtów, który gość wypełnia
dokładnie tymi bajtami, które mają zostać zapisane; koder przenosi je jako surowe bajty, a host zapisuje
je dosłownie.
Host przekazuje gościowi treść, którą już obliczył. Content każdego wpisu
artefaktu to napisana treść z wyrażeniami szablonu już
rozwiązanymi względem kontekstu renderowania — gość nigdy nie oblicza szablonu
i nigdy nie odczytuje pliku. To właśnie zachowuje nienaruszoną granicę kompilacji
ahead-of-time: gość jest czystą funkcją przekształcającą dane w bajty.
Za determinizm odpowiada gość. W zwykłej kompilacji nic go nie sprawdza. Tutaj wynika on z sortowania kluczy pochodzenia przed ich emisją oraz z przechodzenia wpisów artefaktów w kolejności, w jakiej niosą je dane, a kontrole pod koniec tej strony mierzą wynik.
guest/go.mod odwołuje się do lokalnej kopii zestawu narzędzi:
module example.com/dotenv-provider
go 1.26.0
require ( github.com/aggrega-ai/aggrega-pdk/go v0.0.0 github.com/extism/go-pdk v1.1.3)
require github.com/aggrega-ai/aggrega-abi/go v0.0.0 // indirect
replace github.com/aggrega-ai/aggrega-pdk/go => /path/to/aggrega-pdk/go
replace github.com/aggrega-ai/aggrega-abi/go => /path/to/aggrega-abi/go3. Zbudowanie gościa
Gość to zwykła kompilacja Go z wybranym celem WebAssembly:
cd guestgo mod tidyGOWORK=off GOOS=wasip1 GOARCH=wasm go build -trimpath -buildvcs=false \ -ldflags "-X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Version=0.1.0 \ -X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Commit=walkthru" \ -buildmode=c-shared -o ../dotenv.wasm ./go mod tidy zapisuje go.sum, sumy kontrolne zależności, bez których kompilacja odmawia uruchomienia. -trimpath i -buildvcs=false nie dopuszczają do pliku binarnego ścieżek kompilacji ani znaczników systemu kontroli wersji, dzięki czemu ten sam kod źródłowy w tym samym commicie daje te same bajty. Dwie wartości -ldflags wpisują do gościa jego własną wersję, którą odczytuje następny krok.
Przed dalszymi krokami należy sprawdzić eksporty:
aggrega inspect --plugin dotenv.wasmPlugin .wasm: dotenv.wasmExports: render_nodehostFunctions (derived from binary, not yet recorded by aggrega plugin sync): (none)Ten gość nie importuje żadnych funkcji hosta, co jest domyślnym ustawieniem zgodnym z zasadą najmniejszych uprawnień: nie potrzebuje ani systemu plików, ani sieci, ponieważ wszystko, co renderuje, otrzymuje w ładunku.
4. Wygenerowanie encji Plugin
Pól kontraktu encji nie pisze się ręcznie — są odczytywane z gościa, dzięki czemu encja nie może obiecać czegoś, czego plik binarny nie robi. Należy podać jedynie tożsamość, w niewielkiej nakładce.
overlay.yaml:
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: dotenvaggrega plugin gen-catalog --plugin dotenv.wasm \ --overlay overlay.yaml --output-dir dev-catalog/plugingenerated dev-catalog/plugin/provider/dotenv/0.1.0/plugin.yamlWygenerowana encja:
# Generated from the plugin by `aggrega plugin gen-catalog`. You may narrow its capability lists; edit nothing else here.apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: dotenv version: 0.1.0 pluginType: provider description: Render artifact bodies into environment files, quoting and escaping each value as the format requires.spec: abiVersion: v1beta1 exports: - name: render_node provider: capabilities: - dotenvWarto zauważyć, czego tu nie ma: żadnego wskazania na plik .wasm. Lokalizacja pluginu
jest wyprowadzana z jego tożsamości — ze współrzędnej pluginType/name oraz
skonfigurowanego rejestru — więc nie ma pola lokalizacji, które trzeba by napisać
i w którym można by się pomylić. Skrót zawartości jest zapisywany podczas rozwiązywania encji Release,
w pliku blokady tej encji Release, a nie w encji.
5. Umieszczenie gościa tam, gdzie build będzie go szukać
Podczas tworzenia gościa nie ma jeszcze niczego opublikowanego do pobrania, dlatego
build odczytuje go z katalogu katalogowego: plik .wasm leży obok swojej
encji i nosi nazwę utworzoną od gniazda i pluginu.
dev-catalog/plugin/provider/dotenv/0.1.0/plugin.yamldev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasmcp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasmNazwa pliku zawiera zarówno gniazdo, jak i nazwę, ponieważ sama nazwa pluginu
jest unikatowa tylko w obrębie jego gniazda — dwa pluginy o nazwie dotenv w różnych
gniazdach muszą prowadzić do dwóch różnych plików.
Zbudowany plik należy tam skopiować, a nie tworzyć do niego dowiązania. Dowiązanie w tym miejscu jest śledzone tylko wtedy, gdy prowadzi w obręb przestrzeni roboczej — lub, w przypadku katalogu katalogowego wskazanego poza przestrzenią roboczą, w obręb tego katalogu; dowiązanie prowadzące dalej zatrzymuje build i pull z podaniem nazwy dowiązania, jak opisuje granica przestrzeni roboczej.
Encja pluginu providera w katalogu katalogowym nigdy nie jest przypięta, a ani
pull, ani build nie pobiera jej pliku .wasm, więc plik musi być na miejscu w chwili rozwiązywania encji Release. Pull sprawdza to,
zanim zapisze plik blokady: jeśli nie znajdzie pliku .wasm ani obok encji,
ani w żadnym innym miejscu, z którego build odczytuje pluginy, zatrzymuje się i podaje plik oraz
katalog, w którym się go spodziewał, jak opisuje
A plugin’s .wasm is not on this machine (Pliku wasm pluginu nie ma na tej maszynie).
W pliku .aggrega-config.yaml należy wskazać przestrzeni roboczej oba katalogi katalogowe:
workspace: catalog_dirs: - catalog - dev-catalogauto_pull: trueauto_pull pozwala poleceniu aggrega build rozwiązać encję Release w ramach tego samego procesu, więc pierwszy
build nie wymaga osobnego kroku rozwiązywania.
6. Dokumenty kierowane do dostawcy
Cztery pliki. Encja Component deklaruje, co autor może ustawić; encja Recipe wiąże zdolność i definiuje artefakt; encja Aggregate określa intencję; encja Release ją rozmieszcza.
catalog/component/example/compute/checkout/1.0.0/component.yaml:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: example/compute/checkout version: 1.0.0 description: An application whose configuration is delivered as an environment file. labels: component.aggrega.ai/type: server component.aggrega.ai/category: computespec: schema: values: service_name: type: string default: checkout description: The name the application reports itself under. log_level: type: string default: info description: The application's log verbosity. greeting: type: string default: hello description: A value carrying characters the environment-file format must quote. infra: endpoint: type: string default: http://localhost:8080 description: The endpoint the operator points the application at.catalog/recipe/dotenv/checkout/1.0.0/recipe.yaml:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: checkout version: 1.0.0 description: Renders the application's configuration as an environment file.spec: capability: dotenv implements: example/compute/checkout:1.0.0
artifacts: app.env: | service-name = {{ .values.service_name }} log.level = {{ .values.log_level }} greeting = {{ .values.greeting }} endpoint = {{ .infra.endpoint }}spec.capability: dotenv to całe powiązanie. Wskazuje zdolność, a nie
plugin: kompilacja rozwiązuje ją do tego pluginu dostawcy, który deklaruje tę
zdolność. Jeśli robi to dokładnie jeden — jak tutaj — nic więcej nie jest potrzebne.
Zdefiniowane klucze celowo nie mają postaci zmiennych środowiskowych.
service-name i log.level to zapisy, których autor naturalnie by użył,
a ich normalizacja jest zadaniem dostawcy.
aggregate.yaml:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: aggregate version: "1.0.0" description: One application whose configuration is an environment file.spec: components: app: type: example/compute/checkout values: service_name: checkout log_level: debug greeting: hello worldmanifest.yaml:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: manifest version: "1.0.0" description: Binds the component type to the environment-file recipe.spec: mappings: components: type: example/compute/checkout:1.0.0: checkout:1.0.0release.yaml:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: walkthrough environment: production version: "1.0.0"spec: aggregate: aggregate manifest: manifest boundaries: infra: directory: infra components: app: infra: endpoint: "https://checkout.example.net"7. Pierwsza kompilacja i to, czego odmawia
aggrega build --release release.yaml --auto-pull warning: plugin "provider/dotenv" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recorded[… omitted: the notice saying the Release could not be rendered to discover its external inputs, carrying the error below beneath its first line]Pull complete: release.lock (entities=5, source_artifacts=0, external_inputs=0)[… omitted: a line saying again that external inputs were not fully discovered][CATALOG_ERROR E0265] instance app provider does not support the node's input kind (node "app"). provider "dotenv" does not support artifacts-only recipes (this provider supports: none); declare one of the supported input kinds, or target a provider that supports artifacts-onlyObie linie należy czytać osobno, ponieważ mówią różne rzeczy.
Ostrzeżenie jest oczekiwane w trakcie programowania i nie zniknie. Mówi ono, że gość został uruchomiony bez zapisanego skrótu treści, z którym można by go porównać, co jest prawdą w przypadku gościa zbudowanego przed chwilą: nic go nie opublikowało, więc nie ma zapisanego skrótu. Mówi też, dlaczego ponowne rozwiązanie encji Release niczego by nie zmieniło — gość wczytywany obok swojej encji w katalogu jest wczytywany od nowa przez każdą kompilację, a pobranie zapisuje skrót tylko dla wtyczki zarządczej podłączonej w roli transformacji, którą ten gość nie jest — oraz co by to zmieniło: opublikowanie wtyczki i odwołanie się do opublikowanej encji. Ostrzeżenie należy rozumieć jako poprawną odmowę kompilacji przypisania sobie weryfikacji, której nie przeprowadziła, i spodziewać się go tak długo, jak gość jest lokalny.
Błąd jest właściwym wynikiem, a nawias zawiera diagnozę.
Dostawca został znaleziony, wczytany i zapytany, co renderuje, a odpowiedział
none — this provider supports: none. Deskryptor napisany na początku
wskazywał gniazdo, możliwość i eksporty, ale nigdy nie określał, który z
trzech rodzajów wejścia encji Recipe obsługuje gość. Host nie zgaduje: bramka rodzajów
wejścia odczytuje zadeklarowany zbiór gościa i odrzuca węzeł, do którego gość się nie zgłosił.
Tak wygląda większość niepowodzeń przy pierwszym dostawcy. Z gościem wszystko jest w porządku;
niekompletny jest jego samoopis. describe() nie jest formalnością, którą host toleruje —
to cała podstawa, na której agnostyczny wobec formatu host decyduje, co i dokąd wysłać.
8. Zadeklarowanie kontraktu zachowania renderowania
Kontrakt należy dodać do deskryptora w guest/main.go:
Capabilities: []string{"dotenv"}, Contract: &aggrega.ProviderContract{ InputKinds: aggrega.InputKinds{ Sourced: false, Synthesized: false, ArtifactsStandalone: true, }, BoundaryAssembly: "none", }, Exports: []aggrega.PluginExport{ArtifactsStandalone: true to deklaracja, której szukała bramka. Dwie
wartości false także są deklaracjami i właśnie o ich podanie chodzi: encja Recipe, która
dołącza drzewo źródeł, lub taka, która deklaruje workload, jest teraz odrzucana przed
uruchomieniem jakiegokolwiek renderowania, z komunikatem wskazującym ten provider — zamiast dotrzeć do
render_node i zakończyć się błędem gdzieś w jego wnętrzu.
BoundaryAssembly: "none" oznacza, że wynik każdego węzła jest zapisywany tam, gdzie trafia,
bez niczego do łączenia. Provider, który scala kilka komponentów w jeden
dokument, deklaruje zamiast tego merge lub nest i eksportuje assemble_boundary, aby
to wykonać. To naturalny kolejny element do dodania do tego providera; jest
opisany w kontrakcie pluginu.
Należy przebudować gościa, ponownie wygenerować encję i umieścić nowy plik .wasm z powrotem obok
niej:
cd guestGOWORK=off GOOS=wasip1 GOARCH=wasm go build -trimpath -buildvcs=false \ -ldflags "-X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Version=0.1.0 \ -X github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega.Commit=walkthru" \ -buildmode=c-shared -o ../dotenv.wasm ./cd ..aggrega plugin gen-catalog --plugin dotenv.wasm \ --overlay overlay.yaml --output-dir dev-catalog/plugincp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasmPonownie wygenerowana encja zawiera teraz kontrakt odczytany z pliku binarnego:
[… omitted: the header comments and the metadata block, unchanged from the first generation]spec: abiVersion: v1beta1 exports: - name: render_node provider: capabilities: - dotenv contract: inputKinds: artifactsStandalone: true boundaryAssembly: nonePonowne generowanie encji po każdej przebudowie gościa jest częścią cyklu pracy. Encja powtarza to, co zgłasza plik binarny, a oba są porównywane podczas ładowania gościa: eksport lub wartość kontraktu, które encja deklaruje, a plik binarny ich nie zgłasza, to niezgodność, na której build się zatrzymuje, wskazując tę deklarację. Deklaracja pominięta w encji nie jest sprawdzana, więc encja nieodświeżona po przebudowie, która coś do pliku binarnego dodała — jak ten krok — nadal się ładuje, choć już go nie opisuje.
9. Kompilacja, która renderuje
aggrega build --release release.yaml --auto-pull warning: plugin "provider/dotenv" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recordedPull complete: release.lock (entities=5, source_artifacts=0, external_inputs=0)[… omitted: a line reporting total build time, which differs on every run]Build completed: 1 file written to <workspace>/distOstatni wiersz podaje pełną ścieżkę katalogu wyjściowego, gdzie <workspace> oznacza
katalog główny obszaru roboczego. Wyrenderowane drzewo poniżej niego:
dist/infra/dotenv/app/app.envOraz plik zapisany przez provider, w całości:
# aggrega.ai/boundary-path=infraSERVICE_NAME=checkoutLOG_LEVEL=debugGREETING="hello world"ENDPOINT=https://checkout.example.netKażda decyzja podjęta przez moduł gościa jest widoczna w tych siedmiu wierszach.
service-nameilog.leveldotarły w postaci nadanej przez autora i wyszły jakoSERVICE_NAMEiLOG_LEVEL. Autor nigdy nie musiał pisać w gramatyce formatu docelowego.GREETINGjest ujęte w cudzysłów, a pozostałe trzy nie.hello worldzawiera spację, więc bez cudzysłowu wartość kończyłaby się nahello; punkt końcowy nie zawiera żadnego ze znaków, które format odczytuje jako składnię, więc cudzysłów dodałby tylko szum.- Dwa klucze pochodzenia są komentarzami, ponieważ plik środowiskowy nie ma innego miejsca, w którym można je umieścić. Provider, którego wynik ma blok metadanych, umieszcza te same klucze właśnie tam. Klucze obliczył host; moduł gościa wybrał ich położenie.
- Wartości pochodzą od dwóch różnych autorów.
service_name,log_leveligreetingto intencja programisty, z encji Aggregate.endpointpochodzi od operatora, z encji Release. Moduł gościa nie widział żadnego z tych rozróżnień — otrzymał jedną obliczoną treść.
10. Dwie rzeczy, które warto sprawdzić, zanim się mu zaufa
Czy jest deterministyczny. Należy przechwycić wynik, przebudować i porównać:
cp -r dist ../capture && rm -rf distaggrega build --release release.yamldiff -r ../capture distOczekiwanym wynikiem jest to, że diff niczego nie wypisuje. Determinizm jest kontraktem gościa, a nie hosta, a gość, który gdzieś na ścieżce generowania wyniku iteruje po mapie Go,
nie przejdzie tego testu, choć w pojedynczej kompilacji wygląda na całkowicie poprawny.
Czy jego odmowy są głośne. Należy zepsuć jeden wiersz artefaktu encji Recipe, tak aby nie deklarował żadnej wartości:
artifacts: app.env: | service-name = {{ .values.service_name }} this line declares no value[… omitted: the unverified-plugin warning, and the pull's lines saying the Release could not be rendered to discover its external inputs][CATALOG_ERROR] instance app rendering node "app" caused by: wasm: plugin "provider/dotenv:0.1.0" call to render_node: dotenv: app.env line 2: "this line declares no value" declares no value; an entry is KEY=valueWłasny komunikat gościa dociera do autora w nienaruszonej postaci, wraz z plikiem i wierszem, z którego pochodzi. Warto to celowo sprawdzić, ponieważ alternatywny błąd — gość, który po cichu pomija wiersz, którego nie potrafi przeanalizować — daje kompilację, która kończy się powodzeniem, i wdrożenie bez jednej zmiennej, a nic w wyniku o tym nie informuje.
11. Co dodać w następnej kolejności
Zbudowany tutaj provider jest kompletny, ale minimalny. W przybliżonej kolejności od najczęściej potrzebnych:
-
assemble_boundary, aby scalić wyjście kilku komponentów w jeden dokument, deklarowane przezBoundaryAssembly. -
validate_node_input, aby sprawdzić strukturę wejścia węzła przed uruchomieniem jakiegokolwiek renderowania, tak aby błędne wejście zostało zgłoszone na granicy tworzenia, a nie w trakcie renderowania. -
Fakty renderowania, aby zgłosić coś o tym, co zapisał gość, co widać tylko dzięki wiedzy tego providera o formacie pliku środowiskowego — tutaj nazwy zmiennych definiowanych przez każdy plik. Fakt to nazwa i lista, obie należące do własnego słownictwa tego providera, zwracane obok plików — a wartość jest zawsze tablicą JSON, nawet z jednym wpisem, w przeciwnym razie budowanie zostaje zatrzymane:
// names lists the variables the files define, in the order they were written.value, err := json.Marshal(names)if err != nil {pdk.SetError(fmt.Errorf("dotenv: marshal render fact: %w", err))return 1}out := aggrega.RenderNodeOutput{Files: files,RenderFacts: []aggrega.RenderFact{{Name: "variable_names", Value: value}},}Kompilator zachowuje fakty w kolejności, w jakiej wymienia je gość, sprawdza jedynie, czy każda wartość jest listą, przekazuje listy szablonom encji Feature, które je odczytują, i zapisuje te same pliki niezależnie od tego, czy fakty zostały zgłoszone. Nazwę każdego faktu i zawartość jego wpisów należy udokumentować jako część kontraktu providera.
-
Wpisy pominięć, gdy provider zacznie renderować źródło. Wejście renderowania źródła może zawierać
Omits, czyli wpisy wskazujące renderowane jednostki do pominięcia, obok swojegoSourceListing; provider, który je respektuje, pomija każdą dopasowaną jednostkę w tym, co zwraca, zgłasza jedną liczbę na wpis wOmittedi deklarujeOmits: truew swoim kontrakcie. Nigdy nie towarzyszą one renderowaniu samych artefaktów, takiemu jak w tym providerze, więc napotka je on dopiero wtedy, gdy wyrenderuje wejście ze źródłem. Pełny kształt opisuje sekcja Pomijanie renderowanych jednostek w kontrakcie wtyczki. -
Publikowanie, które zamienia lokalny układ
dev-catalogw artefakt przypięty skrótem, który encja Release rozwiązuje i weryfikuje. Przewodnik dla twórców wtyczek omawia ten cykl życia w etapach publikowania, pobierania i budowania.
Kształty ładunku i wyniku każdego gniazda opisuje kontrakt wtyczki.
Powiązane materiały
- Przewodnik programisty wtyczek Wasm — encja
Plugin, zakres możliwości oraz cykl życia publikacji. - Kontrakt Plugin — kształty wejścia i wyjścia każdego gniazda.
- Architektura Provider — jak dostawcy wpisują się w potok kompilacji.
- Indeks referencyjny Provider — co generuje każdy dostawca z biblioteki standardowej.
- Odczytywanie wyników na tych stronach — konwencja, której przestrzegają powyższe bloki wyników.