Viết một provider: hướng dẫn từng bước qua ví dụ
Trang này đi qua toàn bộ công việc viết một guest provider, từ một thư mục trống đến một bản build ghi ra các tệp mà provider đã kết xuất. Đây là phần ví dụ đi kèm hướng dẫn dành cho nhà phát triển plugin, tài liệu mô tả thực thể và vòng đời, và hợp đồng plugin, tài liệu mô tả các socket.
Provider được xây dựng ở đây đủ nhỏ để đọc trong một lần và làm việc thực sự: nó kết xuất các tệp môi trường. Đích này là một provider đầu tiên tốt vì việc chuyển đổi của nó thực sự phụ thuộc vào định dạng — một tệp môi trường có ngữ pháp khóa riêng, quy tắc đặt dấu nháy riêng, và không có khối metadata nào để đặt thông tin nguồn gốc của bản build — nên guest phải đưa ra mọi quyết định mà một provider lớn hơn đưa ra, mà không có một khối mã lớn che giấu chúng.
Về các khối trên trang này. Mọi khối hiển thị đầu ra đều được sao chép từ một lần chạy thực các bước dưới đây, theo đúng thứ tự chúng xuất hiện, tuân theo quy ước về đầu ra: một khối hoặc là đầy đủ, hoặc là một đoạn trích có đánh dấu chỗ các dòng bị lược bỏ. Đây là một hướng dẫn bạn tự lắp ráp chứ không phải một workspace bạn có thể clone, nên các khối mã nguồn là các tệp cần tạo chứ không phải các tệp cần check out.
Những gì bạn cần
- Bộ công cụ Go, có khả năng biên dịch sang WebAssembly mà không cần thêm công cụ nào khác.
- Một bản checkout của bộ công cụ phát triển plugin, được giới thiệu trong hướng dẫn dành cho nhà phát triển plugin, và của gói ABI mà bộ công cụ dựa trên:
go.modcủa guest bên dưới trỏ tới cả hai. - Tệp nhị phân
aggrega.
Hình dạng của sản phẩm hoàn chỉnh
Một provider gồm hai tạo phẩm: một guest .wasm, và một thực thể Plugin mang
nó vào một catalog. Không gì khác — không thay đổi host, không đăng ký, không build
lại trình biên dịch. Thêm một provider là thêm hai tệp đó vào nơi mà một bản build có thể thấy chúng.
Workspace mà hướng dẫn này kết thúc với:
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. Bản tự mô tả của guest
Mọi plugin đều xuất describe(). Host gọi hàm này một lần khi nạp
guest và đọc câu trả lời như lời tự mô tả của chính guest về bản thân nó. Đối với một
provider, có bốn phần của câu trả lời đó là quan trọng.
Tạo 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 cho biết guest này phục vụ socket nào. Capabilities là danh sách mà một
Recipe được phân giải dựa vào: một Recipe có spec.capability là dotenv sẽ được
định tuyến tới guest này. Exports liệt kê các điểm vào mà host có thể điều phối
tới; render_node là điểm vào mà mọi provider đều phải có.
Descriptor này được cố ý để chưa hoàn chỉnh, theo cách mà một bản nháp đầu tiên thường như vậy. Bản build đầu tiên bên dưới là nơi điều đó lộ ra.
2. Render một node
render_node được gọi một lần cho mỗi component mà bản build render thông qua
provider này. Nó nhận định danh của node, ngữ cảnh render và bất kỳ đầu vào
đã được đánh giá trước nào mà Recipe được liên kết khai báo — ở đây là một tập artifact mà host
đã đọc và đánh giá như một template.
Toàn bộ công việc của guest là quyết định những byte nào được xuất ra. Thêm vào 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}Ba quyết định trong đoạn mã đó thuộc về chính provider, và không lớp nào khác có thể đưa ra chúng. Những ký tự nào buộc phải đặt trong dấu ngoặc kép là một đặc điểm của tệp môi trường. Ngữ pháp tên biến cũng vậy, và lựa chọn từ chối một khóa không phù hợp thay vì đổi tên nó cũng vậy — một biến bị đổi tên là biến mà ứng dụng sẽ tìm nhưng không thấy, điều này tệ hơn một bản build bị dừng lại.
Giờ là hai phần còn lại: thông tin nguồn gốc được đặt ở đâu, và chính hàm export.
// 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 được truyền qua ở dạng mã hóa nhị phân, và kit đọc và ghi nó.
Host truyền đầu vào cho render_node dưới dạng CBOR chuẩn tắc và đọc câu trả lời
ở cùng dạng mã hóa đó, nên guest giải mã bằng DecodeCBOR của kiểu đầu vào
và mã hóa bằng EncodeCBOR của kiểu đầu ra — không cần thư viện CBOR, và không có gì
phải phân tích thủ công. Content của một tệp là một byte slice mà guest điền vào bằng
chính xác các byte cần ghi; bộ mã hóa mang chúng dưới dạng byte thô và host ghi
chúng nguyên văn.
Host truyền cho guest nội dung mà nó đã đánh giá. Content của mỗi mục
artifact là phần thân được viết với các biểu thức template đã được
phân giải theo ngữ cảnh render — guest không bao giờ đánh giá template và
không bao giờ đọc tệp. Đó là điều giữ cho ranh giới ahead-of-time của trình biên dịch
nguyên vẹn: guest là một hàm thuần túy từ payload thành byte.
Tính tất định là trách nhiệm của guest. Không có gì kiểm tra điều đó thay bạn trong một bản build thông thường. Ở đây nó đến từ việc sắp xếp các khóa nguồn gốc trước khi xuất chúng và từ việc duyệt các mục artifact theo thứ tự mà payload mang, và các bước kiểm tra gần cuối trang này đo lường kết quả.
guest/go.mod tham chiếu đến bản checkout kit của bạn:
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. Build guest
Một guest là một bản build Go thông thường với target WebAssembly được chọn:
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 ghi go.sum, các checksum của phần phụ thuộc, thứ mà bản build từ chối chạy nếu thiếu. -trimpath và -buildvcs=false loại bỏ đường dẫn build và dấu vết quản lý phiên bản khỏi tệp nhị phân, nhờ đó cùng một mã nguồn tại cùng một commit tạo ra cùng các byte. Hai giá trị -ldflags ghi phiên bản riêng của guest vào trong nó, thông tin mà bước tiếp theo sẽ đọc.
Hãy xác nhận các export trước khi đi tiếp:
aggrega inspect --plugin dotenv.wasmPlugin .wasm: dotenv.wasmExports: render_nodehostFunctions (derived from binary, not yet recorded by aggrega plugin sync): (none)Guest này không import hàm host nào, đó là mặc định đặc quyền tối thiểu: nó không cần đến hệ thống tệp lẫn mạng, vì mọi thứ nó render đều đến trong payload.
4. Tạo entity Plugin
Các trường hợp đồng của entity không được viết bằng tay — chúng được đọc ra từ guest để entity không thể hứa hẹn điều mà binary không làm. Bạn chỉ cung cấp phần định danh, trong một overlay nhỏ.
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.yamlEntity được tạo ra:
# 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: - dotenvHãy chú ý điều không có ở đó: bất kỳ con trỏ nào tới .wasm. Vị trí của một plugin được
suy ra từ định danh của nó — tọa độ pluginType/name cộng với registry nào
được cấu hình — nên không có trường vị trí nào để viết và cũng không có trường nào để
viết sai. Digest nội dung được ghi lại khi một Release được phân giải, trong lockfile của
Release đó, không phải trong entity.
5. Đặt guest vào nơi bản build sẽ tìm nó
Trong khi bạn đang phát triển một guest thì chưa có gì được phát hành để tải về, nên
bản build đọc nó từ một thư mục catalog: tệp .wasm nằm bên cạnh entity
của nó, được đặt tên theo socket và 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.wasmTên tệp mang cả socket lẫn tên vì một tên plugin đơn thuần
chỉ là duy nhất trong socket của chính nó — hai plugin cùng tên dotenv ở hai socket
khác nhau phải trỏ tới hai tệp.
Hãy sao chép tệp đã build vào đó thay vì tạo liên kết tới nó. Một liên kết ở vị trí đó chỉ được đi theo tới nơi nằm bên trong workspace — hoặc, với một thư mục catalog được liệt kê bên ngoài workspace, tới nơi nằm bên trong thư mục đó; một liên kết dẫn ra xa hơn sẽ dừng bản build và lệnh pull kèm theo tên liên kết, như ranh giới workspace trình bày.
Entity plugin của một provider trong thư mục catalog không bao giờ được ghim, và cả
lệnh pull lẫn bản build đều không tải .wasm của nó, nên tệp phải có sẵn ở đó khi Release được phân giải. Lệnh pull kiểm tra
trước khi ghi lockfile: khi không tìm thấy .wasm bên cạnh entity
cũng như ở bất kỳ nơi nào khác mà bản build đọc plugin, nó dừng lại và nêu tên tệp cùng
thư mục mà nó mong đợi, như
A plugin’s .wasm is not on this machine (Tệp của plugin không có trên máy này)
mô tả.
Trỏ workspace tới cả hai thư mục catalog trong .aggrega-config.yaml:
workspace: catalog_dirs: - catalog - dev-catalogauto_pull: trueauto_pull cho phép aggrega build phân giải Release ngay trong tiến trình, nên bản
build đầu tiên không cần một bước phân giải riêng.
6. Các tài liệu nhắm tới provider
Bốn tệp. Component khai báo những gì một tác giả có thể thiết lập; Recipe liên kết capability và tạo artifact; Aggregate nêu ý định; Release đặt nó vào vị trí.
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 là toàn bộ phần liên kết. Nó nêu tên một capability, không phải một plugin: bản build phân giải nó thành plugin provider nào khai báo capability đó. Khi có đúng một plugin như vậy — như ở đây — thì không cần gì thêm.
Các khóa được viết ra cố ý không ở dạng biến môi trường. service-name và log.level là cách viết mà một tác giả sẽ viết một cách tự nhiên, và việc chuẩn hóa chúng là việc của 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. Lần build đầu tiên và những gì nó từ chố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-onlyHãy đọc riêng từng dòng, vì chúng nói những điều khác nhau.
Cảnh báo là điều được dự kiến trong khi bạn phát triển, và nó sẽ không biến mất. Cảnh báo cho biết guest đã chạy mà không có digest nội dung được ghi nhận để đối chiếu, và đó là sự thật với một guest bạn vừa build cách đây một phút: chưa có gì công bố nó, nên không có digest nào được ghi nhận. Cảnh báo cũng cho biết vì sao việc phân giải lại Release sẽ không thay đổi điều đó — một guest được đọc từ bên cạnh entity của nó trong một thư mục catalog sẽ được mọi lần build đọc lại từ đầu, và một lần pull chỉ ghi nhận digest cho một plugin quản trị được gắn ở vai trò transform, mà guest này thì không phải — và điều gì sẽ thay đổi được: công bố plugin và tham chiếu đến entity đã công bố. Hãy hiểu cảnh báo này là việc build đúng đắn từ chối khẳng định một phép xác minh mà nó chưa thực hiện, và hãy chờ đợi nó chừng nào guest còn ở cục bộ.
Lỗi mới là phát hiện thực sự, và phần trong ngoặc đơn là chẩn đoán. Provider
đã được tìm thấy, được tải và được hỏi nó render những gì, và nó trả lời
none — this provider supports: none. Descriptor được viết ở phần đầu
đã nêu socket, capability và các export, nhưng chưa bao giờ nói guest xử lý loại nào trong
ba loại đầu vào của Recipe. Host sẽ không đoán: cổng kiểm tra loại đầu vào
đọc tập hợp mà guest đã khai báo và từ chối một node mà guest chưa từng nhận.
Đây là dạng của hầu hết các lỗi khi viết provider đầu tiên. Guest không có vấn đề gì; phần
tự khai báo của nó chưa đầy đủ. describe() không phải là một thủ tục hình thức mà host chấp nhận cho qua —
nó là toàn bộ cơ sở để một host không phụ thuộc vào định dạng quyết định gửi gì đến đâu.
8. Khai báo hợp đồng hành vi kết xuất
Thêm hợp đồng vào bộ mô tả trong 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 là khẳng định mà cổng kiểm tra đang tìm. Hai giá trị
false cũng là các khẳng định, và việc nêu rõ chúng chính là mục đích: một Recipe
đóng gói kèm một cây mã nguồn, hoặc một Recipe khai báo một workload, giờ đây bị từ chối trước khi
bất kỳ lần kết xuất nào chạy, với một thông báo nêu tên provider này — thay vì đi tới
render_node và thất bại ở đâu đó bên trong nó.
BoundaryAssembly: "none" cho biết đầu ra của mỗi nút được ghi tại nơi nó được đặt,
không có gì cần kết hợp. Một provider gộp nhiều component vào một
tài liệu sẽ khai báo merge hoặc nest thay vào đó, và xuất assemble_boundary để
thực hiện việc này. Đó là điều tự nhiên tiếp theo nên thêm vào provider này, và nó được
mô tả trong hợp đồng plugin.
Xây dựng lại guest, tạo lại thực thể, và đặt tệp .wasm mới trở lại bên cạnh
nó:
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.wasmThực thể được tạo lại giờ đây mang hợp đồng, được đọc từ tệp nhị phân:
[… 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: noneViệc tạo lại thực thể sau mỗi lần xây dựng lại guest là một phần của vòng lặp. Thực thể nhắc lại những gì tệp nhị phân báo cáo, và hai thứ này được đối chiếu chéo khi guest được nạp: một export hoặc một giá trị hợp đồng mà thực thể tuyên bố nhưng tệp nhị phân không báo cáo là một điểm không khớp khiến bản dựng dừng lại, nêu tên tuyên bố đó. Một tuyên bố mà thực thể bỏ qua thì không được kiểm tra, nên một thực thể bị bỏ lại sau một lần xây dựng lại có thêm nội dung vào tệp nhị phân — như bước này đã làm — vẫn được nạp, trong khi không còn mô tả tệp nhị phân đó nữa.
9. Lần build kết xuất thành công
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>/distDòng cuối cùng nêu đầy đủ thư mục đầu ra, trong đó <workspace> là
thư mục gốc của workspace. Cây thư mục được kết xuất bên dưới nó:
dist/infra/dotenv/app/app.envVà tệp mà provider đã ghi, đầy đủ:
# aggrega.ai/boundary-path=infraSERVICE_NAME=checkoutLOG_LEVEL=debugGREETING="hello world"ENDPOINT=https://checkout.example.netMọi quyết định của guest đều hiện rõ trong bảy dòng đó.
service-namevàlog.levelđến đúng như khi được viết và đi ra dưới dạngSERVICE_NAMEvàLOG_LEVEL. Người viết không bao giờ phải viết theo cú pháp của định dạng đích.GREETINGđược đặt trong dấu ngoặc kép còn ba giá trị kia thì không.hello worldchứa một dấu cách, nên nếu để trần thì nó sẽ kết thúc ởhello; endpoint không chứa ký tự nào mà định dạng đọc là cú pháp, nên đặt nó trong ngoặc kép chỉ thêm nhiễu.- Hai khóa nguồn gốc là chú thích, vì một tệp môi trường không có chỗ nào khác để đặt chúng. Một provider có đầu ra chứa khối siêu dữ liệu sẽ đặt cùng các khóa đó vào đấy. Host tính toán các khóa; guest chọn vị trí đặt.
- Các giá trị đến từ hai người viết khác nhau.
service_name,log_levelvàgreetinglà ý định của nhà phát triển, từ Aggregate.endpointlà của người vận hành, từ Release. Guest không thấy sự phân biệt nào trong số đó — nó nhận một phần thân đã được đánh giá duy nhất.
10. Hai điều nên kiểm tra trước khi tin tưởng nó
Rằng nó có tính tất định. Lưu lại đầu ra, build lại và so sánh:
cp -r dist ../capture && rm -rf distaggrega build --release release.yamldiff -r ../capture distdiff không in ra gì là kết quả bạn mong muốn. Tính tất định là hợp đồng của guest, không phải của host, và một guest duyệt qua một map của Go ở đâu đó trên đường tạo đầu ra sẽ không vượt qua bước này dù trông hoàn toàn đúng trong một lần build đơn lẻ.
Rằng các lần từ chối của nó được báo rõ ràng. Làm hỏng một dòng trong artifact của Recipe, để dòng đó không khai báo giá trị nào:
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=valueThông báo của chính guest đến được với tác giả nguyên vẹn, kèm theo tệp và dòng mà nó xuất phát. Điều này đáng được kiểm tra một cách có chủ ý, vì kiểu lỗi thay thế — một guest lặng lẽ bỏ qua một dòng mà nó không phân tích được — tạo ra một bản build thành công và một bản triển khai thiếu một biến, mà không có gì trong đầu ra cho biết điều đó.
11. Những gì nên bổ sung tiếp theo
Provider được xây dựng ở đây đã hoàn chỉnh nhưng còn tối giản. Theo thứ tự tương đối về mức độ thường được cần đến:
-
assemble_boundary, để gộp đầu ra của nhiều component vào một tài liệu, được khai báo thông quaBoundaryAssembly. -
validate_node_input, để kiểm tra cấu trúc đầu vào của một node trước khi bất kỳ lần render nào chạy, nhờ đó đầu vào sai định dạng được báo cáo tại ranh giới soạn thảo thay vì giữa lúc render. -
Render facts, để báo cáo một điều về những gì guest đã ghi mà chỉ hiểu biết của provider này về định dạng tệp môi trường mới thấy được — ở đây là tên các biến mà mỗi tệp định nghĩa. Một fact gồm một tên và một danh sách, cả hai đều là từ vựng riêng của provider này, được trả về bên cạnh các tệp — và giá trị luôn là một mảng JSON, kể cả khi chỉ có một phần tử, nếu không bản build sẽ dừng:
// 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}},}Trình biên dịch giữ các fact theo thứ tự guest liệt kê, chỉ kiểm tra rằng mỗi giá trị là một danh sách, chuyển các danh sách cho các template Feature đọc chúng, và ghi ra cùng các tệp dù chúng có được báo cáo hay không. Hãy ghi tài liệu tên của mỗi fact và nội dung các phần tử của nó như một phần hợp đồng của provider.
-
Các mục omit, khi provider đã render một source. Đầu vào của một lần render source có thể mang
Omits, các mục chỉ định những đơn vị đã render cần loại bỏ, bên cạnhSourceListingcủa nó; một provider tuân theo chúng sẽ loại mọi đơn vị khớp khỏi những gì nó trả về, báo cáo một số đếm cho mỗi mục trongOmitted, và khai báoOmits: truetrong hợp đồng của nó. Chúng không bao giờ đi kèm một lần render chỉ có artifact như của provider này, nên nó chỉ gặp chúng sau khi render một đầu vào có source. Loại bỏ các đơn vị đã render trong hợp đồng plugin mô tả đầy đủ cấu trúc. -
Xuất bản, biến cách bố trí
dev-catalogcục bộ thành một artifact được ghim theo digest mà một Release phân giải và xác minh. Hướng dẫn cho nhà phát triển plugin trình bày vòng đời đó, trong các giai đoạn publish, pull và build.
Cấu trúc payload và kết quả của mỗi socket có trong hợp đồng plugin.
Tài liệu tham khảo liên quan
- Hướng dẫn phát triển Wasm plugin — thực thể
Plugin, bề mặt năng lực và vòng đời xuất bản. - Hợp đồng Plugin — hình dạng đầu vào và đầu ra của mọi socket.
- Kiến trúc Provider — cách các provider khớp vào pipeline biên dịch.
- Chỉ mục tham khảo Provider — những gì mỗi provider của thư viện chuẩn tạo ra.
- Đọc đầu ra trên các trang này — quy ước mà các khối đầu ra ở trên tuân theo.