Rust SDK

Installation

cargo add iii-sdk

Initialization

Create and return a connected SDK instance. The WebSocket connection is established automatically in a background Tokio task.

use iii_sdk::{register_worker, InitOptions};

let iii = register_worker("ws://localhost:49134", InitOptions::default());

Methods

shutdown

Shutdown the III client.

This stops the connection loop and sends a shutdown signal. If the otel feature is enabled, this will spawn a background task to flush telemetry data, but does NOT wait for it to complete. For guaranteed telemetry flush, use shutdown_async() instead.

Signature

shutdown()

shutdown_async

Shutdown the III client and flush all pending telemetry data.

This method stops the connection loop and sends a shutdown signal. When the otel feature is enabled, it additionally awaits the OpenTelemetry flush, ensuring all spans, metrics, and logs are exported before returning.

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(message: RegisterFunctionMessage, handler: H) -> FunctionRef

Parameters

Example

use iii_sdk::{register_worker, InitOptions, RegisterFunctionMessage};
use serde_json::{json, Value};
let iii = register_worker("ws://localhost:49134", InitOptions::default());
iii.register_function(
    RegisterFunctionMessage {
        id: "greet".to_string(),
        description: None,
        request_format: None,
        response_format: None,
        metadata: None,
        invocation: None,
    },
    |input: Value| async move {
        Ok(json!({"message": format!("Hello, {}!", input["name"])}))
    },
);

register_service

Register a service with the engine.

Signature

register_service(message: RegisterServiceMessage)

Parameters

register_trigger_type

Register a custom trigger type with the engine.

Signature

register_trigger_type(id: impl Into<String>, description: impl Into<String>, handler: H)

Parameters

unregister_trigger_type

Unregister a previously registered trigger type.

Signature

unregister_trigger_type(id: impl Into<String>)

Parameters

register_trigger

Bind a trigger configuration to a registered function.

Signature

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

Parameters

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" }),
})?;
// 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

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: "enqueue".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

list_functions

List all registered functions from the engine

Signature

async list_functions() -> Result<Vec<FunctionInfo>, IIIError>

on_functions_available

Subscribe to function availability events Returns a guard that will unsubscribe when dropped

Signature

on_functions_available(callback: F) -> FunctionsAvailableGuard

Parameters

list_workers

List all connected workers from the engine

Signature

async list_workers() -> Result<Vec<WorkerInfo>, IIIError>

list_triggers

List all registered triggers from the engine

Signature

async list_triggers(include_internal: bool) -> Result<Vec<TriggerInfo>, IIIError>

Parameters

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

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

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

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

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

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].

IIIError

Errors returned by the III SDK.

IIIConnectionState

Connection state for the III WebSocket client

TriggerRequest

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

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.

HttpInvocationConfig

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

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.

HttpMethod

Channel

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

ChannelReader

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

ChannelWriter

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

ChannelDirection

StreamChannelRef

FunctionInfo

Function information returned by engine::functions::list

FunctionRef

TriggerInfo

Trigger information returned by engine::triggers::list

WorkerInfo

Worker information returned by engine::workers::list

WorkerMetadata

Worker metadata for auto-registration

Trigger

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

RegisterFunctionMessage

RegisterServiceMessage

OtelConfig

Configuration for OpenTelemetry initialization

ReconnectionConfig

Configuration for WebSocket reconnection behavior