Build PluginsDynamic PluginsgRPC WorkerRust

gRPC Worker Plugins (Rust)

View as Markdown

Use the nemo-relay-worker crate to build an out-of-process Rust plugin. The SDK implements the grpc-v1 service, exchanges JSON envelopes with Relay, handles cancellation, and provides typed registration and host-runtime helpers. Refer to gRPC Worker Plugin Concepts to compare the Rust, Python, and command worker runtimes.

Create the Project

Create a binary Rust project with the following Cargo.toml file:

1[package]
2name = "examples-rust-worker"
3version = "0.1.0"
4edition = "2024"
5
6[dependencies]
7nemo-relay-worker = "0.5.0"
8tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Implement the Worker

Add the following implementation to src/main.rs:

1use nemo_relay_worker::{Json, PluginContext, Result, WorkerPlugin, serve_plugin};
2
3struct ExampleWorker;
4
5impl WorkerPlugin for ExampleWorker {
6    fn plugin_id(&self) -> &str {
7        "examples.rust_worker"
8    }
9
10    fn validate(&self, config: &Json) -> Vec<nemo_relay_worker::ConfigDiagnostic> {
11        let _ = config;
12        Vec::new()
13    }
14
15    fn register(&self, context: &mut PluginContext, _config: &Json) -> Result<()> {
16        context.register_subscriber("example", |event| {
17            let _ = event.name();
18        });
19        Ok(())
20    }
21}
22
23#[tokio::main]
24async fn main() -> Result<()> {
25    serve_plugin(ExampleWorker).await
26}

Relay provides the worker and host endpoints, activation ID, plugin ID, and activation token through environment variables. The Rust SDK derives plugin identity from WorkerPlugin::plugin_id(); custom launchers can use NEMO_RELAY_PLUGIN_ID. serve_plugin consumes the endpoints and activation credentials and runs until Relay requests shutdown. Do not start the worker directly for normal operation.

Package the Worker

Create relay-plugin.toml with the following content. The artifact digest must match the executable that operators receive:

1manifest_version = 1
2
3[plugin]
4id = "examples.rust_worker"
5kind = "worker"
6
7[compat]
8relay = ">=0.5,<1.0"
9worker_protocol = "grpc-v1"
10
11[defaults]
12enabled = false
13
14[capabilities]
15items = ["plugin_worker"]
16
17[source]
18artifact = "target/release/examples-rust-worker"
19
20[integrity]
21sha256 = "sha256:<artifact-sha256>"
22
23[load]
24runtime = "rust"
25entrypoint = "target/release/examples-rust-worker"

Build the executable with the following command:

$cargo build --release

Calculate the SHA-256 digest of the executable with the following command: This command requires Python 3.

Use the following PowerShell command on Windows:

1$artifact = ".\\target\\release\\examples-rust-worker.exe"
2$hash = (Get-FileHash -Algorithm SHA256 $artifact).Hash.ToLower()
3"sha256:$hash"

Replace sha256:<artifact-sha256> with the output before you register the plugin. On Windows, use the .exe artifact name in source.artifact, load.entrypoint, and the digest command.

Register the Worker

Register, enable, and validate the worker with the following commands:

$nemo-relay plugins add ./relay-plugin.toml
$nemo-relay plugins enable examples.rust_worker
$nemo-relay plugins validate examples.rust_worker