コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

provider の作成:実践ウォークスルー

このページでは、provider ゲストを作成する作業全体を、空のディレクトリから、provider がレンダリングしたファイルを書き出すビルドまで順に説明します。エンティティとライフサイクルを説明するプラグイン開発者ガイドと、ソケットを説明するプラグインコントラクトに対応する実践編です。

ここで作成する provider は、一度に読み通せるほど小さく、それでいて実際の処理を行います。環境ファイルをレンダリングするものです。このターゲットが最初の provider に適しているのは、その変換が本当にフォーマット固有だからです。環境ファイルには独自のキー文法と独自のクォート規則があり、ビルドの来歴を入れるメタデータブロックがありません。そのため、ゲストは大規模な provider が行う判断をすべて行う必要があり、しかもそれらの判断が大量のコードに埋もれることがありません。

このページのブロックについて。 出力を示すブロックはすべて、以下の手順を記載の順に実際に実行した結果からコピーしたもので、出力の慣例に従っています。つまり、各ブロックは完全なものか、行を省略した箇所を明示した抜粋のいずれかです。これはクローンできるワークスペースではなく自分で組み立てるウォークスルーなので、ソースのブロックはチェックアウトするファイルではなく、作成するファイルです。

必要なもの

  • Go ツールチェーン。追加のツールなしで WebAssembly にコンパイルできます。
  • プラグイン開発キット(プラグイン開発者ガイドで紹介しています)と、キットが基盤とする ABI パッケージのチェックアウト。下記のゲストの go.mod は両方を参照します。
  • aggrega バイナリ。

完成形の構成

provider は 2 つの成果物から成ります。.wasm ゲストと、それをカタログに持ち込む Plugin エンティティです。 それ以外は何も要りません。ホストの変更も、登録も、コンパイラの ビルドも不要です。provider を追加するとは、この 2 つのファイルをビルドから見える場所に追加することです。

このウォークスルーの最後に得られるワークスペースは次のとおりです。

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() をエクスポートします。ホストはゲストをロードする際にこれを一度呼び出し、その応答をゲスト自身による自己の説明として読み取ります。プロバイダーにとっては、その応答のうち 4 つの部分が重要です。

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 が解決の対象とするリストです。spec.capability が dotenv である Recipe は、このゲストにルーティングされます。Exports はホストがディスパッチできるエントリポイントを列挙します。render_node は、すべてのプロバイダーが持たなければならないエントリポイントです。

この記述子は、最初の草稿がたいていそうであるように、意図的に不完全にしてあります。それが表面化するのは、後述の最初のビルドです。

2. ノードのレンダリング

render_node は、このプロバイダーを通じてビルドがレンダリングするコンポーネントごとに 1 回呼び出されます。ノードの識別情報、レンダーコンテキスト、そしてバインドされた 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
}

このコード片にある 3 つの判断はプロバイダー自身のものであり、他のどの層もそれを下すことはできません。どの文字がクォートを必要とするかは、環境ファイルに関する事実です。変数名の文法も同様であり、適合しないキーを名前変更するのではなく拒否するという選択も同様です。名前を変更された変数は、アプリケーションが探しても見つからない変数であり、ビルドが停止するよりも悪い結果になります。

残る 2 つの要素は、来歴情報の出力先と、エクスポートそのものです。

// 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. ゲストをビルドする

ゲストは、WebAssembly ターゲットを選択した通常の Go ビルドです。

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 は、ビルドパスとバージョン管理のスタンプをバイナリに含めないようにします。これにより、同じコミットの同じソースから同じバイト列が生成されます。2 つの -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 が解決されるときに、エンティティではなくその 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 という名前の 2 つのプラグインは、2 つの別々のファイルに到達しなければなりません。

ビルドしたファイルは、リンクを張るのではなくそこにコピーしてください。その場所にあるリンクは、ワークスペース内のどこか、またはワークスペース外に列挙されたカタログディレクトリの場合はそのディレクトリ内のどこかを指す場合にのみたどられます。それより外を指すリンクがあると、ワークスペース境界で説明しているとおり、ビルドとプルはそのリンクを示して停止します。

catalog ディレクトリにある provider の plugin エンティティは決してピン留めされず、pull も build もその .wasm を取得しないため、Release が解決される時点でファイルがそこに存在している必要があります。pull は lockfile を書き込む前に確認を行います。エンティティの横にも、build がプラグインを読み込むその他の場所にも .wasm が見つからない場合、pull は停止し、そのファイルと想定していたディレクトリを示します。詳細は A plugin’s .wasm is not on this machine(プラグインの .wasm がこのマシン上にありません) で説明しています。

.aggrega-config.yaml で、ワークスペースが両方のカタログディレクトリを参照するように設定します。

workspace:
catalog_dirs:
- catalog
- dev-catalog
auto_pull: true

auto_pull により aggrega build がプロセス内で Release を解決するため、最初のビルドで別途解決の手順を行う必要はありません。

6. provider を対象とするドキュメント

ファイルは 4 つです。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 がバインディングのすべてです。これが指定するのはケイパビリティであり、プラグインではありません。ビルドはこれを、そのケイパビリティを宣言している provider プラグインに解決します。ここでのように、宣言しているものがちょうど 1 つであれば、ほかには何も必要ありません。

記述されたキーは、意図的に環境変数の形式にしていません。 service-name と log.level は作成者が自然に書く綴りであり、それらを正規化するのは provider の役割です。

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

2 行はそれぞれ異なることを述べているため、別々に読んでください。

この警告は開発中には想定どおりのものであり、消えることはありません。 この警告は、照合対象となる記録済みのコンテンツダイジェストなしにゲストが実行されたことを示しています。これは 1 分前にビルドしたゲストの実情そのものです。何もそれを公開していないため、記録されたダイジェストは存在しません。また、この警告は、Release を再度解決してもそれが変わらない理由も示しています。カタログディレクトリ内のエンティティの隣から読み込まれたゲストはビルドのたびに新たに読み込まれ、プルがダイジェストを記録するのは transform ロールにアタッチされたガバナンスプラグインに対してのみであり、このゲストはそれに該当しないためです。さらに、何をすれば変わるか、つまりプラグインを公開して公開済みのエンティティを参照することも示しています。この警告は、実行していない検証を主張することをビルドが正しく控えているものと読み取り、ゲストがローカルである限り表示されるものと考えてください。

エラーこそが本当の発見であり、括弧内がその診断です。 プロバイダは見つかり、ロードされ、何をレンダリングするかを問い合わせられ、none と答えました(this provider supports: none)。最初に書いたディスクリプタはソケット、ケイパビリティ、エクスポートを指定していましたが、ゲストが 3 種類の 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 は、ゲートが探していた宣言です。2 つの false の値も宣言であり、それを明示することこそが要点です。ソースツリーを取り込む Recipe や、ワークロードを宣言する Recipe は、 render_node に到達してその内部のどこかで失敗するのではなく、レンダリングが一切実行される前に、このプロバイダを名指しするメッセージとともに拒否されるようになります。

BoundaryAssembly: "none" は、各ノードの出力がその配置先にそのまま書き込まれ、 結合するものがないことを示します。複数のコンポーネントを 1 つのドキュメントにまとめるプロバイダは、代わりに 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

ゲストが行うすべての判断が、この 7 行に表れています。

  • service-name と log.level は記述されたとおりに届き、 SERVICE_NAME と LOG_LEVEL として出力されました。作成者がターゲットの 文法を書く必要は一度もありませんでした。
  • GREETING は引用符で囲まれ、他の 3 つは囲まれていません。hello world には 空白が含まれるため、囲まなければ hello で終わってしまいます。エンドポイントには、このフォーマットが構文として読む文字が 一つも含まれないため、引用符で囲むと余計なノイズになります。
  • 2 つの来歴キーはコメントになっています。環境ファイルには 他に置く場所がないためです。出力にメタデータブロックを持つプロバイダであれば、 同じキーをそこに置きます。キーを計算したのはホストで、配置を選んだのは ゲストです。
  • 値は 2 人の異なる作成者から来ています。service_name、log_level、 greeting は Aggregate に由来する開発者の意図です。endpoint は Release に由来するオペレーターの値です。ゲストはどちらの区別も認識していません。受け取ったのは 評価済みの 1 つの本体だけです。

10. 信頼する前に確認しておきたい 2 つのこと

決定的であること。 出力を保存し、再ビルドして比較します。

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

diff が何も出力しないことが望ましい結果です。決定性はホストではなくゲストの契約であり、出力経路のどこかで Go の map を反復するゲストは、1 回のビルドではまったく正しく見えても、この確認には失敗します。

拒否が明確に報告されること。 Recipe のアーティファクトの 1 行を壊し、値を宣言しないようにします。

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. 次に追加するもの

ここで作成した provider は完結していますが、最小限のものです。必要とされる頻度のおおよその順に挙げます。

  • assemble_boundary: 複数の component の出力を 1 つのドキュメントにまとめます。 BoundaryAssembly で宣言します。

  • validate_node_input: レンダリングが実行される前にノードの入力を構造的に検査します。 これにより、不正な入力はレンダリングの途中ではなく、 オーサリングの境界で報告されます。

  • レンダリングファクト: ゲストが書き出した内容について、この provider が持つ 環境ファイル形式の知識でしか見えないもの(ここでは各ファイルが定義する変数名)を 報告します。ファクトは名前とリストからなり、どちらもこの provider 独自の語彙で、 ファイルと並べて返されます。値は、エントリが 1 つだけの場合でも 常に 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 テンプレートにリストを渡します。ファクトが報告されるかどうかにかかわらず、書き出すファイルは同じです。各ファクトの名前とそのエントリが保持する内容は、 provider の契約の一部として文書化してください。

  • Omit エントリ: provider がソースをレンダリングするようになったら対応します。ソースレンダリングの 入力は、SourceListing と並んで、除外するレンダリング単位を指定するエントリである Omits を持つことがあります。これに対応する provider は、一致したすべての単位を 返す内容から除外し、エントリごとに 1 つのカウントを Omitted で報告し、 契約で Omits: true を宣言します。この provider のような artifacts のみの レンダリングに Omits が伴うことはないため、ソース付きの入力をレンダリングするように なって初めて扱うことになります。全体の構造は plugin contract の レンダリング単位の除外 にあります。

  • 公開: ローカルの dev-catalog の構成を、Release が解決して検証する ダイジェスト固定の artifact に変換します。このライフサイクルは plugin 開発者ガイドの publish、pull、build の各段階で説明しています。

各ソケットのペイロードと結果の構造は plugin contractにあります。