Client

III struct and connection management

Overview

The III struct is the main entry point for the SDK. It manages WebSocket connections to the III Engine, handles function registration, and provides methods for invoking remote functions.

Creating a Client

III::new

Create a new III client with default worker metadata.

pub fn new(address: &str) -> Self

address · &str · required

WebSocket address of the III Engine (e.g., ws://localhost:49134)

III · III

A new III client instance

Example:

use iii_sdk::III;

let iii = III::new("ws://localhost:49134");

III::with_metadata

Create a new III client with custom worker metadata.

pub fn with_metadata(address: &str, metadata: WorkerMetadata) -> Self

address · &str · required

WebSocket address of the III Engine

metadata · WorkerMetadata · required

Custom metadata describing this worker (runtime, version, name, OS)

Example:

use iii_sdk::{III, WorkerMetadata};

let metadata = WorkerMetadata {
    runtime: "rust".to_string(),
    version: "0.4.1".to_string(),
    name: "my-worker".to_string(),
    os: "linux x86_64".to_string(),
    telemetry: None,
};

let iii = III::with_metadata("ws://localhost:49134", metadata);

Connection Management

connect

Connect to the III Engine and start the message loop.

pub async fn connect(&self) -> Result<(), IIIError>

Result · Result<(), IIIError>

Returns Ok(()) on successful connection, or an error if connection fails

Example:

let iii = III::new("ws://localhost:49134");
iii.connect().await?;

The connect method spawns a background task that maintains the WebSocket connection. If the connection is lost, it will automatically reconnect with exponential backoff.

shutdown_async

Shutdown the client and flush all pending telemetry data.

pub async fn shutdown_async(&self)

Example:

iii.shutdown_async().await;

When the otel feature is enabled, this method waits for all spans, metrics, and logs to be exported before returning. Use this instead of the deprecated shutdown() method to ensure telemetry is not lost.

Configuration

address

Get the WebSocket address this client connects to.

pub fn address(&self) -> &str

Example:

let addr = iii.address();
println!("Connected to: {}", addr);

set_metadata

Set custom worker metadata (must be called before connect).

pub fn set_metadata(&self, metadata: WorkerMetadata)

metadata · WorkerMetadata · required

Worker metadata to register with the engine

set_otel_config

Set OpenTelemetry configuration (requires otel feature, must be called before connect).

#[cfg(feature = "otel")]
pub fn set_otel_config(&self, config: OtelConfig)

config · OtelConfig · required

OpenTelemetry configuration including service name, metrics settings, etc.

Example:

#[cfg(feature = "otel")]
{
    use iii_sdk::{III, OtelConfig};
    
    let iii = III::new("ws://localhost:49134");
    
    let otel_config = OtelConfig {
        enabled: Some(true),
        service_name: Some("my-service".to_string()),
        metrics_enabled: Some(true),
        logs_enabled: Some(true),
        ..Default::default()
    };
    
    iii.set_otel_config(otel_config);
    iii.connect().await?;
}

Types

WorkerMetadata

Metadata about a worker that is registered with the engine.

pub struct WorkerMetadata {
    pub runtime: String,
    pub version: String,
    pub name: String,
    pub os: String,
    pub telemetry: Option<WorkerTelemetryMeta>,
}

Default Implementation:

The default implementation auto-detects:

• Runtime: "rust"
• Version: SDK version from Cargo.toml
• Name: "{hostname}:{pid}"
• OS: System architecture and family
• Telemetry: Language locale from environment

IIIError

Error types returned by SDK operations.

pub enum IIIError {
    NotConnected,
    Timeout,
    Remote { code: String, message: String },
    Handler(String),
    Serde(String),
    WebSocket(String),
}

See Also

• Functions API - Register and handle function invocations
• Invocation API - Call remote functions
• Telemetry API - Configure OpenTelemetry