Hợp đồng Wasm plugin
Pipeline biên dịch của Aggrega có các điểm socket được chỉ định, nơi các plugin WebAssembly (Wasm) mở rộng hành vi của trình biên dịch: bốn vai trò của socket governance, trong đó có một Mutation Gate ở bước xây dựng topology và một Validation Gate ở bước phân tích tĩnh; một pipeline plugin hậu kết xuất cho các bước FeatureRecipe và Recipe; một socket kết xuất provider; một socket parser; một socket importer; và một socket linting ngoài luồng. Trang này mô tả hợp đồng Wasm plugin công khai: những socket nào tồn tại, mỗi socket tiêu thụ và tạo ra gì, mỗi socket nằm ở đâu trong pipeline biên dịch, và sandbox mà mọi plugin thực thi bên trong.
Trang này đề cập đến các socket — các điểm trong pipeline và dạng đầu vào/đầu ra của chúng. Về plugin — thực thể Plugin, các khai báo năng lực theo từng export, các giới hạn thời gian chạy, và vòng đời publish→pull→build — hãy xem hướng dẫn dành cho nhà phát triển Wasm plugin.
Aggrega nhúng một runtime host Wasm — Extism chạy trên engine Wazero — để nạp và thực thi plugin phía sau một bức tường lửa bảo đảm tính thuần AOT: host cấp cho guest không một năng lực môi trường nào — không mạng, không hệ thống tệp, không biến môi trường, stdio bị loại bỏ, đồng hồ thực quan sát được bị đóng băng ở một thời điểm bất biến theo bản build — nhờ đó plugin không thể phá vỡ các bảo đảm biên dịch trước (ahead-of-time) của trình biên dịch. Toàn bộ bề mặt năng lực — quy tắc import-module khi nạp, các từ chối tại thời điểm khởi tạo và các hàm host được tuyển chọn — được mô tả trong khế ước sandbox bên dưới. Plugin authors nhắm tới host thông qua PDK ba ngôn ngữ (Go, Rust, TypeScript). aggrega lint điều phối socket linter — publishing-linter tiêu chuẩn — qua host. aggrega build điều phối các vai trò thời điểm build của socket governance khi workspace cấu hình chúng: vai trò annotation-transform trong giai đoạn phân giải và vai trò label-transform khi xây dựng topology (cả hai đều định hình đầu ra), cùng với phán quyết IR ở giai đoạn phân tích tĩnh và phán quyết render trên các artifact đã render. Mỗi vai trò là no-op khi không có plugin nào được gắn ở vai trò đó, nên một bản build không có cấu hình governance sẽ không thay đổi. aggrega build cũng điều phối pipeline: của FeatureRecipe và Recipe trong pipeline plugin khép lại quá trình render — mỗi bước được khai báo chạy qua host trên tập tài liệu đã render, áp dụng các bản vá RFC 6902 của bước đó và phát ra các tác dụng phụ của nó. Xem Trạng thái của ngôn ngữ → Các giai đoạn của pipeline biên dịch.
Hợp đồng sandbox
Mọi socket đều điều phối plugin của nó qua cùng một sandbox của host. Sandbox có hai lớp độc lập — một bước kiểm tra cấu trúc khi nạp và việc từ chối năng lực khi khởi tạo — và cùng nhau chúng xác định những gì một plugin có thể truy cập, những gì nó không thể, và những gì nó chịu trách nhiệm.
Quy tắc import-module (lúc nạp). Trình nạp duyệt phần import của tệp nhị phân plugin và chỉ chấp nhận các import hàm thuộc ba không gian tên module: wasi_snapshot_preview1 (runtime WASI preview-1 mà runtime của ngôn ngữ guest liên kết tới), extism:host/env (ABI của runtime Extism — các hàm nội tại về bộ nhớ và IO của chính PDK), và extism:host/user (các hàm host được tuyển chọn của Aggrega). Một guest có thể import bất kỳ tên hàm nào thuộc một module được phép; một import thuộc bất kỳ module nào khác chỉ tới một bề mặt mà host không cung cấp, và plugin bị từ chối khi nạp kèm một chẩn đoán nêu tên module và import đó. Quy tắc này cố ý không kiểm duyệt từng tên hàm WASI: một runtime ngôn ngữ liên kết tĩnh import các hàm hệ thống tệp và socket mà các đường mã thực thi của nó không bao giờ gọi — được kéo vào một cách bắc cầu qua các phụ thuộc — và việc khai báo một import không cấp quyền gì. Chính việc từ chối năng lực khi khởi tạo, chứ không phải kiểm duyệt import, mới bảo đảm không có I/O.
Không có năng lực ngầm định (lúc khởi tạo). Host khởi tạo guest với hành vi WASI thực và không có quyền hạn ngầm định nào:
- không có hệ thống tệp — không có thư mục được mở sẵn, nên một lời gọi hệ thống tệp thất bại tại ranh giới lời gọi;
- không có socket mạng;
- một môi trường rỗng;
- stdio bị loại bỏ — không gì guest ghi vào stdout hay stderr tới được các luồng của host;
- một đồng hồ thời gian thực quan sát được bị đóng băng, cố định tại một thời điểm bất biến theo bản build, nên một guest đọc thời gian không thể làm lộ thời điểm build vào đầu ra của nó;
- một đồng hồ đơn điệu thực, đang chạy — runtime của ngôn ngữ guest cần nó để khởi động, và thời gian đơn điệu đo khoảng thời gian đã trôi qua, không phải một thời điểm của đồng hồ thực;
- entropy thực của host — entropy bị cố định sẽ làm ổn định hạt giống băm nội bộ của runtime ngôn ngữ và che giấu tính không tất định của guest thay vì để nó lộ ra dưới dạng đầu ra khác nhau;
- một tên chương trình tổng hợp duy nhất làm argv.
Một lời gọi I/O mà guest thực sự thực hiện — mở một tệp, quay số tới một socket — thất bại tại ranh giới lời gọi. Đây là mô hình bảo mật dựa trên năng lực của chính WASI: sandbox từ chối năng lực thay vì kiểm soát mã.
Đầu vào chỉ đến qua payload và các hàm host được tuyển chọn. Một plugin nhận mọi thứ nó render hoặc đánh giá trong payload mà socket của nó mang theo — các phép chiếu đồ thị và nút, các giá trị, và ngữ cảnh render. Payload đến theo mã hóa nào được cố định cho từng socket và được nêu trong phần riêng của socket đó bên dưới; mỗi kiểu payload được công bố đều đi kèm một điểm vào mã hóa và một điểm vào giải mã cho mã hóa của socket đó, nên guest chỉ gọi một hàm thay vì phải chọn một trình phân tích. Với một lần render provider có nguồn, payload mang một danh sách nguồn thay vì các byte nguồn: một tập đã sắp xếp gồm các mục {path, is_dir} dưới gốc nguồn của nút, không có diễn giải bố cục provider nào từ phía host. Guest áp dụng logic bố cục của riêng nó — chọn tệp compose duy nhất, đi xuống gốc của một chart, yêu cầu một Chart.yaml, vendor một module một cách đệ quy — và đọc lại chính xác phần nó chọn qua một callback của host. Ngoài payload, host gắn một tập hàm host được tuyển chọn, theo nguyên tắc đặc quyền tối thiểu, và chỉ cấp cho plugin đúng những hàm mà tệp nhị phân của nó import:
aggrega_log— một dòng log tới đích log của host.aggrega_emit_warning— một cảnh báo có cấu trúc mà host hiển thị sau lời gọi.aggrega_fetch_external_input— kênh lấy đầu vào bên ngoài (bên dưới).aggrega_pack_source— callback chọn nguồn: guest nêu một lựa chọn{file | dir | tree, path}dưới gốc nguồn và host đọc rồi đóng gói chính xác phần đó trong một sandbox phân giải đường dẫn dưới gốc và từ chối...aggrega_read_source_file— đọc nội dung một tệp đơn trong cùng sandbox đó, phục vụ việc chọn nguồn phụ thuộc vào nội dung.aggrega_parse_source— callback tiêu thụ producer: guest nêu một định dạng cú pháp và chuyển giao các byte nguồn, còn host phân giải một trình phân tích cho định dạng đó, chạy nó và trả về cây chuẩn tắc mà nó tạo ra. Đây là cách một consumer lấy đầu ra của một producer qua host thay vì tự gọi một guest producer, và host giới hạn nó ở một cấp duy nhất — một producer được gọi theo cách này mà lại gọi nó lần nữa sẽ bị từ chối — nên một consumer gọi nó một lần cho mỗi nguồn và có thể tiêu thụ nhiều nguồn lần lượt.
Host suy ra tập hàm mà plugin import từ tệp nhị phân .wasm của nó, kiểm tra tập đó với danh sách cho phép được tuyển chọn, và đối chiếu nó với các hàm host mà describe() của guest khai báo. aggrega plugin sync ghi tập đó vào spec.runtime.hostFunctions của entity, và việc công bố sẽ từ chối một entity có bản ghi khác với tệp nhị phân, nên bề mặt host của mọi plugin đều hiển thị trong catalog và không thể lệch khỏi tệp nhị phân.
Lỗi callback mang một mã có thể so khớp bằng máy, dưới hostfunc_error_code. Các callback host có trả lời — aggrega_fetch_external_input, aggrega_pack_source, aggrega_read_source_file, và callback tiêu thụ producer aggrega_parse_source — truyền lỗi ngay trong kênh: phong bì trả lời mang một thông điệp con người đọc được và, bên cạnh đó, một mã tùy chọn có thể so khớp bằng máy dưới hostfunc_error_code, lấy từ một bộ từ vựng đóng. Thông điệp là văn xuôi tự do dành cho con người; mã là định danh ổn định mà guest dùng để rẽ nhánh mà không cần phân tích thông điệp. Khi thành công thì không có mã; khi thất bại host đặt cả hai. PDK đưa cặp này ra dưới dạng một lỗi có kiểu, với văn bản là thông điệp và trường mã mà guest so khớp với các hằng mã được ngôn ngữ re-export. Guest chấp nhận việc thiếu mã và một mã mà nó không nhận ra bằng cách quay về thông điệp — nên việc so khớp theo mã là một sự tinh chỉnh theo kiểu cố gắng tối đa đặt trên thông điệp luôn có mặt, không bao giờ thay thế nó. Tập giá trị đóng là lược đồ mã lỗi của hàm host.
🔴 Hai bộ từ vựng khác nhau đặt tên cho một lỗi trên ranh giới này, và khóa bạn đọc cho biết bạn đang cầm bộ nào. Nhầm lẫn chúng là lỗi duy nhất đáng nêu ra ở đây, vì một giá trị từ bộ nào cũng là một chuỗi thuần và cả host lẫn guest đều không kiểm tra nó đến từ tập nào.
hostfunc_error_code, trên một trả lời mà host gửi cho guest. Giá trị của nó là một phần tử của danh mục đóng được liên kết ở trên — một danh sách cố định, ít thay đổi, nêu tên các cách một callback host có thể thất bại. Vì tập này đóng, guest có thể so khớp một giá trị với một hằng có tên mà bộ kit của nó re-export và rẽ nhánh theo kết quả.condition_codebên cạnhcondition_short_code, trên một đầu ra socket mà guest trả về cho host. Đây là hai định danh của một điều kiện dừng do chính guest phát sinh, và chúng đến từ tập điều kiện mở, ngày càng tăng mà trình biên dịch đăng ký chứ không phải từ danh mục.condition_codelà mã mô tả mà điều kiện được đăng ký dưới đó;condition_short_codelà dạng rút gọn — chữEvà bốn chữ số — mà người đọc trích dẫn, tìm kiếm và dán vào báo cáo. Host in mã rút gọn trong phần đầu đặt trong ngoặc vuông của chẩn đoán mà nó hiển thị, nên một điều kiện do guest phát sinh có thể được trích dẫn y như một điều kiện do trình biên dịch phát sinh. Host không suy ra giá trị nào, nhưng có kiểm tra chúng: một mã rút gọn không phân giải tới điều kiện nào mà trình biên dịch này khai báo, hoặc tới một điều kiện có số đã bị loại bỏ, sẽ dừng bản build thay vì đến tay người đọc như một định danh không trỏ tới gì.
Hai định danh ở phía guest được báo cáo cùng nhau: một guest đặt định danh này mà không đặt định danh kia là đã nêu một điều kiện mà host không thể phân giải, và khi đó host báo cáo điều kiện lỗi plugin chung của chính nó thay thế, trong khi thông điệp vẫn mang toàn bộ lỗi. Và một condition_code không bao giờ là thành viên của danh mục hàm host, nên việc so sánh nó với một hằng số được tái xuất không bao giờ khớp — đó là lý do mỗi khóa nêu tên bộ từ vựng riêng của nó thay vì lỗi nói chung.
Các slot của mỗi callback mang một mã hóa được nêu rõ, và mọi slot chứa một tài liệu payload đều chứa nó dưới dạng nhị phân. Mọi đối số mà một callback host nhận đều là một con trỏ vào bộ nhớ guest, ngoại trừ mức số của aggrega_log; một callback trả về phản hồi cũng trả lời bằng một con trỏ. Nội dung mỗi slot chứa được cố định theo từng callback:
| Callback | Các slot đối số | Slot phản hồi |
|---|---|---|
aggrega_log, aggrega_emit_warning | Văn bản UTF-8 — không có tài liệu payload | không có phản hồi |
aggrega_fetch_external_input | một URL UTF-8 trần — không có tài liệu payload | CBOR chuẩn tắc |
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_source | CBOR chuẩn tắc (RFC 8949 §4.2.1) | CBOR chuẩn tắc |
Bảng phân chia theo nội dung mà mỗi slot chứa thay vì theo danh tính của callback: một slot chứa tài liệu payload mang CBOR chuẩn tắc, và một slot chứa một chuỗi trần — một dòng log, một trường chẩn đoán, một URL — mang văn bản UTF-8. aggrega_fetch_external_input là callback duy nhất có hai slot khác nhau: đối số của nó là một URL trần, được đọc dưới dạng văn bản UTF-8, và phản hồi của nó là một tài liệu payload ở dạng CBOR chuẩn tắc.
Một guest làm gì tại một slot mang payload, và điều nó không được làm. 🔴 Một slot chứa tài liệu payload chứa một chuỗi byte mờ, không phải văn bản UTF-8 — nên đây là dạng mà guest khai báo, không chỉ là các byte nó đặt vào đó. Một guest cấp phát yêu cầu như vậy dưới dạng chuỗi, hoặc đọc phản hồi như vậy dưới dạng chuỗi, sẽ không tương tác được: một phép chuyển đổi văn bản theo bất kỳ chiều nào cũng làm hỏng các byte nhị phân. Lỗi xảy ra rõ ràng chứ không cục bộ — một yêu cầu mà host không thể giải mã sẽ trả về dưới dạng một phong bì phản hồi mang mã request_undecodable, theo cùng dạng trong băng như mọi lỗi callback khác, nên guest báo cáo nó thay vì tiếp tục với một payload chỉ đọc được một nửa. Các kiểu payload là SourcePackRequest và SourcePackResponse cho aggrega_pack_source, SourceFileRequest và SourceFileResponse cho aggrega_read_source_file, ParseInput và ParseSourceResponse cho aggrega_parse_source, và chỉ riêng kiểu phản hồi FetchExternalInputResponse cho aggrega_fetch_external_input, có URL được cấp phát dưới dạng văn bản. Cụ thể, theo từng kit:
- Go — xây dựng yêu cầu bằng
EncodeCBOR()của kiểu yêu cầu, cấp phát nó bằngpdk.AllocateBytes(không phảipdk.AllocateString), và đọc phản hồi bằngReadBytes()trên vùng bộ nhớ mà con trỏ phản hồi trỏ tới, đưa vàoDecodeCBORcủa kiểu phản hồi. URL fetch là ngoại lệ ở phía yêu cầu, được cấp phát bằngpdk.AllocateString; phản hồi của nó được đọc như mọi phản hồi khác. Khai báo//go:wasmimportdù sao cũng là một con trỏ, nên không có gì trong chữ ký cho thấy dạng dữ liệu — việc cấp phát và việc đọc mới là nơi nó thể hiện. - Rust — khai báo
#[host_fn]nêu trực tiếp dạng dữ liệu: mỗi callback trong ba callback payload có dạngfn <callback>(request: Vec<u8>) -> Vec<u8>;, và callback fetch có dạngfn aggrega_fetch_external_input(url: String) -> Vec<u8>;. Xây dựng yêu cầu bằngencode_cbor()của kiểu yêu cầu và đọc phản hồi bằngdecode_cbor(&raw)của kiểu phản hồi. - TypeScript — xây dựng yêu cầu bằng hàm
encodeCBOR…của kiểu yêu cầu, cấp phát nó bằngMemory.fromBuffer(không phảiMemory.fromString), và đọc phản hồi bằngreadBytes()đưa vào hàmdecodeCBOR…của kiểu phản hồi. URL fetch được cấp phát bằngMemory.fromString; phản hồi của nó được đọc bằngreadBytes()như các phản hồi khác. Giống như trong Go, mụcdeclare moduledù sao cũng là một con trỏ.
Một guest gọi một wrapper của PDK không cần làm điều nào trong số đó. Các wrapper — FetchExternalInput, PackSource, ReadSourceFile và ParseSource, theo cách viết riêng của mỗi ngôn ngữ — thực hiện việc cấp phát và mã hóa, và không chữ ký nào của chúng nêu tên một kiểu wire, nên một guest truy cập các callback này qua kit của nó không tự cấp phát hay giải mã gì cả; một guest tự khai báo và gọi các hàm host thì cấp phát và đọc bộ nhớ của nó như mô tả ở trên. Một yêu cầu được cấp phát dưới dạng văn bản sẽ bị từ chối thay vì được phục vụ nửa vời, và một phản hồi được đọc dưới dạng văn bản sẽ không thể giải mã, nên sự không khớp giữa hai phía sẽ lộ rõ thay vì diễn ra lặng lẽ.
Có hai thuộc tính đáng để dựa vào. Phản hồi mang cùng một mã hóa dù thành công hay thất bại: một guest đọc một slot và không thể biết trước khi giải mã slot đó chứa trường hợp nào, nên một điểm vào giải mã đọc được cả hai, và mã lỗi cùng thông điệp mô tả ở trên đến qua nó. Và một guest điền một trường có giá trị byte bằng kiểu trường riêng của kit nó — một byte slice trong Go, một chuỗi base64 trong Rust và TypeScript — vì việc chuyển đổi sang chuỗi byte thô mà mã hóa nhị phân mang là công việc của bộ mã hóa được sinh ra, được thực hiện khi xuất và đảo ngược khi nhập. Điều đó bao gồm các byte nguồn của ParseInput, nội dung tệp mà aggrega_read_source_file trả về, nội dung mà aggrega_fetch_external_input đã fetch, và nội dung của từng tệp được đóng gói trong một phản hồi pack-source: các byte đó đi qua ranh giới một lần thay vì bị mã hóa hai lần, và không guest nào base64 thứ mà bộ mã hóa sắp giải base64. Trường content của các phản hồi read-source-file và fetch bị lược bỏ khi nó rỗng, nên phản hồi cho một tệp rỗng hoặc một payload fetch có độ dài bằng không hoàn toàn không mang nội dung; một phản hồi như vậy vẫn là thành công, vì một lỗi luôn mang thông điệp và mã của nó, và wrapper của mỗi kit trả về byte rỗng cho trường hợp đó. Cây mà aggrega_parse_source trả về được truyền dưới dạng một chuỗi byte chứa nguyên văn tài liệu JSON của chính nó; host không đọc cũng không định hình lại nó. Một parser đọc cùng ParseInput, theo cùng mã hóa, trên export parse của chính nó — xem socket parser.
Chuẩn tắc có nghĩa là đầu vào giống hệt nhau tạo ra các byte giống hệt nhau ở mọi phía, đó là điều cho phép một payload được so sánh giữa ba kit plugin thay vì chỉ được chuyển đi chuyển lại, và đó là lý do đầu ra của một bản build luôn giống hệt nhau đến từng byte. Không cần thư viện CBOR nào trong guest và không có gì phân tích byte thủ công: mỗi kiểu payload được công bố đều đi kèm các điểm vào mã hóa và giải mã mà mã hóa của slot đó cần.
Tính tất định là trách nhiệm của tác giả plugin. Host tiêu thụ nguyên văn các byte đầu ra của guest và không chạy bộ tuần tự hóa nào trên chúng, nên hợp đồng mà mọi plugin phải tuân thủ là: đầu vào giống hệt nhau tạo ra các byte đầu ra giống hệt nhau. Sandbox loại bỏ các nguồn bất định từ môi trường xung quanh — thời gian thực, biến môi trường, trạng thái hệ thống tệp — nhưng cố ý không che giấu phần còn lại: một guest mã hóa entropy hoặc thời gian đơn điệu đã trôi qua vào đầu ra của nó sẽ tạo ra các byte khác nhau rõ ràng giữa các lần chạy thay vì một lỗi bị ẩn đi một cách ổn định.
Kênh fetch đầu vào bên ngoài. aggrega_fetch_external_input là kênh duy nhất được chấp thuận cho nội dung từ xa, và nó do host làm trung gian, không phải là quyền truy cập mạng của guest: guest nêu một URL, và host phục vụ các byte 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 với digest đã ghi; một URL chưa được ghim bị từ chối kèm một chẩn đoán nêu tên URL và bước ghim nó, vì một lần render tiêu thụ bao đóng mà lockfile của nó ghi lại và không bao giờ mở rộng nó. Các ghim được ghi khi các phụ thuộc của Release được phân giải, đó là thời điểm duy nhất bất cứ thứ gì được ghim. Hướng dẫn cho nhà phát triển trình bày đầy đủ cách viết và kỷ luật ghim.
Các map giữ nguyên thứ tự
Một số map mà payload mang theo được đánh dấu là giữ nguyên thứ tự trong schema của socket tương ứng, vì thứ tự các mục của chúng là một phần của nội dung chúng mang: các node của một bản build, các nhãn của một node, các attachment trên một node, các đầu vào và đầu ra của một bước pipeline, các không gian khóa mà một provider khai báo. Các kiểu payload được công bố lưu mỗi map như vậy trong một container giữ các mục theo đúng thứ tự chúng được đặt:
| Kit | Container |
|---|---|
| Go | aggrega.OrderedMap[V] — tên mà kit dùng cho abi.OrderedMap[V] của gói ABI |
| Rust | OrderedMap<V> từ crate aggrega-abi, được kit tái xuất |
| TypeScript | Map<string, V> có sẵn của ngôn ngữ |
Các container của Go và Rust có các thao tác của một map — tra cứu một khóa, đặt khóa, xóa khóa, đọc các khóa, duyệt các mục theo thứ tự, đếm chúng. Đặt một khóa mà container đã có sẽ thay thế giá trị của nó và giữ nguyên vị trí; một khóa mới được đặt sau mọi khóa hiện có.
Thứ tự được giữ qua cả hai cách mã hóa. Ở mã hóa nhị phân, một map được đánh dấu được ghi dưới dạng một danh sách có thứ tự các mục — mỗi mục là một danh sách hai phần tử, khóa rồi đến giá trị — theo thứ tự của container, trong khi mã hóa chuẩn tắc lẽ ra sẽ ghi map với các khóa được sắp xếp. Ở mã hóa văn bản, nó là một đối tượng JSON có các thành viên được ghi theo thứ tự của container. Bộ giải mã ở cả hai cách mã hóa đều từ chối một map lặp lại khóa, và nêu tên khóa đó. Một map mà schema không đánh dấu giữ dạng map được sắp xếp ở mã hóa nhị phân và dùng kiểu map thông thường của ngôn ngữ trong các kiểu được công bố.
Ba hệ quả đối với một guest:
- Thứ tự là một phần của đầu ra. Vì một map được đánh dấu được ghi theo thứ tự nó được điền, một guest điền map từ một nguồn không có thứ tự cố định — chẳng hạn duyệt một map dựng sẵn của Go — sẽ ghi ra các byte khác nhau giữa các lần chạy với cùng đầu vào. Hãy điền map theo một thứ tự cố định.
- Thứ tự chỉ được giữ khi map còn nằm trong container của nó. Một guest chuyển payload sang một kiểu giá trị tổng quát của ngôn ngữ mình sẽ nhận thứ tự của kiểu đó:
map[string]anycủa Go không có thứ tự, vàserde_json::Valuecủa Rust giữ các khóa đối tượng được sắp xếp trừ khi crate được build với tính năngpreserve_ordercủa nó. - Trong TypeScript, hãy đọc và ghi thông qua các hàm được sinh ra. Một kiểu chứa map được đánh dấu sẽ giải mã JSON của nó theo từng thành viên, nên một khóa trông như chỉ số mảng, chẳng hạn
"8080", vẫn giữ vị trí của nó, trong khiJSON.parsesẽ chuyển nó lên đầu đối tượng; và bộ mã hóa của nó ghi mỗiMapthành một đối tượng, trong khiJSON.stringifyghi mộtMapthành{}.Object.keyscủa mộtMapcũng rỗng: hãy đọc các khóa của mộtMapbằngkeys()của chính nó.
Các giá trị được đầu vào đánh dấu là nhạy cảm
Một plugin không bao giờ trích dẫn, trong một lời từ chối hay một cảnh báo mà nó trả về, một giá trị mà đầu vào của nó đánh dấu là nhạy cảm — theo khóa của giá trị đó, hoặc như một phần của một payload được đánh dấu toàn bộ. Một lời từ chối là error mà một đầu ra mang theo; một cảnh báo là một Diagnostic mà đầu ra mang theo, bất kể mức độ nghiêm trọng của nó, hoặc một cảnh báo được phát qua aggrega_emit_warning. Host truyền văn bản đó nguyên vẹn ở bất cứ nơi nào nó báo cáo — dòng lệnh, language server và danh sách vấn đề của trình soạn thảo, các công cụ trợ lý — và không đọc giá trị nào từ đó, nên plugin là bên duy nhất có thể giữ giá trị không bị lộ ra. Thay vào đó, hãy nêu tên khóa, thiết lập hoặc vị trí: người đọc sẽ tìm ra giá trị từ đó.
Quy tắc này bao gồm văn bản mà một thư viện viết thay cho plugin cũng như văn bản do chính plugin viết. Một template engine báo cáo dữ liệu mà nó đang đánh giá, một trình xác thực schema trích dẫn một giá trị không khớp một pattern, một parser trích dẫn token mà nó không đọc được. Khi một lỗi như vậy xảy ra trên một giá trị mà đầu vào đánh dấu, hãy báo cáo lỗi mà không kèm giá trị — chẳng hạn, chạy lại cùng bước đó với mọi giá trị được đánh dấu thay bằng một placeholder, báo cáo lỗi của lần chạy đó khi nó thất bại ở cùng vị trí, và nếu không thì nói rằng văn bản lỗi được giữ lại. Trong một payload được đánh dấu toàn bộ, mọi giá trị trong payload đó là một giá trị được đánh dấu, còn các khóa của nó — hình dạng của tài liệu — vẫn đọc được.
Nơi một đầu vào đánh dấu một khóa hoặc một payload là nhạy cảm, viết theo cách wire đặt tên:
| Socket và export | Nơi đọc việc đánh dấu |
|---|---|
provider render_node và validate_node_input (RenderNodeInput) | node.sensitive_rendered_keys: mỗi khóa chỉ tới một mục của node.values khi các giá trị đó là của chính Component, được đặt khóa theo các lá mà nó khai báo — valuesMapping của một Recipe viết các khóa mà không khai báo nào nêu tên, nên không khóa nào trong số đó được đánh dấu ở đây — hoặc một mục của map attachments của một container workload đọc một slot được khai báo là nhạy cảm. node.sensitive_values đánh dấu toàn bộ node.values: nó là true khi một valuesMapping — của Recipe, hoặc của FeatureRecipe của một attachment — tạo ra các giá trị đó và đọc một giá trị mà tác giả đã khai báo là nhạy cảm. workload_projection.sensitive_workload đánh dấu mọi giá trị của workload theo cùng cách khi template của workload đọc một giá trị như vậy, và mỗi mục của artifacts_projection.entries mang sensitive_content cho nội dung riêng của nó, kể cả thông báo của một parser về nội dung đó. Mỗi mục của omits mang sensitive khi template tạo ra bất kỳ kind, name hay namespace nào của nó đọc một giá trị như vậy, và khi đó mọi trường của mục đó là một giá trị được đánh dấu. Mỗi mục của node.features mang việc đánh dấu của chính attachment của nó: sensitive_payload_leaves (các lá values.<path> và infra.<path> mà Feature của nó khai báo là nhạy cảm), sensitive_inject (các khóa phân phối inject đọc một khóa provides mà Feature của nó khai báo là nhạy cảm) và sensitive (attachment có xử lý dữ liệu được khai báo là nhạy cảm hay không). |
governance ir-verdict (PolicyInput) | graph: sensitive_payload_leaves của mỗi node, và sensitive_payload_leaves, sensitive_inject và sensitive của mỗi attachment. Mọi giá trị mà các đánh dấu đó nêu tên đều đã đến dưới dạng dấu giữ lại {"aggrega_withheld": "declared"}, nên bản thân giá trị không bao giờ tới được plugin. |
Không đầu vào socket nào khác, và không đầu vào của export provider nào khác, mang đánh dấu. Một đánh dấu khóa chỉ nêu tên những gì nó nối chính xác với một khai báo, nên việc thiếu một khóa không bao giờ có nghĩa là một giá trị an toàn để trích dẫn: nó có nghĩa là không khai báo nào có thể nối với khóa đó. Một đánh dấu payload được đọc từ các tham chiếu của template đã tạo ra payload — một tham chiếu tới một giá trị đã khai báo, template chuyển tiếp toàn bộ dữ liệu của nó, hoặc một template không parse được — và không bao giờ từ một giá trị, nên việc thiếu nó có nghĩa là template đó không đọc giá trị đã khai báo nào theo những gì các tham chiếu của nó cho thấy, hoặc không template nào tạo ra payload; đó không phải là khẳng định rằng payload không mang gì nhạy cảm.
Vị trí của các socket Wasm trong pipeline
Pipeline biên dịch dành sẵn các điểm socket sau. Các nhãn hình dạng tuân theo hệ phân loại bốn nhãn từ trang Status.
| Socket | Vị trí trong pipeline | Trạng thái hiện nay |
|---|---|---|
Socket quản trị, vai trò annotation-transform | Phân giải (trước khi mở rộng annotation) | khả dụng — được gọi khi một workspace gắn một plugin annotation-transform; chèn các annotation mà bước mở rộng biến thành các attachment Feature |
Socket quản trị, vai trò label-transform | Xây dựng topology (Topology Builder) | khả dụng — được gọi khi một workspace gắn một plugin label-transform; tự động gắn nhãn cho node qua JSON Patch |
Socket quản trị, vai trò ir-verdict | Phân tích tĩnh (Static Analyzer, trên đồ thị IR) | khả dụng — được gọi khi một workspace gắn một plugin ir-verdict; một phán quyết halt dừng bản build |
Socket quản trị, vai trò render-verdict | Render (trên các artifact đã render) | khả dụng — được gọi khi một workspace gắn một plugin render-verdict; một phán quyết halt dừng bản build |
Các plugin pipeline: của FeatureRecipe và Recipe | Pipeline plugin (biến đổi sau render) | khả dụng — mỗi bước được khai báo chạy trên tập tài liệu đã render, áp dụng các bản vá RFC 6902 và phát sinh các hiệu ứng phụ |
| Các plugin render của Provider (helm, helm-chart, compose, terraform, cloudformation) | Render cơ sở (các provider) | khả dụng — mọi provider render thông qua guest Wasm của nó; việc render chỉ dùng Wasm, không có trình render dự phòng trong host |
Các plugin parser (parse:<format>) | Render, cho một policy render-verdict; và ngoài luồng, cho một lần nhập | khả dụng — được gọi cho một artifact ở định dạng mà policy render-verdict không đọc nguyên bản, cho một importer thông qua aggrega_parse_source, và để nhận diện định dạng của một lần nhập không nêu định dạng nào |
Các plugin importer (import:<format>) | Ngoài luồng (aggrega import) | khả dụng — được điều phối bởi aggrega import, phiên trình soạn thảo và công cụ dành cho trợ lý |
Các plugin linter (linter/publishing) | Ngoài luồng (aggrega lint) | khả dụng — publishing-linter được phát hành kèm và chạy thông qua host bằng aggrega lint |
Giai đoạn con mở rộng Feature dựa trên annotation, một phần của bước phân giải, là một lượt pipeline Go gốc, không phải một socket Wasm. Nó kiểm tra giá trị annotation theo spec.schema của Feature đích và chèn các attachment Feature tổng hợp tại thời điểm build IR. Xem vocabulary/labels-and-annotations.md về sáu bề mặt mang annotation và nhãn, và providers/well-known-annotations.md về hình dạng binding và hướng dẫn soạn thảo.
Hợp đồng hình dạng đầu ra — những gì hiện có
Socket quản trị mang một bề mặt hợp đồng có kiểu tại mỗi vai trò trong bốn vai trò của nó, và vai trò quyết định đó là bề mặt nào. Các tác giả Plugin triển khai mã phía guest tạo ra các dạng được mô tả trong tài liệu; host đọc chúng tại thời điểm build, một lần cho mỗi plugin được cấu hình, khi một workspace gắn một plugin vào vai trò đó. Các tiểu mục dưới đây theo thứ tự mà pipeline điều phối chúng.
Vai trò annotation-transform — đầu ra chèn annotation
Vị trí trong pipeline. Giai đoạn phân giải, sau khi các component được phân giải và trước khi bước mở rộng Feature dựa trên annotation chạy.
Hình dạng đầu vào (host → guest). Một tài liệu AnnotationTransformInput mang:
targets— các đích chèn: các component đã phân giải mà guest có thể gắn annotation — những component mà một boundary nêu trực tiếp, và mọi component mà một mục định tuyến dướiaggregates:của boundary định tuyến vào, dù mục đó có nêu tên nó hay không — mỗi đích mangboundary_path,component_namecủa nó (với một component được định tuyến, đó là id có dấu chấm của nó trong đồ thị build, chẳng hạnmetrics.query) và cácannotationsmà Release viết trên nó, để guest có thể quyết định thêm gì mà không thay thế một giá trị do tác giả viết. Mỗi giá trị annotation đến đúng như được viết — một chuỗi, một đối tượng gồm các khóa con, hoặcnullkhi component từ chối một annotation mà nó lẽ ra sẽ kế thừa — và mọi khóa mà component mang đều có mặt bất kể giá trị của nó. Được host sắp xếp một cách tất định.binding_keys— các khóa annotation mà Manifest đăng ký một binding, theo thứ tự của tác giả. Một lần chèn dưới một khóa đã đăng ký sẽ tiếp tục được mở rộng thành một Feature attachment, vì vậy guest đọc danh sách này để chèn các khóa sẽ có hiệu lực. Host không yêu cầu một lần chèn phải dùng một khóa đã đăng ký: một annotation được chèn mà chưa đăng ký hoạt động đúng như một annotation không có binding do tác giả viết.sources— các tệp định nghĩa mà attachment đã khai báo dướiwith.sources, mỗi tệp mang đường dẫn tên gốc và nội dung của nó, được sắp xếp theo đường dẫn.settings— đối tượng cài đặt dạng tự do mà attachment đã khai báo dướiwith.settings, được chuyển nguyên văn cho guest.
settings và sources là cùng một kênh with không phụ thuộc vào engine mà mọi vai trò khác đều đọc, và cả hai đều vắng mặt khi attachment không khai báo gì. Vì đầu ra của vai trò này định hình bản build, các cài đặt và nội dung nguồn của attachment được ghim trong release lockfile khi pull và được tái tạo từ đó khi build.
Hình dạng đầu ra (guest → host). Một tài liệu AnnotationTransformOutput mang:
injections— các annotation cần thêm, theo thứ tự. Mỗi mục nêu một tọa độ đích hiện có (boundary_pathvàcomponent_name) cùng vớiannotation_keyvàannotation_valuecủa nó: một chuỗi, hoặc một đối tượng gồm các khóa con, cung cấp cho một binding định tuyến nhiều khóa con cùng lúc.
Host chỉ áp dụng các bổ sung annotation, chỉ vào các tọa độ mà nó cung cấp, mỗi mục với một giá trị mà tác giả có thể viết trên annotation đó. Nó đọc một giá trị được chèn đúng như cách nó đọc cùng giá trị đó khi được viết trong Release — các khóa con của một đối tượng theo thứ tự guest đã viết — nên quá trình mở rộng gặp nó giống như gặp một annotation do tác giả viết. Một lần chèn nêu một tọa độ mà payload không mang, hoặc mang null, một danh sách, một số, một boolean hay một đối tượng không có khóa con, sẽ dừng bản build với một thông điệp nêu tọa độ và annotation, thay vì bị bỏ qua hay áp dụng một cách lặng lẽ; toàn bộ đầu ra được kiểm tra trước khi bất kỳ phần nào được áp dụng. Chính sự giới hạn đó định ra phạm vi của vai trò: một operator gắn plugin ở đây đã khai báo việc chèn annotation và không gì hơn. Khi bản build sau đó từ chối một annotation được chèn vì cách nó định tuyến, vì một giá trị khóa con mà schema của Feature được gắn không chấp nhận, hoặc vì một trụ cột mà annotation phía Release không được dùng, thông điệp của nó nêu tên plugin đã chèn annotation và vai trò mà plugin được gắn.
Mã hóa truyền tải. Payload và kết quả của vai trò này được truyền dưới dạng CBOR chuẩn tắc (RFC 8949 §4.2.1), theo cả hai chiều. Guest đọc và ghi nó thông qua các điểm vào mà các kiểu payload mang — DecodeCBOR và EncodeCBOR trong Go, decode_cbor và encode_cbor trong Rust, decodeCBORAnnotationTransformInput và encodeCBORAnnotationTransformOutput trong TypeScript — nên không cần thư viện CBOR nào và không có gì phải tự phân tích byte. Trong Rust, export nhận và trả về Vec<u8>; trong TypeScript, nó đọc Host.inputBytes() và ghi Host.outputBytes(...). annotations của mỗi đích là một map mà schema đánh dấu là giữ thứ tự, nên nó được truyền dưới dạng một danh sách mục có thứ tự theo thứ tự mà đích lưu giữ, và guest đọc nó qua container giữ thứ tự của kit của mình; mỗi giá trị được truyền dưới dạng các byte JSON của nó, giống như annotation_value của một lần chèn theo chiều ngược lại. settings được truyền dưới dạng các byte của tài liệu JSON của nó, mà guest phân tích như JSON để xem bên trong. Một câu trả lời không phải là một AnnotationTransformOutput trong cách mã hóa này — một câu trả lời được viết bằng JSON, hoặc mang một trường cấp cao nhất mà hình dạng không khai báo — sẽ dừng bản build, nêu tên plugin và export của nó, thay vì được đọc như một danh sách chèn rỗng. Khi được gọi trực tiếp bằng aggrega plugin run-local --export transform_annotations, guest nhận payload JSON do tác giả viết đã được chuyển sang cách mã hóa này, và câu trả lời của nó được đọc theo hình dạng đầu ra của export và in ra dưới dạng JSON — một câu trả lời không có hình dạng đó sẽ bị từ chối, nêu tên export, giống như một bản build từ chối nó.
Định nghĩa kiểu. Các kiểu truyền tải annotation-transform — AnnotationTransformInput, AnnotationTransformOutput, AnnotationTarget, AnnotationInjection, AnnotationSource — được công bố trong cả ba gói ABI, được sinh ra từ một codec duy nhất để cả ba luôn đồng bộ.
Vai trò label-transform — đầu ra JSONPatch
Vị trí trong pipeline. Bước xây dựng topology, sau khi đồ thị được làm phẳng và trước khi đồ thị IR được xây dựng, nên các bộ chọn socket và Feature mà bộ phân tích đánh giá sẽ đọc các nhãn mà vai trò này để lại.
Dạng đầu vào (host → guest). Một tài liệu MutatorInput mang:
compilation_context— định danh của release (release_name,environment).graph— một phép chiếuMutatorGraphgồm các nút topology: Component của mỗi nút, phiên bản đã phân giải, các nhãn, và cácvaluesmà instance của nó khai báo.settings— đối tượng cài đặt dạng tự do mà attachment đã khai báo dướiwith.settings, được chuyển nguyên văn cho guest.sources— các tệp định nghĩa mà phần đính kèm khai báo dướiwith.sources, mỗi tệp mang đường dẫn dạng tên cơ sở và nội dung, để một mutator có thể được điều khiển bởi một tệp quy tắc hoặc tệp ánh xạ được đưa vào kho mã thay vì các thiết lập nội tuyến.
Đồ thị là một phép chiếu chứ không phải đồ thị IR: mỗi nút mang tập nhãn đã phân giải của nó và các giá trị mà instance của nó khai báo trong Aggregate, còn các cạnh và payload feature nằm lại bên trong trình biên dịch. Các giá trị là của chính Aggregate, với các template đã được đánh giá theo tham số của nó, nên một giá trị được đưa lên thành tham số sẽ đến dưới dạng giá trị mà Release cung cấp; một giá trị mặc định mà schema của Component khai báo, và bất cứ thứ gì một Recipe hay một Feature đóng góp, đều không nằm trong số đó, và một nút không khai báo giá trị nào thì không mang khóa values. Một giá trị mà Component của nút khai báo là nhạy cảm sẽ bị giữ lại đúng như cách phán quyết trên đồ thị giữ lại nó — nó được đọc là {"aggrega_withheld": "declared"} — còn mọi giá trị anh em mà không khai báo nào chạm tới đều đến đúng như được viết. Đó là điều cho phép một cấu hình mà nhà phát triển khai báo quyết định một nhãn — chẳng hạn một cơ sở dữ liệu có giá trị bật một phần mở rộng vector được nâng lên datastore.aggrega.ai/engine: vector. settings và sources là cùng một kênh with không phụ thuộc vào engine mà các vai trò phán quyết đọc; host chuyển chúng qua và không bao giờ diễn giải nội dung của chúng. Vì đầu ra của một mutator định hình bản build, các thiết lập và nội dung nguồn của phần đính kèm được ghim trong lockfile của release khi pull và được dựng lại từ đó khi build, nên đầu vào của mutator không đổi trước một thay đổi sau khi pull ở bất kỳ thứ nào trong hai thứ đó cho đến lần pull tiếp theo.
Dạng đầu ra (guest → host). Một tài liệu MutatorOutput mang:
patches— một mảng các tài liệu JSONPatch mờ (RFC 6902) mà host chỉ áp dụng lên nhãn của các nút; các giá trị mà đầu vào mang là chỉ đọc.
Mỗi patch trỏ tới nhãn của một nút cụ thể thông qua JSON Pointer (RFC 6901); host áp dụng các patch theo thứ tự trong mảng và nạp lại tập nhãn đã biến đổi vào đồ thị IR. Nhiệm vụ của vai trò label-transform là tự động gắn thẻ cho doanh nghiệp — thêm các nhãn tuân thủ / khả năng quan sát / phân bổ chi phí do chính sách doanh nghiệp khai báo mà không sửa đổi nội dung catalog. Bề mặt nhãn là đích duy nhất được phép của vai trò này: một patch chạm vào một trường của nút khác với nhãn của nó, thêm hoặc xóa một nút, hoặc đặt một giá trị nhãn không phải chuỗi sẽ dừng bản build thay vì bị hấp thụ một cách âm thầm. RFC 6901 là chuẩn cơ sở về ngữ pháp đường dẫn cho mọi bề mặt đường dẫn tài liệu trong Aggrega — hợp đồng Wasm plugin ở đây, cùng các export *_path của .locals, cùng các trường schema *Path ở những nơi khác trong tài liệu. Xem 02-naming-conventions.md “Document-path naming-suffix discipline” để biết khai báo chuẩn cơ sở chính thức và kỷ luật hậu tố *Path / *_path phân biệt hai phía soạn thảo.
Mã hóa trên đường truyền. Payload và kết quả của vai trò này được truyền dưới dạng canonical CBOR (RFC 8949 §4.2.1), theo cả hai chiều. Canonical có nghĩa là đầu vào giống nhau tạo ra các byte giống nhau ở mọi phía, đó là điều cho phép so sánh một payload giữa ba bộ kit plugin thay vì chỉ chuyển đi chuyển lại, và đó là lý do đầu ra của một bản build giữ nguyên từng byte. Một guest đọc và ghi nó thông qua các điểm vào mà kiểu payload của kit đã mang sẵn — DecodeCBOR và EncodeCBOR trong Go, decode_cbor và encode_cbor trong Rust, decodeCBORMutatorInput và encodeCBORMutatorOutput trong TypeScript — nên không cần thư viện CBOR nào và không có gì phải tự phân tích byte. Trong Rust, export nhận và trả về Vec<u8>; trong TypeScript, nó đọc Host.inputBytes() và ghi Host.outputBytes(...). nodes của đồ thị, labels của mỗi nút và values của mỗi nút là các map mà schema đánh dấu là giữ thứ tự, nên chúng được truyền dưới dạng danh sách mục có thứ tự — các nút theo thứ tự bản build giữ chúng, tức thứ tự của tác giả, nhãn của mỗi nút theo thứ tự nút mang chúng, và giá trị của mỗi nút theo thứ tự Aggregate viết chúng — và một guest đọc cả ba thông qua container giữ thứ tự của kit. Mỗi giá trị được truyền dưới dạng các byte của tài liệu JSON của nó: kit Go và Rust giao nó cho guest dưới dạng JSON đó, để phân tích đến mức một quy tắc cần, còn kit TypeScript giao dưới dạng giá trị đã phân tích.
Có hai điều mà việc này không thay đổi. Mảng patches vẫn là JSON: socket mang nguyên văn mỗi tài liệu patch như nội dung mờ và không phía nào đọc vào bên trong, nên dạng của bản thân tài liệu patch độc lập với mã hóa mà socket của nó mang. Và settings cùng sources vẫn được chuyển qua nguyên văn — settings đến dưới dạng các byte mà phần đính kèm đã soạn, mà một guest phân tích như JSON nếu cần xem bên trong.
Mọi vai trò quản trị khác đều mang cùng mã hóa này — vai trò annotation-transform và hai vai trò phán quyết đều nói như vậy trong phần riêng của chúng — nên một guest phục vụ nhiều hơn một vai trò sẽ dùng canonical CBOR ở mọi vai trò nó phục vụ, đọc mỗi payload thông qua điểm vào giải mã của kiểu riêng của payload đó.
Định nghĩa kiểu. Các kiểu đường truyền của mutator — MutatorInput, MutatorOutput, CompilationContext, MutatorGraph, MutatorNode — được công bố trong cả ba gói ABI (github.com/aggrega-ai/aggrega-abi/go, crate aggrega-abi, và @aggrega-ai/aggrega-abi), được sinh từ một codec duy nhất để ba gói luôn đồng bộ. Host lắp ráp đầu vào và áp dụng các patch mà guest trả về.
Các vai trò verdict — đầu ra mảng verdict
Một guest chính sách kiểm tra một bản build và trả về một danh sách verdict; host hành động theo mức độ nghiêm trọng của từng verdict và không bao giờ tự diễn giải chính sách. Phần trình bày đầy đủ — bốn vai trò, các mức độ nghiêm trọng, kênh đầu vào do người vận hành cung cấp, 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, cách bọc một engine chính sách bên ngoài, các guest tham chiếu, và cách người vận hành gắn một chính sách — nằm ở trang governance socket. Phần này ghi lại vị trí trong pipeline và các dạng wire có kiểu.
Vị trí trong pipeline. Một chính sách được gắn ở đúng một vai trò verdict, điều này cố định nơi nó được đánh giá:
ir-verdict— được đánh giá ở bước phân tích tĩnh, trước khi render cơ sở. Bộ phân tích lắp ráp payload trong mọi bản build.render-verdict— được đánh giá sau khi render, trên các artifact đã xuất ra.
Khi một workspace gắn một plugin vai trò verdict, pipeline marshal payload của vai trò đó tới plugin và đọc lại các verdict của nó.
Dạng đầu vào (host → guest). Vai trò quyết định payload:
PolicyInputcủair-verdictmanggraph— toàn bộ đồ thị IR không phụ thuộc vào capability (cùng dạng mà Topology Builder xuất ra), với mọi chi tiết về node, cạnh và attachment mà trình biên dịch nắm giữ, ngoại trừ việc một giá trị mà tác giả khai báo là nhạy cảm sẽ đến ở dạng bị giữ lại (xem Các giá trị mà đầu vào đánh dấu là nhạy cảm) — vàprecalculated_paths, các đường định tuyến mà bộ phân tích liệt kê kèm theo, để một chính sách có thể suy luận về khả năng tiếp cận mà không phải duyệt lại đồ thị. Đồ thị là đồ thị IR có phiên bản, lấy nguồn duy nhất từ schemair-v1beta1; dạng IR không phải bí mật (đó là cùng đồ thị màaggrega inspectxuất ra) và các secret trong đó là con trỏ, không bao giờ là bản rõ.RenderPolicyInputcủarender-verdictmangartifacts— các tệp đầu ra đã render được sắp xếp theo đường dẫn, để wire giống hệt nhau từng byte giữa các lần chạy với cùng đầu vào. Mỗi mục mangpathđầu ra của artifact vàcontentđã render của nó; nó cũng mangformatmà nó được render theo, khi provider tạo ra nó có khai báo, và mộttree, khung nhìn chuẩn tắc đã phân tích của một định dạng mà guest không đọc trực tiếp, được host phân tích qua parser đã phân giải và chuyển tiếp nguyên trạng. Cả hai đều vắng mặt khi không áp dụng — một định dạng mà guest đọc trực tiếp (JSON, YAML) được để nguyên không phân tích để guest đọc từcontent.
Cả hai vai trò còn mang thêm sources của attachment (các tệp định nghĩa chính sách mà host đọc lúc build và giao nguyên văn cho guest, đường dẫn là tên cơ sở, nội dung không được diễn giải) và settings (một object dạng tự do được chuyển qua không thay đổi). Cả hai đều vắng mặt khi attachment không khai báo gì.
Dạng đầu ra (guest → host). Một tài liệu PolicyOutput mang:
results— một mảng các mụcDiagnostic, mỗi mục có mộtseverity(halt,warnhoặcinfo) và một chuỗimessage. Một verdict cũng có thể đặtcode,rule_id,classification,source_ref,locationvàsuggesttrên cùng mục đó; host nối thêm bất kỳ trường nào trong số đó mà verdict mang vào verdict đã render, trên mọi tuyến mức độ nghiêm trọng.
Chỉ các verdict được kích hoạt mới xuất hiện; một lần đánh giá cho phép trả về một mảng rỗng. Host duyệt các verdict và ánh xạ mỗi mức độ nghiêm trọng thành một hành động: halt dừng bản build (hiển thị mọi thông điệp halt), warn đánh dấu verdict và để bản build tiếp tục, info ghi lại nó mà không ảnh hưởng đến kết quả. Một halt dừng qua cùng cổng mà một vi phạm selector hoặc appliesTo sử dụng.
Mã hóa wire. Payload của cả hai vai trò, và PolicyOutput mà guest trả về ở vai trò nào cũng vậy, đều được truyền dưới dạng canonical CBOR (RFC 8949 §4.2.1). Guest đọc và ghi chúng qua các điểm vào mà các kiểu payload mang — DecodeCBOR và EncodeCBOR trong Go, decode_cbor và encode_cbor trong Rust, decodeCBORPolicyInput, decodeCBORRenderPolicyInput và encodeCBORPolicyOutput trong TypeScript — nên không cần thư viện CBOR nào và không có gì phải tự phân tích byte. Trong Rust mỗi export nhận và trả về Vec<u8>; trong TypeScript nó đọc Host.inputBytes() và ghi Host.outputBytes(...). Các map giữ thứ tự của đồ thị, trong đó có nodes và labels của mỗi node, được truyền dưới dạng danh sách mục có thứ tự theo thứ tự mà bản build nắm giữ, và guest đọc chúng qua container giữ thứ tự của kit của nó; thứ tự mà một chính sách gặp chúng dưới mỗi engine chính sách được trình bày ở trang governance socket. settings, và tree đã phân tích của một artifact, được truyền dưới dạng byte của tài liệu JSON tương ứng, mà guest phân tích như JSON để xem bên trong. Một câu trả lời không phải là PolicyOutput theo mã hóa này — một câu trả lời viết bằng JSON, hoặc mang một trường cấp cao nhất mà dạng không khai báo — sẽ dừng bản build, nêu tên plugin và export của nó, thay vì được đọc như một danh sách verdict rỗng. Khi được gọi trực tiếp bằng aggrega plugin run-local --export verdict_ir hoặc --export verdict_render, guest được giao payload JSON đã soạn, được chuyển sang mã hóa này, và câu trả lời của nó được đọc theo dạng đầu ra của export và in ra dưới dạng JSON — một câu trả lời không có dạng đó sẽ bị từ chối, nêu tên export, giống như một bản build từ chối nó.
Định nghĩa kiểu. Các kiểu wire chính sách được công bố trong cùng ba gói ABI: PolicyInput (vai trò ir-verdict), RenderPolicyInput (vai trò render-verdict), PolicySource dùng chung, và PolicyOutput, có các mục results là các giá trị Diagnostic. Mức độ nghiêm trọng của một diagnostic là một trong ba giá trị mà mọi socket dùng chung — halt, warn hoặc info — và ba giá trị này được công bố dưới dạng hằng số cùng với các kiểu wire trong mỗi gói của ba gói, để guest báo cáo từ cùng tập đóng mà host định tuyến theo. Một guest trả về bất kỳ giá trị nào khác sẽ dừng bản build, với thông điệp nêu tên plugin và giá trị nó đã trả về: một mức độ nghiêm trọng không định tuyến được là một lỗi của plugin mà host báo cáo chứ không phải một diagnostic mà nó bỏ qua.
Hợp đồng hình dạng đầu ra — pipeline FeatureRecipe và các socket provider
Các socket dưới đây mang các bề mặt hợp đồng có kiểu mà trình biên dịch điều phối khi build. Các bước pipeline: của FeatureRecipe và Recipe chạy trong pipeline plugin trên tập tài liệu đã render; socket render provider chạy ở giai đoạn render cơ sở; publishing-linter chạy ngoài luồng.
Các bản vá RFC 6902 (pipeline plugin)
Các bước pipeline: của FeatureRecipe và Recipe chạy trong pipeline plugin phát ra các thao tác JSON Patch RFC 6902 trên tập tài liệu đã render. Host giao cho mỗi bước toàn bộ tập tài liệu có khóa; bước chọn các tài liệu nó nhắm tới theo nội dung và trả về các bản vá định địa chỉ theo khóa, mà engine áp dụng sẽ áp lên các tài liệu được định địa chỉ — thường là thêm một container sidecar, gắn một volume secret, hoặc viết lại một biến môi trường. Một bước cũng trả về side_effects (bên dưới), diagnostics — mỗi mục có cùng hình dạng Diagnostic dùng chung mà mọi socket dùng để báo cáo vấn đề — và outputs (bên dưới). Được mô tả tại examples/04-secrets.md.
Trạng thái hiện tại: có sẵn. Mỗi bước được khai báo chạy trong quá trình aggrega build.
Mã hóa trên đường truyền. Đầu vào của một bước (FRPStepInput) và câu trả lời của nó (FRPStepOutput) được truyền dưới dạng CBOR chuẩn tắc (RFC 8949 §4.2.1), theo cả hai chiều. Một guest giải mã đầu vào và mã hóa câu trả lời thông qua các điểm vào mà các kiểu payload mang theo — DecodeCBOR và EncodeCBOR trong Go, decode_cbor và encode_cbor trong Rust (trên các kiểu mà crate aggrega-abi công bố), decodeCBORFRPStepInput và encodeCBORFRPStepOutput trong TypeScript — đọc và ghi byte (Vec<u8> trong Rust, Host.inputBytes() và Host.outputBytes(...) trong TypeScript). Không cần thư viện CBOR nào và không có gì phải tự phân tích byte. Đầu vào with của bước (step_input), các outputs nó trả về, và các tập tài liệu own và host là các map mà schema đánh dấu là giữ thứ tự, vì vậy chúng được truyền dưới dạng danh sách các mục có thứ tự theo thứ tự pipeline nắm giữ, và một guest đọc và ghi chúng thông qua container giữ thứ tự của kit — đó là điều cho phép các đầu ra của một bước đến được .steps.<id>.outputs theo thứ tự bước đã trả về. tree của mỗi đơn vị, mỗi giá trị của step_input và outputs, value của một bản vá, crd của một side effect và context render được truyền dưới dạng byte của các tài liệu JSON của chúng, mà guest phân tích như JSON để xem bên trong; bytes của một đơn vị được truyền dưới dạng một chuỗi byte thô mà bộ giải mã được sinh ra điền vào kiểu trường riêng của kit — một byte slice trong Go, một chuỗi base64 trong Rust và TypeScript. Mỗi diagnostic được truyền theo hình dạng Diagnostic dùng chung. Một câu trả lời không phải là FRPStepOutput trong mã hóa này — một câu trả lời viết bằng JSON, hoặc mang một trường cấp cao nhất mà hình dạng không khai báo — làm bước thất bại, nêu tên hàm mà nó chạy, điều này dừng build trừ khi bước là optional. Khi được gọi trực tiếp bằng aggrega plugin run-local --export step, một bước được giao payload JSON đã soạn, chuyển đổi sang mã hóa này, và câu trả lời của nó được đọc theo hình dạng đầu ra của export và in ra dưới dạng JSON — một câu trả lời không có hình dạng đó sẽ bị từ chối, nêu tên export, giống như một bản build từ chối nó.
Side effect — phát ra tài nguyên (các plugin thông tin xác thực trong pipeline plugin)
Các pipeline FeatureRecipe về thông tin xác thực (Nguyên tắc Plugin hai phần: Fetcher + Injector) phát ra các tài nguyên đầy đủ cùng với một bản vá thông qua side_effects của một bước, mỗi mục khai báo một trong hai loại mà hợp đồng định nghĩa: emit_crd, một tài liệu custom resource như một CRD ExternalSecret hoặc VaultSecret mà cluster tải về lúc chạy, hoặc emit_file, một tệp được ghi. Một bước trả về bất kỳ loại nào khác sẽ dừng bản build, nêu tên node, chỉ số của side effect và loại mà nó khai báo. Bước của Fetcher phát ra tài nguyên hoàn chỉnh; bước của Injector trả về một bản vá gắn Kubernetes Secret thu được. Được mô tả tại examples/04-secrets.md.
Trạng thái hiện tại: có sẵn.
Đầu ra của bước (map outputs của bước pipeline:)
Một bước pipeline plugin công bố các đầu ra có tên mà các bước tiếp theo sử dụng qua {{ .steps.<id>.outputs.<key> }}. Hình dạng đầu ra do provider định nghĩa theo từng plugin; các đầu ra của bước có phạm vi trong cùng pipeline và chỉ hiển thị với các bước tiếp theo theo thứ tự khai báo. Được tài liệu hóa tại templates/expansion-matrix.md hàng 10.
Trạng thái hiện tại: có sẵn.
Provider rendering — socket do guest điều khiển
Một provider là một guest Wasm. Việc render chỉ dùng Wasm: tên capability: của một Recipe được phân giải tới Plugin render provider (pluginType: provider) liệt kê tên đó trong spec.provider.capabilities của nó và quảng bá một export render_node, và guest của plugin đó render node. Không có trình render trong host để dự phòng; một tên provider không phân giải tới Plugin phục vụ nào sẽ dừng build tại thời điểm định tuyến. Thêm một provider tiêu chuẩn là phát hành một guest .wasm và một thực thể Plugin trong catalog — host không mang mã riêng cho từng provider.
Một capability mà provider phục vụ không chứa dấu hai chấm, và một capability mà bước pipeline tự khai báo là tương thích cũng vậy. capability: của một Recipe được đọc là capability tính đến dấu hai chấm cuối cùng và một ghim phiên bản sau đó — helm:1.0.0 yêu cầu helm ở 1.0.0 — vì vậy một tên chứa dấu hai chấm là tên mà không Recipe nào có thể yêu cầu. Host từ chối tên như vậy trong capabilities của describe() đối với guest provider hoặc pipeline-step khi guest được nạp và khi thực thể của nó được sinh ra để công bố, nêu tên guest và tên đó. parse:<format> của parser và import:<format> của importer giữ dấu hai chấm: chúng được tra cứu theo định dạng, không bao giờ qua capability: của một Recipe.
Host là một bộ định tuyến chung. Nó đọc bản tự báo cáo describe() của guest — bao gồm hợp đồng hành vi render của nó — và điều phối các export của guest mà không cần hiểu bất kỳ định dạng provider nào. Hợp đồng đó điều khiển việc điều phối dưới dạng dữ liệu:
input_kinds(sourced,synthesized,artifacts_standalone) — những loại đầu vào Recipe mà guest render; host kiểm tra loại đầu vào của một node đối chiếu với tập này.boundary_assembly(none|merge|nest) — cách guest kết hợp đầu ra của một nhóm điều phối:mergephân loại đầu ra theo từng node thành các mảnh mà bộ lắp ráp hợp nhất thành một artifact,nestlồng các tệp theo từng node dưới một lớp bao đã lắp ráp,noneghi trực tiếp đầu ra của mỗi node.nest_segment(tùy chọn) — với một assemblynest, thư mục mà thư mục con riêng của mỗi bên đóng góp được đặt bên dưới, viết dưới dạng một tên thư mục; nếu vắng mặt, thư mục con của mỗi bên đóng góp nằm trực tiếp tại vị trí điều phối.assembly_name_annotation(tùy chọn) — một annotation boundary mà giá trị đã phân giải của nó đặt tên cho artifact mà guest lắp ráp từ một nhóm điều phối; nếu vắng mặt, guest đặt tên cho assembly của nó chỉ từ đường dẫn điều phối.cross_boundary_linking(tùy chọn) — guest có nối một cạnhusesxuyên boundary thông qua các exportlink_publishvàlink_resolvecủa nó hay không; guest khai báo nó là true đúng khi nó export cả hai, và việc nạp sẽ từ chối một guest có cờ và các export không khớp nhau.artifact_delimiters(tùy chọn) — cặp dấu phân cách Go-template mà guest áp dụng cho nội dung artifact.reusable_instance(tùy chọn) — liệu một instance đã nạp có thể phục vụ mọi lần gọi qua lại của build hay không (xem Tính tất định và tái sử dụng instance bên dưới).omits(tùy chọn) — liệu guest có tuân theo các mục omit mà một lần render nguồn mang theo hay không (xem Loại bỏ các đơn vị đã render bên dưới).boundary_artifacts(tùy chọn) — liệu đích của guest có chấp nhận các tệp mà một Recipe đóng góp vào đầu ra dùng chung của boundary hay không (xem Chấp nhận các tệp mà một Recipe đóng góp vào boundary bên dưới).source_ignore(tùy chọn) — các tệp mà hệ sinh thái của guest không bao giờ phát hành kèm một nguồn mà nó render (xem Khai báo những gì hệ sinh thái của một nguồn không bao giờ phát hành bên dưới).
Socket là một tập export cố định — một export bắt buộc, các export còn lại là tùy chọn và được quảng bá trong describe():
render_node(bắt buộc) — render một node IR thành các tệp gốc của provider.assemble_boundary(tùy chọn) — hợp nhất đầu ra theo từng node của một nhóm điều phối thành một artifact cho mỗi đường dẫn (có mặt khiboundary_assemblylàmergehoặcnest).validate_node_input(tùy chọn) — xác thực cấu trúc trước khi render đối với đầu vào của một node; một diagnostichaltdừng build, mộtwarnđược đưa vào kết quả build.carve/reassemble(tùy chọn, đi theo cặp) — codec vá trung thực đến từng byte của chính guest cho các bước pipeline sau render, chỉ được dùng khi cả hai đều được quảng bá.name_bound(tùy chọn) — guest đánh giá xem một tên mà host đề xuất làm định danh component có tạo ra các tên mà đích của nó chấp nhận hay không, và trả lời bằng một ràng buộc thay vì một tên của riêng nó.rendered_name(tùy chọn) — guest báo cáo tên mà đích của nó đặt cho các tài nguyên nó kết xuất cho một node.link_publish/link_resolve(tùy chọn, đi theo cặp) — guest nối một cạnhusesxuyên ranh giới: endpoint được tiêu thụ công bố một handle, và endpoint tiêu thụ phân giải nó vào đầu ra đã lắp ráp của chính mình.
Các artifacts: của Recipe được gộp vào render_node thông qua một phép chiếu artifacts trên đầu vào: host thực hiện việc đọc $import, việc đánh giá Go-template và việc tính toán key/value nguồn gốc, rồi trao cho guest từng mục đã được đọc và đánh giá; guest chịu trách nhiệm về vị trí đặt và việc phát ra theo định dạng mà chỉ nó biết. Được mô tả tại architecture/13-catalog-and-registry.md.
Đầu vào của một lần kết xuất nguồn mang các giá trị của node trên node.values, và node.values_mapped cho biết chúng đến từ đâu: nó là true khi chúng là đầu ra của valuesMapping của Recipe — hoặc, với lần kết xuất riêng của một attachment, của FeatureRecipe của nó — và vắng mặt khi chúng là các giá trị riêng của component được chuyển tiếp nguyên như đã viết. Việc một guest có đọc nó hay không là hợp đồng riêng của guest đó. Provider cloudformation chỉ gắn Parameters của một template có nguồn từ các giá trị mà một mapping tạo ra, vì các giá trị riêng của một component có thể đã được viết cho các đầu vào khác của Recipe; provider terraform ghi các đối số của một module có nguồn từ các giá trị mà quá trình lắp ráp của nó nhận được, và không đọc cờ này. Các giá trị đó đi kèm trên mỗi node đã kết xuất của một đầu vào assemble_boundary đối với một node được kết xuất từ một nguồn — của một component dù có hay không có mapping tạo ra chúng, của một Feature được gắn chỉ khi valuesMapping của FeatureRecipe của nó tạo ra chúng — và cùng cờ đó đi bên cạnh chúng và chỉ ở nơi chúng đi, để một bộ lắp ráp đọc được cùng câu trả lời mà lần kết xuất riêng của node đã đọc; provider cloudformation đọc nó ở đó để biết những tham số nào mà việc gắn của một node đã điền, và từ chối một tham chiếu tới một tham số như vậy từ bất kỳ nơi nào khác trong stack, kể cả host của một Feature được gắn. Cờ này ghi lại cách các giá trị được tạo ra và không bao giờ được suy ra từ một key hay một giá trị.
Mã hóa trên đường truyền. Mọi export của socket này nhận đầu vào và trả về đầu ra dưới dạng CBOR chuẩn tắc (RFC 8949 §4.2.1), theo cả hai chiều. Một guest giải mã đầu vào và mã hóa đầu ra của nó thông qua các điểm vào mà các kiểu payload đã mang sẵn — DecodeCBOR và EncodeCBOR trong Go, decode_cbor và encode_cbor trong Rust, và trong TypeScript là hàm decodeCBOR và encodeCBOR của mỗi kiểu, chẳng hạn decodeCBORRenderNodeInput và encodeCBORRenderNodeOutput — đọc và ghi byte (Vec<u8> trong Rust, Host.inputBytes() và Host.outputBytes(...) trong TypeScript). Không cần thư viện CBOR nào và không có gì phải phân tích byte thủ công. content của một tệp đã kết xuất, và mọi trường byte khác, được truyền dưới dạng một dãy byte thô mà bộ giải mã được sinh ra điền vào kiểu trường riêng của kit: một byte slice trong Go, một chuỗi base64 trong Rust và TypeScript. Các map mà schema đánh dấu là giữ thứ tự — trong đó có values, features và uses của một node, derived_keys của một phản hồi, và values của một bên đóng góp vào lắp ráp — được truyền dưới dạng danh sách các mục có thứ tự theo thứ tự mà bản build lưu giữ chúng, và một guest đọc chúng thông qua container giữ thứ tự của kit. Mỗi giá trị trong values của một node được truyền dưới dạng các byte của tài liệu JSON riêng của nó, nên các key bên trong một giá trị giữ đúng thứ tự chúng được viết; điều này cũng đúng với mỗi mục attachment của features, render context, workload đã phân tích, mỗi cạnh đã được làm giàu, mỗi đơn vị đã cắt và mỗi thao tác patch, và một guest phân tích chúng như JSON để xem bên trong. Mỗi diagnostic được truyền theo dạng Diagnostic dùng chung. Một câu trả lời không phải là dạng đầu ra của export đó trong cách mã hóa này — một câu trả lời viết bằng JSON, hoặc mang một trường cấp cao nhất mà dạng đó không khai báo — sẽ dừng bản build, nêu tên export mà nó đã gọi. Các ví dụ payload trên trang này được viết bằng JSON để dễ đọc. Khi được gọi trực tiếp bằng aggrega plugin run-local --export render_node, hoặc bằng bất kỳ export nào khác của socket, một guest được trao payload JSON đã soạn, chuyển đổi sang cách mã hóa này, và câu trả lời của nó được đọc theo dạng đầu ra của export và in ra dưới dạng JSON — một câu trả lời không có dạng đó sẽ bị từ chối, nêu tên export, giống như một bản build từ chối nó.
Trạng thái hiện tại: đã có cho cả năm provider. Guest helm kết xuất các chart có nguồn (phân giải thư mục gốc của chart), các workload được tổng hợp và các artifact độc lập thành các manifest Kubernetes phẳng. Guest helm-chart lắp ráp một umbrella chart, lồng chart có nguồn của mỗi node làm một sub-chart, và mang một patch codec trung thực từng byte cùng các dấu phân cách artifact dạng ngoặc vuông ([[ ]]). Guest compose kết xuất các tệp compose có nguồn và các workload được tổng hợp, gộp một nhóm dispatch thành một docker-compose.yaml, và đưa một service vào các mạng của những component mà x-aggrega-networks-of của nó nêu tên. Guest terraform phát ra cấu hình Terraform nguyên văn (HCL hoặc JSON) hoặc vendor một module có nguồn và cung cấp đầu vào của nó dưới dạng các đối số module-block của component đó, kiểm tra cấu trúc HCL của một module có nguồn trước khi kết xuất, và hợp thành một ranh giới thành một cấu hình gốc duy nhất khai báo mỗi component là một module block lấy nguồn từ thư mục con riêng của component đó. Guest cloudformation kết xuất các template có nguồn và các mảnh stack độc lập, gộp một nhóm dispatch thành một template stack, và nối một cạnh uses xuyên ranh giới thông qua link_publish và link_resolve. Mỗi guest kết xuất ngoại tuyến và một cách tất định.
Khai báo các tên mà một guest suy ra
Một guest của provider thường suy ra những tên mà đầu ra của nó cần nhưng không ai viết ra — định danh mà một target dùng để chỉ tới một tài nguyên, tên mà một đầu ra được công bố dưới đó để đầu ra khác tham chiếu — từ định danh của node và tài nguyên mà nó đang phát ra. Hai node có thể đi đến cùng một tên bất cứ khi nào các phần dùng để suy ra tên trùng nhau, và vì tên nằm bên trong các byte của tệp mà host ghi nguyên văn, host không thể thấy xung đột: nó sẽ phải phân tích định dạng của provider để tìm ra, mà đó chính là kiến thức nằm lại trong guest.
Vì vậy render_node trả về một derived_keys tùy chọn trong đầu ra của nó, và chiều được đảo ngược — thay vì host kiểm tra đầu ra, guest khai báo và host kiểm tra:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "derived_keys": { "logical-ids": ["paymentsapiQueue", "paymentsapiTopic"], "export-names": ["aggrega--prod--api--orders-db--host"] }}Mỗi khóa của derived_keys là một không gian khóa do guest đặt tên, và mỗi không gian mang các tên mà guest đã suy ra vào đó, theo thứ tự suy ra. Cả tên không gian lẫn các tên bên trong đều là từ vựng của bạn: host chỉ đọc chúng như các chuỗi để so sánh bằng nhau trong cùng một không gian. Host không phân tích một tên, không biết một không gian hay một tên có nghĩa gì, và không bao giờ tự suy ra tên nào — vì vậy một lần kiểm tra bao quát mọi loại tên mà mọi provider suy ra, và một provider mới không cần mã host mới. Trong các kiểu được công bố, derived_keys là một map giữ thứ tự, nên các không gian được truyền qua theo thứ tự mà guest của bạn đặt chúng.
Việc host làm với chúng chỉ là một câu hỏi: trong một không gian, mọi tên được khai báo có khác biệt giữa các contributor có đầu ra hợp nhất vào cùng một assembly hay không? Hai contributor khai báo cùng một tên trong cùng một không gian sẽ làm dừng bản build, và thông báo dừng nêu tên không gian, tên đó và cả hai contributor, để tác giả có thể xử lý mà không cần đọc provider. Các tên khác nhau, và các tên tình cờ trùng nhau ở hai không gian khác nhau, đều được chấp nhận.
Ba thuộc tính đáng biết khi bạn quyết định khai báo gì:
- Phạm vi là một đầu ra được lắp ráp — tập các contributor có tệp được hợp nhất với nhau. Một guest muốn tính duy nhất trên phạm vi hẹp hơn hoặc rộng hơn thế sẽ thể hiện phạm vi đó trong tên không gian mà nó khai báo, nhờ vậy lựa chọn thuộc về bạn chứ không phải host.
- Một contributor có thể lặp lại một tên tùy ý. Một node có thể render qua nhiều lần truyền — một lần render nguồn, một lần tổng hợp workload, một lần đặt artifacts — và các khai báo được hợp nhất. Cùng một tên được một contributor khai báo hai lần là contributor đó mô tả một tài nguyên hai lần, không phải xung đột.
- Việc khai báo không thay đổi byte nào. Trường này là một khẳng định về những gì guest đã suy ra, không bao giờ là thay đổi đối với những gì nó đã phát ra, nên đầu ra render của một guest là như nhau dù nó có khai báo hay không. Bỏ qua
derived_keyslà hợp lệ và khiến việc kiểm tra không có tác dụng đối với guest đó.
Báo cáo dữ kiện về những gì một guest đã phát ra
Một số điều về lần render của một node chỉ provider tạo ra nó mới thấy được — các tài liệu nó đã ghi chứa gì, chúng định nghĩa những tên nào, nó đã phát ra bao nhiêu thứ gì đó — vì đọc chúng ra từ các byte của tệp đồng nghĩa với việc hiểu định dạng của provider. render_node có thể tự báo cáo những điều đó, trên một danh sách render_facts tùy chọn bên cạnh các tệp của nó:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "render_facts": [ { "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] }, { "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] } ]}Mỗi dữ kiện là một name và một value, và cả hai đều thuộc về provider của bạn: provider báo cáo những dữ kiện nào, mỗi tên có nghĩa gì và mỗi mục chứa gì là một phần của hợp đồng được tài liệu hóa riêng của provider của bạn, vì vậy hãy viết tài liệu về chúng cho các tác giả sẽ đọc chúng.
Hãy báo cáo giá trị của mọi dữ kiện dưới dạng danh sách — một mảng JSON — kể cả khi nó chỉ chứa một mục. Một tên có thể được báo cáo bởi nhiều lần render của một component: lần render riêng của nó có thể gồm nhiều lời gọi — chẳng hạn một lần render chart và một lần đặt artifacts — và mỗi Feature gắn vào component render qua một lời gọi provider riêng. Không provider nào có thể biết, khi nó render, liệu báo cáo của nó có phải là báo cáo duy nhất dưới một tên hay không, vì vậy mọi báo cáo đều là danh sách, và trình biên dịch nối các danh sách mà một tên nhận được thành một danh sách. Một dữ kiện có giá trị là bất cứ thứ gì khác — một đối tượng, một chuỗi, một số, một boolean, null — sẽ bị từ chối khi guest của bạn trả về nó: bản build dừng với mã ngắn E0325, nêu tên dữ kiện, node và guest của bạn, và cho biết giá trị đó là gì. Các mục bên trong một danh sách là bất kỳ giá trị JSON nào theo hình dạng bạn tài liệu hóa.
Việc một giá trị là danh sách là điều duy nhất trình biên dịch biết về nó. Trình biên dịch lập khóa các dữ kiện theo tên và giao mỗi danh sách cho các template đọc nó — dữ kiện của component host cho mọi Feature gắn vào nó, dữ kiện của mỗi caller cho một Feature khai báo rằng nó đọc render facts của các caller, và dữ kiện của mỗi target cho một Feature khai báo rằng nó đọc render facts của các component mà host của nó được nối tới, như ngữ cảnh template mô tả — giải mã mỗi danh sách thành một giá trị mà template có thể duyệt qua. Trình biên dịch không bao giờ biết một tên hay một mục có nghĩa gì và không bao giờ tự suy ra một dữ kiện, vì vậy một provider mới có thể báo cáo dữ kiện mới mà không cần thay đổi gì ở phía trình biên dịch. Các dữ kiện mà một Feature gắn vào node báo cáo từ lần render riêng của nó được giữ tách biệt với các dữ kiện mà lần render riêng của node đã báo cáo.
Bốn thuộc tính đáng biết khi bạn quyết định báo cáo gì:
- Thứ tự là của bạn. Các dữ kiện giữ thứ tự mà guest của bạn liệt kê, và mỗi giá trị giữ nguyên các byte của nó — thứ tự các mục của một danh sách và các khóa của mỗi đối tượng là thứ tự guest của bạn đã viết. Hãy liệt kê các dữ kiện theo một thứ tự cố định, và viết mỗi mục với thứ tự khóa cố định, để đầu vào giống nhau tạo ra các byte giống nhau; một danh sách dữ kiện thay vì một map tồn tại chính là để thứ tự đó được giữ nguyên trong kiểu chuỗi tuần tự riêng của mọi kit mà không cần đánh dấu gì, trong khi một map chỉ giữ thứ tự guest đã viết khi schema của nó đánh dấu là giữ thứ tự và guest điền vào container giữ thứ tự của kit.
- Việc báo cáo không thay đổi byte nào. Các tệp mà trình biên dịch ghi là các tệp guest của bạn đã trả về, dù có dữ kiện đi kèm hay không.
- Một node có thể báo cáo qua nhiều lần truyền. Một node có thể render dưới dạng một lần render nguồn, một lần tổng hợp workload và một lần đặt artifacts; các dữ kiện mà mỗi lần báo cáo được giữ theo thứ tự các lần truyền đã chạy, và một tên được nhiều lần trong số đó báo cáo sẽ được đọc là một danh sách nối chúng theo thứ tự đó.
- Không báo cáo gì là đầy đủ. Bỏ qua
render_factslà hợp lệ, và một provider không báo cáo gì sẽ render y như khi không có trường này.
Kiểu RenderFact được công bố trong ba gói ABI và được tái xuất bởi bộ công cụ phát triển plugin của mỗi ngôn ngữ, và các ví dụ render của các kit báo cáo hai dữ kiện bên cạnh các tệp của chúng. Trong Go, một giá trị là JSON mà guest của bạn viết; marshal một slice gồm các struct thay vì các map là điều giữ cho các khóa của mỗi mục theo thứ tự bạn đã khai báo:
type stackFact struct { Name string `json:"name"` Resources int `json:"resources"`}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})if err != nil { pdk.SetError(err) return 1}out := aggrega.RenderNodeOutput{ Files: files, RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},}Loại bỏ các đơn vị đã kết xuất
Một lần kết xuất nguồn có thể nêu tên các đơn vị mà provider phải loại khỏi những gì nó kết xuất — chẳng hạn một Secret mà một chart được tải về tạo mới ở mỗi lần kết xuất. Một mục nêu tên đơn vị đã kết xuất nào là kiến thức chỉ provider của bạn có, nên các mục được chuyển đến guest của bạn và guest của bạn thực hiện việc loại bỏ. Chúng đến trên đầu vào của render_node dưới dạng một danh sách omits tùy chọn bên cạnh source_listing:
{ "node": { "id": "payments-api" }, "context": { }, "source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] }, "omits": [ { "kind": "Secret", "name": "payments-api-token", "namespace": "payments" }, { "kind": "ConfigMap", "name": "payments-api-dashboards" } ]}Mỗi mục gồm một kind, một name và một namespace tùy chọn, đã được phân giải thành chuỗi thuần và được liệt kê theo thứ tự tác giả khai báo; một mục không áp dụng cho bản dựng sẽ không được chuyển đi. Ba trường này chọn gì là hợp đồng riêng của provider của bạn — kind, name và namespace của một tài nguyên trong định dạng của đích của bạn — nên hãy ghi tài liệu về nó cho các tác giả viết các mục.
Tác giả có thể tạo các trường của một mục từ một giá trị mà họ đã khai báo là nhạy cảm — chẳng hạn một tài nguyên được đặt tên theo một thiết lập nhạy cảm. Một mục như vậy đến kèm "sensitive": true, và guest của bạn xử lý nó như mọi giá trị được đánh dấu khác mà đầu vào kết xuất mang theo (xem Các giá trị mà một đầu vào đánh dấu là nhạy cảm): nó vẫn khớp và đếm mục theo các trường của mục, đó chính là mục đích của mục, và giữ mọi trường của mục ngoài một lời từ chối, một cảnh báo hay một dòng log. Dấu này bao phủ toàn bộ mục, vì trình biên dịch không cho biết trường nào được tạo ra từ giá trị đó. Nó vắng mặt khi không có trường nào được tạo từ một giá trị như vậy.
Một guest tuân theo các mục sẽ làm ba việc:
- Khớp mọi mục với những gì nó đã kết xuất, theo các khái niệm của định dạng của bạn.
- Loại mỗi đơn vị đã khớp khỏi mọi thứ nó trả về — các
filescủa nó, các tên nó khai báo trongderived_keysvà các dữ kiện nó báo cáo trongrender_facts— để không còn gì trình biên dịch nhận được mô tả đơn vị đó. - Báo cáo một số đếm cho mỗi mục trên một danh sách
omittedtùy chọn trong đầu ra của nó, theo thứ tự các mục đến, mỗi số là số đơn vị mà mục đó đã khớp, được đếm bất kể một mục khác có cũng khớp chúng hay không:
{ "files": [ { "path": "templates/deployment.yaml", "content": "..." } ], "omitted": [1, 0]}Số không là một câu trả lời đầy đủ: mục đó không khớp gì mà guest của bạn đã kết xuất. Các số đếm là tất cả những gì được gửi lại về những thứ đã bị loại bỏ; bản thân các đơn vị đơn giản là vắng mặt khỏi những gì guest của bạn trả về.
Một provider làm cả ba việc sẽ khai báo điều đó bằng omits: true trên hợp đồng của nó. Thực thể Plugin ghi lại cùng tuyên bố đó dưới dạng spec.provider.contract.omits; khi thực thể mang một hợp đồng hành vi kết xuất, việc tải sẽ từ chối một guest mà describe() của nó báo cáo một giá trị khác. Các mục đi kèm một danh sách nguồn và không gì khác: một lần kết xuất một workload được tổng hợp hoặc một tập artifact không bao giờ mang chúng.
Một lần kết xuất không mang mục nào không bị các trường này làm thay đổi. Cả hai trường đều tùy chọn và vắng mặt khi rỗng, nên một lần kết xuất không mang mục nào đi qua socket từng byte như thể các trường không tồn tại, và một guest không bao giờ đọc chúng không bị ảnh hưởng bởi chúng. Kiểu OmitEntry được công bố trong ba gói ABI và được tái xuất bởi bộ công cụ phát triển plugin của mỗi ngôn ngữ.
Trình biên dịch làm gì với câu trả lời của bạn. Các mục đến từ khóa omits: mà tác giả viết trên một Recipe hoặc một FeatureRecipe (Recipe → Trường omits:); trình biên dịch đánh giá các template của mỗi mục và trao cho guest của bạn những mục áp dụng. Sau đó nó đọc các số đếm của bạn, và chỉ các số đếm của bạn — nó không bao giờ xem vào một tệp được trả về để kiểm tra chúng:
- Một danh sách số đếm không phải là đúng một số đếm không âm cho mỗi mục đã được trao sẽ dừng bản dựng — bị thiếu, quá ngắn, quá dài, hoặc chứa một số đếm nhỏ hơn không — nêu tên node, provider của bạn, số mục đã được gửi đi và số số đếm đã trả về. Một báo cáo không khớp hàng sẽ không còn cách nào để biết mục nào đã loại bỏ cái gì. Xem A provider’s omitted counts do not match the omits entries it was handed (Số đếm đã loại bỏ của một provider không khớp với các mục omits mà nó được trao).
- Một số không sẽ dừng bản dựng, nêu tên mục đầu tiên theo thứ tự của tác giả có số đếm bằng không: node, provider của bạn, vị trí của mục trong danh sách mà tài liệu của nó khai báo, và kind, name và namespace mà nó được phân giải thành. Guest của bạn báo cáo số không; việc dừng là của trình biên dịch. Xem An omits entry left out nothing the source rendered (Một mục omits không loại bỏ gì mà nguồn đã kết xuất).
- Một tài liệu khai báo
omits:mà provider của nó không tuyên bốomits: truesẽ bị từ chối trước khi bất cứ thứ gì được kết xuất, để tác giả biết ngay rằng khóa này sẽ không có tác dụng thay vì thấy tài liệu trong đầu ra. Trình biên dịch đọc tuyên bố của bạn từdescribe()của bạn khi mọi Recipe và FeatureRecipe trong bản dựng đã được gắn kết, và từ chối trước khi component đầu tiên được kết xuất — nên một guest không tuyên bố khóa này không bao giờ được trao một mục nào. Lời từ chối nêu tên provider và component mà tài liệu kết xuất cho, hoặc, với một FeatureRecipe tạo ra một lần cho một boundary, thì nêu boundary và phần đính kèm. Xem The provider does not support omits (Provider không hỗ trợ omits).
Trạng thái hiện tại: khả dụng. Các guest helm, compose và cloudformation được phân phối cùng trình biên dịch khai báo tuyên bố này và tuân theo các mục. Guest helm không ghi trường nào của bất kỳ mục nào vào một văn bản nó trả về. Các guest compose và cloudformation nêu kind, name và namespace của một mục khi chúng từ chối mục đó, và nêu các đơn vị mà một mục đã loại bỏ khi chúng từ chối một tệp hoặc một template vẫn nêu tên các đơn vị đó, và hiển thị mọi trường của một mục được đánh dấu dưới dạng <redacted> ở đó. Các guest helm-chart và terraform không khai báo tuyên bố này, nên một tài liệu khai báo omits: mà một trong số chúng kết xuất sẽ bị từ chối.
Chấp nhận các tệp mà một Recipe đóng góp cho boundary
Một số tệp thuộc về toàn bộ một boundary thay vì một trong các component của nó — chẳng hạn một cấu hình provider mà một đích đọc một lần cho mọi thứ boundary triển khai. Một Recipe viết các tệp đó dưới spec.boundary.artifacts, và trình biên dịch, chứ không phải guest của bạn, làm công việc này: nó đánh giá mỗi tệp dựa trên ngữ cảnh mà một mục artifacts: được đánh giá, hợp nhất theo tên các tệp mà mọi bên đóng góp vào nhóm điều phối đã khai báo, và ghi mỗi tệp một lần trong thư mục chứa đầu ra đã lắp ráp của nhóm, bên cạnh những gì assemble_boundary của bạn trả về. Guest của bạn không được trao tệp nào trong số này trên bất kỳ export nào và không bao giờ được hỏi về chúng, nên không có gì phải triển khai — chỉ có một tuyên bố về đích của bạn cần đưa ra:
"contract": { "input_kinds": { "sourced": true, "artifacts_standalone": true }, "boundary_assembly": "nest", "boundary_artifacts": true}Chỉ khai báo boundary_artifacts: true khi đích của bạn đọc một tệp đặt trong thư mục đó như một phần đầu ra của boundary. Thực thể Plugin ghi lại cùng tuyên bố đó dưới dạng spec.provider.contract.boundaryArtifacts; khi thực thể mang một hợp đồng hành vi kết xuất, việc tải sẽ từ chối một guest mà describe() của nó báo cáo một giá trị khác. Một Recipe khai báo khối này mà provider của nó không tuyên bố hỗ trợ sẽ bị từ chối trước khi bất cứ thứ gì được kết xuất, nêu tên provider và component; xem The provider does not support boundary artifacts (Provider không hỗ trợ boundary artifacts). Một tệp mà một trong các lần hợp nhất này đặt dưới một tên mà quá trình lắp ráp của bạn cũng ghi sẽ dừng bản dựng theo trường hợp two contributors writing one output path (hai bên đóng góp ghi cùng một đường dẫn đầu ra), nên các tên mà quá trình lắp ráp của bạn ghi là một phần của những gì bạn ghi tài liệu cho tác giả.
Trạng thái hiện tại: khả dụng. Guest terraform được phân phối cùng trình biên dịch khai báo tuyên bố này, và Terraform đọc mỗi tệp bên cạnh cấu hình gốc của boundary; các guest helm, compose, helm-chart và cloudformation không khai báo nó.
Khai báo những gì hệ sinh thái của một nguồn không bao giờ phát hành
Thư mục nguồn cục bộ của một Recipe — một chart đặt cùng chỗ, một module — được phát hành cùng với Recipe, và không phải mọi tệp trong đó đều thuộc về nó. Một guest của provider nói rõ những gì hệ sinh thái của chính nó không bao giờ phát hành thông qua source_ignore trên hợp đồng của nó, dưới dạng các quy tắc bỏ qua theo cú pháp mà .gitignore sử dụng:
"contract": { "input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false }, "boundary_assembly": "none", "source_ignore": { "patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"], "files": [".helmignore"] }}patternslà các quy tắc được đọc từ gốc của thư mục nguồn, áp dụng theo thứ tự, một kết quả khớp sau ghi đè một kết quả khớp trước.filesnêu tên các tệp bỏ qua mà hệ sinh thái của bạn tuân theo bên trong một nguồn. Bất cứ nơi nào quá trình duyệt một nguồn gặp một tệp như vậy, các dòng của nó được đọc như các quy tắc bổ sung cho thư mục chứa nó, sau các pattern của bạn.
Khai báo được đọc khi một thực thể được ghim, không phải khi nó được render. Bước ghim của tác giả phân giải plugin phục vụ capability của thực thể trong workspace của họ, kết hợp các quy tắc của bạn với .aggregaignore của chính họ — mà các dòng của nó đứng cuối và vì vậy thắng trên bất kỳ đường dẫn nào chúng nêu — và ghi lại tên plugin của bạn, không kèm phiên bản, cùng với chính xác các quy tắc đã kết hợp, trong entity.lock của thực thể. Mọi lần phát hành, so sánh và render sau đó của thực thể đó đều áp dụng các quy tắc đã ghi; host so khớp chúng và không có quan điểm riêng nào về bất kỳ hệ sinh thái nào. Vì vậy, các tệp mà guest của bạn được trao khi render — danh sách, và mọi tệp nó yêu cầu host đóng gói hoặc đọc — chính xác là các tệp mà một bản phát hành của thực thể mang theo, và một tệp bị các quy tắc loại ra được trả lời là không tồn tại, kèm tên của nó. Một liên kết tượng trưng trong một nguồn bị từ chối trước khi guest của bạn được gọi.
Tính tương thích suy ra từ những gì đã được ghi lại. Một guest có thể render một Recipe được phát hành cho capability của nó khi nó dùng cùng phiên bản ABI, hợp đồng của nó khớp với tuyên bố của thực thể của nó, và nó không cần tệp nào nằm ngoài tập đã phát hành. Một guest cần một tệp mà tập đó đã loại ra phải làm thất bại bản build của nó một cách rõ ràng và nêu tên tệp — việc host từ chối một thao tác đóng gói hoặc đọc sẽ nêu tên tệp, và guest mang điều đó vào lỗi của chính nó. Khi plugin mà workspace của một bên dùng gắn cho một capability khai báo các quy tắc khác với các quy tắc mà lock của thực thể ghi lại, lệnh pull của bên dùng in ra một cảnh báo nêu tên cả hai plugin và sự khác biệt; nó không bao giờ dừng lại vì điều đó.
Bỏ qua source_ignore nghĩa là không khai báo quy tắc nào, và một nguồn bạn render khi đó giữ lại mọi tệp mà các quy tắc riêng của tác giả giữ lại. Trường này là tùy chọn và không cần phiên bản ABI riêng: một guest bỏ qua nó được nạp như một guest không khai báo gì. Thực thể Plugin ghi lại cùng khai báo đó dưới dạng spec.provider.contract.sourceIgnore; khi có ghi lại, quá trình nạp từ chối một guest mà describe() của nó báo cáo điều gì khác.
Tính tất định và tái sử dụng instance
Host sử dụng nguyên văn các byte đầu ra của guest, vì vậy guest phải tạo ra đầu ra giống hệt nhau từ đầu vào giống hệt nhau. Theo mặc định, một guest được nạp mới cho mỗi node — không có trạng thái nào được mang qua các node, theo thiết kế. Một guest tự khai báo reusable_instance thay vào đó được nạp một lần cho mỗi bản build và instance duy nhất của nó phục vụ mọi lượt gọi, giúp thu hồi chi phí khởi tạo theo từng node vốn chiếm phần lớn. Vì việc tái sử dụng chỉ an toàn với một guest không trạng thái, aggrega build --verify-determinism render mỗi node hai lần qua cùng một instance và dừng bản build nếu hai lần render của bất kỳ node nào khác nhau; bản build mặc định render một lần và tin vào khai báo. Bộ nhớ đệm biên dịch Wasm được lưu trên đĩa và dùng chung toàn tiến trình, vì vậy một guest chỉ biên dịch một lần và các bản build ấm bỏ qua việc biên dịch lại.
Socket linter — linter phát hành
Socket linter được phát hành dưới dạng publishing-linter tiêu chuẩn, một cổng kiểm tra nằm ngoài luồng chạy qua aggrega lint thay vì lúc biên dịch. Nó nhận một thực thể catalog (và, ở chế độ --pre-publish, phiên bản hiện đang được phát hành của thực thể) và trả về một danh sách phát hiện, mỗi phát hiện có một mức độ nghiêm trọng và một thông điệp; ở chế độ --pre-publish nó còn trả về một phân loại mức tăng phiên bản. Host điều phối nó qua runtime Wasm nhúng, sau cùng tường lửa AOT-purity như mọi socket khác. Toàn bộ tập quy tắc, các mức độ nghiêm trọng và các tùy chọn tắt theo từng quy tắc được mô tả tại cli/aggrega-lint.md.
Linter là kỷ luật catalog tự chọn tham gia: trình biên dịch không chạy nó trong aggrega build (với ngoại lệ duy nhất là cảnh báo không khuyến khích x-aggrega-*, xuất hiện ở mức warn trong lúc build và ở mức halt dưới aggrega lint --pre-publish). Vì các quy tắc nằm trong một plugin, một doanh nghiệp có thể trỏ aggrega lint tới một plugin linter khác để áp đặt kỷ luật riêng của mình.
Không có giá trị tham số nào đến được một plugin linter, ở bất kỳ phạm vi nào mà aggrega lint chạy. Trước khi bất kỳ tài liệu nào được trao đi, host giữ lại các giá trị mặc định tham số của một Aggregate, các giá trị nó truyền cho mỗi module nó import, và các tham số của một Release, đồng thời giữ lại hợp đồng của mỗi khai báo tham số — chỉ các khóa mà một khai báo được viết cùng, ở mọi cấp lồng nhau — và mọi văn bản template đọc một tham số: giá trị của một tham số có thể chính là một thông tin xác thực, và plugin gắn ở đây có thể là mã mà workspace không viết. Những gì mỗi tài liệu mang theo được trình bày tại What a linter plugin is handed (Những gì một plugin linter được trao).
Mã hóa trên đường truyền. Cả đầu vào và đầu ra đều được truyền dưới dạng CBOR chuẩn tắc (RFC 8949 §4.2.1). Một guest giải mã đầu vào và mã hóa đầu ra của nó thông qua các điểm vào mà LinterInput và LinterOutput trong kit của nó đã có sẵn — DecodeCBOR và EncodeCBOR trong Go, decode_cbor và encode_cbor trong Rust, decodeCBORLinterInput và encodeCBORLinterOutput trong TypeScript — đọc và ghi các byte (Vec<u8> trong Rust, Host.inputBytes() và Host.outputBytes(...) trong TypeScript). Không cần thư viện CBOR nào và không có gì phân tích byte thủ công. Các tài liệu thực thể — proposed, previous, implemented_component và release — và mỗi giá trị của components được truyền dưới dạng các byte của tài liệu JSON của chúng, vì vậy guest phân tích chúng như JSON để xem bên trong. components là một map mà schema đánh dấu là giữ thứ tự, vì vậy trên đầu vào của một quy tắc đọc toàn bộ một Release, nó được truyền dưới dạng một danh sách mục có thứ tự theo thứ tự mà Aggregate khai báo các instance component của nó, và guest đọc nó qua container giữ thứ tự trong kit của mình. policies được truyền dưới dạng một map chỉ chứa các cờ được bật, vì vậy một cờ mà nó không mang được đọc là false, và mỗi phát hiện được truyền theo dạng Diagnostic dùng chung. Một câu trả lời không phải là một LinterOutput theo cách mã hóa này — một câu trả lời viết bằng JSON, hoặc mang một trường cấp cao nhất mà dạng này không khai báo — làm lint thất bại, nêu tên export mà nó đã gọi, thay vì được đọc như một lần chạy không tìm thấy gì. Khi được gọi trực tiếp bằng aggrega plugin run-local --export lint_rules, một linter được trao payload JSON do tác giả viết đã chuyển sang cách mã hóa này, và câu trả lời của nó được đọc theo dạng đầu ra của export và in ra dưới dạng JSON — một câu trả lời không có dạng đó sẽ bị từ chối, nêu tên export, giống như một bản build từ chối nó.
Trạng thái hiện tại: đã có sẵn. publishing-linter được phát hành và chạy qua host thông qua aggrega lint.
Socket parser — đầu ra cây chuẩn tắc
Một parser chuyển một nguồn được viết bằng một định dạng mà trình biên dịch không đọc được một cách tự nhiên thành một cây có cấu trúc chuẩn tắc, để bên tiêu thụ đọc cây đó thay vì phải mang theo một parser của riêng mình. Host phân giải parser quảng bá định dạng được yêu cầu dưới dạng parse:<format> và gọi export parse của nó ở ba nơi: khi một policy render-verdict được trao một artifact đã render ở định dạng mà nó không đọc được một cách tự nhiên, khi một importer yêu cầu host cung cấp một cây thông qua aggrega_parse_source, và khi một lần import không nêu định dạng nào được nhận diện (xem socket importer bên dưới). Một guest không bao giờ tự gọi một parser.
Hình dạng đầu vào (host → guest). Một tài liệu ParseInput mang:
format— định dạng được yêu cầu, là một trong các capabilityparse:<format>của parser, không có tiền tố.bytes— các byte của nguồn.options— một tài liệu tùy chọn mà bên tiêu thụ cung cấp cho hành vi riêng của parser, được chuyển nguyên văn. Vắng mặt khi bên tiêu thụ không cung cấp.
Hình dạng đầu ra (guest → host). Một tài liệu ParseOutput mang tree — nguồn đã được phân tích dưới dạng một tài liệu JSON, mà cấp cao nhất có thể là một object, một array hoặc một giá trị vô hướng — mọi chẩn đoán theo hình dạng Diagnostic dùng chung, các span nguồn tùy chọn định vị các nút của cây trong các byte gốc, và một error báo lỗi khi việc phân tích không thể hoàn tất. Mọi trường và các ràng buộc của chúng có trong tài liệu tham chiếu schema của socket parser được sinh ra.
Mã hóa trên đường truyền. Cả đầu vào lẫn đầu ra đều được truyền dưới dạng CBOR chuẩn tắc (RFC 8949 §4.2.1), cũng là mã hóa mà chính ParseInput được truyền khi một guest trao nó cho aggrega_parse_source. Một guest giải mã đầu vào và mã hóa đầu ra thông qua các điểm vào mà ParseInput và ParseOutput trong kit của nó đã có sẵn — DecodeCBOR và EncodeCBOR trong Go, decode_cbor và encode_cbor trong Rust, decodeCBORParseInput và encodeCBORParseOutput trong TypeScript — đọc và ghi các byte (Vec<u8> trong Rust, Host.inputBytes() và Host.outputBytes(...) trong TypeScript). Không cần thư viện CBOR nào và không có gì phải tự phân tích byte thủ công. Các byte nguồn được truyền dưới dạng một dãy byte thô, và bộ giải mã được sinh ra điền chúng vào kiểu trường riêng của kit: một byte slice trong Go, một chuỗi base64 trong Rust và TypeScript. options và tree được truyền dưới dạng các byte của tài liệu JSON của chúng, nên cây mà một parser viết ra đến được bên tiêu thụ nguyên văn. Một parser không thể hoàn tất sẽ nêu lý do trong error của đầu ra, và việc phân tích thất bại, nêu tên parser và thông điệp đó; một câu trả lời không phải là một ParseOutput theo mã hóa này — một câu trả lời viết dưới dạng JSON, hoặc mang một trường cấp cao nhất mà hình dạng không khai báo — cũng làm việc phân tích thất bại, nêu tên parser và export parse của nó. Một lần phân tích thất bại sẽ dừng một bản build ở vai trò render-verdict, và đến với một importer dưới dạng lỗi mà aggrega_parse_source trả về. Một nguồn bị parser từ chối cũng vậy — một nguồn mà parser trả lời bằng một chẩn đoán halt bên cạnh cây của nó: lời gọi của importer thất bại với thông điệp của từng chẩn đoán như vậy, theo thứ tự của parser, và không bao giờ được trao cây. Khi được gọi trực tiếp bằng aggrega plugin run-local --export parse, một parser được trao payload JSON đã soạn, được chuyển đổi sang mã hóa này — nguồn được viết trong payload đó dưới dạng base64, như JSON viết mọi trường byte — và câu trả lời của nó được đọc theo dạng đầu ra của export và in ra dưới dạng JSON — một câu trả lời không có dạng đó sẽ bị từ chối, nêu tên export, giống như một bản build từ chối nó.
Định nghĩa kiểu. Các kiểu truyền của parser — ParseInput, ParseOutput, NodeSpan và SourceSpan — được công bố trong cả ba gói ABI và được export lại bởi bộ công cụ phát triển plugin của từng ngôn ngữ, được sinh ra từ một codec duy nhất để ba gói luôn đồng bộ. Ví dụ parse của mỗi kit đọc đầu vào và ghi đầu ra theo cách này, và các parser cho HCL, TOML, YAML, JSON và JSON có chú thích đi kèm bên trong tệp nhị phân cũng vậy.
Trạng thái hiện tại: đã có — được điều phối ở vai trò render-verdict cho một artifact ở định dạng mà policy không đọc được một cách tự nhiên, thông qua aggrega_parse_source cho một importer, và để nhận diện định dạng của một lần import không nêu định dạng nào.
Socket importer — đầu ra soạn thảo bản nháp
Một importer biến một nguồn được viết cho công cụ khác — chẳng hạn một luồng xuất từ một trình dựng agent — thành các tệp soạn thảo Aggrega dạng bản nháp. Nó chạy ngoài luồng: aggrega import, phương thức aggrega/import của phiên trình soạn thảo và công cụ import dành cho trợ lý phân giải importer quảng bá định dạng được yêu cầu dưới dạng import:<format> và gọi export import của nó một lần cho mỗi lần import. Một bản build không bao giờ điều phối nó. Importer nào chạy, và người vận hành truyền gì cho nó, được mô tả tại Which importer turns a source into drafts. Các importer riêng của trình biên dịch, mỗi cái cho một định dạng nó đọc, được mô tả tại Core importers: đó là những định dạng nào, mỗi cái đọc gì, soạn nháp gì, các thiết lập nó nhận, 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, và cách một lần import tải về và xác minh một importer mà máy chưa có.
Hình dạng đầu vào (host → guest). Một tài liệu ImportInput mang:
format— định dạng mà lần import yêu cầu, một trong các capabilityimport:<format>của importer, bỏ tiền tố.bytes— các byte nguồn: toàn bộ tệp khi import một tệp, và rỗng khi import một thư mục, khi đó các tệp của thư mục đến dướisources.name— tên của nguồn, không kèm thư mục phía trước, để importer có thể nêu tên nguồn trong những gì nó báo cáo và trong những gì nó phác thảo: khi import một tệp, đó là tên cơ sở của tệp màbytesđược đọc từ đó; khi import một thư mục, đó là tên cơ sở của chính thư mục, được đọc từ đường dẫn đầy đủ của nó, nênaggrega import .chuyển tên của thư mục mà lệnh chạy trong đó, trong khi mỗi tệp của thư mục vẫn đến dưới tên riêng của nó. Vắng mặt khi nguồn không có tên nào để cung cấp.sources— các nguồn có tên, mỗi nguồn mang tên và các byte của nó, trong một danh sách sắp xếp theo tên: với một lần import thư mục, mọi tệp của thư mục mà các mẫu tệp được khai báo của importer chọn, trừ thư mục đầu ra build của workspace, được đặt tên theo đường dẫn phân tách bằng dấu gạch chéo bên trong thư mục; và các tệp mà mụcplugins.importergắn importer này khai báo dướiwith.sources, mỗi tệp dưới tên cơ sở của nó. Một tệp thư mục và một tệpwith.sourcestrùng tên sẽ khiến lần import bị từ chối thay vì để tệp này che tệp kia. Vắng mặt khi không có nguồn nào.settings— đối tượng thiết lập mà mục đó khai báo dướiwith.settings, dưới dạng một tài liệu JSON với các khóa được sắp xếp, được truyền nguyên văn. Vắng mặt khi không có mục nào gắn importer hoặc mục đó không khai báo thiết lập nào.catalog— một góc nhìn về các Components mà catalog riêng của workspace chứa: catalog mà chính importer được chọn từ đó — các thư mục catalog của workspace, hoặc, khi workspace không chỉ định thư mục nào, bản chụp catalog mà registry mặc định của nó công bố, được lưu trên máy này — không tải về gì cho chính góc nhìn đó. Danh sáchcomponentscủa nó chứa một mục cho mỗi tên Component, sắp xếp theo tên; khi catalog chứa nhiều phiên bản của một Component, mục đó mô tả phiên bản mà một tham chiếu nêu tên nó không kèm phiên bản phân giải tới. Mỗi mục mangnamevàversioncủa Component, cáclabelscủa nó, tên các khóa cấp cao nhất mà values và provides của nó khai báo (valuesvàprovides, mỗi cái đã sắp xếp), và cácsocketscủa nó — mỗi cái gồmnamecủa socket vàselectornhãn mà một phụ thuộc nối qua nó phải thỏa mãn — theo thứ tự Component khai báo chúng. Một Component mở rộng Component khác mang cả những gì nó kế thừa lẫn những gì nó khai báo, và các socket kế thừa đứng trước. Góc nhìn chỉ chứa tên, phiên bản, nhãn và selector — không bao giờ có giá trị, giá trị mặc định hay bí mật — và thứ tự của nó cố định, nên một catalog cho ra một chuỗi byte. Vắng mặt khi catalog không chứa Component nào.
Hình dạng đầu ra (guest → host). Một tài liệu ImportOutput mang các thực thể mà lần import tạo ra — mỗi cái là một tham chiếu tới một thực thể catalog có sẵn hoặc một phần thân được soạn nháp — các quyết định ánh xạ đằng sau chúng, các chẩn đoán theo hình dạng Diagnostic dùng chung, các tệp scaffold cần ghi, và một error báo lỗi khi lần import không thể hoàn tất. Mọi trường và ràng buộc của chúng có trong tài liệu tham chiếu schema socket importer được sinh tự động.
Mã hóa trên đường truyền. Cả đầu vào và đầu ra đều được truyền dưới dạng CBOR chuẩn tắc (RFC 8949 §4.2.1). Một guest giải mã đầu vào và mã hóa đầu ra thông qua các điểm vào mà ImportInput và ImportOutput trong kit của nó đã mang sẵn — DecodeCBOR và EncodeCBOR trong Go, decode_cbor và encode_cbor trong Rust, decodeCBORImportInput và encodeCBORImportOutput trong TypeScript — đọc và ghi các byte (Vec<u8> trong Rust, Host.inputBytes() và Host.outputBytes(...) trong TypeScript). Không cần thư viện CBOR nào và không có gì phải tự phân tích byte. settings đi bên trong tài liệu nhị phân dưới dạng các byte của tài liệu JSON của nó, nên guest phân tích nó như JSON để xem bên trong, như trên mọi socket khác. Một importer không thể hoàn tất sẽ nói lý do trong error của đầu ra, và lần import dừng lại, nêu tên importer và thông điệp đó; một câu trả lời không phải là ImportOutput theo mã hóa này — một câu trả lời viết bằng JSON, hoặc mang một trường cấp cao nhất mà hình dạng không khai báo — cũng làm lần import dừng lại, nêu tên importer và export import của nó. Khi được gọi trực tiếp bằng aggrega plugin run-local --export import, importer nhận payload JSON được soạn, chuyển sang mã hóa này, và câu trả lời của nó được đọc theo dạng đầu ra của export và in ra dưới dạng JSON — một câu trả lời không có dạng đó sẽ bị từ chối, nêu tên export, giống như một bản build từ chối nó.
Cách một nguồn thuộc định dạng của bạn được nhận diện. Một lần import có thể không nêu định dạng nào, và khi đó host nhận diện một định dạng từ những gì các importer khai báo, bản thân host không biết định dạng nào. Một importer khai báo trong bản tự báo cáo describe() của nó, dưới importer (một ImporterContract), một danh sách detect gồm các chữ ký mà nhờ đó một nguồn thuộc các định dạng của nó được nhận diện. Mỗi DetectSignature nêu:
syntax— định dạng cú pháp mà nguồn được phân tích theo, một định dạng mà một plugin parser quảng bá dưới dạngparse:<syntax>, chẳng hạnjsonhoặcyaml;files— các mẫu tên tệp tùy chọn, được so khớp với phần cuối tên của nguồn: một đoạn so với tên riêng của tệp, nhiều đoạn phân tách bằng dấu gạch chéo so với chừng ấy đoạn cuối của đường dẫn, với*,?và[...]khớp trong phạm vi một đoạn. Một chữ ký không khai báo mẫu nào áp dụng cho một nguồn là một tệp dù nó tên gì, và không áp dụng cho tệp nào của một thư mục;match— các vị từ mà cây đã phân tích phải thỏa mãn tất cả, mỗi cái là mộtPathMatchvới mộtpathgồm các khóa nối bằng dấu chấm từ gốc cây (một đoạn là số nguyên chọn một vị trí trong mảng), mộtislàpresent,absent,object,array,string,numberhoặcboolean, và tùy chọn một chuỗiequalshoặc một chuỗiprefix— nhiều nhất một trong hai.
Khi một lần import không nêu định dạng, host so khớp các chữ ký của mọi importer mà lần import chọn trong số đó — các importer trong catalog của workspace và các core importers của trình biên dịch — theo thứ tự định danh và phiên bản của chúng: nó phân tích nguồn qua parser mà catalog cung cấp cho một cú pháp — hoặc, với cú pháp mà catalog không cung cấp parser, parser mà chính trình biên dịch mang theo — nhiều nhất một lần cho mỗi cú pháp, đánh giá các vị từ trên cây, và đọc nguồn theo định dạng của importer duy nhất có chữ ký khớp. Đó cũng là parser mà lời gọi aggrega_parse_source của importer được trả lời qua, nên importer đọc nguồn của nó qua đúng parser mà nó được nhận diện qua. Một nguồn không phân tích được theo một cú pháp sẽ không khớp chữ ký nào nêu cú pháp đó; một cú pháp mà cả catalog lẫn trình biên dịch đều không cung cấp parser sẽ dừng việc nhận diện, nêu rõ việc thiếu parser. Một nguồn không khớp chữ ký nào bị từ chối kèm yêu cầu nêu định dạng, và một nguồn được nhận diện là nhiều hơn một định dạng bị từ chối kèm tên các định dạng đó. Một chữ ký nhận diện một nguồn là mọi định dạng mà importer của nó quảng bá, nên một importer muốn nguồn của mình được nhận diện chỉ phục vụ một định dạng, và một importer không khai báo chữ ký nào chỉ được dùng tới khi nêu định dạng của nó.
Thực thể Plugin của importer ghi lại cùng danh sách đó dưới dạng spec.importer.detect, được suy ra từ describe() khi thực thể được tạo từ guest; việc nhận diện đọc bản ghi đó, nên guest không được nạp cho đến khi định dạng của nó được xác định. Việc nạp và phát hành guest sẽ từ chối một guest có báo cáo khác với bản ghi của thực thể, nêu tên importer.detect, và một thực thể không ghi lại gì thì không khẳng định điều gì. Descriptor bị từ chối khi nạp nếu contract được khai báo trên một plugin không phải importer, nếu một chữ ký không nêu cú pháp nào hoặc nêu một mẫu tệp sai định dạng, và nếu một vị từ không nêu đường dẫn nào, nêu một is nằm ngoài bảy giá trị, hoặc nêu cả equals lẫn prefix.
Các core importer của trình biên dịch và ví dụ import của bộ kit Go khai báo chữ ký của chúng theo cách này. Importer Langflow đọc nguồn dưới dạng JSON và yêu cầu một mảng tại data.nodes; importer Flowise yêu cầu các mảng tại nodes và edges và không có gì tại data.nodes; importer n8n yêu cầu một mảng tại nodes, một đối tượng tại connections và không có gì tại edges hay data.nodes; importer MCP khai báo một chữ ký cho mỗi cấu hình client, nêu tên tệp của nó — .mcp.json, claude_desktop_config.json và .cursor/mcp.json, được đọc dưới dạng JSON với một đối tượng tại mcpServers, và .vscode/mcp.json, được đọc dưới dạng JSON có chú thích, như Visual Studio Code đọc nó, với một đối tượng tại servers — và một chữ ký không nêu tệp nào, yêu cầu một chuỗi $schema bắt đầu bằng https://static.modelcontextprotocol.io/schemas/; importer Compose đọc nguồn dưới dạng YAML, nêu tên các tệp mà Compose đọc theo mặc định — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml và bốn tệp override của chúng — và yêu cầu một đối tượng tại services; importer Dify đọc nguồn dưới dạng YAML, không nêu tệp nào, và yêu cầu chuỗi app tại kind cùng một giá trị nào đó tại app.mode và tại version; importer CrewAI nêu tên config/agents.yaml và config/tasks.yaml, được đọc dưới dạng YAML mà không yêu cầu gì ở cây, crew.jsonc và crew.json, được đọc dưới dạng JSON có chú thích với một danh sách tại agents, và agents/*.jsonc cùng agents/*.json, được đọc dưới dạng JSON có chú thích với một giá trị nào đó tại role, nhờ vậy không có hai chữ ký nào khớp cùng một nguồn, và một tệp được nhập riêng lẻ mà không nêu định dạng sẽ được đọc cả dưới dạng YAML lẫn JSON; importer LangGraph nêu tên langgraph.json, được đọc dưới dạng JSON với một đối tượng tại graphs, khai báo một chữ ký không nêu tệp nào, yêu cầu một đối tượng tại graphs và chuỗi https://langgra.ph/schema.json tại $schema, và không nêu tệp môi trường nào, vì việc nhận diện đọc mọi tệp mà các mẫu của bất kỳ importer nào chọn, nên một mẫu nêu tên tệp môi trường sẽ mở các tệp môi trường của mọi thư mục được nhập mà không nêu định dạng; importer Google ADK nêu tên root_agent.yaml, được đọc dưới dạng YAML với một giá trị nào đó tại name và tại instruction, hoặc một chuỗi tại agent_class và một giá trị nào đó tại name, và không nêu tệp nào khác, vì cấu hình của một sub-agent có thể mang bất kỳ tên nào và một mẫu nêu mọi tệp YAML sẽ mở từng tệp của mọi thư mục được nhập mà không nêu định dạng; importer Agent Framework đọc nguồn dưới dạng YAML, không nêu tệp nào, và yêu cầu chuỗi Prompt tại kind cùng một đối tượng tại model; ví dụ import của bộ kit Go đọc nguồn dưới dạng YAML và yêu cầu chuỗi DemoSource tại kind. Trong Go:
Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{ Syntax: "json", Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},}}},Việc nhập một thư mục đọc những gì. Nguồn có thể là một thư mục, và các mẫu tệp mà importer khai báo quyết định những gì nó đọc: host đọc đúng những tệp của thư mục, ở bất kỳ độ sâu nào, được một trong các mẫu files của các chữ ký của importer chọn — mỗi mẫu được khớp với phần cuối đường dẫn phân tách bằng dấu gạch chéo của tệp bên trong thư mục — và chuyển chúng dưới dạng sources theo thứ tự tên, với bytes để trống và tên của chính thư mục làm name. Không tệp nào khác của thư mục được mở. Thư mục mà một lần build của workspace ghi các tệp đã render vào — dist/ bên dưới thư mục gốc của workspace — không được đọc như một phần của thư mục chứa nó: không tệp nào của nó được chuyển hay được nhận diện, và một liên kết dẫn tới nó sẽ bị bỏ qua, nên một thư mục đã được build sẽ được đọc như dự án mà nó chứa, còn một thư mục chính là thư mục đó, hoặc nằm bên trong nó, sẽ được đọc đúng như được chỉ định. Một chữ ký không khai báo mẫu files nào sẽ không chọn tệp nào của thư mục, nên một importer không khai báo mẫu nào sẽ đọc một tệp và từ chối thư mục, và một thư mục không chứa tệp nào mà các mẫu chọn cũng bị từ chối. Thư mục bị giới hạn trong chính nó: một liên kết nằm trong số các tệp sẽ được đọc, hoặc trỏ tới một thư mục, mà dẫn ra ngoài thư mục sẽ bị từ chối trước khi đọc bất cứ thứ gì, một liên kết tới thư mục không bao giờ được đi vào, và một liên kết tới tệp mà không mẫu nào chọn sẽ bị bỏ qua mà không đọc. Việc nhận diện định dạng của một thư mục theo cùng quy tắc — mỗi chữ ký được thử với các tệp mà mẫu của nó chọn, theo thứ tự tên, mỗi tệp được đọc và phân tích nhiều nhất một lần cho mỗi cú pháp, và một chữ ký không khai báo mẫu nào không áp dụng cho tệp nào. Host không giới hạn gì: một thư mục quá lớn đối với importer sẽ bị từ chối bởi các giới hạn runtime của chính importer. Không importer nào trong số các importer Langflow, Flowise, n8n, Dify và Agent Framework của trình biên dịch khai báo mẫu files, nên mỗi importer đọc một tệp; importer MCP của nó khai báo tên của bốn cấu hình client, nên nó đọc mọi tệp trong số đó mà thư mục chứa, importer Compose của nó khai báo tám tên tệp Compose, nên nó được chuyển mọi tệp Compose mà thư mục chứa và hợp nhất những tệp mà Compose sẽ đọc; và importer CrewAI của nó khai báo sáu tên mà các khai báo của một dự án CrewAI được ghi dưới đó, nên nó được chuyển các khai báo của dự án và không phần nào của chương trình; và importer LangGraph của nó khai báo langgraph.json, nên nó được chuyển cấu hình của ứng dụng và không phần nào của mã hay các tệp môi trường, một tệp môi trường chỉ đến được với nó qua with.sources của phần đính kèm; và importer Google ADK của nó khai báo root_agent.yaml, nên nó được chuyển cấu hình root agent của ứng dụng và không phần nào của mã hay tệp môi trường, các cấu hình mà sub-agent của nó nêu tên chỉ đến được với nó qua with.sources của phần đính kèm.
Định nghĩa kiểu. Các kiểu wire của importer — ImportInput, ImportSource, CatalogProjection, CatalogComponent, CatalogSocket, ImportOutput cùng các dạng thực thể, quyết định và scaffold mà nó mang — được phát hành trong cả ba gói ABI và được xuất lại bởi bộ công cụ phát triển plugin của mỗi ngôn ngữ, được sinh ra từ một codec duy nhất để ba gói luôn đồng bộ, và các kiểu nhận diện ImporterContract, DetectSignature và PathMatch mà bản tự báo cáo describe mang cũng vậy. Gói importer của bộ kit Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer, mang mọi thứ một importer làm bất kể định dạng, và các core importer của trình biên dịch, tất cả đều được xây dựng trên nó, đọc đầu vào và ghi đầu ra theo cách này.
Importer được xây dựng trên bộ kit Go chấm điểm dựa trên những gì. Bộ chấm điểm của kit cân nhắc mỗi nút nguồn với các Components của view catalog và không gì khác: các ứng viên là catalog của chính workspace — Components của một catalog doanh nghiệp cũng y như của thư viện chuẩn — và kit không mang ứng viên nào của riêng nó. Với mỗi Component, nó đọc tên, danh mục mà nhãn component.aggrega.ai/category mang, các nhãn, và tên các khóa mà values của nó khai báo; các khóa provides và socket của nó không được cân nhắc. Một Component được thêm vào catalog sẽ là ứng viên ở lần nhập tiếp theo, mà không cần build lại importer nào. Khi view vắng mặt, vì catalog không chứa Component nào, không nút nào có ứng viên: không nút nào được tham chiếu hay gợi ý, và mọi nút mà bản nháp cấp cho một Component riêng đều được soạn nháp. Mọi importer chấm điểm thông qua kit đều chấm điểm theo cách này — trong đó có các importer Langflow, Flowise, n8n và Compose của trình biên dịch, còn importer MCP của nó không cân nhắc ứng viên nào; một importer không dùng kit sẽ đọc view theo cách nó chọn.
Một importer xây dựng trên Go kit đọc các socket của một nền tảng để làm gì. Các socket không có trọng số nào trong điểm số, nhưng kit đọc chúng để bố trí một bản nháp. Một định dạng có các luồng mà một nền tảng chạy đúng như khi được viết — như luồng của Langflow, Flowise và n8n — theo mặc định được soạn nháp thành một instance của Component của nền tảng đó mang luồng, và mỗi phần của luồng được nối vào socket đầu tiên, theo thứ tự mà mục catalog của nền tảng liệt kê các sockets của nó, có selector được các nhãn của Component của phần đó thỏa mãn, theo các nhãn mà view mang. Chỉ selector và các nhãn được đọc, và selector được so khớp bằng một hàm do importer cung cấp, vì kit không mang ngữ pháp selector riêng nào; khi view không chứa Component nào mang tên của nền tảng, không phần nào được nối. Các importer lõi mô tả bản nháp mà các importer Langflow, Flowise và n8n của trình biên dịch tạo ra theo cách này, và thiết lập layout để thay vào đó soạn nháp mỗi node thành một Component riêng.
Trạng thái hiện tại: đã có — được điều phối bởi aggrega import và bởi cùng thao tác đó trên phiên trình soạn thảo và công cụ dành cho trợ lý.
Tiêu chí đặt vị trí: socket linter so với các vai trò phán quyết quản trị
Hai trong số các socket được mô tả có bề mặt tương tự nhau — cả hai đều phát ra kết quả theo từng quy tắc — nhưng khác nhau về vị trí trong pipeline và ngữ nghĩa chặn. Tiêu chí để quyết định socket nào đảm nhận một kiểm tra cụ thể:
- Các vai trò phán quyết quản trị (trong luồng, dừng bản build). Dành cho các chính sách dừng bản build: một phán quyết
haltdừng pipeline biên dịch và bản build không tạo ra artifact nào. Các trường hợp sử dụng là những chính sách mà việc vi phạm khiến đầu ra không an toàn để áp dụng: các cổng tuân thủ (vị trí ranh giới PCI / SOC2), các bất biến về cấu trúc liên kết (ingress zero-trust, xác thực xuyên ranh giới), hình dạng luồng thông tin xác thực (không có secret dạng văn bản thuần trong IR), v.v. Một chính sách suy luận trên đồ thị IR (ir-verdict, trước khi render) hoặc trên các artifact đã render (render-verdict, sau khi render). - Socket linter (ngoài luồng, CI / IDE, mang tính tư vấn). Dành cho các kiểm tra thực hành tốt nhất và khả năng khám phá: các quy tắc mà việc vi phạm là đáng ngờ nhưng không gây mất an toàn — secret mồ côi, tham số không được dùng, từ vựng nhãn đã lỗi thời, mức độ đầy đủ của tag để phân bổ chi phí, sai lệch so với quy ước đặt tên. Lỗi tạo ra đầu ra mang tính tư vấn; bản build vẫn tạo ra artifact.
Tiêu chí đặt vị trí diễn đạt thành một quy tắc duy nhất: nếu kiểm tra cần dừng bản build, nó thuộc về một vai trò phán quyết quản trị; nếu kiểm tra cần cảnh báo tác giả hoặc người review mà không chặn pipeline, nó thuộc về socket linter.
Cả hai đều có thể dùng ngay hôm nay. Socket linter chạy publishing-linter thông qua aggrega lint; các vai trò phán quyết quản trị được điều phối trong luồng trong khi chạy aggrega build khi một workspace gắn một plugin vai trò phán quyết. Lưu ý rằng một vai trò phán quyết có các mức độ nghiêm trọng riêng — bản thân một chính sách có thể phát ra các phán quyết warn và info để tư vấn mà không dừng — vì vậy ranh giới giữa dừng và tư vấn ở trên là hướng dẫn đặt vị trí cho toàn bộ các kiểm tra, không phải khẳng định rằng một chính sách chỉ có thể dừng. Xem trang về socket quản trị để biết mô hình mức độ nghiêm trọng.
Tham chiếu chéo
policy-socket.md— phần trình bày đầy đủ về governance socket: bốn vai trò, 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 policy cho một trong hai engine đi kèm trong trình biên dịch, cách bọc một policy engine bên ngoài, và các guest 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: 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.10-status.md#compilation-pipeline-phases— phân loại plugin pipeline trên trang Status (mức độ sẵn sàng của runtime cho pipeline plugin Wasm).architecture/04-entity-taxonomy.md§“Domain 3: Infrastructure Base” — Nguyên tắc Plugin hai phần cho các FeatureRecipes thông tin xác thực (mẫu Fetcher + Injector).architecture/13-catalog-and-registry.md— phân loại OCI bắt đầu bằng phân đoạn provider.entities/featurerecipe.md— bề mặt soạn thảopipeline:của FeatureRecipe.when-to-use-a-pipeline-step.md— hướng dẫn lựa chọn: một bước pipeline so với một FeatureRecipe dùng template.templates/expansion-matrix.md— các quy tắc đánh giá template của khốipipeline:with:trong plugin pipeline và ngữ nghĩa truy cập.steps.examples/04-secrets.md— cấu trúc pipeline Fetcher + Injector mà một FeatureRecipe thông tin xác thực có thể có.errors/error-translation.md— nguyên tắc dịch lỗi mà các plugin guest tham gia.