Bir provider yazmak: uygulamalı bir anlatım
Bu sayfa, bir provider konuğu yazma işinin tamamını, boş bir dizinden provider’ın oluşturduğu dosyaları yazan bir derlemeye kadar adım adım anlatır. Varlığı ve yaşam döngüsünü belgeleyen eklenti geliştirici kılavuzunun ve soketleri belgeleyen eklenti sözleşmesinin uygulamalı tamamlayıcısıdır.
Burada oluşturulan provider tek oturuşta okunacak kadar küçüktür ve gerçek bir iş yapar: ortam dosyaları oluşturur. Bu hedef iyi bir ilk provider’dır, çünkü çevirisi gerçekten biçime özgüdür — bir ortam dosyasının kendi anahtar dilbilgisi, kendi tırnaklama kuralları vardır ve derleme kökenini koyacak bir meta veri bloğu yoktur — bu nedenle konuk, daha büyük bir provider’ın verdiği her kararı, bunları gizleyen büyük bir kod gövdesi olmadan vermek zorundadır.
Bu sayfadaki bloklar hakkında. Çıktı gösteren her blok, aşağıdaki adımların göründükleri sırayla gerçek bir çalıştırmasından, çıktı uzlaşımına uyularak kopyalanmıştır: bir blok ya eksiksizdir ya da satırların atlandığı yeri işaretleyen bir alıntıdır. Bu, klonlayabileceğiniz bir çalışma alanı değil, kendiniz bir araya getirdiğiniz bir anlatımdır; bu nedenle kaynak bloklar, çekilecek dosyalar değil, oluşturulacak dosyalardır.
Gerekenler
- Ek bir araç gerektirmeden WebAssembly’ye derleyen Go araç zinciri.
- Plugin geliştirici kılavuzunun tanıttığı plugin geliştirme kitinin ve kitin üzerine kurulduğu ABI paketinin birer checkout’u: aşağıdaki guest’in
go.moddosyası ikisine de işaret eder. aggregaikili dosyası.
Bitmiş hâlinin yapısı
Bir provider iki yapıttan oluşur: bir .wasm konuğu ve onu bir kataloğa taşıyan bir Plugin varlığı.
Başka hiçbir şey gerekmez: ne ana makinede bir değişiklik, ne bir kayıt, ne de bir derleyici
derlemesi. Bir provider eklemek, bu iki dosyayı bir derlemenin görebileceği bir yere eklemektir.
Bu adım adım anlatımın sonunda ortaya çıkan çalışma alanı:
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. Konuğun kendi hakkındaki beyanı
Her plugin describe() dışa aktarır. Ana makine bunu konuğu yüklediğinde bir kez çağırır
ve yanıtı, konuğun ne olduğuna dair kendi açıklaması olarak okur. Bir
provider için bu yanıtın dört bölümü önemlidir.
guest/main.go dosyasını oluşturun:
// 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, bu konuğun hangi yuvaya hizmet ettiğini belirtir. Capabilities, bir
Recipe’in karşısında çözümlendiği listedir: spec.capability değeri dotenv olan bir Recipe
bu konuğa yönlendirilir. Exports, ana makinenin yönlendirme yapabileceği giriş noktalarını
adlandırır; render_node her provider’da bulunması gereken giriş noktasıdır.
Bu tanımlayıcı, bir ilk taslağın genellikle olduğu gibi, kasıtlı olarak eksiktir. Bunun ortaya çıktığı yer aşağıdaki ilk derlemedir.
2. Bir düğümün işlenmesi
render_node, derlemenin bu sağlayıcı üzerinden işlediği her bileşen için bir kez çağrılır. Düğümün kimliğini, işleme bağlamını ve bağlı Recipe’in bildirdiği önceden değerlendirilmiş girdileri alır; burada bu, ana makinenin zaten okuduğu ve şablon olarak değerlendirdiği bir yapıt kümesidir.
Konuğun tüm işi, hangi baytların çıkacağına karar vermektir. guest/main.go dosyasına şunu ekleyin:
// 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}Bu parçadaki üç karar sağlayıcının kendisine aittir ve başka hiçbir katman bunları veremez. Hangi karakterlerin tırnak içine almayı zorunlu kıldığı, ortam dosyalarına ilişkin bir olgudur. Değişken adı dilbilgisi de öyledir; uymayan bir anahtarı yeniden adlandırmak yerine reddetme seçimi de öyle. Yeniden adlandırılmış bir değişken, uygulamanın arayıp bulamayacağı bir değişkendir ve bu, durdurulmuş bir derlemeden daha kötüdür.
Şimdi kalan iki parça: kaynak bilgisinin nereye gittiği ve dışa aktarımın kendisi.
// 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() {}Yük ikili bir kodlamayla aktarılır ve kit onu okur ve yazar.
Ana makine, render_node girdisini kanonik CBOR olarak verir ve yanıtı aynı kodlamayla okur; bu nedenle konuk, girdi türünün DecodeCBOR yöntemiyle çözer ve çıktı türünün EncodeCBOR yöntemiyle kodlar: CBOR kitaplığı gerekmez ve hiçbir şey elle ayrıştırılmaz. Bir dosyanın Content alanı, konuğun yazılacak baytların tam olarak kendisiyle doldurduğu bir bayt dilimidir; kodlayıcı bunları ham bayt olarak taşır ve ana makine bunları olduğu gibi yazar.
Ana makine konuğa zaten değerlendirmiş olduğu içeriği verir. Her yapıt girdisinin Content alanı, şablon ifadeleri işleme bağlamına göre önceden çözümlenmiş olan yazılmış gövdedir; konuk hiçbir zaman şablon değerlendirmez ve hiçbir zaman dosya okumaz. Derleyicinin önceden derleme (ahead-of-time) sınırını bozulmadan koruyan budur: konuk, yükten baytlara giden saf bir fonksiyondur.
Belirlenimcilik konuğun sorumluluğundadır. Sıradan bir derlemede bunu sizin için hiçbir şey denetlemez. Burada belirlenimcilik, kaynak bilgisi anahtarlarını yaymadan önce sıralamaktan ve yapıt girdilerini yükün taşıdığı sırayla dolaşmaktan gelir; bu sayfanın sonuna doğru yer alan denetimler de sonucu ölçer.
guest/go.mod, kitin sizdeki çalışma kopyasına başvurur:
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. Guest’i derleyin
Bir guest, WebAssembly hedefi seçilmiş sıradan bir Go derlemesidir:
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, bağımlılıkların sağlama toplamları olan go.sum’ı yazar; derleme bu dosya olmadan çalışmayı reddeder. -trimpath ve -buildvcs=false, derleme yolu ve sürüm denetimi damgalarını ikili dosyanın dışında tutar; böylece aynı commit’teki aynı kaynak aynı baytları üretir. İki -ldflags değeri, guest’in kendi sürümünü içine damgalar; bir sonraki adım bu sürümü okur.
Devam etmeden önce dışa aktarımları doğrulayın:
aggrega inspect --plugin dotenv.wasmPlugin .wasm: dotenv.wasmExports: render_nodehostFunctions (derived from binary, not yet recorded by aggrega plugin sync): (none)Bu guest hiçbir host işlevini içe aktarmaz; bu, en az ayrıcalık varsayılanıdır: ne dosya sistemine ne de ağa ihtiyaç duyar, çünkü oluşturduğu her şey yük içinde gelir.
4. Plugin varlığını oluşturun
Varlığın sözleşme alanları elle yazılmaz; varlığın ikili dosyanın yapmadığı bir şeyi vaat edememesi için bu alanlar konuktan okunur. Siz yalnızca kimliği, küçük bir katman dosyasında sağlarsınız.
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.yamlOluşturulan varlık:
# 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: - dotenvOrada olmayan şeye dikkat edin: .wasm dosyasına herhangi bir işaretçi. Bir plugin’in konumu
kimliğinden türetilir — pluginType/name koordinatı ile yapılandırılmış olan kayıt defteri —
bu nedenle yazılacak ve yanlış yazılabilecek bir konum alanı yoktur. İçerik özeti, bir Release
çözümlendiğinde varlıkta değil, o Release’in kilit dosyasında kaydedilir.
5. Guest’i bir derlemenin arayacağı yere koyun
Bir guest geliştirirken getirilecek yayımlanmış bir şey yoktur; bu nedenle
derleme onu bir katalog dizininden okur: .wasm, varlığının yanında durur ve
soket ile plugin’e göre adlandırılır.
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.wasmDosya adı, adın yanı sıra soketi de taşır, çünkü yalın bir plugin adı yalnızca
kendi soketi içinde benzersizdir — farklı soketlerde dotenv adlı iki plugin iki
ayrı dosyaya ulaşmak zorundadır.
Derlenmiş dosyaya bağlantı vermek yerine dosyayı oraya kopyalayın. O konumdaki bir bağlantı yalnızca çalışma alanının içindeki bir yere — ya da çalışma alanının dışında listelenen bir katalog dizini için o dizinin içindeki bir yere — kadar izlenir; daha öteye giden bir bağlantı, çalışma alanı sınırı sayfasında açıklandığı gibi, derlemeyi ve pull işlemini bağlantıyı adlandırarak durdurur.
Bir katalog dizinindeki bir provider’ın plugin varlığı hiçbir zaman sabitlenmez ve ne pull ne de
derleme onun .wasm dosyasını getirir; bu nedenle Release çözümlendiğinde dosyanın orada olması gerekir. Pull,
kilit dosyasını yazmadan önce denetim yapar: .wasm dosyasını ne varlığın yanında ne de bir
derlemenin plugin’leri okuduğu başka herhangi bir yerde bulursa, durur ve dosyayı ve beklediği
dizini adlandırır;
A plugin’s .wasm is not on this machine (Bir plugin’in dosyası bu makinede değil)
bunu açıklar.
Çalışma alanını .aggrega-config.yaml içinde her iki katalog dizinine yönlendirin:
workspace: catalog_dirs: - catalog - dev-catalogauto_pull: trueauto_pull, aggrega build komutunun Release’i süreç içinde çözümlemesini sağlar; böylece ilk
derleme ayrı bir çözümleme adımı gerektirmez.
6. Provider’ı hedefleyen belgeler
Dört dosya. Component, bir yazarın neleri ayarlayabileceğini bildirir; Recipe yeteneği bağlar ve yapıtı yazar; Aggregate amacı belirtir; Release onu yerleştirir.
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 bağlamanın tamamıdır. Bir plugin’i değil, bir yeteneği adlandırır: derleme bunu, o yeteneği bildiren provider plugin’i hangisiyse ona çözümler. Burada olduğu gibi tam olarak bir tane bildiriyorsa başka hiçbir şey gerekmez.
Yazılan anahtarlar bilinçli olarak ortam değişkeni biçiminde değildir. service-name ve log.level, bir yazarın doğal olarak yazacağı yazımlardır ve bunları normalleştirmek provider’ın işidir.
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. İlk derleme ve neyi reddettiği
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İki satırı ayrı ayrı okuyun, çünkü farklı şeyler söylüyorlar.
Uyarı geliştirme sırasında beklenir ve ortadan kalkmaz. Uyarı, guest’in karşılaştırılacak kayıtlı bir içerik özeti (digest) olmadan çalıştığını söyler; bu, bir dakika önce derlediğiniz bir guest için doğrudur: onu hiçbir şey yayımlamadı, dolayısıyla kayıtlı bir özet yoktur. Uyarı ayrıca Release’i yeniden çözümlemenin bunu neden değiştirmeyeceğini de söyler — bir katalog dizininde entity’sinin yanından okunan bir guest her derlemede yeniden okunur ve bir çekme (pull) özetini yalnızca bir dönüştürme rolüne bağlı bir yönetişim plugin’i için kaydeder, bu guest ise öyle değildir — ve neyin değiştireceğini de söyler: plugin’i yayımlamak ve yayımlanan entity’ye başvurmak. Uyarıyı, derlemenin gerçekleştirmediği bir doğrulamayı iddia etmeyi doğru biçimde reddetmesi olarak okuyun ve guest yerel olduğu sürece bu uyarıyı bekleyin.
Asıl bulgu hatadır ve parantez içindeki kısım teşhistir. Provider
bulundu, yüklendi ve neyi işlediği soruldu; o da none yanıtını verdi
— this provider supports: none. Başlangıçta yazılan tanımlayıcı
soketi, yeteneği ve dışa aktarımları adlandırıyordu, ancak guest’in üç Recipe girdi türünden
hangisini işlediğini hiç söylemiyordu. Ana bilgisayar (host) tahminde bulunmaz: girdi türü
kapısı guest’in bildirdiği kümeyi okur ve guest’in hiç sahiplenmediği bir düğümü reddeder.
İlk provider hatalarının çoğu bu biçimdedir. Guest sorunsuzdur; kendi
hakkındaki bildirimi eksiktir. describe(), host’un katlandığı bir formalite değildir —
biçimden bağımsız bir host’un neyi nereye göndereceğine karar verdiği temelin tamamıdır.
8. Render davranışı sözleşmesini bildirin
Sözleşmeyi guest/main.go içindeki tanımlayıcıya ekleyin:
Capabilities: []string{"dotenv"}, Contract: &aggrega.ProviderContract{ InputKinds: aggrega.InputKinds{ Sourced: false, Synthesized: false, ArtifactsStandalone: true, }, BoundaryAssembly: "none", }, Exports: []aggrega.PluginExport{ArtifactsStandalone: true, kapının aradığı beyandır. İki
false değeri de birer beyandır ve bunları belirtmenin amacı da budur: bir kaynak ağacını içine alan ya da bir workload bildiren bir Recipe, artık
herhangi bir render çalışmadan önce, bu provider’ı adlandıran bir iletiyle reddedilir;
render_node’a ulaşıp içinde bir yerde başarısız olmaz.
BoundaryAssembly: "none", her düğümün çıktısının, birleştirilecek bir şey olmadan,
vardığı yere yazıldığını söyler. Birkaç bileşeni tek bir belgede birleştiren bir provider bunun yerine merge ya da nest bildirir ve bunu yapmak için assemble_boundary’yi dışa aktarır. Bu provider’a eklenecek doğal bir sonraki şey budur ve
plugin sözleşmesinde belgelenmiştir.
Konuğu yeniden derleyin, varlığı yeniden oluşturun ve yeni .wasm dosyasını yeniden
yanına koyun:
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.wasmYeniden oluşturulan varlık artık ikili dosyadan okunan sözleşmeyi taşır:
[… 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: noneHer konuk yeniden derlemesinden sonra varlığı yeniden oluşturmak döngünün bir parçasıdır. Varlık, ikili dosyanın bildirdiğini yeniden ifade eder ve konuk yüklendiğinde ikisi çapraz denetlenir: varlığın iddia ettiği ama ikili dosyanın bildirmediği bir dışa aktarma ya da sözleşme değeri, derlemenin iddiayı adlandırarak üzerinde durduğu bir uyuşmazlıktır. Varlığın dışarıda bıraktığı bir iddia denetlenmez; bu nedenle ikili dosyaya ekleme yapan bir yeniden derlemenin — bu adımda olduğu gibi — geride bıraktığı bir varlık yine yüklenir, ancak artık onu tanımlamaz.
9. Render eden derleme
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>/distSon satır, çıktı dizinini tam olarak adlandırır; burada <workspace> çalışma alanının
kökünü temsil eder. Altındaki render edilmiş ağaç:
dist/infra/dotenv/app/app.envVe provider’ın yazdığı dosyanın tamamı:
# aggrega.ai/boundary-path=infraSERVICE_NAME=checkoutLOG_LEVEL=debugGREETING="hello world"ENDPOINT=https://checkout.example.netGuest’in verdiği her karar bu yedi satırda görülebilir.
service-namevelog.levelyazıldıkları gibi geldi veSERVICE_NAMEileLOG_LEVELolarak çıktı. Yazarın hedefin dilbilgisini hiçbir zaman yazması gerekmedi.GREETINGtırnak içinde, diğer üçü değil.hello worldbir boşluk içerir, bu yüzden tırnaksız olsaydıhellonoktasında biterdi; endpoint ise biçimin sözdizimi olarak okuduğu karakterlerin hiçbirini içermez, bu yüzden onu tırnak içine almak yalnızca gürültü eklerdi.- İki köken anahtarı yorum satırıdır, çünkü bir ortam dosyasında onları koyacak başka bir yer yoktur. Çıktısında bir meta veri bloğu bulunan bir provider, aynı anahtarları bunun yerine oraya koyar. Anahtarları host hesapladı; yerleşimi guest seçti.
- Değerler iki farklı yazardan geldi.
service_name,log_levelvegreetinggeliştiricinin niyetidir ve Aggregate’ten gelir.endpointise operatörünkidir ve Release’ten gelir. Guest bu ayrımların hiçbirini görmedi — tek bir değerlendirilmiş gövde aldı.
10. Güvenmeden önce denetlemeye değer iki şey
Deterministik olduğu. Çıktıyı kaydedin, yeniden derleyin ve karşılaştırın:
cp -r dist ../capture && rm -rf distaggrega build --release release.yamldiff -r ../capture distdiff komutunun hiçbir şey yazdırmaması istediğiniz sonuçtur. Determinizm host’un değil, guest’in sözleşmesidir; çıktı yolunun bir yerinde bir Go map’i üzerinde dolaşan bir guest, tek bir derlemede tamamen doğru görünürken bu denetimde başarısız olur.
Reddetmelerinin açıkça görüldüğü. Recipe’nin artifact’ının bir satırını bozun, böylece o satır hiçbir değer bildirmesin:
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=valueGuest’in kendi mesajı, geldiği dosya ve satırla birlikte yazara olduğu gibi ulaşır. Bunu bilerek denetlemeye değer, çünkü diğer başarısızlık türü — ayrıştıramadığı bir satırı sessizce atlayan bir guest — başarılı olan bir derleme ve bir değişkeni eksik bir dağıtım üretir ve çıktıda bunu söyleyen hiçbir şey olmaz.
11. Sırada ne eklenmeli
Burada oluşturulan provider eksiksizdir ancak asgari düzeydedir. Her birinin ne sıklıkla istendiğine göre kabaca sıralanmış olarak:
-
assemble_boundary: birkaç bileşenin çıktısını tek bir belgede birleştirmek için;BoundaryAssemblyaracılığıyla bildirilir. -
validate_node_input: herhangi bir render çalışmadan önce bir düğümün girdisini yapısal olarak denetlemek için; böylece hatalı biçimlendirilmiş bir girdi render ortasında değil, yazım sınırında bildirilir. -
Render olguları: guest’in yazdığı şey hakkında, yalnızca bu provider’ın ortam dosyası biçimine ilişkin bilgisinin görebildiği bir şeyi bildirmek için; burada bu, her dosyanın tanımladığı değişken adlarıdır. Bir olgu, her ikisi de bu provider’ın kendi sözcük dağarcığına ait olan bir ad ve bir listedir ve dosyaların yanında döndürülür; değer, tek bir girdi içerse bile her zaman bir JSON dizisidir, aksi hâlde derleme durur:
// 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}},}Derleyici olguları guest’in listelediği sırada tutar, yalnızca her değerin bir liste olduğunu denetler, listeleri onları okuyan Feature şablonlarına iletir ve olgular bildirilse de bildirilmese de aynı dosyaları yazar. Her olgunun adını ve girdilerinin neyi içerdiğini provider’ın sözleşmesinin bir parçası olarak belgeleyin.
-
Omit girdileri: provider bir kaynağı render ettiğinde. Bir kaynak render’ının girdisi,
SourceListing’inin yanında, dışarıda bırakılacak render edilmiş birimleri adlandıran girdiler olanOmitstaşıyabilir; bunlara uyan bir provider, eşleşen her birimi döndürdüğü şeyin dışında bırakır,Omittediçinde girdi başına bir sayı bildirir ve sözleşmesindeOmits: truebildirir. Bunlar hiçbir zaman bu provider’ınki gibi yalnızca yapıtlardan oluşan bir render’a eşlik etmez; dolayısıyla provider bunlarla ancak kaynaklı bir girdiyi render ettikten sonra karşılaşır. Eklenti sözleşmesindeki Render edilmiş birimleri dışarıda bırakma bölümü yapının tamamını verir. -
Yayımlama: yerel
dev-catalogdüzenini, bir Release’in çözümlediği ve doğruladığı, özet ile sabitlenmiş bir yapıta dönüştürür. Eklenti geliştirici kılavuzu bu yaşam döngüsünü yayımlama, çekme ve derleme aşamaları altında ele alır.
Her soketin yük ve sonuç yapıları eklenti sözleşmesinde yer alır.
İlgili başvurular
- Wasm eklenti geliştirici kılavuzu —
Pluginvarlığı, yetenek yüzeyi ve yayımlama yaşam döngüsü. - Plugin sözleşmesi — her soketin girdi ve çıktı biçimleri.
- Provider mimarisi — provider’ların derleme hattına nasıl yerleştiği.
- Provider başvuru dizini — her bir standart kütüphane provider’ının ne ürettiği.
- Bu sayfalardaki çıktıyı okumak — yukarıdaki çıktı bloklarının izlediği uzlaşım.