> ## Documentation Index > Fetch the complete documentation index at: https://motiadev-add-real-system-tutorial-round-2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Rust SDK > API reference for the iii SDK for Rust. ## Installation ```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} 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. ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} 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** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} set_headers(headers: HashMap) ``` #### Parameters | Name | Type | Required | Description | | --------- | ------------------------- | -------- | ----------- | | `headers` | `HashMap` | 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** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} 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`](#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`](#shutdown) is used to join the thread. **Signature** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} 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** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} register_function(registration: R) -> FunctionRef ``` #### Parameters | Name | Type | Required | Description | | -------------- | ---- | -------- | ----------- | | `registration` | `R` | Yes | - | #### Example ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} 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 { 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** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} register_function_with(message: RegisterFunctionMessage, handler: H) -> FunctionRef ``` #### Parameters | Name | Type | Required | Description | | --------- | ----------------------------------------------------- | -------- | ----------- | | `message` | [`RegisterFunctionMessage`](#registerfunctionmessage) | Yes | - | | `handler` | `H` | Yes | - | ### register\_service Register a service with the engine. **Signature** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} register_service(message: RegisterServiceMessage) ``` #### Parameters | Name | Type | Required | Description | | --------- | --------------------------------------------------- | -------- | ------------------------------------------------------------------ | | `message` | [`RegisterServiceMessage`](#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** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} register_trigger_type(registration: RegisterTriggerType) -> TriggerTypeRef ``` #### Parameters | Name | Type | Required | Description | | -------------- | ------------------------------ | -------- | ----------- | | `registration` | `RegisterTriggerType` | Yes | - | #### Example ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} let my_trigger = iii.register_trigger_type( RegisterTriggerType::new("my-trigger", "My custom trigger", MyHandler) .trigger_request_format::() .call_request_format::(), ); // Compile-time safe: config must be MyConfig, function input must be MyRequest my_trigger.register_function("my::handler", |req: MyRequest| -> Result { 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** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} unregister_trigger_type(id: impl Into) ``` #### Parameters | Name | Type | Required | Description | | ---- | ------------------- | -------- | ----------- | | `id` | `impl Into` | Yes | - | ### register\_trigger Bind a trigger configuration to a registered function. **Signature** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} register_trigger(input: RegisterTriggerInput) -> Result ``` #### Parameters | Name | Type | Required | Description | | ------- | ---------------------- | -------- | ------------------------------------------------------------------------------------------- | | `input` | `RegisterTriggerInput` | Yes | Trigger registration input with trigger\_type, function\_id, config, and optional metadata. | #### Example ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} 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** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} async trigger(request: impl Into) -> Result ``` #### Parameters | Name | Type | Required | Description | | --------- | ----------------------------------------------- | -------- | ----------- | | `request` | impl Into\<[`TriggerRequest`](#triggerrequest)> | Yes | - | #### Example ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} // 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** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} 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** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} async create_channel(buffer_size: Option) -> Result ``` #### Parameters | Name | Type | Required | Description | | ------------- | --------------- | -------- | ----------- | | `buffer_size` | `Option` | 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** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} info(message: &str, data: Option) ``` #### Parameters | Name | Type | Required | Description | | --------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message` | `&str` | Yes | Human-readable log message. | | `data` | `Option` | 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 ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} logger.info("Order processed", Some(json!({ "order_id": "ord_123", "status": "completed" }))); ``` ### warn Log a warning-level message. **Signature** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} warn(message: &str, data: Option) ``` #### Parameters | Name | Type | Required | Description | | --------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message` | `&str` | Yes | Human-readable log message. | | `data` | `Option` | 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 ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} logger.warn("Retry attempt", Some(json!({ "attempt": 3, "max_retries": 5, "endpoint": "/api/charge" }))); ``` ### error Log an error-level message. **Signature** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} error(message: &str, data: Option) ``` #### Parameters | Name | Type | Required | Description | | --------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message` | `&str` | Yes | Human-readable log message. | | `data` | `Option` | 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 ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} logger.error("Payment failed", Some(json!({ "order_id": "ord_123", "gateway": "stripe", "error_code": "card_declined" }))); ``` ### debug Log a debug-level message. **Signature** ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} debug(message: &str, data: Option) ``` #### Parameters | Name | Type | Required | Description | | --------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message` | `&str` | Yes | Human-readable log message. | | `data` | `Option` | 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 ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} logger.debug("Cache lookup", Some(json!({ "key": "user:42", "hit": false }))); ``` ## Types [`InitOptions`](#initoptions) · [`IIIError`](#iiierror) · [`IIIConnectionState`](#iiiconnectionstate) · [`TriggerRequest`](#triggerrequest) · [`TriggerAction`](#triggeraction) · [`HttpInvocationConfig`](#httpinvocationconfig) · [`HttpAuthConfig`](#httpauthconfig) · [`HttpMethod`](#httpmethod) · [`Channel`](#channel) · [`ChannelReader`](#channelreader) · [`ChannelWriter`](#channelwriter) · [`ChannelDirection`](#channeldirection) · [`StreamChannelRef`](#streamchannelref) · [`FunctionInfo`](#functioninfo) · [`FunctionRef`](#functionref) · [`TriggerInfo`](#triggerinfo) · [`WorkerInfo`](#workerinfo) · [`WorkerMetadata`](#workermetadata) · [`Trigger`](#trigger) · [`RegisterFunctionMessage`](#registerfunctionmessage) · [`RegisterServiceMessage`](#registerservicemessage) · [`OtelConfig`](#otelconfig) · [`ReconnectionConfig`](#reconnectionconfig) ### InitOptions Configuration options passed to \[`register_worker`]. | Name | Type | Required | Description | | ---------- | -------------------------------------------- | -------- | --------------------------------------------------------- | | `metadata` | Option\<[`WorkerMetadata`](#workermetadata)> | No | Custom worker metadata. Auto-detected if `None`. | | `headers` | `Option>` | No | Custom HTTP headers sent during the WebSocket handshake. | | `otel` | Option\<[`OtelConfig`](#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 }` | 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`](#triggeraction)> | No | - | | `timeout_ms` | `Option` | 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`](#httpmethod) | Yes | - | | `timeout_ms` | `Option` | No | - | | `headers` | `HashMap` | Yes | - | | `auth` | Option\<[`HttpAuthConfig`](#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`](#channelwriter) | Yes | - | | `reader` | [`ChannelReader`](#channelreader) | Yes | - | | `writer_ref` | [`StreamChannelRef`](#streamchannelref) | Yes | - | | `reader_ref` | [`StreamChannelRef`](#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\>, [`IIIError`](#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\, [`IIIError`](#iiierror)> | Yes | Read the entire stream into a single `Vec`. | | `close` | async fn() -> Result\<(), [`IIIError`](#iiierror)> | Yes | - | ### ChannelWriter WebSocket-backed writer for streaming binary data and text messages. | Name | Type | Required | Description | | -------------- | -------------------------------------------------------------- | -------- | ----------- | | `write` | async fn(data: &\[u8]) -> Result\<(), [`IIIError`](#iiierror)> | Yes | - | | `send_message` | async fn(msg: \&str) -> Result\<(), [`IIIError`](#iiierror)> | Yes | - | | `close` | async fn() -> Result\<(), [`IIIError`](#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`](#channeldirection) | Yes | - | ### FunctionInfo Function information returned by `engine::functions::list` | Name | Type | Required | Description | | ----------------- | ---------------- | -------- | ----------- | | `function_id` | `String` | Yes | - | | `description` | `Option` | No | - | | `request_format` | `Option` | No | - | | `response_format` | `Option` | No | - | | `metadata` | `Option` | 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` | No | Arbitrary metadata attached to the trigger. | ### WorkerInfo Worker information returned by `engine::workers::list` | Name | Type | Required | Description | | -------------------- | ---------------- | -------- | ----------- | | `id` | `String` | Yes | - | | `name` | `Option` | No | - | | `runtime` | `Option` | No | - | | `version` | `Option` | No | - | | `os` | `Option` | No | - | | `ip_address` | `Option` | No | - | | `status` | `String` | Yes | - | | `connected_at_ms` | `u64` | Yes | - | | `function_count` | `usize` | Yes | - | | `functions` | `Vec` | 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` | No | - | | `telemetry` | `Option` | No | - | ### Trigger Handle returned by [`III::register_trigger`](#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` | No | - | | `request_format` | `Option` | No | - | | `response_format` | `Option` | No | - | | `metadata` | `Option` | No | - | | `invocation` | Option\<[`HttpInvocationConfig`](#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` | No | - | | `parent_service_id` | `Option` | No | - | | `to_message` | `fn() -> Message` | Yes | - | ### OtelConfig Configuration for OpenTelemetry initialization | Name | Type | Required | Description | | ------------------------------- | ---------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | `Option` | No | - | | `service_name` | `Option` | No | - | | `service_version` | `Option` | No | - | | `service_namespace` | `Option` | No | - | | `service_instance_id` | `Option` | No | - | | `engine_ws_url` | `Option` | No | - | | `metrics_enabled` | `Option` | No | - | | `metrics_export_interval_ms` | `Option` | No | - | | `reconnection_config` | Option\<[`ReconnectionConfig`](#reconnectionconfig)> | No | - | | `shutdown_timeout_ms` | `Option` | No | Timeout in milliseconds for the shutdown sequence (default: 10,000) | | `channel_capacity` | `Option` | 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` | No | Whether to enable the log exporter (default: true) | | `logs_flush_interval_ms` | `Option` | No | Log processor flush delay in milliseconds. Defaults to 100ms when not set. | | `logs_batch_size` | `Option` | No | Maximum number of log records exported per batch. Defaults to 1 when not set. | | `fetch_instrumentation_enabled` | `Option` | 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` | 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. |