Создание провайдера: пошаговый разбор
На этой странице пошагово разобрана вся задача создания гостевого модуля провайдера — от пустого каталога до сборки, которая записывает файлы, отрисованные провайдером. Это практическое дополнение к руководству разработчика плагинов, где описаны сущность и жизненный цикл, и к контракту плагина, где описаны сокеты.
Провайдер, который создаётся здесь, достаточно мал, чтобы прочитать его за один раз, и выполняет реальную работу: он отрисовывает файлы окружения. Эта цель хорошо подходит для первого провайдера, поскольку преобразование в ней действительно зависит от формата — у файла окружения своя грамматика ключей, свои правила кавычек и нет блока метаданных, куда можно поместить сведения о происхождении сборки, — поэтому гостевому модулю приходится принимать все решения, которые принимает более крупный провайдер, без большого объёма кода, который бы их скрывал.
О блоках на этой странице. Каждый блок с выводом скопирован из реального выполнения описанных ниже шагов в том порядке, в котором они приведены, согласно соглашению о выводе: блок либо приведён полностью, либо является фрагментом с пометкой о том, где строки пропущены. Это пошаговый разбор, который вы собираете самостоятельно, а не рабочее пространство, которое можно клонировать, поэтому блоки исходного кода — это файлы, которые нужно создать, а не файлы, которые нужно извлечь.
Что понадобится
- Набор инструментов 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() {}Полезная нагрузка передаётся в двоичной кодировке, а 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/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. Поместите гостевой модуль туда, где сборка будет его искать
Пока вы разрабатываете гостевой модуль, загружать ещё нечего, поэтому
сборка читает его из каталожного каталога: файл .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 проверяет это
перед записью lock-файла: если он не находит .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) дайджест записывается только для управляющего плагина, подключённого в роли преобразования, а этот гостевой модуль таким не является, — и что это изменит: публикация плагина и ссылка на опубликованную сущность. Воспринимайте предупреждение как корректный отказ сборки заявлять о проверке, которую она не выполняла, и ожидайте его, пока гостевой модуль остаётся локальным.
Ошибка — это настоящая находка, а текст в скобках — диагноз. Провайдер был найден, загружен и опрошен о том, что он отрисовывает, и ответил 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 обратно рядом
с ней:
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И файл, который записал провайдер, целиком:
# 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 — что создаёт каждый провайдер стандартной библиотеки.
- Как читать вывод на этих страницах — соглашение, которому следуют приведённые выше блоки вывода.