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

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.mod goś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.yaml

1. 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 describe
func 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_node
func 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/go

3. Zbudowanie gościa

Gość to zwykła kompilacja Go z wybranym celem WebAssembly:

Terminal window
cd guest
go mod tidy
GOWORK=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:

Terminal window
aggrega inspect --plugin dotenv.wasm
Plugin .wasm: dotenv.wasm
Exports:
render_node
hostFunctions (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/v1beta1
kind: Plugin
metadata:
name: dotenv
Terminal window
aggrega plugin gen-catalog --plugin dotenv.wasm \
--overlay overlay.yaml --output-dir dev-catalog/plugin
generated dev-catalog/plugin/provider/dotenv/0.1.0/plugin.yaml

Wygenerowana encja:

# Generated from the plugin by `aggrega plugin gen-catalog`. You may narrow its capability lists; edit nothing else here.
apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
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:
- dotenv

Warto 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.yaml
dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasm
Terminal window
cp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasm

Nazwa 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-catalog
auto_pull: true

auto_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/v1beta1
kind: Component
metadata:
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: compute
spec:
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/v1beta1
kind: Recipe
metadata:
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/v1beta1
kind: Aggregate
metadata:
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 world

manifest.yaml:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
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.0

release.yaml:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
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

Terminal window
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-only

Obie 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:

Terminal window
cd guest
GOWORK=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/plugin
cp dotenv.wasm dev-catalog/plugin/provider/dotenv/0.1.0/provider--dotenv.wasm

Ponownie 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: none

Ponowne 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

Terminal window
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
Pull 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>/dist

Ostatni 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.env

Oraz plik zapisany przez provider, w całości:

1.0.0
# aggrega.ai/boundary-path=infra
SERVICE_NAME=checkout
LOG_LEVEL=debug
GREETING="hello world"
ENDPOINT=https://checkout.example.net

Każda decyzja podjęta przez moduł gościa jest widoczna w tych siedmiu wierszach.

  • service-name i log.level dotarły w postaci nadanej przez autora i wyszły jako SERVICE_NAME i LOG_LEVEL. Autor nigdy nie musiał pisać w gramatyce formatu docelowego.
  • GREETING jest ujęte w cudzysłów, a pozostałe trzy nie. hello world zawiera spację, więc bez cudzysłowu wartość kończyłaby się na hello; 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_level i greeting to intencja programisty, z encji Aggregate. endpoint pochodzi 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ć:

Terminal window
cp -r dist ../capture && rm -rf dist
aggrega build --release release.yaml
diff -r ../capture dist

Oczekiwanym 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=value

Wł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 przez BoundaryAssembly.

  • 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 swojego SourceListing; provider, który je respektuje, pomija każdą dopasowaną jednostkę w tym, co zwraca, zgłasza jedną liczbę na wpis w Omitted i deklaruje Omits: true w 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-catalog w 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.