Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Hướng dẫn phát triển plugin Wasm

Đây là hướng dẫn chuẩn để viết một plugin WebAssembly (Wasm) của Aggrega và xuất bản nó dưới dạng một thực thể trong catalog. Hướng dẫn trình bày trọn vẹn hợp đồng của tác giả plugin: plugin là gì, plugin tự mô tả với host như thế nào, cách viết các export và các khai báo năng lực của plugin, các giới hạn runtime và các hàm host mà host áp dụng, thực thể Plugin đưa một plugin vào catalog, cách một Recipe hoặc FeatureRecipe tham chiếu đến một plugin, và vòng đời publish→pull→build đưa một plugin từ một tệp .wasm trên đĩa thành một artifact đã được xác minh, được ghim theo digest mà một bản build sử dụng.

Trang đi kèm plugin-contract.md mô tả các socket — những điểm trong pipeline nơi plugin gắn vào, cùng các dạng đầu vào/đầu ra mà mỗi socket tiếp nhận và tạo ra. Hướng dẫn này mô tả plugin — thực thể, bề mặt năng lực và vòng đời. Hãy đọc trang hợp đồng để biết plugin của bạn nhắm đến socket nào; đọc trang này để biết cách viết và phát hành nó.

Để có một lộ trình thực hành xuyên suốt toàn bộ công việc thay vì một tài liệu tham chiếu, viết một provider xây dựng trọn vẹn một guest provider nhỏ — descriptor, build, thực thể, việc gắn kết, và một lần render có đầu ra bạn có thể đọc — bao gồm cả lời từ chối mà bản nháp đầu tiên thường gặp và cách đọc nó.

1. Plugin Wasm là gì

Một plugin Wasm là một mô-đun WebAssembly mở rộng trình biên dịch tại một socket được chỉ định. Tệp nhị phân host viết bằng Go không chứa logic dành riêng cho đám mây hay hạ tầng; toàn bộ trí tuệ chuyên biệt theo miền — render template, chuyển đổi định dạng, đánh giá chính sách, linting — nằm bên trong các plugin. Host điều phối pipeline và truyền payload của từng socket qua ranh giới ABI sang guest; guest thực hiện công việc của miền và trả về kết quả theo cấu trúc của socket đó. Payload và kết quả của mọi socket đều được truyền dưới dạng CBOR chuẩn tắc, với hai ngoại lệ: một plugin CLI nhận vectơ đối số dưới dạng văn bản JSON và trả lời bằng một mã thoát cùng văn bản mà nó stream ra, và bản tự báo cáo describe là văn bản JSON. Phần dành cho từng socket trong hợp đồng plugin nêu rõ cách mã hóa của socket đó, và guest đọc và ghi nó thông qua các điểm vào mà kiểu payload trong bộ kit của nó đã có sẵn, nên không guest nào phải tự phân tích byte thủ công.

Một plugin chạy sau một bức tường lửa bảo đảm tính thuần khiết ahead-of-time. Host nạp và thực thi mô-đun thông qua một runtime Wasm nhúng với cấu hình từ chối mọi capability: không có socket mạng, không có hệ thống tệp, không có biến môi trường, stdio bị loại bỏ, và đồng hồ thực quan sát được bị cố định tại một thời điểm bất biến qua các lần build. Mọi lệnh gọi I/O mà guest thử thực hiện đều thất bại ngay tại ranh giới lệnh gọi, nên plugin không thể truy cập trạng thái runtime. Hãy viết plugin với bức tường lửa này trong đầu: một plugin biến đổi payload được trao cho nó và trả về một kết quả mà host dùng nguyên văn, và tính tất định là trách nhiệm của bạn — đầu vào giống hệt nhau phải tạo ra các byte đầu ra giống hệt nhau. Kênh duy nhất được chấp thuận cho nội dung từ xa là việc tải đầu vào bên ngoài do host làm trung gian (Mục 4), cung cấp byte theo nguyên tắc ghim digest thay vì cho guest truy cập mạng trực tiếp.

Các socket mà một plugin có thể nhắm tới — trong đó có cổng biến đổi khi xây dựng topology, cổng kiểm tra hợp lệ khi phân tích tĩnh, pipeline FeatureRecipe, linter ngoài luồng, và socket render của provider — cùng các cấu trúc đầu vào/đầu ra của từng socket được mô tả trong plugin-contract.md. Socket mà một plugin phục vụ là giá trị duy nhất nó khai báo trong metadata.pluginType, và toàn bộ tập giá trị mà trường đó chấp nhận là mục tham chiếu cho nó trong entities/plugin.md §“metadata.pluginType”. Các ví dụ trong hướng dẫn này dùng provider (render các nút IR thành artifact gốc của provider), linter (kiểm tra nội dung được viết và phát ra chẩn đoán), và pipeline-step (một bước trong pipeline: của một FeatureRecipe hoặc một Recipe, áp patch lên tập tài liệu đã render).

Bạn viết guest dựa trên host thông qua bộ công cụ phát triển plugin (PDK) cho ba ngôn ngữ — Go, Rust hoặc TypeScript. PDK bọc chuỗi công cụ Wasm bên dưới bằng các builder có kiểu Aggrega cho các cấu trúc đầu vào và đầu ra mà mỗi socket mang theo.

2. Bản tự báo cáo describe()

Mọi plugin đều xuất một hàm describe() trả về bản tự báo cáo của plugin: (các) loại socket mà nó triển khai, phiên bản ABI mà nó nhắm tới, các capability mà nó khai báo — được đọc tùy theo loại socket, nên đó là tên capability đối với một provider hoặc một bước pipeline, và là các định dạng nguồn có tiền tố đối với một parser hoặc một importer — các hàm host mà nó import, và capability theo từng export của mỗi entry point mà nó cung cấp. describe() là lời tự thuật của chính plugin về việc nó là gì và nó làm gì.

Bản tự báo cáo là điểm neo của mô hình tin cậy. Thực thể Plugin đưa plugin vào catalog (Mục 5) nêu lại chính những thông tin đó dưới dạng các khai báo do tác giả viết, và host đối chiếu các khai báo của thực thể với đầu ra describe() của plugin tại hai thời điểm — khi publish, trước khi bất kỳ byte nào được đưa vào registry, và khi load, trước khi plugin chạy. Một điểm không khớp sẽ dừng quá trình với thông báo rõ ràng. Thực thể là bề mặt dễ đọc đối với con người và hiển thị trong catalog; describe() là nguồn ghi nhận chính thức ở phía máy mà host dùng để xác minh thực thể. Hãy viết cả hai sao cho khớp nhau; việc đối chiếu tồn tại chính là để phát hiện trường hợp hai bên lệch nhau. Việc đối chiếu kiểm tra những gì thực thể khai báo chứ không kiểm tra những gì nó bỏ sót: một thực thể khai báo ít hơn những gì binary báo cáo — chẳng hạn một thực thể bị bỏ lại sau một lần build lại có thêm một export — vẫn được load, dù không còn mô tả mọi thứ binary làm.

3. Khai báo các export và tuyên bố khả năng của chúng

Một plugin cung cấp một hoặc nhiều export — các điểm vào có tên mà host điều phối tới (ví dụ render_node, lint_naming, step). Mỗi export mang một khối khả năng: tuyên bố của tác giả về việc export đó làm gì. Khả năng của một export có bốn trường:

  • name — tên ABI của export, tên mà host điều phối tới. Bắt buộc.
  • operates — thao tác pipeline mà export thực hiện: patch (sửa đổi một tài liệu đã được render) hoặc emit (thêm một tài liệu mới). Đây là một tuyên bố khả năng được khai báo. Host đối chiếu nó với bản tự báo cáo describe() của plugin khi publish và khi tải, vì vậy tuyên bố do tác giả viết trên thực thể và bản mô tả của chính plugin phải khớp nhau. Đây là một tuyên bố được xác thực về export, không phải công tắc điều phối: tại thời điểm render, thao tác mà một bước thực sự thực hiện được mang trong kết quả mà guest trả về, không được chọn từ trường này. Khi vắng mặt, không có tuyên bố thao tác nào.
  • scope — gốc tài liệu mà export thao tác trên đó: own (các tài liệu đã render của chính node) hoặc host (các tài liệu của component mà một FeatureRecipe phạm vi component được gắn vào). Trước khi plugin của một bước pipeline chạy, host đọc phạm vi export đã khai báo của bước đó và đảm bảo rằng provider render các tài liệu của phạm vi đó xuất hiện trong spec.pipelineStep.capabilities của plugin (Mục 5) — một export phạm vi own được kiểm tra với provider render các tài liệu của chính node, một export phạm vi host được kiểm tra với provider của component host, và một phạm vi rỗng mặc định là own cho lần kiểm tra này. Đây là cổng tương thích provider, chạy trước bước đó; tài liệu mà một thao tác của guest thực sự tác động được chỉ định theo từng thao tác trong kết quả mà guest trả về, không được chọn từ trường đã khai báo này. Khi vắng mặt, mặc định là own.
  • selector — một mô tả dạng tự do, dễ đọc với con người, về đối tượng mà export tác động (ví dụ workloads carrying a pod template). Là tài liệu cho người đọc catalog và cho giao diện aggrega inspect; trình biên dịch không diễn giải nó.

Hãy khai báo các export theo thứ tự bạn muốn chúng được đọc; các mục giữ nguyên thứ tự của tác giả trên thực thể và trong inspect. Một plugin không khai báo export nào thì không có bề mặt export — điều này hợp lệ đối với một plugin có socket không cần tuyên bố khả năng theo từng export.

4. Giới hạn thời gian chạy và các hàm host

Một thực thể plugin có thể mang một khối runtime tùy chọn, ràng buộc cách host nạp và chạy plugin.

Giới hạn bộ nhớ và thời gian. maxMemoryPages giới hạn bộ nhớ tuyến tính của plugin theo số trang Wasm (64 KiB mỗi trang); timeoutMs giới hạn thời gian mã riêng của plugin được phép chạy trong một lần gọi, tính bằng mili giây. Thời gian trải qua bên trong các hàm host mà plugin gọi không được tính vào giới hạn này. Trên Linux, thước đo là thời gian bộ xử lý của luồng đang chạy guest, nên thời gian guest chờ bộ xử lý trên một máy bận cũng không được tính; trên các hệ thống khác, đó là thời gian thực đã trôi qua. Lần gọi đầu tiên tới một plugin vừa được nạp cũng tính cả bước khởi tạo một lần của runtime ngôn ngữ guest, vốn chạy bên trong lần gọi đó. Cả hai giới hạn đều tùy chọn và có giá trị mặc định: giá trị không hoặc vắng mặt sẽ áp dụng mức giới hạn mặc định của nền tảng. Bộ nạp giới hạn mọi plugin ở mức mặc định của nền tảng khi thực thể không khai báo giới hạn nào, nên một lần nạp không bao giờ là không giới hạn và một lần gọi không bao giờ là không thể hủy. Hãy nâng giới hạn trên thực thể khi một attachment thực sự cần nhiều bộ nhớ hoặc nhiều thời gian hơn mức mặc định cho phép.

Các hàm host. hostFunctions ghi lại tên các hàm host mà plugin import. Đây là một trường do máy suy ra — đừng tự viết nó. aggrega plugin sync đọc các hàm host trực tiếp từ phần import của .wasm và ghi trường này vào tệp thực thể cho bạn, còn bước publish suy ra lại chúng từ binary và từ chối một thực thể có bản ghi khác đi; vì vậy một plugin nhận đúng các hàm host mà binary của nó thực sự import, được kiểm tra đối chiếu với một danh sách cho phép được tuyển chọn (một import nằm ngoài danh sách cho phép sẽ bị từ chối rõ ràng). Bản ghi này là một ảnh chụp của binary đã publish, giống như tham chiếu plugin: định địa chỉ theo nội dung là một ảnh chụp của các byte đã publish: nó phản ánh binary tại thời điểm publish và được suy ra lại cũng như xác minh khi plugin được pull. Để xem các hàm host mà một .wasm cục bộ import trước khi publish — tức giá trị mà aggrega plugin sync ghi lại — hãy chạy aggrega inspect --plugin <file.wasm>.

Bề mặt host được tuyển chọn. Ba trong số các hàm host có mục đích chung: aggrega_log (một mức và một thông điệp, được phát ra thành một dòng log tại đích log của host), aggrega_emit_warning (một mã, một thông điệp và một đường dẫn, được tích lũy thành một cảnh báo có cấu trúc mà host hiển thị sau lần gọi), và aggrega_fetch_external_input (một URL, được trả lời bằng các byte của đầu vào theo kỷ luật ghim mô tả bên dưới). PDK bao bọc cả ba trong mỗi ngôn ngữ — Go: aggrega.Log, aggrega.EmitWarning, aggrega.FetchExternalInput; Rust: log, emit_warning, fetch_external_input; TypeScript: log, emitWarning, fetchExternalInput — nên guest gọi một hàm có kiểu thay vì ABI thô. Các callback nguồn và phân tích cú pháp — dành cho guest đọc các lát cắt của một nguồn đã thu nhận hoặc lấy một cây đã phân tích thông qua host — cùng cách mã hóa mà các slot của từng callback mang được liệt kê trong plugin-contract.md.

Nội dung nguồn cục bộ đến qua host — không bao giờ từ hệ thống tệp. Một plugin render của provider không bao giờ đọc nguồn từ đĩa; một lời gọi hệ thống tệp sẽ thất bại tại ranh giới lời gọi. Host trao cho guest một danh sách nguồn bên trong payload render — đường dẫn tương đối với gốc nguồn của mọi mục và việc mục đó có phải thư mục hay không, theo thứ tự đã sắp xếp, không có nội dung tệp — và guest áp dụng logic bố cục riêng của nó lên danh sách đó, rồi đọc lại đúng những tệp nó chọn thông qua các callback nguồn, vốn trả về các byte mà host đọc dưới gốc nguồn. Hình dạng payload của từng socket và các callback được mô tả trong plugin-contract.md.

Nội dung từ xa đến qua cơ chế tải đầu vào bên ngoài. Một plugin cần nội dung từ xa — một kho lưu trữ chart, một tài liệu schema từ xa — sẽ gọi hàm bao tải của PDK. Trên đường truyền, guest chuyển URL cho aggrega_fetch_external_input dưới dạng văn bản UTF-8 và nhận một phản hồi ở dạng CBOR chuẩn tắc, mang hoặc các byte đã tải, ở dạng thô, hoặc một thông điệp lỗi kèm mã lỗi mà máy có thể so khớp; hàm bao giải mã phản hồi thành byte-hoặc-lỗi. Các byte đến đúng như khi được tải, kể cả một payload không phải UTF-8 hợp lệ, và một payload có độ dài bằng không được trả về dưới dạng byte rỗng thay vì lỗi. Host phục vụ URL theo kỷ luật ghim đầu vào bên ngoài:

  • Một URL đã được ghim trong lockfile của Release được phục vụ từ kho lưu trữ định địa chỉ theo nội dung cục bộ và được xác minh đối chiếu với digest đã ghi ở mỗi lần đọc. Một blob bị thiếu trong kho được nạp lại từ mạng theo digest đã ghi — một lần nạp lại đã xác minh digest không thể thay đổi đầu ra.
  • Một URL chưa được ghim sẽ bị từ chối, kèm một lỗi nêu tên URL và cách khắc phục. Một lần build render bao đóng mà lockfile của nó ghi lại, nên không lần build nào tải một tham chiếu chưa được ghim và không có thiết lập nào cho phép điều đó.
  • Việc ghim diễn ra khi các phụ thuộc của Release được phân giải: aggrega pull render Release để tìm ra những đầu vào bên ngoài mà quá trình render của nó yêu cầu, tải từng đầu vào, và ghi nó vào lockfile bên cạnh các ghim phụ thuộc. Vì vậy vòng làm việc của tác giả plugin là phân giải một lần, rồi build ngoại tuyến bao nhiêu lần tùy thích.

Các scheme được phép là https, http chỉ tới các host loopback, và oci (được ghim theo digest của manifest). Lockfile ghi lại mọi đầu vào đã ghim — URL, digest sha256, kích thước, và các plugin đã yêu cầu nó — nên một lần build lại phục vụ đúng các byte đó từ kho cục bộ: có thể tái lập, và ngoại tuyến sau khi đã ghim.

Với Go PDK:

import "github.com/aggrega-ai/aggrega-pdk/go/pkg/aggrega"
chart, err := aggrega.FetchExternalInput("https://charts.example.com/postgresql-16.3.2.tgz")
if err != nil {
// The error names the URL and the remedy — an unpinned URL reports exactly
// what to pin and how. Surface it as a render failure; do not mask it.
return fmt.Errorf("fetching chart archive: %w", err)
}

Điều gì thất bại, và vì sao.

  • Một lời gọi hệ thống tệp hoặc mạng sẽ thất bại tại ranh giới lời gọi: guest không giữ thư mục mở sẵn nào và không có socket nào. Điều này áp dụng cho mọi đường đi của mã, kể cả một thư viện phụ thuộc cố đọc một tệp — hãy đọc nguồn thông qua các callback nguồn thay vào đó.
  • Một import thuộc một module nằm ngoài wasi_snapshot_preview1, extism:host/env và extism:host/user sẽ thất bại khi nạp, kèm một chẩn đoán nêu tên module và import. Các tên hàm WASI riêng lẻ trong một module được phép không bao giờ bị kiểm duyệt — các import hệ thống tệp và socket không dùng tới của một runtime ngôn ngữ liên kết tĩnh là không sao, vì việc nêu tên một import không cấp quyền gì.
  • Một lần tải URL mà lockfile không ghim sẽ thất bại với một lỗi nêu tên URL; cách khắc phục là chạy aggrega pull --release <release>, lệnh này ghim mọi đầu vào bên ngoài mà quá trình render của Release sử dụng, rồi build.

Không có trường danh sách host cho phép nào cho truy cập mạng ra ngoài. Một plugin không bao giờ chạm tới mạng tại thời điểm build — đó là ranh giới biên dịch trước (ahead-of-time) — nên không tồn tại trường nào như vậy để viết. Nội dung từ xa đến qua kênh đầu vào bên ngoài do host làm trung gian và được ghim theo digest ở trên, không bao giờ qua truy cập mạng tùy ý.

Cấu hình. configKV là một map từ chuỗi sang chuỗi mà runtime trao cho plugin khi khởi động. Các mục giữ nguyên thứ tự của tác giả để bản ghi được phát ra giống hệt từng byte qua các lần chạy. Nếu vắng mặt, cấu hình rỗng mặc định của runtime sẽ có hiệu lực.

5. Thực thể Plugin

Một plugin đi vào catalog dưới dạng một thực thể Plugin — bề mặt soạn thảo và siêu dữ liệu của plugin. Thực thể khai báo plugin là gì và trỏ tới artifact .wasm; trình biên dịch không diễn giải hành vi của plugin mà chỉ định tuyến tham chiếu đã ghim, còn runtime Wasm thực thi các byte.

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: aws-secrets-manager
version: 1.2.0
pluginType: pipeline-step
spec:
abiVersion: v1beta1
pipelineStep:
capabilities:
- helm
- compose
signature:
type: sigstore-cosign
runtime:
maxMemoryPages: 256
timeoutMs: 5000
# hostFunctions is recorded by `aggrega plugin sync` from the .wasm — do not author it.
exports:
- name: fetch
operates: emit
scope: own
selector: external-secret resources for the bound credential

Các trường:

  • Không có trường vị trí artifact, một cách có chủ ý. Thực thể không mang con trỏ nào tới .wasm và schema không chấp nhận con trỏ nào. Vị trí artifact của một plugin được suy ra từ danh tính của nó — tọa độ metadata.pluginType/metadata.name, tạo thành đường dẫn repository plugin/<pluginType>/<name> — cộng với registry mà workspace được cấu hình, nên không có vị trí nào để soạn và cũng không có vị trí nào để viết sai. Digest nội dung đã phân giải được ghi lại theo từng Release trong lockfile của Release đó, và quá trình build xác minh các byte đã tải về đối chiếu với nó: danh tính nằm trong thực thể, byte đã xác minh nằm trong lockfile.
  • metadata.version — bản phát hành mà thực thể công bố, phải bằng chính phiên bản build-provenance của guest như được báo cáo trong describe(). Tác giả plugin đánh phiên bản cho .wasm tại thời điểm build — quá trình build đóng dấu phiên bản vào guest, và một bản build lấy phiên bản từ tag phát hành chỉ đóng dấu phiên bản phát hành trên commit mà tag đó chỉ tới — và metadata.version của thực thể nêu đúng bản phát hành đó. Cửa publish đối chiếu hai giá trị và dừng khi chúng khác nhau, nên thực thể luôn nêu chính xác phiên bản của binary mà nó phân phối. aggrega plugin gen-catalog --plugin (bên dưới) sao chép phiên bản mà guest báo cáo vào thực thể nó sinh ra, đó là phiên bản phát hành khi guest được build từ commit đã gắn tag. Bắt buộc.
  • metadata.pluginType — loại socket mà plugin này triển khai, lấy từ provider, linter, pipeline-step, governance, cli, parser và importer. Một plugin triển khai đúng một loại. Trường này nằm trong khối định địa chỉ bên cạnh name và version, và cung cấp phân đoạn <pluginType> của tọa độ được suy ra. Bắt buộc.
  • spec.abiVersion — phiên bản ABI host/guest mà plugin nhắm tới. v1beta1 là giá trị được chấp nhận; một bản sửa đổi ABI trong tương lai sẽ thêm một giá trị được chấp nhận. Bắt buộc.
  • Khối dành cho loại socket của bạn, mang capabilities — một plugin khai báo những gì nó phục vụ bên trong khối thuộc về metadata.pluginType của nó, và chính khối đó xác định ý nghĩa của một mục. spec.provider.capabilities nêu các capability mà một provider phục vụ (tên capability như helm hoặc compose). spec.pipelineStep.capabilities nêu các provider mà đầu ra đã render của chúng tương thích với bước của bạn. spec.parser.capabilities nêu các định dạng nguồn mà một parser đọc, mỗi định dạng viết là parse:<format>. spec.importer.capabilities nêu các định dạng ngoại lai mà một importer soạn nháp thực thể từ đó, mỗi định dạng viết là import:<format>. Một importer viết bằng Go có thể lấy mọi thứ không phụ thuộc vào định dạng của nó — việc chấm điểm, quyết định tham chiếu hay soạn nháp, các bản nháp và việc render chúng, cùng các thiết lập — từ gói importer của bộ kit Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Một plugin linter, governance hoặc cli không phục vụ capability nào và không mang khối nào trong bốn khối này. Các mục giữ nguyên thứ tự của tác giả, và mỗi danh sách là một tuyên bố tường minh, đã được kiểm thử: hãy khai báo những gì bạn thực sự đã build và kiểm thử plugin với, vì bên tiêu thụ phân giải đúng theo những gì được liệt kê. Với một pipeline step, tuyên bố đó được thực thi khi render — khi một bước chạm tới một scope, quá trình build dừng lại trừ khi provider render các tài liệu của scope đó nằm trong số các provider mà plugin của bạn tuyên bố — nên một danh sách rỗng không khớp provider nào và không cho phép bước chạy ở đâu cả.
  • spec.signature — một con trỏ mô tả tùy chọn tới chữ ký đính kèm của plugin (Mục 8). Khối này chỉ mang tính tài liệu: nó ghi lại chữ ký nằm ở đâu và được tạo ra như thế nào cho người đọc catalog; bản thân nó không chấp nhận plugin. Bước kiểm tra có hiệu lực thực thi là chính sách tin cậy theo từng registry được áp dụng khi pull.
  • spec.runtime — khối ràng buộc thực thi tùy chọn từ Mục 4. Tác giả viết maxMemoryPages, timeoutMs và configKV; hostFunctions được máy suy ra và được ghi lại bởi aggrega plugin sync, rồi được publish xác minh, không do tác giả soạn.
  • spec.exports — các tuyên bố capability theo từng export từ Mục 3 (name, operates, scope, selector).

Sinh thực thể từ .wasm của bạn. Bạn không phải tự tay viết các phần của thực thể do máy sở hữu. aggrega plugin gen-catalog --plugin <file.wasm> đọc bản tự báo cáo describe() của guest và tạo ra từ đó một thực thể Plugin sẵn sàng để publish, cộng với một lớp phủ nhỏ do bạn soạn và cung cấp (danh tính, giới hạn runtime và khối provider nếu có). Trình sinh đóng dấu các trường mà binary là nguồn sự thật — các tuyên bố export, hợp đồng capability, bản phản chiếu lệnh và bản ghi host-function — và sao chép metadata.version từ phiên bản build-provenance trong describe() của guest, còn lớp phủ chỉ cung cấp những gì binary không báo cáo. Đây là con đường được hỗ trợ cho tác giả plugin bên thứ ba: build và đánh phiên bản .wasm của bạn, rồi sinh lại thực thể để các trường do máy sở hữu luôn đồng bộ với binary. Phiên bản là trường được sao chép duy nhất nêu một bản phát hành thay vì một sự thật về các byte, nên hãy sinh từ một bản build của commit mà tag của bản phát hành chỉ tới — hoặc, nếu bắt đầu từ một bản build phát triển, hãy đặt metadata.version thành bản phát hành trong thực thể đã sinh trước khi gắn tag cho commit chứa nó. Một guest không mang phiên bản build-provenance thì không thể được sinh thành một thực thể có phiên bản — hãy đánh phiên bản cho guest tại thời điểm build trước.

Tệp .wasm bên cạnh thực thể của nó. Trong khi bạn viết một plugin, chưa có gì được xuất bản để một bản build tải về, vì vậy bản build đọc .wasm của plugin từ bên cạnh thực thể Plugin của nó trong một thư mục catalog, dưới một tên được suy ra từ loại plugin và tên của thực thể: với pipeline-step/patch, tên đó là pipeline-step--patch.wasm. Chữ thường, chữ số và hầu hết các dấu gạch nối được ghi vào tên đó nguyên dạng; mọi ký tự khác được ghi ở dạng thoát, và một dấu gạch nối ở một vài vị trí cũng vậy — vì thế, ở nơi điều đó quan trọng, thông báo từ chối khi thiếu .wasm, A plugin’s .wasm is not on this machine (tệp của một plugin không có trên máy này), đưa ra tên đầy đủ. aggrega lint <plugin.yaml> đọc .wasm từ cùng chỗ đó — bên cạnh tệp thực thể được truyền cho nó, trong bất kỳ thư mục nào chứa tệp đó — trừ khi chính tệp nhị phân mang plugin đó, và in ra một thông báo cho mỗi export, khả năng hoặc hợp đồng mà .wasm báo cáo nhưng thực thể bỏ sót. Nơi không có .wasm nào ở đó, lint cho biết nó đã bỏ qua báo cáo đó, nêu tên tệp nó đã tìm và thư mục, và kết quả của nó không thay đổi.

Để xem tài liệu tham khảo từng trường, hãy xem trang thực thể ../entities/plugin.md.

6. Tham chiếu một plugin

Một bước pipeline hoặc một socket plugin tham chiếu một plugin bằng URI của thực thể Plugin — danh tính của thực thể, chứ không trực tiếp bằng artifact .wasm. Thực thể là lớp mang ghim digest, các khẳng định về capability, các giới hạn runtime và chữ ký; tham chiếu thực thể là cách một bên sử dụng nhận được tất cả những thứ đó.

Một đường dẫn .wasm trần hoặc một tham chiếu artifact thô được để trong trường plugin sẽ bị từ chối khi tải: không có thực thể Plugin nào khớp với nó, nên việc phân giải plugin thất bại một cách rõ ràng. URI của thực thể là bắt buộc — việc đi gián tiếp qua thực thể chính là hợp đồng, không phải một tiện ích tùy chọn. Một bước pipeline của FeatureRecipe nêu tên thực thể trong pipeline[].plugin; xem ../entities/featurerecipe.md để biết bề mặt soạn thảo pipeline.

Khi hai hoặc nhiều plugin được ghép nối — chúng phải thống nhất về một hợp đồng chuyển giao chung, như trong một cặp Fetcher và Injector, nơi đầu ra của plugin này là đầu vào của plugin kia (nguyên tắc Two-Part Plugin Principle được mô tả trong plugin-contract.md) — hãy soạn hợp đồng đó một lần và để mỗi plugin phụ thuộc vào định nghĩa duy nhất đó, thay vì khai báo lại hình dạng chuyển giao JSON một cách độc lập trong từng plugin. Hình dạng chung là cấu trúc JSON mà các plugin trao đổi, có thể nằm trong một mục SchemaLibrary duy nhất mà cả hai plugin cùng tham chiếu. Một nguồn duy nhất cho hợp đồng giúp các plugin được ghép nối luôn đồng bộ khi hợp đồng thay đổi; các bản khai báo lại độc lập sẽ lệch nhau, và sự lệch đó chỉ lộ ra khi hai plugin không còn khớp nhau lúc chạy. Khuyến nghị là chia sẻ hợp đồng, không phải mã Wasm — mỗi plugin vẫn là một artifact riêng.

7. Vòng đời publish → pull → build

Một plugin đi từ một tệp .wasm trên đĩa đến một artifact đã được xác minh, có thể dùng cho build, qua ba giai đoạn.

Publish. aggrega push publish một thực thể Plugin cùng với .wasm của nó dưới dạng một OCI manifest duy nhất, được gắn tag theo metadata.version: YAML của thực thể là config blob của manifest và .wasm đi kèm như một layer của chính manifest đó. Việc publish cặp này thành một manifest có tag duy nhất là điều làm cho thao tác push mang tính nguyên tử — không có khoảng thời gian nào mà một nửa đã được publish còn nửa kia thì chưa — và đó cũng là lý do một chữ ký trên manifest đó bao phủ cả hai nửa. Cả hai nửa đều được đặt tên trên manifest, nên một OCI client thông thường khi pull tag phiên bản sẽ ghi thực thể vào entity.yaml và tệp thực thi vào entity.wasm.

Trước khi bất kỳ byte nào được ghi, publish chạy các bước kiểm tra của nó. Thực thể được đọc theo schema Plugin trước tiên, giống như cách một lần nạp catalog đọc nó, nên một metadata.version không phải là phiên bản ngữ nghĩa — hoặc bất kỳ sai lệch nào khác so với schema — sẽ bị từ chối trước khi .wasm được đọc. Sau đó .wasm được nạp và bản tự báo cáo describe() của nó được đối chiếu với các khai báo năng lực do tác giả viết trong thực thể — nếu không khớp, quá trình dừng lại kèm báo lỗi rõ ràng, nên một thực thể đã publish không bao giờ khai báo điều mà plugin nó phân phối không báo cáo. Một guest có phiên bản nguồn gốc build trong describe() mang dấu -dirty — dấu được đóng lên một bản build từ working tree có thay đổi chưa commit — sẽ bị từ chối: phiên bản đó chỉ đến một commit không chứa những gì đã được build. Một phiên bản phát triển được build từ một commit (1.0.0-3-g1a2b3c4) và một bản prerelease (1.0.0-rc.1) đều publish được. metadata.version được ghi nhận sẽ được đối chiếu với phiên bản nguồn gốc build trong describe() của guest, và nếu có sai khác thì publish dừng lại, nên hai giá trị phải khớp nhau. Cả hai trường hợp từ chối đều được khắc phục theo cùng một cách: build plugin từ một bản checkout sạch của commit mà tag của bản phát hành chỉ đến, để nó báo cáo đúng phiên bản phát hành — với một bản phát hành mới, hãy commit thực thể cùng với mã nguồn mà nó phát hành và gắn tag cho commit đó trước. Sao chép phiên bản mà một bản build phát triển báo cáo vào thực thể không phải là cách sửa: làm vậy sẽ publish bản build đó dưới một phiên bản mà không tag phát hành nào chỉ đến. Các hàm host mà .wasm import được suy ra từ tệp nhị phân và so sánh với bản ghi đã commit trong spec.runtime.hostFunctions; nếu có sai khác thì publish dừng lại và nêu tên aggrega plugin sync, lệnh ghi lại trường này, vì trường này do máy quản lý và một lần publish không bao giờ ghi đè tệp thực thể đã commit. Thực thể được publish mang bản ghi hàm host đã được đóng dấu; digest nội dung của .wasm là một thuộc tính của manifest mà cặp này được publish thành, và nó được ghi lại cho bên sử dụng trong lockfile của Release thay vì được ghi vào thực thể.

Pull. aggrega pull phân giải toàn bộ các phụ thuộc của một Release và ghi một lockfile riêng cho từng Release, ghim mọi thực thể catalog và artifact từ xa vào một phiên bản và digest nội dung. Một Plugin đã publish được phân giải thông qua quá trình phân giải phụ thuộc này; .wasm của nó được tải về cùng với manifest chứa nó và các byte được xác minh với digest nội dung mà lockfile ghi lại. Pull cũng suy ra lại các hàm host từ .wasm đã xác minh và đối chiếu chúng với bản ghi hostFunctions đã đóng dấu, dừng lại nếu hai bên không khớp — một bước kiểm tra phòng thủ nhiều lớp bên trên việc ghim digest, giúp phát hiện một tệp nhị phân có dấu không được tạo ra từ chính các import của nó. Nếu chính sách tin cậy của registry yêu cầu chữ ký, chữ ký của thực thể sẽ được tải về và xác minh ở giai đoạn này, rồi được ghi lại như một dữ kiện đã xác minh trong lockfile (Mục 8). Việc xác minh diễn ra khi pull, không bao giờ khi build — build vẫn thuần túy ahead-of-time.

Build. aggrega build sử dụng plugin đã được ghim và xác minh từ các phụ thuộc đã phân giải. Trình biên dịch định tuyến tham chiếu được ghim theo digest và runtime Wasm thực thi các byte; cổng nạp chạy lại bước đối chiếu describe() cùng việc thực thi giới hạn hàm host và giới hạn runtime trước khi plugin chạy.

8. Ký và tin cậy

Một entity Plugin được ký giống hệt như mọi entity khác trong catalog: digest của manifest được ký và đính kèm dưới dạng một OCI referrer. Artifact .wasm không được ký riêng, và nó không cần chữ ký riêng — nó là một layer của chính manifest có digest được ký, nên chữ ký bao phủ nó trực tiếp: can thiệp vào .wasm sẽ làm thay đổi digest của manifest và làm hỏng chữ ký.

Việc ký là tùy chọn khi publish; việc xác minh được thực thi bởi chính sách tin cậy của từng registry khi pull. Một registry được cấu hình để yêu cầu chữ ký sẽ dừng thao tác pull khi một chữ ký bắt buộc bị thiếu, không được tin cậy hoặc không hợp lệ. Khối spec.signature trên entity là một con trỏ tài liệu chỉ tới nơi chữ ký được lưu và cách nó được tạo ra; nó ghi lại các thông tin cho người đọc catalog và bản thân nó không kiểm soát việc chấp nhận. Cơ chế kiểm soát là chính sách tại thời điểm pull.

Các lệnh và cờ của chúng được mô tả cùng với các bề mặt publish và tiêu thụ — xem ../cli/aggrega-sign.md, ../cli/aggrega-push.md và ../cli/aggrega-pull.md. Hướng dẫn này không nhắc lại các bảng cờ; những trang đó là nơi duy nhất mô tả bề mặt lệnh.

9. Quản lý phiên bản của thực thể

Một thực thể Plugin mang một Semantic Version nghiêm ngặt trong metadata.version. Một phiên bản đã phát hành là bất biến: việc phát hành lại một phiên bản đã tồn tại trong registry với nội dung khác sẽ bị từ chối tại cổng phát hành.

Khi bạn thay đổi một thực thể plugin và phát hành lại, quy trình phát hành sẽ phân loại thay đổi so với phiên bản đã phát hành trước đó và yêu cầu mức tăng phiên bản phải khớp. Việc phân loại tuân theo bảng tiêu chí tăng phiên bản: thay đổi chỉ về tài liệu hoặc chú thích là PATCH; thay đổi thuần túy bổ sung (một trường tùy chọn mới, một mục mới) là MINOR; việc xóa bỏ, thu hẹp kiểu, hoặc một trường trước đây tùy chọn trở thành bắt buộc là MAJOR. Tăng phiên bản cao hơn mức cần thiết luôn được cho phép; tăng thấp hơn mức cần thiết sẽ dừng lại với một chẩn đoán nêu rõ mức tăng bắt buộc. Lần phát hành đầu tiên của một thực thể bỏ qua bước kiểm tra mức tăng và đưa ra cảnh báo rằng không có xác minh nào được thực hiện. Chạy bước kiểm tra trước khi phát hành bằng aggrega lint --pre-publish; xem ../cli/aggrega-lint.md để biết đầy đủ bảng tiêu chí và các thiết lập theo từng quy tắc.

Một Plugin không có bề mặt extends, vì vậy các quy tắc kế thừa chi phối Components và Features của catalog không áp dụng cho nó. Bảng tiêu chí tăng phiên bản và tính bất biến là quy trình quản lý phiên bản chi phối một thực thể plugin.

10. Tham chiếu chéo

  • authoring-a-provider-walkthrough.md — một guest provider được xây dựng từ đầu đến cuối, từ một thư mục trống đến đầu ra đã kết xuất.
  • plugin-contract.md — các điểm socket mà một plugin nhắm tới và hình dạng đầu vào/đầu ra của từng socket.
  • policy-socket.md — socket quản trị chuyên sâu: bốn vai trò của nó, các mức độ nghiêm trọng của phán quyết, kênh đầu vào của người vận hành, cách viết một chính sách cho một trong hai engine đi kèm bên trong trình biên dịch, và các guest chính sách tham chiếu.
  • core-importers.md — các importer riêng của trình biên dịch, mỗi định dạng mà nó đọc có một importer, được xây dựng trên gói importer của bộ công cụ Go: mỗi importer đọc gì, các thiết lập của chúng, và việc phát hành chúng cùng mỗi bản phát hành của trình biên dịch.
  • ../compatibility.md — cách các bộ công cụ plugin được đánh phiên bản, và điều gì giúp một plugin được build cho một bản phát hành vẫn tiếp tục được nạp ở bản phát hành kế tiếp.
  • ../entities/plugin.md — tài liệu tham chiếu từng trường của thực thể Plugin.
  • ../entities/featurerecipe.md — bề mặt soạn thảo pipeline: của FeatureRecipe, nơi tham chiếu một plugin bằng URI thực thể.
  • ../cli/aggrega-lint.md — trình lint phát hành, bảng tiêu chí tăng phiên bản và việc thực thi tính bất biến.
  • ../cli/aggrega-inspect.md — kiểm tra các khả năng, giới hạn thời gian chạy và chữ ký của một thực thể Plugin.
  • ../cli/aggrega-push.md, ../cli/aggrega-pull.md, ../cli/aggrega-sign.md — các bề mặt lệnh phát hành, sử dụng và ký.