Menulis provider: panduan langkah demi langkah
Halaman ini menelusuri seluruh tugas menulis guest provider, dari direktori kosong hingga build yang menulis file yang dirender oleh provider. Halaman ini adalah pendamping praktis bagi panduan pengembang plugin, yang mendokumentasikan entitas dan siklus hidupnya, serta bagi kontrak plugin, yang mendokumentasikan socket-nya.
Provider yang dibangun di sini cukup kecil untuk dibaca dalam sekali duduk dan melakukan pekerjaan nyata: provider ini merender file environment. Target tersebut cocok sebagai provider pertama karena penerjemahannya benar-benar spesifik terhadap format — file environment memiliki tata bahasa kuncinya sendiri, aturan kutipannya sendiri, dan tidak memiliki blok metadata untuk menyimpan provenans build — sehingga guest harus mengambil setiap keputusan yang diambil oleh provider yang lebih besar, tanpa sejumlah besar kode yang menyembunyikannya.
Tentang blok di halaman ini. Setiap blok yang menampilkan output disalin dari eksekusi nyata langkah-langkah di bawah, sesuai urutan kemunculannya, mengikuti konvensi output: sebuah blok bisa lengkap, atau berupa kutipan yang menandai bagian baris yang dihilangkan. Ini adalah panduan yang Anda rakit sendiri, bukan workspace yang dapat Anda clone, sehingga blok sumber adalah file yang harus dibuat, bukan file yang harus di-checkout.
Yang Anda perlukan
- Toolchain Go, yang mengompilasi ke WebAssembly tanpa perkakas tambahan.
- Salinan kerja (checkout) dari kit pengembangan plugin, yang diperkenalkan oleh panduan pengembang plugin, dan dari paket ABI yang menjadi dasar kit tersebut:
go.modmilik guest di bawah menunjuk ke keduanya. - Biner
aggrega.
Bentuk hasil akhirnya
Sebuah provider terdiri atas dua artefak: guest .wasm, dan entitas Plugin yang membawanya
ke dalam katalog. Tidak ada yang lain — tidak ada perubahan host, tidak ada pendaftaran, tidak ada build
kompiler. Menambahkan provider berarti menambahkan kedua file tersebut di tempat yang dapat dilihat oleh build.
Workspace yang dihasilkan di akhir panduan ini:
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. Laporan diri guest
Setiap plugin mengekspor describe(). Host memanggilnya sekali saat memuat
guest dan membaca jawabannya sebagai keterangan guest itu sendiri tentang apa dirinya. Untuk sebuah
provider, empat bagian dari jawaban tersebut penting.
Buat 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 menyatakan soket mana yang dilayani guest ini. Capabilities adalah daftar yang
digunakan sebuah Recipe untuk resolusi: Recipe yang spec.capability-nya adalah dotenv akan
diarahkan ke guest ini. Exports menyebutkan titik masuk yang boleh dituju host
untuk dispatch; render_node adalah titik masuk yang wajib dimiliki setiap provider.
Deskriptor ini sengaja dibuat tidak lengkap, sebagaimana draf pertama biasanya tidak lengkap. Build pertama di bawah adalah tempat hal itu terlihat.
2. Merender sebuah node
render_node dipanggil sekali untuk setiap komponen yang dirender oleh build melalui
provider ini. Fungsi ini menerima identitas node, konteks render, dan input
yang telah dievaluasi sebelumnya yang dideklarasikan oleh Recipe yang terikat — di sini, sebuah set artefak yang telah
dibaca dan dievaluasi oleh host sebagai templat.
Seluruh tugas guest adalah menentukan byte apa yang dihasilkan. Tambahkan ke 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}Tiga keputusan dalam fragmen tersebut adalah milik provider sendiri, dan tidak ada lapisan lain yang dapat membuatnya. Karakter mana yang memaksa pengutipan adalah fakta tentang berkas lingkungan. Begitu pula tata bahasa nama variabel, dan begitu pula pilihan untuk menolak kunci yang tidak sesuai alih-alih mengganti namanya — variabel yang namanya diganti adalah variabel yang akan dicari aplikasi dan tidak ditemukan, yang lebih buruk daripada build yang dihentikan.
Sekarang dua bagian yang tersisa: ke mana provenans ditempatkan, dan ekspor itu sendiri.
// 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() {}Payload melintas dalam pengodean biner, dan kit membaca serta menulisnya.
Host memberikan input kepada render_node sebagai CBOR kanonis dan membaca jawabannya
dalam pengodean yang sama, sehingga guest mendekode dengan DecodeCBOR milik tipe input
dan mengodekan dengan EncodeCBOR milik tipe output — tanpa pustaka CBOR, dan tanpa apa pun
yang diurai secara manual. Content sebuah berkas adalah slice byte yang diisi guest dengan
byte persis yang akan ditulis; encoder membawanya sebagai byte mentah dan host menuliskannya
apa adanya.
Host memberikan kepada guest konten yang telah dievaluasinya. Content setiap entri
artefak adalah isi yang ditulis dengan ekspresi templatnya yang telah
diselesaikan terhadap konteks render — guest tidak pernah mengevaluasi templat dan
tidak pernah membaca berkas. Itulah yang menjaga batas ahead-of-time compiler tetap
utuh: guest adalah fungsi murni dari payload ke byte.
Determinisme adalah tanggung jawab guest. Tidak ada yang memeriksanya untuk Anda pada build biasa. Di sini, determinisme berasal dari pengurutan kunci provenans sebelum mengeluarkannya dan dari penelusuran entri artefak sesuai urutan yang dibawa payload, dan pemeriksaan di dekat akhir halaman ini mengukur hasilnya.
guest/go.mod merujuk ke checkout kit milik Anda:
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. Bangun guest
Guest adalah build Go biasa dengan target WebAssembly yang dipilih:
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 menulis go.sum, checksum dependensi, yang tanpanya build menolak berjalan. -trimpath dan -buildvcs=false menjaga agar jalur build dan cap kontrol versi tidak masuk ke dalam biner, sehingga sumber yang sama pada commit yang sama menghasilkan byte yang sama. Kedua nilai -ldflags menanamkan versi guest itu sendiri ke dalamnya, yang dibaca oleh langkah berikutnya.
Pastikan ekspornya sebelum melanjutkan:
aggrega inspect --plugin dotenv.wasmPlugin .wasm: dotenv.wasmExports: render_nodehostFunctions (derived from binary, not yet recorded by aggrega plugin sync): (none)Guest ini tidak mengimpor fungsi host apa pun, yang merupakan default hak akses minimum: guest ini tidak memerlukan sistem berkas maupun jaringan, karena semua yang direndernya tiba di dalam payload.
4. Membuat entitas Plugin
Bidang kontrak entitas tidak ditulis secara manual — bidang tersebut dibaca dari guest sehingga entitas tidak dapat menjanjikan sesuatu yang tidak dilakukan oleh biner. Anda hanya menyediakan identitasnya, dalam sebuah overlay kecil.
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.yamlEntitas yang dihasilkan:
# 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: - dotenvPerhatikan apa yang tidak ada di sana: penunjuk apa pun ke .wasm. Lokasi sebuah plugin
diturunkan dari identitasnya — koordinat pluginType/name ditambah registry mana pun
yang dikonfigurasi — sehingga tidak ada bidang lokasi yang perlu ditulis dan tidak ada yang
bisa salah. Digest konten dicatat ketika sebuah Release di-resolve, dalam lockfile
Release tersebut, bukan dalam entitas.
5. Letakkan guest di tempat build akan mencarinya
Selama Anda mengembangkan guest, belum ada yang diterbitkan untuk diambil, sehingga
build membacanya dari direktori katalog: berkas .wasm diletakkan di samping
entitasnya, dinamai menurut socket dan plugin.
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.wasmNama berkas memuat socket selain nama karena nama plugin saja
hanya unik di dalam socket-nya sendiri — dua plugin bernama dotenv pada socket
yang berbeda harus menjangkau dua berkas.
Salin berkas hasil build ke sana alih-alih menautkannya. Tautan di tempat itu hanya diikuti sampai ke lokasi di dalam workspace — atau, untuk direktori katalog yang terdaftar di luar workspace, lokasi di dalam direktori tersebut; tautan yang mengarah lebih jauh menghentikan build dan pull dengan menyebutkan tautan itu, seperti yang dijelaskan dalam batas workspace.
Entitas plugin milik provider di direktori katalog tidak pernah di-pin, dan baik
pull maupun build tidak mengambil .wasm-nya, sehingga berkas tersebut harus sudah ada ketika Release di-resolve. Pull memeriksa
sebelum menulis lockfile: jika tidak menemukan .wasm di samping entitas
maupun di tempat lain mana pun yang menjadi sumber build membaca plugin, pull berhenti dan menyebutkan berkas serta
direktori yang diharapkannya, seperti yang dijelaskan dalam
A plugin’s .wasm is not on this machine (Berkas plugin tidak ada di mesin ini).
Arahkan workspace ke kedua direktori katalog di .aggrega-config.yaml:
workspace: catalog_dirs: - catalog - dev-catalogauto_pull: trueauto_pull memungkinkan aggrega build me-resolve Release di dalam proses, sehingga build
pertama tidak memerlukan langkah resolve terpisah.
6. Dokumen yang menargetkan provider
Empat berkas. Component menyatakan apa yang boleh diatur oleh penulis; Recipe mengikat kapabilitas dan menyusun artefak; Aggregate menyatakan maksud; Release menempatkannya.
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 adalah seluruh pengikatannya. Ini menyebut sebuah kapabilitas, bukan
plugin: build me-resolve-nya ke plugin provider mana pun yang mendeklarasikan kapabilitas
tersebut. Jika tepat satu plugin yang mendeklarasikannya — seperti di sini — tidak ada lagi yang diperlukan.
Kunci yang ditulis sengaja tidak dalam bentuk variabel lingkungan.
service-name dan log.level adalah ejaan yang secara alami akan ditulis oleh penulis,
dan menormalkannya adalah tugas provider.
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. Build pertama, dan apa yang ditolaknya
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-onlyBacalah kedua baris itu secara terpisah, karena keduanya menyatakan hal yang berbeda.
Peringatan ini memang diharapkan selama Anda mengembangkan, dan peringatan ini tidak akan hilang. Peringatan ini menyatakan bahwa guest dijalankan tanpa digest konten tercatat untuk memeriksanya, dan itulah kenyataan sebuah guest yang Anda build semenit yang lalu: tidak ada yang memublikasikannya, sehingga tidak ada digest yang tercatat. Peringatan ini juga menyatakan mengapa me-resolve Release lagi tidak akan mengubah hal itu — guest yang dibaca dari samping entitasnya di direktori katalog dibaca ulang oleh setiap build, dan sebuah pull mencatat digest-nya hanya untuk plugin tata kelola yang dipasang pada peran transform, sedangkan guest ini bukan plugin semacam itu — serta apa yang akan mengubahnya: memublikasikan plugin tersebut dan mereferensikan entitas yang telah dipublikasikan. Pahami peringatan ini sebagai build yang dengan tepat menolak mengklaim verifikasi yang tidak dilakukannya, dan perkirakan peringatan ini akan muncul selama guest masih lokal.
Error-lah temuan yang sebenarnya, dan isi tanda kurungnya adalah diagnosisnya. Provider tersebut ditemukan, dimuat, dan ditanya apa yang di-render-nya, lalu menjawab none — this provider supports: none. Deskriptor yang ditulis di awal menyebutkan socket, kapabilitas, dan export, tetapi tidak pernah menyatakan jenis input Recipe mana dari ketiganya yang ditangani guest. Host tidak akan menebak: gerbang jenis input membaca himpunan yang dideklarasikan guest dan menolak node yang tidak pernah diklaim guest.
Inilah bentuk sebagian besar kegagalan provider pertama. Guest-nya baik-baik saja; laporan dirinya yang tidak lengkap. describe() bukan formalitas yang sekadar ditoleransi host — fungsi ini adalah seluruh dasar bagi host yang agnostik terhadap format untuk memutuskan apa yang dikirim ke mana.
8. Deklarasikan kontrak perilaku render
Tambahkan kontrak ke deskriptor di 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 adalah klaim yang dicari oleh gerbang tersebut. Kedua nilai
false juga merupakan klaim, dan menyatakannya justru adalah tujuannya: sebuah Recipe yang
menyertakan pohon sumber, atau yang mendeklarasikan workload, kini ditolak sebelum
render apa pun dijalankan, dengan pesan yang menyebut provider ini — alih-alih mencapai
render_node dan gagal di suatu tempat di dalamnya.
BoundaryAssembly: "none" menyatakan bahwa keluaran setiap node ditulis di tempat ia berakhir,
tanpa ada yang perlu digabungkan. Provider yang melipat beberapa komponen menjadi satu
dokumen mendeklarasikan merge atau nest sebagai gantinya, dan mengekspor assemble_boundary untuk
melakukannya. Itulah hal berikutnya yang wajar untuk ditambahkan ke provider ini, dan hal tersebut
didokumentasikan dalam kontrak plugin.
Bangun ulang guest, buat ulang entitas, lalu letakkan kembali .wasm yang baru di samping
entitas tersebut:
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.wasmEntitas yang dibuat ulang kini membawa kontrak tersebut, yang dibaca dari biner:
[… 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: noneMembuat ulang entitas setelah setiap kali guest dibangun ulang adalah bagian dari siklus kerja. Entitas menyatakan ulang apa yang dilaporkan biner, dan keduanya diperiksa silang saat guest dimuat: export atau nilai kontrak yang diklaim entitas tetapi tidak dilaporkan biner adalah ketidakcocokan yang membuat build berhenti, dengan menyebut klaim tersebut. Klaim yang dihilangkan entitas tidak diperiksa, sehingga entitas yang tertinggal oleh pembangunan ulang yang menambahkan sesuatu ke biner — seperti langkah ini — tetap dimuat, meskipun tidak lagi mendeskripsikannya.
9. Build yang merender
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>/distBaris penutup menyebutkan direktori keluaran secara lengkap, dengan <workspace> mewakili
root workspace. Pohon hasil render di bawahnya:
dist/infra/dotenv/app/app.envDan file yang ditulis oleh provider, secara lengkap:
# aggrega.ai/boundary-path=infraSERVICE_NAME=checkoutLOG_LEVEL=debugGREETING="hello world"ENDPOINT=https://checkout.example.netSetiap keputusan yang dibuat guest terlihat dalam tujuh baris tersebut.
service-namedanlog.levelmasuk sebagaimana ditulis dan keluar sebagaiSERVICE_NAMEdanLOG_LEVEL. Penulis tidak pernah perlu menulis tata bahasa target.GREETINGdiberi tanda kutip, sedangkan tiga lainnya tidak.hello worldmengandung spasi, sehingga tanpa tanda kutip nilainya akan berakhir dihello; endpoint tidak mengandung satu pun karakter yang dibaca format sebagai sintaks, sehingga memberinya tanda kutip hanya akan menambah gangguan.- Kedua kunci provenans berupa komentar, karena file environment tidak memiliki tempat lain untuk menaruhnya. Provider yang keluarannya memiliki blok metadata menaruh kunci yang sama di sana. Host menghitung kunci tersebut; guest memilih penempatannya.
- Nilai-nilai tersebut berasal dari dua penulis yang berbeda.
service_name,log_level, dangreetingadalah maksud pengembang, dari Aggregate.endpointmilik operator, dari Release. Guest tidak melihat satu pun perbedaan itu — guest menerima satu body yang telah dievaluasi.
10. Dua hal yang perlu diperiksa sebelum Anda memercayainya
Bahwa ia deterministik. Tangkap keluarannya, bangun ulang, lalu bandingkan:
cp -r dist ../capture && rm -rf distaggrega build --release release.yamldiff -r ../capture distdiff yang tidak mencetak apa pun adalah hasil yang Anda inginkan. Determinisme adalah kontrak guest, bukan kontrak host, dan guest yang mengiterasi map Go di suatu tempat dalam jalur keluarannya akan gagal dalam pemeriksaan ini, meskipun tampak sepenuhnya benar dalam satu kali build.
Bahwa penolakannya terlihat jelas. Rusak satu baris artefak Recipe sehingga baris itu tidak mendeklarasikan nilai:
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=valuePesan guest itu sendiri sampai ke penulis secara utuh, beserta file dan baris asalnya. Hal ini layak diperiksa secara sengaja, karena kegagalan alternatifnya — guest yang diam-diam melewati baris yang tidak dapat diuraikannya — menghasilkan build yang berhasil dan deployment yang kehilangan sebuah variabel, tanpa ada apa pun dalam keluaran yang menyatakannya.
11. Apa yang ditambahkan berikutnya
Provider yang dibangun di sini sudah lengkap tetapi minimal. Kira-kira menurut urutan seberapa sering masing-masing dibutuhkan:
-
assemble_boundary, untuk menggabungkan keluaran beberapa komponen ke dalam satu dokumen, yang dideklarasikan melaluiBoundaryAssembly. -
validate_node_input, untuk memeriksa input sebuah node secara struktural sebelum render apa pun dijalankan, sehingga input yang salah bentuk dilaporkan di batas penulisan dan bukan di tengah render. -
Fakta render, untuk melaporkan sesuatu tentang apa yang ditulis guest yang hanya dapat dilihat oleh pengetahuan provider ini tentang format file lingkungan — di sini, nama variabel yang didefinisikan setiap file. Sebuah fakta adalah sebuah nama dan sebuah daftar, keduanya kosakata milik provider ini sendiri, yang dikembalikan di samping file — dan nilainya selalu berupa array JSON, bahkan dengan satu entri, atau build akan berhenti:
// 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}},}Compiler menyimpan fakta-fakta tersebut dalam urutan yang dicantumkan guest, hanya memeriksa bahwa setiap nilai adalah daftar, menyerahkan daftar tersebut ke templat Feature yang membacanya, dan menulis file yang sama baik fakta tersebut dilaporkan maupun tidak. Dokumentasikan nama setiap fakta dan isi entrinya sebagai bagian dari kontrak provider.
-
Entri omit, setelah provider merender sebuah sumber. Input render sumber dapat membawa
Omits, yaitu entri yang menamai unit hasil render yang harus dihilangkan, di sampingSourceListing-nya; provider yang mematuhinya menghilangkan setiap unit yang cocok dari apa yang dikembalikannya, melaporkan satu hitungan per entri diOmitted, dan mendeklarasikanOmits: truepada kontraknya. Entri tersebut tidak pernah menyertai render khusus artefak seperti milik provider ini, sehingga provider ini baru menjumpainya setelah merender input yang bersumber. Menghilangkan unit hasil render dalam kontrak plugin menjelaskan bentuk lengkapnya. -
Publikasi, yang mengubah susunan lokal
dev-catalogmenjadi artefak yang dipatok dengan digest yang di-resolve dan diverifikasi oleh sebuah Release. Panduan pengembang plugin membahas siklus hidup tersebut, pada tahap publish, pull, dan build.
Bentuk payload dan hasil setiap socket ada di kontrak plugin.
Referensi terkait
- Panduan pengembang plugin Wasm — entitas
Plugin, permukaan kapabilitas, dan siklus hidup publikasi. - Kontrak Plugin — bentuk input dan output setiap soket.
- Arsitektur Provider — bagaimana provider masuk ke dalam pipeline kompilasi.
- Indeks referensi Provider — apa yang dihasilkan setiap provider pustaka standar.
- Membaca output di halaman-halaman ini — konvensi yang diikuti blok output di atas.