Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Panduan pengembang plugin Wasm

Ini adalah panduan kanonis untuk menulis plugin WebAssembly (Wasm) Aggrega dan menerbitkannya sebagai entitas katalog. Panduan ini mengajarkan kontrak penulis plugin dari awal hingga akhir: apa itu plugin, bagaimana plugin mendeskripsikan dirinya kepada host, cara menulis ekspor dan klaim kapabilitasnya, batas runtime dan fungsi host yang diterapkan host, entitas Plugin yang membawa plugin ke dalam katalog, bagaimana sebuah Recipe atau FeatureRecipe mereferensikan plugin, serta siklus hidup publish→pull→build yang membawa plugin dari berkas .wasm di disk menjadi artefak terverifikasi yang disematkan dengan digest dan dikonsumsi oleh build.

Halaman pendamping plugin-contract.md mendokumentasikan soket — titik-titik pipeline tempat plugin terpasang serta bentuk input/output yang dikonsumsi dan dihasilkan setiap soket. Panduan ini mendokumentasikan plugin — entitasnya, permukaan kapabilitasnya, dan siklus hidupnya. Baca halaman kontrak untuk mengetahui soket mana yang ditargetkan plugin Anda; baca halaman ini untuk mengetahui cara menulis dan mengirimkannya.

Untuk rute praktis melalui seluruh tugas alih-alih referensinya, menulis sebuah provider membangun satu guest provider kecil dari awal hingga akhir — deskriptor, build, entitas, pemasangan, dan render yang keluarannya dapat Anda baca — termasuk penolakan yang biasanya ditemui draf pertama dan cara membacanya.

1. Apa itu plugin Wasm

Plugin Wasm adalah modul WebAssembly yang memperluas compiler pada socket yang telah ditentukan. Biner host Go tidak berisi logika khusus cloud maupun logika infrastruktur; seluruh kecerdasan khusus domain — rendering templat, penerjemahan format, evaluasi kebijakan, linting — berada di dalam plugin. Host mengorkestrasi pipeline dan meneruskan payload setiap socket melintasi batas ABI ke guest; guest mengerjakan pekerjaan domain dan mengembalikan bentuk hasil socket tersebut. Payload dan hasil setiap socket dikirim sebagai CBOR kanonis, dengan dua pengecualian: plugin CLI menerima vektor argumennya sebagai teks JSON dan menjawab dengan kode keluar serta teks yang dialirkannya, dan laporan diri describe berupa teks JSON. Bagian setiap socket dalam kontrak plugin menyatakan pengodeannya, dan guest membaca serta menulisnya melalui titik masuk yang sudah dimiliki tipe payload dari kit-nya, sehingga tidak ada guest yang mengurai byte secara manual.

Plugin berjalan di balik firewall kemurnian ahead-of-time. Host memuat dan mengeksekusi modul melalui runtime Wasm tertanam dengan konfigurasi yang menolak semua kapabilitas: tanpa socket jaringan, tanpa sistem berkas, tanpa environment, stdio dibuang, dan jam dinding yang dapat diamati dibekukan pada satu instan yang invarian terhadap build. Setiap panggilan I/O yang dicoba guest gagal di batas panggilan, sehingga plugin tidak dapat menjangkau state runtime. Tulislah plugin dengan memperhatikan firewall ini: plugin mentransformasi payload yang diberikan kepadanya dan mengembalikan hasil yang dikonsumsi host apa adanya, dan determinisme adalah tanggung jawab Anda — input yang identik harus menghasilkan byte output yang identik. Satu-satunya saluran resmi untuk konten jarak jauh adalah pengambilan input eksternal yang dimediasi host (Bagian 4), yang menyajikan byte dengan disiplin yang dipatok pada digest alih-alih memberi guest akses jaringan langsung.

Socket yang dapat dituju plugin — di antaranya gerbang mutasi pada konstruksi topologi, gerbang validasi pada analisis statis, pipeline FeatureRecipe, linter di luar jalur utama, dan socket rendering provider — beserta bentuk input/output per socket didokumentasikan di plugin-contract.md. Socket yang dilayani plugin adalah satu nilai yang dideklarasikannya di metadata.pluginType, dan seluruh himpunan nilai yang diterima field tersebut ada pada entri referensinya di entities/plugin.md §“metadata.pluginType”. Contoh dalam panduan ini menggunakan provider (merender node IR menjadi artefak native provider), linter (memeriksa konten yang ditulis dan memunculkan diagnostik), dan pipeline-step (langkah dalam pipeline: milik FeatureRecipe atau Recipe yang menerapkan patch pada himpunan dokumen yang dirender).

Anda menulis guest terhadap host melalui plugin development kit (PDK) tiga bahasa — Go, Rust, atau TypeScript. PDK membungkus toolchain Wasm yang mendasarinya dengan builder bertipe Aggrega untuk bentuk input dan output yang dibawa setiap socket.

2. Laporan diri describe()

Setiap plugin mengekspor fungsi describe() yang mengembalikan laporan diri plugin tersebut: jenis soket yang diimplementasikannya, versi ABI yang ditargetkannya, kapabilitas yang diklaimnya — dibaca sesuai jenis soket, sehingga berupa nama kapabilitas untuk provider atau langkah pipeline dan format sumber berprefiks untuk parser atau importer — fungsi host yang diimpornya, serta kapabilitas per ekspor dari setiap titik masuk yang ditawarkannya. describe() adalah keterangan plugin itu sendiri tentang apa dirinya dan apa yang dilakukannya.

Laporan diri ini adalah jangkar model kepercayaan. Entitas Plugin yang membawa plugin ke dalam katalog (Bagian 5) menyatakan kembali fakta yang sama sebagai klaim yang ditulis, dan host memeriksa silang klaim entitas tersebut terhadap keluaran describe() plugin pada dua saat — saat publikasi, sebelum byte apa pun masuk ke registri, dan saat pemuatan, sebelum plugin dijalankan. Ketidakcocokan menghentikan proses secara eksplisit. Entitas adalah permukaan yang dapat dibaca manusia dan terlihat di katalog; describe() adalah sumber resmi berbasis mesin yang menjadi acuan verifikasi host. Tulislah keduanya agar selaras; pemeriksaan silang ini ada justru untuk menangkap kasus ketika keduanya menyimpang. Pemeriksaan ini memeriksa apa yang diklaim entitas, bukan apa yang dihilangkannya: entitas yang mengklaim lebih sedikit daripada yang dilaporkan biner — misalnya entitas yang tertinggal setelah build ulang yang menambahkan sebuah export — tetap dimuat, meskipun tidak lagi menjelaskan semua yang dilakukan biner.

3. Menulis export dan klaim kapabilitasnya

Sebuah plugin menawarkan satu atau beberapa export — titik masuk bernama yang menjadi tujuan dispatch dari host (misalnya render_node, lint_naming, step). Setiap export membawa blok kapabilitas: klaim penulis tentang apa yang dilakukan export tersebut. Kapabilitas sebuah export memiliki empat field:

  • name — nama ABI export, yaitu nama yang menjadi tujuan dispatch dari host. Wajib.
  • operates — operasi pipeline yang dilakukan export: patch (mengubah dokumen hasil render yang sudah ada) atau emit (menambahkan dokumen baru). Ini adalah klaim kapabilitas yang dideklarasikan. Host memeriksa silang klaim ini terhadap laporan diri describe() plugin saat publish dan saat load, sehingga klaim yang ditulis pada entitas dan keterangan plugin sendiri harus sesuai. Ini adalah klaim tervalidasi tentang export, bukan sakelar dispatch: saat render, operasi yang benar-benar dilakukan sebuah step dibawa oleh hasil yang dikembalikan guest, bukan dipilih dari field ini. Jika tidak ada, tidak ada klaim operasi.
  • scope — akar dokumen tempat export beroperasi: own (dokumen hasil render milik node itu sendiri) atau host (dokumen milik komponen tempat FeatureRecipe dengan cakupan komponen dilampirkan). Sebelum plugin sebuah pipeline step dijalankan, host membaca cakupan export yang dideklarasikan step tersebut dan memastikan bahwa provider yang me-render dokumen cakupan itu tercantum dalam spec.pipelineStep.capabilities plugin (Bagian 5) — export bercakupan own diperiksa terhadap provider yang me-render dokumen milik node itu sendiri, export bercakupan host terhadap provider komponen host, dan cakupan kosong dianggap own untuk pemeriksaan ini. Inilah gerbang kompatibilitas provider, yang dijalankan sebelum step; dokumen yang benar-benar disentuh oleh operasi guest disebutkan per operasi dalam hasil yang dikembalikan guest, bukan dipilih dari field yang dideklarasikan ini. Jika tidak ada, defaultnya adalah own.
  • selector — deskripsi bebas yang dapat dibaca manusia tentang apa yang menjadi sasaran export (misalnya workloads carrying a pod template). Ini adalah dokumentasi bagi pembaca katalog dan permukaan aggrega inspect; compiler tidak menafsirkannya.

Tulislah export dalam urutan yang Anda inginkan untuk dibaca; entri mempertahankan urutan penulis pada entitas dan di inspect. Plugin tanpa export yang ditulis tidak mendeklarasikan permukaan export — hal ini sah untuk plugin yang socket-nya tidak memerlukan klaim kapabilitas per export.

4. Batas runtime dan fungsi host

Entitas plugin dapat membawa blok runtime opsional yang membatasi cara host memuat dan menjalankan plugin.

Batas memori dan waktu. maxMemoryPages membatasi memori linear plugin dalam halaman Wasm (64 KiB per halaman); timeoutMs membatasi berapa lama kode plugin itu sendiri boleh berjalan selama satu panggilan, dalam milidetik. Waktu yang dihabiskan di dalam fungsi host yang dipanggil plugin tidak dihitung. Di Linux, ukurannya adalah waktu prosesor dari thread yang menjalankan guest, sehingga waktu yang dihabiskan guest untuk menunggu prosesor pada mesin yang sibuk juga tidak dihitung; pada sistem lain, ukurannya adalah waktu yang berlalu. Panggilan pertama ke plugin yang baru dimuat juga menghitung inisialisasi satu kali runtime bahasa guest, yang berjalan di dalam panggilan tersebut. Kedua batas bersifat opsional dengan nilai bawaan: nol atau tidak ada berarti batas bawaan platform berlaku. Loader membatasi setiap plugin pada batas bawaan platform ketika entitas tidak mendeklarasikan batas, sehingga pemuatan tidak pernah tanpa batas dan panggilan selalu dapat dibatalkan. Naikkan batas pada entitas ketika sebuah lampiran benar-benar membutuhkan lebih banyak memori atau waktu daripada yang diizinkan nilai bawaan.

Fungsi host. hostFunctions mencatat nama-nama fungsi host yang diimpor plugin. Ini adalah field yang diturunkan mesin — jangan menuliskannya. aggrega plugin sync membaca fungsi host langsung dari bagian impor .wasm dan mencatat field tersebut di file entitas untuk Anda, dan publish menurunkannya ulang dari biner serta menolak entitas yang catatannya berbeda; sehingga plugin mendapatkan tepat fungsi host yang benar-benar diimpor binernya, divalidasi terhadap allowlist yang dikurasi (impor di luar allowlist ditolak secara tegas). Catatan tersebut adalah snapshot dari biner yang dipublikasikan, sama seperti referensi plugin: yang dialamatkan berdasarkan konten adalah snapshot dari byte yang dipublikasikan: catatan itu mencerminkan biner pada saat publish serta diturunkan ulang dan diverifikasi ketika plugin di-pull. Untuk melihat fungsi host yang diimpor .wasm lokal sebelum dipublikasikan — nilai yang dicatat aggrega plugin sync — jalankan aggrega inspect --plugin <file.wasm>.

Permukaan host yang dikurasi. Tiga fungsi host bersifat umum: aggrega_log (sebuah level dan pesan, dikeluarkan sebagai satu baris log pada tujuan log host), aggrega_emit_warning (sebuah kode, pesan, dan path, dikumpulkan sebagai peringatan terstruktur yang ditampilkan host setelah panggilan), dan aggrega_fetch_external_input (sebuah URL, dijawab dengan byte input berdasarkan disiplin pin di bawah). PDK membungkus ketiganya dalam setiap bahasa — Go: aggrega.Log, aggrega.EmitWarning, aggrega.FetchExternalInput; Rust: log, emit_warning, fetch_external_input; TypeScript: log, emitWarning, fetchExternalInput — sehingga guest memanggil fungsi bertipe alih-alih ABI mentah. Callback sumber dan parse — untuk guest yang membaca potongan dari sumber yang diperoleh atau mendapatkan pohon hasil parse melalui host — beserta encoding yang dibawa slot setiap callback tercantum di plugin-contract.md.

Konten sumber lokal datang melalui host — tidak pernah dari filesystem. Plugin render provider tidak pernah membaca sumbernya dari disk; panggilan filesystem gagal di batas panggilan. Host menyerahkan kepada guest sebuah listing sumber di dalam payload render — path relatif terhadap root sumber dari setiap entri dan apakah entri itu direktori, dalam urutan yang diurutkan, tanpa konten file — lalu guest menerapkan logika tata letaknya sendiri padanya, kemudian membaca kembali tepat file yang dipilihnya melalui callback sumber, yang mengembalikan byte yang dibaca host di bawah root sumber. Bentuk payload per soket dan callback-nya didokumentasikan di plugin-contract.md.

Konten jarak jauh datang melalui pengambilan input eksternal. Plugin yang membutuhkan konten jarak jauh — arsip chart, dokumen skema jarak jauh — memanggil wrapper fetch milik PDK. Pada tingkat wire, guest meneruskan URL ke aggrega_fetch_external_input sebagai teks UTF-8 dan menerima satu balasan dalam CBOR kanonis, yang membawa byte hasil pengambilan secara mentah, atau pesan kesalahan beserta kodenya yang dapat dicocokkan mesin; wrapper mendekode balasan menjadi byte-atau-kesalahan. Byte tiba persis seperti yang diambil, termasuk payload yang bukan UTF-8 valid, dan payload dengan panjang nol dikembalikan sebagai byte kosong, bukan kesalahan. Host melayani URL berdasarkan disiplin pin input eksternal:

  • URL yang sudah di-pin dalam lockfile Release dilayani dari penyimpanan lokal yang dialamatkan berdasarkan konten dan diverifikasi terhadap digest yang tercatat pada setiap pembacaan. Blob yang hilang dari penyimpanan diisi ulang dari jaringan berdasarkan digest yang tercatat — pengisian ulang yang diverifikasi digest tidak dapat mengubah output.
  • URL yang tidak di-pin ditolak, dengan kesalahan yang menyebutkan URL dan cara memperbaikinya. Build merender closure yang dicatat lockfile-nya, sehingga tidak ada build yang mengambil referensi yang tidak di-pin dan tidak ada pengaturan yang memungkinkannya.
  • Pinning terjadi ketika dependensi Release di-resolve: aggrega pull merender Release untuk mengetahui input eksternal mana yang diminta render-nya, mengambil masing-masing, dan mencatatnya di lockfile di samping pin dependensi. Jadi, siklus kerja penulis plugin adalah resolve sekali, lalu build secara offline sesering yang Anda mau.

Skema yang diizinkan adalah https, http hanya ke host loopback, dan oci (di-pin berdasarkan digest manifest). Lockfile mencatat setiap input yang di-pin — URL-nya, digest sha256, ukuran, dan plugin yang membutuhkannya — sehingga build ulang melayani byte yang sama dari penyimpanan lokal: dapat direproduksi, dan offline setelah di-pin.

Dengan PDK Go:

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

Apa yang gagal, dan mengapa.

  • Panggilan filesystem atau jaringan gagal di batas panggilan: guest tidak memiliki direktori yang dibuka sebelumnya dan tidak memiliki soket. Ini berlaku untuk setiap jalur kode, termasuk dependensi pustaka yang mencoba membaca file — bacalah sumber melalui callback sumber sebagai gantinya.
  • Impor di bawah modul di luar wasi_snapshot_preview1, extism:host/env, dan extism:host/user gagal saat dimuat, dengan diagnostik yang menyebutkan modul dan impornya. Nama fungsi WASI individual di dalam modul yang diizinkan tidak pernah disensor — impor filesystem dan soket yang tidak digunakan dari runtime bahasa yang ditautkan secara statis tidak masalah, karena menamai impor tidak memberikan apa pun.
  • Pengambilan URL yang tidak di-pin oleh lockfile gagal dengan kesalahan yang menyebutkan URL tersebut; cara memperbaikinya adalah menjalankan aggrega pull --release <release>, yang mem-pin setiap input eksternal yang dikonsumsi render Release, lalu melakukan build.

Tidak ada field allowlist host untuk akses jaringan keluar. Plugin tidak pernah menjangkau jaringan pada waktu build — itulah batas ahead-of-time — sehingga tidak ada field semacam itu untuk dituliskan. Konten jarak jauh tiba melalui saluran input eksternal yang dimediasi host dan di-pin dengan digest di atas, tidak pernah melalui akses jaringan ambien.

Konfigurasi. configKV adalah map string-ke-string yang diserahkan runtime kepada plugin saat mulai. Entri mempertahankan urutan penulis sehingga record yang dikeluarkan identik byte demi byte di setiap run. Jika tidak ada, konfigurasi kosong bawaan runtime tetap berlaku.

5. Entitas Plugin

Sebuah plugin masuk ke katalog sebagai entitas Plugin — permukaan penulisan dan metadata untuk plugin tersebut. Entitas menyatakan apa plugin itu dan menunjuk ke artefak .wasm; compiler tidak menafsirkan perilaku plugin dan meneruskan referensi yang disematkan, sementara runtime Wasm mengeksekusi byte-nya.

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

Field-fieldnya:

  • Tidak ada field lokasi artefak, secara sengaja. Entitas tidak membawa penunjuk ke .wasm dan skema tidak menerimanya. Lokasi artefak sebuah plugin diturunkan dari identitasnya — koordinat metadata.pluginType/metadata.name, yang membentuk path repositori plugin/<pluginType>/<name> — ditambah registry mana pun yang dikonfigurasi untuk workspace, sehingga tidak ada lokasi yang perlu ditulis dan tidak ada yang bisa salah. Digest konten yang telah di-resolve dicatat per Release di lockfile Release tersebut, dan build memverifikasi byte yang diambil terhadapnya: identitas di entitas, byte terverifikasi di lockfile.
  • metadata.version — rilis yang dipublikasikan entitas, yang harus sama dengan versi build-provenance milik guest sendiri sebagaimana dilaporkan dalam describe(). Penulis plugin memberi versi pada .wasm saat build — build mencap versi ke dalam guest, dan build yang mengambilnya dari tag rilis mencap versi rilis hanya pada commit yang dinamai tag tersebut — dan metadata.version milik entitas menamai rilis yang sama itu. Gerbang publikasi memeriksa silang keduanya dan berhenti jika terjadi perbedaan, sehingga entitas selalu menamai versi persis dari biner yang dikirimkannya. aggrega plugin gen-catalog --plugin (di bawah) menyalin versi yang dilaporkan guest ke dalam entitas yang dihasilkannya, yaitu versi rilis ketika guest di-build dari commit yang diberi tag. Wajib.
  • metadata.pluginType — tipe soket yang diimplementasikan plugin ini, diambil dari provider, linter, pipeline-step, governance, cli, parser, dan importer. Sebuah plugin mengimplementasikan tepat satu. Field ini berada di blok pengalamatan di samping name dan version serta menyediakan segmen <pluginType> dari koordinat yang diturunkan. Wajib.
  • spec.abiVersion — versi ABI host/guest yang ditargetkan plugin. v1beta1 adalah nilai yang diterima; revisi ABI di masa depan akan menambahkan nilai yang diterima. Wajib.
  • Blok untuk tipe soket Anda, yang membawa capabilities — sebuah plugin menyatakan apa yang dilayaninya di dalam blok milik metadata.pluginType-nya, dan blok itulah yang menetapkan arti sebuah entri. spec.provider.capabilities menamai kapabilitas yang dilayani sebuah provider (nama kapabilitas seperti helm atau compose). spec.pipelineStep.capabilities menamai provider yang output render-nya kompatibel dengan step Anda. spec.parser.capabilities menamai format sumber yang dibaca sebuah parser, masing-masing ditulis parse:<format>. spec.importer.capabilities menamai format asing yang menjadi dasar sebuah importer menyusun draf entitas, masing-masing ditulis import:<format>. Importer yang ditulis dalam Go dapat mengambil semua hal yang tidak bergantung pada formatnya — penilaian, keputusan untuk mereferensikan atau membuat draf, draf dan rendering-nya, serta pengaturannya — dari paket importer milik kit Go, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer. Plugin linter, governance, atau cli tidak melayani kapabilitas apa pun dan tidak membawa satu pun dari keempat blok tersebut. Entri mempertahankan urutan penulis, dan setiap daftar adalah klaim yang eksplisit dan teruji: nyatakan apa yang benar-benar telah Anda bangun dan uji terhadap plugin, karena konsumen melakukan resolusi terhadap persis apa yang terdaftar. Untuk sebuah pipeline step, klaim itu ditegakkan saat render — ketika sebuah step menyentuh suatu scope, build berhenti kecuali provider yang me-render dokumen scope tersebut termasuk di antara yang diklaim plugin Anda — sehingga daftar kosong tidak cocok dengan provider mana pun dan tidak mengizinkan step di mana pun.
  • spec.signature — penunjuk deskriptif opsional ke tanda tangan yang dilampirkan pada plugin (Bagian 8). Blok ini hanya berupa dokumentasi: blok ini mencatat di mana tanda tangan berada dan bagaimana tanda tangan itu dibuat bagi pembaca katalog; blok ini sendiri tidak mengizinkan plugin. Pemeriksaan yang menegakkan adalah kebijakan kepercayaan per registry yang diterapkan saat pull.
  • spec.runtime — blok batasan eksekusi opsional dari Bagian 4. Penulis menulis maxMemoryPages, timeoutMs, dan configKV; hostFunctions diturunkan oleh mesin dan dicatat oleh aggrega plugin sync, yang diverifikasi oleh publish, bukan ditulis.
  • spec.exports — klaim kapabilitas per export dari Bagian 3 (name, operates, scope, selector).

Menghasilkan entitas dari .wasm Anda. Anda tidak perlu menulis secara manual bagian entitas yang dimiliki mesin. aggrega plugin gen-catalog --plugin <file.wasm> membaca laporan diri describe() milik guest dan menghasilkan entitas Plugin yang siap dipublikasikan darinya, ditambah overlay kecil yang Anda tulis dan sediakan (identitas, batas runtime, dan blok provider apa pun). Generator mencap field yang sumber kebenarannya adalah biner — klaim export, kontrak kapabilitas, cermin perintah, dan catatan fungsi host — dan menyalin metadata.version dari versi build-provenance describe() milik guest, sementara overlay hanya menyediakan apa yang tidak dilaporkan biner. Inilah jalur yang didukung bagi penulis plugin pihak ketiga: build dan beri versi pada .wasm Anda, lalu hasilkan ulang entitas agar field yang dimiliki mesin tetap selaras dengan biner. Versi adalah satu-satunya field salinan yang menamai sebuah rilis alih-alih fakta tentang byte, jadi hasilkan dari build commit yang dinamai tag rilis — atau, jika memulai dari build pengembangan, atur metadata.version ke rilis tersebut di entitas yang dihasilkan sebelum Anda memberi tag pada commit yang membawanya. Guest yang tidak membawa versi build-provenance tidak dapat dihasilkan menjadi entitas berversi — beri versi pada guest saat build terlebih dahulu.

.wasm di samping entitasnya. Selama Anda menulis plugin, belum ada yang dipublikasikan untuk diambil oleh build, sehingga build membaca .wasm plugin dari samping entitas Plugin miliknya dalam direktori katalog, dengan nama yang diturunkan dari tipe plugin dan nama entitas: untuk pipeline-step/patch namanya adalah pipeline-step--patch.wasm. Huruf kecil, angka, dan sebagian besar tanda hubung ditulis ke dalam nama itu apa adanya; karakter lain ditulis dalam bentuk escape, demikian pula tanda hubung di beberapa posisi — sehingga di tempat yang penting, penolakan atas .wasm yang hilang, A plugin’s .wasm is not on this machine (berkas sebuah plugin tidak ada di mesin ini), memberikan nama tersebut secara lengkap. aggrega lint <plugin.yaml> membaca .wasm dari tempat yang sama — di samping berkas entitas yang diberikan kepadanya, di direktori mana pun berkas itu berada — kecuali biner itu sendiri membawa plugin tersebut, dan mencetak pemberitahuan untuk setiap ekspor, kapabilitas, atau kontrak yang dilaporkan .wasm tetapi tidak dicantumkan oleh entitas. Jika tidak ada .wasm di sana, lint menyatakan bahwa ia melewati laporan itu, dengan menyebutkan berkas yang dicarinya dan direktorinya, dan hasilnya tidak berubah.

Untuk referensi field demi field, lihat halaman entitas ../entities/plugin.md.

6. Mereferensikan plugin

Sebuah langkah pipeline atau soket plugin mereferensikan plugin melalui URI entitas Plugin-nya — identitas entitas tersebut, bukan artefak .wasm secara langsung. Entitas adalah lapisan yang membawa pin digest, klaim kapabilitas, batas runtime, dan tanda tangan; dengan mereferensikan entitas, konsumen memperoleh semuanya.

Path .wasm polos atau referensi artefak mentah yang ditulis dalam field plugin ditolak saat pemuatan: tidak ada entitas Plugin yang cocok dengannya, sehingga resolusi plugin gagal secara eksplisit. URI entitas wajib digunakan — indireksi melalui entitas adalah kontraknya, bukan kemudahan opsional. Langkah pipeline FeatureRecipe menyebut entitas tersebut dalam pipeline[].plugin; lihat ../entities/featurerecipe.md untuk permukaan penulisan pipeline.

Ketika dua plugin atau lebih saling terkait — keduanya harus menyepakati kontrak serah terima bersama, seperti pada pasangan Fetcher dan Injector di mana keluaran satu plugin menjadi masukan plugin lainnya (Prinsip Plugin Dua Bagian yang dijelaskan dalam plugin-contract.md) — tulis kontrak tersebut satu kali dan buat setiap plugin bergantung pada definisi tunggal itu, alih-alih menyatakan ulang bentuk serah terima JSON secara terpisah di setiap plugin. Bentuk bersama tersebut adalah struktur JSON yang dipertukarkan plugin, yang dapat ditempatkan dalam satu entri SchemaLibrary yang direferensikan kedua plugin. Satu sumber untuk kontrak menjaga plugin yang terkait tetap selaras seiring kontrak berkembang; pernyataan ulang yang terpisah akan bergeser, dan pergeseran itu baru terlihat ketika keduanya tidak lagi sepakat saat runtime. Rekomendasinya adalah berbagi kontrak, bukan kode Wasm — setiap plugin tetap menjadi artefaknya sendiri.

7. Siklus hidup publish → pull → build

Sebuah plugin berpindah dari berkas .wasm di disk menjadi artefak terverifikasi yang dapat dikonsumsi build melalui tiga tahap.

Publish. aggrega push menerbitkan sebuah entitas Plugin beserta .wasm-nya bersama-sama sebagai satu manifest OCI, yang diberi tag berdasarkan metadata.version: YAML entitas menjadi blob config manifest tersebut dan .wasm ikut sebagai layer dari manifest yang sama. Menerbitkan pasangan ini sebagai satu manifest bertag itulah yang membuat push bersifat atomik — tidak ada jeda waktu ketika satu bagian sudah diterbitkan sementara bagian lainnya belum — dan karena itulah satu tanda tangan atas manifest tersebut mencakup kedua bagian. Kedua bagian diberi nama pada manifest, sehingga klien OCI generik yang menarik tag versi tersebut menulis entitas ke entity.yaml dan berkas eksekusi ke entity.wasm.

Sebelum byte apa pun tersimpan, publish menjalankan pemeriksaannya. Entitas terlebih dahulu dibaca berdasarkan skema Plugin, dengan cara yang sama seperti pemuatan katalog membacanya, sehingga metadata.version yang bukan versi semantik — atau penyimpangan lain apa pun dari skema — ditolak sebelum .wasm dibaca. Kemudian .wasm dimuat dan laporan diri describe()-nya dicocokkan dengan klaim kapabilitas yang ditulis pada entitas — ketidakcocokan menghentikan proses secara tegas, sehingga entitas yang diterbitkan tidak pernah mengklaim apa yang tidak dilaporkan oleh plugin yang dibawanya. Guest yang versi asal-usul build pada describe()-nya membawa tanda -dirty, yang dibubuhkan pada build dari working tree dengan perubahan yang belum di-commit, akan ditolak: versi tersebut merujuk pada commit yang tidak memuat apa yang di-build. Versi pengembangan yang di-build dari sebuah commit (1.0.0-3-g1a2b3c4) dan prarilis (1.0.0-rc.1) dapat diterbitkan. metadata.version yang tercatat dicocokkan dengan versi asal-usul build pada describe() milik guest, dan perbedaan akan menghentikan publish, sehingga keduanya harus sesuai. Kedua penolakan ini diatasi dengan cara yang sama: build plugin dari checkout bersih atas commit yang dirujuk oleh tag rilis, sehingga plugin melaporkan versi rilis itu sendiri — untuk rilis baru, commit entitas bersama sumber yang dirilisnya dan beri tag pada commit tersebut terlebih dahulu. Menyalin versi yang dilaporkan build pengembangan ke dalam entitas bukanlah perbaikan: hal itu menerbitkan build tersebut dengan versi yang tidak dirujuk oleh tag rilis mana pun. Fungsi host yang diimpor oleh .wasm diturunkan dari biner dan dibandingkan dengan catatan yang di-commit di spec.runtime.hostFunctions; perbedaan akan menghentikan publish dan menyebut aggrega plugin sync, yang mencatat ulang field tersebut, karena field itu dimiliki mesin dan publish tidak pernah menulis ulang berkas entitas yang sudah di-commit. Entitas yang diterbitkan membawa catatan fungsi host yang telah dibubuhkan; digest konten .wasm adalah properti dari manifest tempat pasangan tersebut diterbitkan, dan digest itu dicatat untuk konsumen di lockfile Release, bukan ditulis ke dalam entitas.

Pull. aggrega pull me-resolve semua dependensi sebuah Release dan menulis lockfile per Release yang mengunci setiap entitas katalog dan artefak jarak jauh ke sebuah versi dan digest konten. Plugin yang telah diterbitkan di-resolve melalui resolusi dependensi ini; .wasm-nya diambil bersama manifest yang membawanya dan byte-nya diverifikasi terhadap digest konten yang dicatat lockfile. Pull juga menurunkan ulang fungsi host dari .wasm yang telah diverifikasi dan memeriksanya terhadap catatan hostFunctions yang telah dibubuhkan, lalu berhenti jika keduanya tidak sesuai — pemeriksaan pertahanan berlapis di atas penguncian digest yang menangkap biner yang cap-nya tidak dihasilkan dari impornya sendiri. Jika kebijakan kepercayaan registry mewajibkan tanda tangan, tanda tangan entitas diambil dan diverifikasi pada tahap ini dan dicatat sebagai fakta terverifikasi di lockfile (Bagian 8). Verifikasi terjadi saat pull, tidak pernah saat build — build tetap murni ahead-of-time.

Build. aggrega build mengonsumsi plugin yang telah dikunci dan diverifikasi dari dependensi yang telah di-resolve. Compiler meneruskan referensi yang dikunci dengan digest dan runtime Wasm mengeksekusi byte-nya; gerbang pemuatan menjalankan ulang pencocokan describe() serta penegakan fungsi host dan batas runtime sebelum plugin berjalan.

8. Penandatanganan dan kepercayaan

Entitas Plugin ditandatangani persis seperti setiap entitas katalog lainnya: digest manifest ditandatangani dan dilampirkan sebagai referrer OCI. Artefak .wasm tidak ditandatangani secara terpisah, dan tidak memerlukan tanda tangan terpisah — artefak tersebut merupakan sebuah layer dari manifest yang digest-nya ditandatangani, sehingga tanda tangan mencakupnya secara langsung: mengubah .wasm secara tidak sah akan mengubah digest manifest dan merusak tanda tangan.

Penandatanganan bersifat opsional (opt-in) saat publikasi; verifikasi ditegakkan oleh kebijakan kepercayaan per registry saat pull. Registry yang dikonfigurasi untuk mewajibkan tanda tangan akan menghentikan pull ketika tanda tangan yang diwajibkan tidak ada, tidak tepercaya, atau tidak valid. Blok spec.signature pada entitas adalah penunjuk dokumentasi ke lokasi tanda tangan dan cara tanda tangan itu dibuat; blok ini mencatat fakta bagi pembaca katalog dan tidak dengan sendirinya menentukan penerimaan. Penentu penerimaan adalah kebijakan saat pull.

Perintah-perintah beserta flag-nya didokumentasikan bersama antarmuka publikasi dan konsumsi — lihat ../cli/aggrega-sign.md, ../cli/aggrega-push.md, dan ../cli/aggrega-pull.md. Panduan ini tidak mengulang tabel flag; halaman-halaman tersebut merupakan satu-satunya tempat dokumentasi antarmuka perintah.

9. Pemberian versi pada entitas

Entitas Plugin membawa Semantic Version yang ketat di metadata.version. Versi yang telah dipublikasikan tidak dapat diubah: memublikasikan ulang versi yang sudah ada di registry dengan konten yang berbeda akan ditolak di gerbang publikasi.

Ketika Anda mengubah entitas plugin dan memublikasikannya ulang, disiplin publikasi mengklasifikasikan perubahan tersebut terhadap versi yang sebelumnya dipublikasikan dan mengharuskan kenaikan versi sesuai dengannya. Klasifikasinya adalah rubrik kenaikan versi: perubahan yang hanya menyangkut dokumentasi atau komentar adalah PATCH; perubahan yang murni bersifat tambahan (field opsional baru, entri baru) adalah MINOR; penghapusan, penyempitan tipe, atau field yang sebelumnya opsional menjadi wajib adalah MAJOR. Kenaikan versi yang berlebih selalu diizinkan; kenaikan versi yang kurang akan berhenti dengan diagnostik yang menyebutkan kenaikan yang diperlukan. Publikasi pertama sebuah entitas melewati pemeriksaan kenaikan versi dan menampilkan peringatan bahwa tidak ada verifikasi yang dilakukan. Jalankan pemeriksaan sebelum memublikasikan dengan aggrega lint --pre-publish; lihat ../cli/aggrega-lint.md untuk rubrik lengkap dan pengaturan per aturan.

Plugin tidak memiliki permukaan extends, sehingga aturan pewarisan yang mengatur Components dan Features dalam katalog tidak berlaku padanya. Rubrik kenaikan versi dan sifat tidak dapat diubah merupakan disiplin pemberian versi yang mengatur entitas plugin.

10. Referensi silang

  • authoring-a-provider-walkthrough.md — satu guest provider yang dibangun dari awal hingga akhir, dari direktori kosong hingga keluaran yang dirender.
  • plugin-contract.md — titik soket yang ditargetkan oleh plugin dan bentuk masukan/keluaran per soket.
  • policy-socket.md — soket tata kelola secara mendalam: empat perannya, tingkat keparahan putusan, kanal masukan operator, penulisan kebijakan untuk salah satu dari dua mesin yang disertakan di dalam compiler, dan guest kebijakan referensi.
  • core-importers.md — importer milik compiler sendiri, satu untuk setiap format yang dibacanya, yang dibangun di atas paket importer dari kit Go: apa yang dibaca masing-masing, pengaturannya, dan publikasinya bersama setiap rilis compiler.
  • ../compatibility.md — cara kit plugin diberi versi, dan apa yang membuat plugin yang dibangun untuk satu rilis tetap dapat dimuat pada rilis berikutnya.
  • ../entities/plugin.md — referensi entitas Plugin per bidang.
  • ../entities/featurerecipe.md — permukaan penulisan pipeline: pada FeatureRecipe yang mereferensikan plugin melalui URI entitas.
  • ../cli/aggrega-lint.md — linter publikasi, rubrik kenaikan versi, dan penegakan imutabilitas.
  • ../cli/aggrega-inspect.md — memeriksa kapabilitas, batas runtime, dan tanda tangan entitas Plugin.
  • ../cli/aggrega-push.md, ../cli/aggrega-pull.md, ../cli/aggrega-sign.md — permukaan perintah untuk publikasi, konsumsi, dan penandatanganan.