Creating a New Built-in Plugin
Use plugins/otlp-exporter/, builtin-artifacts.json, and the registry plugin provisioner as the source of truth. Built-in plugins are standalone Golem applications. Development uses local WASMs; tagged releases publish immutable assets in golemcloud/golem-builtins and generate a checksum-pinned release manifest.
Workflow
- Create
plugins/<plugin>/as a standalone workspace and Golem application. Follow the OTLP exporter layout and its scopedAGENTS.md. - Select dependencies from current workspace/plugin manifests rather than copying old versions. For an oplog processor, use the current
golem-rustpath andexport_oplog_processorfeature plus the exact asyncwit-bindgensetup used by the OTLP exporter. - Implement the current async SDK interface. The essential shape is:
use golem_rust::bindings::golem::api::oplog::{OplogEntry, OplogIndex};
use golem_rust::oplog_processor::exports::golem::api::oplog_processor::Guest as OplogProcessorGuest;
use golem_rust::schema::wit::wire::{AgentId, ComponentId};
impl OplogProcessorGuest for MyPluginComponent {
async fn process(
_account_info: golem_rust::oplog_processor::exports::golem::api::oplog_processor::AccountInfo,
config: Vec<(String, String)>,
component_id: ComponentId,
worker_id: AgentId,
metadata: golem_rust::oplog_processor::host::AgentMetadata,
_first_entry_index: OplogIndex,
entries: Vec<OplogEntry>,
) -> Result<(), String> {
todo!()
}
}
golem_rust::oplog_processor::export_oplog_processor!(MyPluginComponent with_types_in golem_rust::oplog_processor);
- Add a
copycustom command to a component template's release preset and apply that template to the component. Template variables are rendered only in component templates, not directly in components. Writeplugins/<plugin>.wasmfrom the final artifact selected bycomponentWasm. Use{{ cargoTarget }}/wasm32-wasip2/release/<crate_name>.wasmas the source so the command follows the resolved compiler Cargo target directory. Resolve the destination with{{ appRootDir }}and quote both paths. Follow the template custom command pattern inbuiltin-tools/bash/golem.yaml. - Extend
build-pluginsinMakefile.toml. Keep it as duckscript, resolve the local binary throughCARGO_MAKE_CRATE_TARGET_DIRECTORY, and pass--yesto everygolem buildinvocation. Never hardcodetarget/or usecargo metadatain the task. - Run
cargo make build-plugins. Confirm the generated destination exists, is non-empty, changed when expected, and validates withwasm-tools validate --features all plugins/<plugin>.wasm. Do not commit it. - Add one
BuiltinPluginDescriptorentry with component name, artifact ID, plugin name, version, and description. Add the component name, output path, build task, and transitive source inputs under that artifact ID inbuiltin-artifacts.json. - Run
cargo make ensure-builtin-artifactsand verify local provisioning. Publication happens during tagged release preparation, not before merging development changes.
Do not add per-plugin fields, bytes, or paths to BuiltinPluginsConfig; it only selects Enabled or Disabled. Do not add include_bytes! or commit generated WASMs. Bootstrap calls the descriptor-driven provisioner once through the shared artifact cache.
Provisioning and Grants
The shared provisioner creates or finds the built-in owner's golem-system application and builtin-plugins environment, uploads or hash-updates every descriptor component, deploys once, and idempotently registers each plugin. Existing registration by the same name/version is accepted. Existing environments are not iterated during provisioning: EnvironmentService::create grants every plugin owned by the built-in-plugin owner transactionally to each new environment, and built-in grants cannot be deleted.
If changing this behavior, update focused service/integration tests. Tests that invoke Cargo, Golem, or another compiler as a subprocess belong specifically in the CLI integration test suite; unit, worker-executor, and non-CLI integration tests must not spawn them. Implement the current contract directly; backward-compatibility paths remain prohibited until the repository-wide policy is revised.
Verification
cargo make build-pluginswasm-tools validate --features all plugins/<plugin>.wasmcargo check -p golem-registry-servicecargo make integration-tests-group7for built-in plugin provisioning/grant behavior (the authoritative task; it runsotlp_pluginandpluginsserially)- Inspect
git diff -- plugins builtin-artifacts.json Makefile.toml golem-registry-service; confirm the generated WASM is ignored. Loadpublishing-builtin-artifactswhen preparing a tagged release.