Rust SDK

API reference for the iii SDK for Rust.

Installation

cargo add iii-sdk

Initialization

Create and return a connected SDK instance. The WebSocket connection is established automatically in a dedicated background thread with its own tokio runtime.

Call [III::shutdown] before the end of main to cleanly stop the connection and join the background thread. In Rust the process exits when main returns, terminating all threads — so shutdown() must be called while main is still running.

use iii_sdk::{register_worker, InitOptions};

fn main() {
    let iii = register_worker("ws://localhost:49134", InitOptions::default());
    // register functions, handle events, etc.
    iii.shutdown(); // cleanly stops the connection thread
}

Methods

set_headers

Set custom HTTP headers for the WebSocket handshake (call before connect).

Signature

set_headers(headers: HashMap<String, String>)

Parameters

Name	Type	Required	Description
headers	HashMap<String, String>	Yes	-

shutdown

Shutdown the III client and wait for the connection thread to finish.

This stops the connection loop, sends a shutdown signal, and joins the background connection thread. When the otel feature is enabled, telemetry is flushed inside the connection thread before it exits.

Signature

shutdown()

shutdown_async

Shutdown the III client.

This stops the connection loop and sends a shutdown signal, but it does not join connection_thread.

Unlike shutdown, this method does not block to wait for run_connection() to finish, making it safe to call from an async context without stalling the executor. When the otel feature is enabled, telemetry::shutdown_otel() still runs inside the connection thread after run_connection() returns, so it may not complete unless shutdown is used to join the thread.

Signature

async shutdown_async()

register_function

Register a function with the engine.

Pass a closure/async fn for local execution, or an [HttpInvocationConfig] for HTTP-invoked functions (Lambda, Cloudflare Workers, etc.).

Signature

register_function(registration: R) -> FunctionRef

Parameters

Name	Type	Required	Description
registration	R	Yes	-

Example

use iii_sdk::{register_worker, InitOptions, RegisterFunction};
use serde::Deserialize;
use schemars::JsonSchema;

#[derive(Deserialize, JsonSchema)]
struct Input { name: String }
fn greet(input: Input) -> Result<String, String> {
    Ok(format!("Hello, {}!", input.name))
}

let iii = register_worker("ws://localhost:49134", InitOptions::default());
iii.register_function(RegisterFunction::new("greet", greet));

register_function_with

Register a function with a message and handler directly.

Signature

register_function_with(message: RegisterFunctionMessage, handler: H) -> FunctionRef

Parameters

Name	Type	Required	Description
message	RegisterFunctionMessage	Yes	-
handler	H	Yes	-

register_service

Register a service with the engine.

Signature

register_service(message: RegisterServiceMessage)

Parameters

Name	Type	Required	Description
message	RegisterServiceMessage	Yes	Service registration message with id, name, and optional metadata.

register_trigger_type

Register a custom trigger type with the engine.

Returns a [TriggerTypeRef] handle that can register triggers and functions with compile-time validated types.

Signature

register_trigger_type(registration: RegisterTriggerType<H, C, R>) -> TriggerTypeRef<C, R>

Parameters

Name	Type	Required	Description
registration	RegisterTriggerType<H, C, R>	Yes	-

Example

let my_trigger = iii.register_trigger_type(
    RegisterTriggerType::new("my-trigger", "My custom trigger", MyHandler)
        .trigger_request_format::<MyConfig>()
        .call_request_format::<MyRequest>(),
);

// Compile-time safe: config must be MyConfig, function input must be MyRequest
my_trigger.register_function("my::handler", |req: MyRequest| -> Result<serde_json::Value, String> {
    Ok(serde_json::json!({ "data": req.data }))
});
my_trigger.register_trigger("my::handler", MyConfig { url: "/hook".into() });

unregister_trigger_type

Unregister a previously registered trigger type.

Signature

unregister_trigger_type(id: impl Into<String>)

Parameters

Name	Type	Required	Description
id	impl Into<String>	Yes	-

register_trigger

Bind a trigger configuration to a registered function.

Signature

register_trigger(input: RegisterTriggerInput) -> Result<Trigger, IIIError>

Parameters

Name	Type	Required	Description
input	RegisterTriggerInput	Yes	Trigger registration input with trigger_type, function_id, config, and optional metadata.

Example

let trigger = iii.register_trigger(RegisterTriggerInput {
    trigger_type: "http".to_string(),
    function_id: "greet".to_string(),
    config: json!({ "api_path": "/greet", "http_method": "GET" }),
    metadata: None,
})?;
// Later...
trigger.unregister();

trigger

Invoke a remote function.

The routing behavior depends on the action field of the request:

• No action: synchronous — waits for the function to return.
• [TriggerAction::Enqueue] - async via named queue.
• [TriggerAction::Void] — fire-and-forget.

Signature

async trigger(request: impl Into<TriggerRequest>) -> Result<Value, IIIError>

Parameters

Name	Type	Required	Description
request	impl Into<TriggerRequest>	Yes	-

Example

// Synchronous
let result = iii.trigger(TriggerRequest {
    function_id: "greet".to_string(),
    payload: json!({"name": "World"}),
    action: None,
    timeout_ms: None,
}).await?;

// Fire-and-forget
iii.trigger(TriggerRequest {
    function_id: "notify".to_string(),
    payload: json!({}),
    action: Some(TriggerAction::Void),
    timeout_ms: None,
}).await?;

// Enqueue
let receipt = iii.trigger(TriggerRequest {
    function_id: "iii::durable::publish".to_string(),
    payload: json!({"topic": "test"}),
    action: Some(TriggerAction::Enqueue { queue: "test".to_string() }),
    timeout_ms: None,
}).await?;

get_connection_state

Get the current connection state.

Signature

get_connection_state() -> IIIConnectionState

create_channel

Create a streaming channel pair for worker-to-worker data transfer.

Returns a Channel with writer, reader, and their serializable refs that can be passed as fields in invocation data to other functions.

Signature

async create_channel(buffer_size: Option<usize>) -> Result<Channel, IIIError>

Parameters

Name	Type	Required	Description
buffer_size	Option<usize>	No	-

Logger

Structured logger that emits logs as OpenTelemetry LogRecords.

Every log call automatically captures the active trace and span context, correlating your logs with distributed traces without any manual wiring. When OTel is not initialized, Logger gracefully falls back to the tracing crate.

Pass structured data as the second argument to any log method. Using a serde_json::Value object of key-value pairs (instead of string interpolation) lets you filter, aggregate, and build dashboards in your observability backend.

info

Log an info-level message.

Signature

info(message: &str, data: Option<Value>)

Parameters

Name	Type	Required	Description
message	&str	Yes	Human-readable log message.
data	Option<Value>	No	Structured context attached as OTel log attributes. Use serde_json::json! objects to enable filtering and aggregation in your observability backend (e.g. Grafana, Datadog, New Relic).

Example

logger.info("Order processed", Some(json!({ "order_id": "ord_123", "status": "completed" })));

warn

Log a warning-level message.

Signature

warn(message: &str, data: Option<Value>)

Parameters

Name	Type	Required	Description
message	&str	Yes	Human-readable log message.
data	Option<Value>	No	Structured context attached as OTel log attributes. Use serde_json::json! objects to enable filtering and aggregation in your observability backend (e.g. Grafana, Datadog, New Relic).

Example

logger.warn("Retry attempt", Some(json!({ "attempt": 3, "max_retries": 5, "endpoint": "/api/charge" })));

error

Log an error-level message.

Signature

error(message: &str, data: Option<Value>)

Parameters

Name	Type	Required	Description
message	&str	Yes	Human-readable log message.
data	Option<Value>	No	Structured context attached as OTel log attributes. Use serde_json::json! objects to enable filtering and aggregation in your observability backend (e.g. Grafana, Datadog, New Relic).

Example

logger.error("Payment failed", Some(json!({ "order_id": "ord_123", "gateway": "stripe", "error_code": "card_declined" })));

debug

Log a debug-level message.

Signature

debug(message: &str, data: Option<Value>)

Parameters

Name	Type	Required	Description
message	&str	Yes	Human-readable log message.
data	Option<Value>	No	Structured context attached as OTel log attributes. Use serde_json::json! objects to enable filtering and aggregation in your observability backend (e.g. Grafana, Datadog, New Relic).

Example

logger.debug("Cache lookup", Some(json!({ "key": "user:42", "hit": false })));

Types

InitOptions · IIIError · IIIConnectionState · TriggerRequest · TriggerAction · HttpInvocationConfig · HttpAuthConfig · HttpMethod · Channel · ChannelReader · ChannelWriter · ChannelDirection · StreamChannelRef · FunctionInfo · FunctionRef · TriggerInfo · WorkerInfo · WorkerMetadata · Trigger · RegisterFunctionMessage · RegisterServiceMessage · OtelConfig · ReconnectionConfig

InitOptions

Configuration options passed to [register_worker].

Name	Type	Required	Description
metadata	Option<WorkerMetadata>	No	Custom worker metadata. Auto-detected if None.
headers	Option<HashMap<String, String>>	No	Custom HTTP headers sent during the WebSocket handshake.
otel	Option<OtelConfig>	No	OpenTelemetry configuration. Requires the otel feature.

IIIError

Errors returned by the III SDK.

Name	Type	Required	Description
NotConnected	unit	Yes	-
Timeout	unit	Yes	-
Runtime	(String)	Yes	-
Remote	{ code: String, message: String, stacktrace: Option<String> }	Yes	-
Handler	(String)	Yes	-
Serde	(String)	Yes	-
WebSocket	(String)	Yes	-

IIIConnectionState

Connection state for the III WebSocket client

Name	Type	Required	Description
Disconnected	unit	Yes	-
Connecting	unit	Yes	-
Connected	unit	Yes	-
Reconnecting	unit	Yes	-
Failed	unit	Yes	-

TriggerRequest

Request object for trigger(). Matches the Node/Python SDK signature: trigger({ function_id, payload, action?, timeout_ms? })

Name	Type	Required	Description
function_id	String	Yes	-
payload	Value	Yes	-
action	Option<TriggerAction>	No	-
timeout_ms	Option<u64>	No	-

TriggerAction

Routing action for [TriggerRequest]. Determines how the engine handles the invocation.

• Enqueue — Routes through a named queue for async processing.
• Void — Fire-and-forget, no response.

Name	Type	Required	Description
Enqueue	{ queue: String }	Yes	Routes the invocation through a named queue.
Void	unit	Yes	Fire-and-forget routing.

HttpInvocationConfig

Configuration for registering an HTTP-invoked function (Lambda, Cloudflare Workers, etc.) instead of a local handler.

Name	Type	Required	Description
url	String	Yes	-
method	HttpMethod	Yes	-
timeout_ms	Option<u64>	No	-
headers	HashMap<String, String>	Yes	-
auth	Option<HttpAuthConfig>	No	-

HttpAuthConfig

Authentication configuration for HTTP-invoked functions.

• Hmac — HMAC signature verification using a shared secret.
• Bearer — Bearer token authentication.
• ApiKey — API key sent via a custom header.

Name	Type	Required	Description
Hmac	{ secret_key: String }	Yes	-
Bearer	{ token_key: String }	Yes	-
ApiKey	{ header: String, value_key: String }	Yes	-

HttpMethod

Name	Type	Required	Description
Get	unit	Yes	-
Post	unit	Yes	-
Put	unit	Yes	-
Patch	unit	Yes	-
Delete	unit	Yes	-

Channel

A streaming channel pair for worker-to-worker data transfer.

Name	Type	Required	Description
writer	ChannelWriter	Yes	-
reader	ChannelReader	Yes	-
writer_ref	StreamChannelRef	Yes	-
reader_ref	StreamChannelRef	Yes	-

ChannelReader

WebSocket-backed reader for streaming binary data and text messages.

Name	Type	Required	Description
on_message	async fn(callback: F)	Yes	Register a callback for text messages received on this channel.
next_binary	async fn() -> Result<Option<Vec<u8>>, IIIError>	Yes	Read the next binary chunk from the channel. Text messages are dispatched to registered callbacks. Returns None when the stream is closed.
read_all	async fn() -> Result<Vec<u8>, IIIError>	Yes	Read the entire stream into a single Vec<u8>.
close	async fn() -> Result<(), IIIError>	Yes	-

ChannelWriter

WebSocket-backed writer for streaming binary data and text messages.

Name	Type	Required	Description
write	async fn(data: &[u8]) -> Result<(), IIIError>	Yes	-
send_message	async fn(msg: &str) -> Result<(), IIIError>	Yes	-
close	async fn() -> Result<(), IIIError>	Yes	-

ChannelDirection

Name	Type	Required	Description
Read	unit	Yes	-
Write	unit	Yes	-

StreamChannelRef

Name	Type	Required	Description
channel_id	String	Yes	-
access_key	String	Yes	-
direction	ChannelDirection	Yes	-

FunctionInfo

Function information returned by engine::functions::list

Name	Type	Required	Description
function_id	String	Yes	-
description	Option<String>	No	-
request_format	Option<Value>	No	-
response_format	Option<Value>	No	-
metadata	Option<Value>	No	-

FunctionRef

Name	Type	Required	Description
id	String	Yes	-
unregister	fn()	Yes	-

TriggerInfo

Trigger information returned by engine::triggers::list

Name	Type	Required	Description
id	String	Yes	-
trigger_type	String	Yes	-
function_id	String	Yes	-
config	Value	Yes	-
metadata	Option<Value>	No	Arbitrary metadata attached to the trigger.

WorkerInfo

Worker information returned by engine::workers::list

Name	Type	Required	Description
id	String	Yes	-
name	Option<String>	No	-
runtime	Option<String>	No	-
version	Option<String>	No	-
os	Option<String>	No	-
ip_address	Option<String>	No	-
status	String	Yes	-
connected_at_ms	u64	Yes	-
function_count	usize	Yes	-
functions	Vec<String>	Yes	-
active_invocations	usize	Yes	-

WorkerMetadata

Worker metadata for auto-registration

Name	Type	Required	Description
runtime	String	Yes	-
version	String	Yes	-
name	String	Yes	-
os	String	Yes	-
pid	Option<u32>	No	-
telemetry	Option<WorkerTelemetryMeta>	No	-

Trigger

Handle returned by III::register_trigger. Call unregister to remove the trigger from the engine.

Name	Type	Required	Description
unregister	fn()	Yes	Remove this trigger from the engine.

RegisterFunctionMessage

Name	Type	Required	Description
id	String	Yes	-
description	Option<String>	No	-
request_format	Option<Value>	No	-
response_format	Option<Value>	No	-
metadata	Option<Value>	No	-
invocation	Option<HttpInvocationConfig>	No	-
with_id	fn(name: String) -> Self	Yes	-
with_description	fn(description: String) -> Self	Yes	-
to_message	fn() -> Message	Yes	-

RegisterServiceMessage

Name	Type	Required	Description
id	String	Yes	-
name	String	Yes	-
description	Option<String>	No	-
parent_service_id	Option<String>	No	-
to_message	fn() -> Message	Yes	-

OtelConfig

Configuration for OpenTelemetry initialization

Name	Type	Required	Description
enabled	Option<bool>	No	-
service_name	Option<String>	No	-
service_version	Option<String>	No	-
service_namespace	Option<String>	No	-
service_instance_id	Option<String>	No	-
engine_ws_url	Option<String>	No	-
metrics_enabled	Option<bool>	No	-
metrics_export_interval_ms	Option<u64>	No	-
reconnection_config	Option<ReconnectionConfig>	No	-
shutdown_timeout_ms	Option<u64>	No	Timeout in milliseconds for the shutdown sequence (default: 10,000)
channel_capacity	Option<usize>	No	Capacity of the internal telemetry message channel (default: 10,000). This controls the in-flight message buffer between exporters and the WebSocket connection loop. Intentionally larger than ReconnectionConfig::max_pending_messages to absorb bursts during normal operation while limiting stale data across reconnects.
logs_enabled	Option<bool>	No	Whether to enable the log exporter (default: true)
logs_flush_interval_ms	Option<u64>	No	Log processor flush delay in milliseconds. Defaults to 100ms when not set.
logs_batch_size	Option<usize>	No	Maximum number of log records exported per batch. Defaults to 1 when not set.
fetch_instrumentation_enabled	Option<bool>	No	Whether to auto-instrument outgoing HTTP calls. When Some(true) (default), execute_traced_request() can be used to create CLIENT spans for reqwest requests. Set Some(false) to opt out. None is treated as true.

ReconnectionConfig

Configuration for WebSocket reconnection behavior

Name	Type	Required	Description
initial_delay_ms	u64	Yes	-
max_delay_ms	u64	Yes	-
backoff_multiplier	f64	Yes	-
jitter_factor	f64	Yes	-
max_retries	Option<u64>	No	-
max_pending_messages	usize	Yes	Maximum messages preserved across reconnects. Messages beyond this limit are dropped to prevent delivering stale data after a long disconnect. This is intentionally smaller than OtelConfig::channel_capacity (the in-flight buffer between exporters and the WebSocket loop).
effective_initial_delay_ms	fn() -> u64	Yes	Returns initial_delay_ms, clamped to a minimum of 1ms to prevent division by zero.