Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Створення провайдера: покроковий приклад

На цій сторінці покроково розглянуто все завдання створення гостя-провайдера: від порожнього каталогу до збірки, яка записує файли, відрендерені провайдером. Це практичний супровід до посібника розробника плагінів, який описує сутність і життєвий цикл, та до контракту плагіна, який описує сокети.

Провайдер, який тут створюється, достатньо малий, щоб прочитати його за один раз, і виконує справжню роботу: він рендерить файли змінних середовища. Ця ціль добре підходить для першого провайдера, бо її перетворення справді залежить від формату: файл змінних середовища має власну граматику ключів, власні правила лапок і не має блоку метаданих, куди можна було б записати походження збірки. Тож гість мусить ухвалити кожне рішення, яке ухвалює більший провайдер, і жоден великий обсяг коду цих рішень не приховує.

Про блоки на цій сторінці. Кожен блок із виводом скопійовано зі справжнього виконання наведених нижче кроків у тому порядку, у якому вони йдуть, згідно з домовленістю щодо виводу: блок або повний, або є уривком, у якому позначено, де пропущено рядки. Це покроковий приклад, який ви збираєте самостійно, а не робочий простір, який можна клонувати, тож блоки з кодом — це файли, які слід створити, а не файли, які слід отримати з репозиторію.

Що вам знадобиться

  • Набір інструментів 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.yaml

1. Самоопис гостя

Кожен плагін експортує 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 describe
func 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_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() {}

Корисне навантаження передається у двійковому кодуванні, і набір інструментів читає та записує його. Хост передає 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/go

3. Зберіть гостьовий модуль

Гостьовий модуль — це звичайна збірка Go з вибраною ціллю 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 записує go.sum — контрольні суми залежностей, без яких збірка відмовляється запускатися. -trimpath і -buildvcs=false не допускають у бінарний файл шляхів збірки та позначок системи керування версіями, тож той самий вихідний код на тому самому коміті дає ті самі байти. Два значення -ldflags вписують у гостьовий модуль його власну версію, яку зчитує наступний крок.

Перш ніж продовжувати, перевірте експорти:

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)

Цей гостьовий модуль не імпортує жодних функцій хоста, що є типовим налаштуванням мінімальних привілеїв: йому не потрібні ні файлова система, ні мережа, бо все, що він рендерить, надходить у корисному навантаженні.

4. Згенеруйте сутність Plugin

Поля контракту сутності не пишуться вручну — вони зчитуються з гостя, щоб сутність не могла обіцяти те, чого не робить двійковий файл. Ви надаєте лише ідентичність у невеликому накладенні.

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

Згенерована сутність:

# 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

Зверніть увагу, чого тут немає: жодного вказівника на .wasm. Розташування плагіна виводиться з його ідентичності — координати pluginType/name разом із тим реєстром, який налаштовано, — тож немає поля розташування, яке треба писати, і немає такого, у якому можна помилитися. Дайджест вмісту записується, коли розв’язується сутність Release, у lock-файлі цієї сутності Release, а не в сутності.

5. Покладіть guest туди, де збірка його шукатиме

Поки ви розробляєте guest, опублікованого нічого немає, тож збірка читає його з каталогу: файл .wasm лежить поруч зі своєю сутністю і названий за сокетом і плагіном.

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

Ім’я файлу містить сокет, а не лише ім’я, бо голе ім’я плагіна унікальне лише в межах його сокета — два плагіни з назвою 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-catalog
auto_pull: true

auto_pull дає змогу aggrega build розв’язати сутність Release у межах процесу, тож першій збірці не потрібен окремий крок розв’язання.

6. Документи, що націлені на провайдер

Чотири файли. Component оголошує, що може задати автор; Recipe прив’язує можливість і створює артефакт; Aggregate формулює намір; Release розміщує його.

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 — це вся прив’язка. Вона називає можливість, а не плагін: збірка зіставляє її з тим плагіном провайдера, який оголошує цю можливість. Якщо такий плагін рівно один, як тут, більше нічого не потрібно.

Створені автором ключі навмисно записано не у формі змінних середовища. service-name і log.level — це написання, яке автор природно використав би, а нормалізувати їх — завдання провайдера.

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. Перша збірка і те, від чого вона відмовляється

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

Читайте ці два рядки окремо, бо вони кажуть різне.

Попередження очікуване під час розробки, і воно не зникне. Воно каже, що гостьовий модуль запустився без записаного дайджесту вмісту, з яким його можна було б звірити, і це правда для гостьового модуля, який ви зібрали хвилину тому: ніхто його не публікував, тож записаного дайджесту немає. Воно також пояснює, чому повторне розв’язання сутності 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 поруч із нею:

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

Повторно згенерована сутність тепер містить контракт, прочитаний із бінарного файлу:

[… 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. Збірка, яка рендерить

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

Останній рядок повністю називає вихідний каталог, де <workspace> позначає корінь робочого простору. Відрендероване дерево під ним:

dist/infra/dotenv/app/app.env

І файл, який записав provider, повністю:

1.0.0
# aggrega.ai/boundary-path=infra
SERVICE_NAME=checkout
LOG_LEVEL=debug
GREETING="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. Дві речі, які варто перевірити, перш ніж довіряти йому

Що він детермінований. Збережіть вивід, зберіть повторно й порівняйте:

Terminal window
cp -r dist ../capture && rm -rf dist
aggrega build --release release.yaml
diff -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 розв’язує та перевіряє. Посібник розробника плагінів описує цей життєвий цикл на етапах публікації, отримання та збирання.

Структури корисного навантаження і результату кожного сокета наведено в контракті плагіна.