Створення провайдера: покроковий приклад
На цій сторінці покроково розглянуто все завдання створення гостя-провайдера: від порожнього каталогу до збірки, яка записує файли, відрендерені провайдером. Це практичний супровід до посібника розробника плагінів, який описує сутність і життєвий цикл, та до контракту плагіна, який описує сокети.
Провайдер, який тут створюється, достатньо малий, щоб прочитати його за один раз, і виконує справжню роботу: він рендерить файли змінних середовища. Ця ціль добре підходить для першого провайдера, бо її перетворення справді залежить від формату: файл змінних середовища має власну граматику ключів, власні правила лапок і не має блоку метаданих, куди можна було б записати походження збірки. Тож гість мусить ухвалити кожне рішення, яке ухвалює більший провайдер, і жоден великий обсяг коду цих рішень не приховує.
Про блоки на цій сторінці. Кожен блок із виводом скопійовано зі справжнього виконання наведених нижче кроків у тому порядку, у якому вони йдуть, згідно з домовленістю щодо виводу: блок або повний, або є уривком, у якому позначено, де пропущено рядки. Це покроковий приклад, який ви збираєте самостійно, а не робочий простір, який можна клонувати, тож блоки з кодом — це файли, які слід створити, а не файли, які слід отримати з репозиторію.
Що вам знадобиться
- Набір інструментів Go, який компілює у WebAssembly без додаткових інструментів.
- Локальна копія набору для розробки плагінів, з яким знайомить посібник розробника плагінів, і пакета ABI, на якому побудовано цей набір:
go.modгостьового модуля нижче вказує на обидва. - Виконуваний файл
aggrega.
Як виглядає готовий результат
Провайдер — це два артефакти: гість .wasm і сутність Plugin, яка переносить
його в каталог. Більше нічого — жодних змін хоста, жодної реєстрації, жодного збирання
компілятора. Додати провайдер означає додати ці два файли туди, де збирання може їх побачити.
Робочий простір, яким завершується цей покроковий посібник:
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. Самоопис гостя
Кожен плагін експортує describe(). Хост викликає цю функцію один раз, коли завантажує
гостя, і сприймає відповідь як власний опис гостя про те, чим він є. Для
провайдера важливі чотири частини цієї відповіді.
Створіть 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 вказує, який сокет обслуговує цей гість. Capabilities — це список, за яким
розв’язується Recipe: Recipe, у якого spec.capability має значення dotenv, буде
спрямовано до цього гостя. Exports називає точки входу, до яких хост може надсилати
виклики; render_node — та, яку повинен мати кожен провайдер.
Цей дескриптор навмисно неповний, як зазвичай буває з першою чернеткою. Саме перше збирання нижче це й покаже.
2. Рендеринг вузла
render_node викликається один раз для кожного компонента, який збірка рендерить через цей
провайдер. Вона отримує ідентичність вузла, контекст рендерингу та ті
попередньо обчислені вхідні дані, які оголосила прив’язана сутність Recipe, — тут це набір артефактів, який хост
уже прочитав і обчислив як шаблон.
Уся робота гостя полягає в тому, щоб вирішити, які байти буде видано. Додайте до guest/main.go:
// 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}Три рішення в цьому фрагменті належать саме провайдеру, і жоден інший рівень не міг би їх ухвалити. Які символи вимагають лапок — це факт про файли середовища. Так само й граматика імен змінних, і так само вибір відхилити ключ, який не відповідає їй, замість того щоб перейменувати його: перейменовану змінну застосунок шукатиме й не знайде, а це гірше, ніж зупинена збірка.
Тепер дві частини, що залишилися: куди потрапляє походження, і сам експорт.
// 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() {}Корисне навантаження передається у двійковому кодуванні, і набір інструментів читає та записує його.
Хост передає render_node вхідні дані як канонічний CBOR і читає відповідь
у тому самому кодуванні, тож гість декодує за допомогою DecodeCBOR типу вхідних даних
і кодує за допомогою EncodeCBOR типу вихідних даних — без бібліотеки CBOR і без жодного
ручного розбору. Content файлу — це зріз байтів, який гість заповнює
точними байтами для запису; кодувальник передає їх як сирі байти, а хост записує
їх дослівно.
Хост передає гостю вміст, який він уже обчислив. Content кожного запису
артефакту — це написане автором тіло, шаблонні вирази якого вже
розв’язано щодо контексту рендерингу: гість ніколи не обчислює шаблон і
ніколи не читає файл. Саме це зберігає непорушною межу компіляції наперед (ahead-of-time):
гість є чистою функцією від корисного навантаження до байтів.
Детермінованість — відповідальність гостя. Під час звичайної збірки ніщо не перевіряє її за вас. Тут вона досягається сортуванням ключів походження перед їх виведенням і обходом записів артефактів у порядку, у якому їх несе корисне навантаження, а перевірки наприкінці цієї сторінки вимірюють результат.
guest/go.mod посилається на ваш локальний клон набору інструментів:
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. Зберіть гостьовий модуль
Гостьовий модуль — це звичайна збірка Go з вибраною ціллю 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 записує go.sum — контрольні суми залежностей, без яких збірка відмовляється запускатися. -trimpath і -buildvcs=false не допускають у бінарний файл шляхів збірки та позначок системи керування версіями, тож той самий вихідний код на тому самому коміті дає ті самі байти. Два значення -ldflags вписують у гостьовий модуль його власну версію, яку зчитує наступний крок.
Перш ніж продовжувати, перевірте експорти:
aggrega inspect --plugin dotenv.wasmPlugin .wasm: dotenv.wasmExports: render_nodehostFunctions (derived from binary, not yet recorded by aggrega plugin sync): (none)Цей гостьовий модуль не імпортує жодних функцій хоста, що є типовим налаштуванням мінімальних привілеїв: йому не потрібні ні файлова система, ні мережа, бо все, що він рендерить, надходить у корисному навантаженні.
4. Згенеруйте сутність Plugin
Поля контракту сутності не пишуться вручну — вони зчитуються з гостя, щоб сутність не могла обіцяти те, чого не робить двійковий файл. Ви надаєте лише ідентичність у невеликому накладенні.
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.yamlЗгенерована сутність:
# 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: - dotenvЗверніть увагу, чого тут немає: жодного вказівника на .wasm. Розташування плагіна виводиться з його ідентичності — координати pluginType/name разом із тим реєстром, який налаштовано, — тож немає поля розташування, яке треба писати, і немає такого, у якому можна помилитися. Дайджест вмісту записується, коли розв’язується сутність Release, у lock-файлі цієї сутності Release, а не в сутності.
5. Покладіть guest туди, де збірка його шукатиме
Поки ви розробляєте guest, опублікованого нічого немає, тож збірка читає його з каталогу: файл .wasm лежить поруч зі своєю
сутністю і названий за сокетом і плагіном.
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.wasmІм’я файлу містить сокет, а не лише ім’я, бо голе ім’я плагіна
унікальне лише в межах його сокета — два плагіни з назвою dotenv на різних
сокетах мають вести до двох різних файлів.
Скопіюйте зібраний файл туди, а не створюйте на нього посилання. Посилання в цьому місці відстежується лише до цілі всередині робочого простору — або, для каталогу, вказаного поза робочим простором, до цілі всередині цього каталогу; посилання, що веде далі, зупиняє збірку й pull із зазначенням цього посилання, як описано в розділі межа робочого простору.
Сутність плагіна провайдера в каталозі ніколи не закріплюється, і ні
pull, ні збірка не завантажують її .wasm, тож файл має бути на місці, коли сутність Release розв’язується. Pull перевіряє це
перед записом lockfile: якщо він не знаходить .wasm ні поруч із сутністю,
ні деінде, звідки збірка читає плагіни, він зупиняється й називає файл і
каталог, де очікував його знайти, як описано в розділі
A plugin’s .wasm is not on this machine (Файл плагіна відсутній на цій машині).
Вкажіть робочому простору обидва каталоги у .aggrega-config.yaml:
workspace: catalog_dirs: - catalog - dev-catalogauto_pull: trueauto_pull дає змогу aggrega build розв’язати сутність Release у межах процесу, тож першій
збірці не потрібен окремий крок розв’язання.
6. Документи, що націлені на провайдер
Чотири файли. Component оголошує, що може задати автор; Recipe прив’язує можливість і створює артефакт; Aggregate формулює намір; Release розміщує його.
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 — це вся прив’язка. Вона називає можливість, а не плагін: збірка зіставляє її з тим плагіном провайдера, який оголошує цю можливість. Якщо такий плагін рівно один, як тут, більше нічого не потрібно.
Створені автором ключі навмисно записано не у формі змінних середовища.
service-name і log.level — це написання, яке автор природно використав би, а нормалізувати їх — завдання провайдера.
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. Перша збірка і те, від чого вона відмовляється
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Читайте ці два рядки окремо, бо вони кажуть різне.
Попередження очікуване під час розробки, і воно не зникне. Воно каже, що гостьовий модуль запустився без записаного дайджесту вмісту, з яким його можна було б звірити, і це правда для гостьового модуля, який ви зібрали хвилину тому: ніхто його не публікував, тож записаного дайджесту немає. Воно також пояснює, чому повторне розв’язання сутності Release не змінило б цього — гостьовий модуль, прочитаний поруч із його сутністю в каталозі, читається заново кожною збіркою, а pull записує дайджест лише для plugin керування, підключеного в ролі перетворення, а цей гостьовий модуль таким не є, — і що змінило б: публікація plugin і посилання на опубліковану сутність. Сприймайте це попередження як те, що збірка слушно відмовляється заявляти про перевірку, якої не виконувала, і очікуйте його, поки гостьовий модуль локальний.
Помилка — це справжня знахідка, а дужки містять діагноз. Provider
було знайдено, завантажено й запитано, що він рендерить, і він відповів
none — this provider supports: none. Дескриптор, написаний на початку,
називав сокет, можливість і експорти, але ніде не вказував, які з
трьох видів вхідних даних сутності Recipe обробляє гостьовий модуль. Хост не вгадуватиме: шлюз видів вхідних даних
читає задекларований гостьовим модулем набір і відхиляє вузол, на який гостьовий модуль ніколи не претендував.
Так виглядає більшість збоїв першого provider. Гостьовий модуль справний; його
самоопис неповний. describe() — це не формальність, яку хост терпить, —
це вся основа, на якій агностичний щодо формату хост вирішує, що куди надсилати.
8. Оголосіть контракт поведінки рендерингу
Додайте контракт до дескриптора в 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 — це саме та заява, яку шукав фільтр. Два значення
false також є заявами, і саме в їх явному зазначенні полягає суть: сутність Recipe, яка
вендорить дерево вихідного коду, або та, що оголошує workload, тепер відхиляється ще до
будь-якого рендерингу, з повідомленням, що називає цей provider, — замість того щоб дійти до
render_node і зазнати збою десь усередині нього.
BoundaryAssembly: "none" означає, що вивід кожного вузла записується туди, куди він потрапляє,
і нічого не потрібно об’єднувати. Provider, який згортає кілька компонентів в один
документ, натомість оголошує merge або nest і експортує assemble_boundary, щоб
це зробити. Це природний наступний крок для цього provider, і його
описано в контракті плагіна.
Перезберіть гостьовий модуль, повторно згенеруйте сутність і знову покладіть новий .wasm поруч
із нею:
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.wasmПовторно згенерована сутність тепер містить контракт, прочитаний із бінарного файлу:
[… 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Повторна генерація сутності після кожного перезбирання гостьового модуля є частиною циклу. Сутність повторює те, що повідомляє бінарний файл, і під час завантаження гостьового модуля їх перехресно перевіряють: експорт або значення контракту, які заявляє сутність, але не повідомляє бінарний файл, — це невідповідність, на якій збірка зупиняється, називаючи це твердження. Твердження, яке сутність пропускає, не перевіряється, тож сутність, що залишилася після перезбирання, яке щось додало до бінарного файлу, — як цей крок, — усе одно завантажується, хоча вже не описує його.
9. Збірка, яка рендерить
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>/distОстанній рядок повністю називає вихідний каталог, де <workspace> позначає
корінь робочого простору. Відрендероване дерево під ним:
dist/infra/dotenv/app/app.envІ файл, який записав provider, повністю:
# aggrega.ai/boundary-path=infraSERVICE_NAME=checkoutLOG_LEVEL=debugGREETING="hello world"ENDPOINT=https://checkout.example.netКожне рішення, яке ухвалює гість, видно в цих семи рядках.
service-nameіlog.levelнадійшли такими, як їх написав автор, а вийшли якSERVICE_NAMEіLOG_LEVEL. Авторові ніколи не доводилося писати граматикою цільового формату.GREETINGузято в лапки, а три інші — ні.hello worldмістить пробіл, тож без лапок значення закінчилося б наhello; кінцева точка не містить жодного із символів, які формат читає як синтаксис, тож лапки лише додали б шуму.- Два ключі походження є коментарями, бо у файлі середовища більше ніде їх розмістити. Провайдер, вихідні дані якого мають блок метаданих, натомість розміщує ті самі ключі там. Ключі обчислив хост; гість вибрав їхнє розташування.
- Значення надійшли від двох різних авторів.
service_name,log_levelіgreeting— це наміри розробника, із сутності Aggregate.endpointналежить операторові, із сутності Release. Гість не бачив жодної з цих відмінностей — він отримав одне обчислене тіло.
10. Дві речі, які варто перевірити, перш ніж довіряти йому
Що він детермінований. Збережіть вивід, зберіть повторно й порівняйте:
cp -r dist ../capture && rm -rf distaggrega build --release release.yamldiff -r ../capture distБажаний результат — коли diff нічого не виводить. Детермінованість є контрактом гостя, а не хоста, і гість, який десь на шляху формування виводу ітерує map у Go, не пройде цієї перевірки, хоча в окремій збірці виглядатиме цілком коректним.
Що його відмови помітні. Зіпсуйте один рядок артефакту сутності Recipe, щоб він не оголошував значення:
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Власне повідомлення гостя доходить до автора без змін, разом із файлом і рядком, з яких воно походить. Це варто перевірити навмисно, бо альтернативна відмова — гість, що мовчки пропускає рядок, який не може розібрати, — дає збірку, яка завершується успішно, і розгортання без змінної, і ніщо у виводі про це не повідомляє.
11. Що додати далі
Створений тут провайдер повний, але мінімальний. Приблизно в порядку того, як часто потрібне кожне:
-
assemble_boundary, щоб об’єднати вивід кількох компонентів в один документ, оголошується черезBoundaryAssembly. -
validate_node_input, щоб структурно перевірити вхідні дані вузла до запуску будь-якого рендерингу, і тоді некоректні вхідні дані буде повідомлено на межі створення, а не посеред рендерингу. -
Факти рендерингу, щоб повідомити про те, що записав гостьовий модуль, і що бачить лише знання цього провайдера про формат файлу середовища, — тут це імена змінних, які визначає кожен файл. Факт — це ім’я і список, обидва з власного словника цього провайдера, що повертаються поруч із файлами, — і значення завжди є масивом JSON, навіть з одним елементом, інакше збірка зупиняється:
// 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}},}Компілятор зберігає факти в порядку, в якому їх перелічує гостьовий модуль, перевіряє лише те, що кожне значення є списком, передає списки шаблонам Feature, які їх читають, і записує ті самі файли незалежно від того, чи повідомлено факти. Задокументуйте ім’я кожного факту і те, що містять його елементи, як частину контракту провайдера.
-
Записи пропуску, щойно провайдер рендерить джерело. Вхідні дані рендерингу джерела можуть містити
Omits, записи з назвами відрендерених одиниць, які слід пропустити, поруч ізSourceListing; провайдер, який їх враховує, пропускає кожну знайдену одиницю у тому, що повертає, повідомляє одну кількість на запис уOmittedі оголошуєOmits: trueу своєму контракті. Вони ніколи не супроводжують рендеринг лише артефактів, як у цього провайдера, тож він зустрічає їх лише після того, як рендерить вхідні дані з джерелом. Пропуск відрендерених одиниць у контракті плагіна містить повну структуру. -
Публікація, яка перетворює локальне розміщення
dev-catalogна артефакт, закріплений за дайджестом, який сутність Release розв’язує та перевіряє. Посібник розробника плагінів описує цей життєвий цикл на етапах публікації, отримання та збирання.
Структури корисного навантаження і результату кожного сокета наведено в контракті плагіна.
Пов’язані довідники
- Посібник розробника Wasm-плагінів — сутність
Plugin, поверхня можливостей і життєвий цикл публікації. - Контракт Plugin — форми вхідних і вихідних даних кожного сокета.
- Архітектура Provider — як провайдери вбудовуються в конвеєр компіляції.
- Довідковий покажчик Provider — що створює кожен провайдер стандартної бібліотеки.
- Як читати вивід на цих сторінках — домовленість, якої дотримуються наведені вище блоки виводу.