Перейти к содержимому
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() {}

Полезная нагрузка передаётся в двоичной кодировке, а kit читает и записывает её. Хост передаёт render_node входные данные в каноническом CBOR и читает ответ в той же кодировке, поэтому гостевой модуль декодирует с помощью DecodeCBOR входного типа и кодирует с помощью EncodeCBOR выходного типа — без библиотеки CBOR и без ручного разбора. Content файла — это срез байтов, который гостевой модуль заполняет точными байтами для записи; кодировщик передаёт их как сырые байты, а хост записывает их дословно.

Хост передаёт гостевому модулю уже вычисленное содержимое. Content каждой записи артефакта — это авторское тело, шаблонные выражения которого уже разрешены относительно контекста рендеринга: гостевой модуль никогда не вычисляет шаблоны и никогда не читает файлы. Именно это сохраняет границу AOT-компиляции компилятора: гостевой модуль — чистая функция от полезной нагрузки к байтам.

За детерминированность отвечает гостевой модуль. При обычной сборке ничто не проверяет её за вас. Здесь она достигается сортировкой ключей сведений о происхождении перед их выводом и обходом записей артефактов в том порядке, в котором их передаёт полезная нагрузка, а проверки в конце этой страницы измеряют результат.

guest/go.mod ссылается на ваш локальный клон kit:

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. Поместите гостевой модуль туда, где сборка будет его искать

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

Ошибка — это настоящая находка, а текст в скобках — диагноз. Провайдер был найден, загружен и опрошен о том, что он отрисовывает, и ответил none — this provider supports: none. Дескриптор, написанный в начале, указывал сокет, возможность и экспорты, но не сообщал, какие из трёх видов входных данных сущности Recipe обрабатывает гостевой модуль. Хост не будет гадать: проверка видов входных данных читает объявленный гостевым модулем набор и отклоняет узел, который гостевой модуль никогда не заявлял.

Так выглядит большинство сбоев первого провайдера. С гостевым модулем всё в порядке; неполон его отчёт о себе. 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, теперь отклоняется до запуска любого рендеринга с сообщением, называющим этот провайдер, — а не доходит до render_node и не падает где-то внутри него.

BoundaryAssembly: "none" означает, что вывод каждого узла записывается туда, куда он попадает, и объединять ничего не нужно. Провайдер, который сводит несколько компонентов в один документ, вместо этого объявляет merge или nest и экспортирует assemble_boundary, чтобы это сделать. Это естественный следующий шаг для этого провайдера, и он описан в контракте плагина.

Пересоберите гостевой модуль, заново сгенерируйте сущность и положите новый .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

И файл, который записал провайдер, целиком:

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 разрешает и проверяет. Руководство разработчика плагинов описывает этот жизненный цикл в разделах об этапах публикации, получения и сборки.

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