Struct IIIClient 

pub struct IIIClient { /* private fields */ }

WebSocket client for communication with the III Engine.

Create with register_worker.

Implementations

impl IIIClient

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

Create a new III with default worker metadata (auto-detected runtime, os, hostname)

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

Create a new III with custom worker metadata

pub fn address(&self) -> &str

Get the engine WebSocket address this client connects to.

pub fn set_metadata(&self, metadata: WorkerMetadata)

Set custom worker metadata (call before connect)

pub fn set_headers(&self, headers: HashMap<String, String>)

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

pub fn set_otel_config(&self, config: OtelConfig)

Set OpenTelemetry configuration (call before connect)

pub fn shutdown(&self)

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. OpenTelemetry is flushed inside the connection thread before it exits.

pub async fn shutdown_async(&self)

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. The OpenTelemetry flush (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.

pub fn register_function( &self, id: impl Into<String>, registration: RegisterFunction, ) -> FunctionRef

Register a function with the engine.

Argument order matches the Node and Python SDKs: (id, registration).

Arguments

• id: Function identifier.
• registration: Built via RegisterFunction::new, RegisterFunction::new_async, or RegisterFunction::http. Chain .description(...), .metadata(...), .request_format(...), .response_format(...) as needed.

Panics

Panics if id is empty or already registered.

Examples

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

#[derive(Deserialize, JsonSchema)]
struct Input { name: String }
#[derive(Serialize, JsonSchema)]
struct Output { message: String }

async fn greet(input: Input) -> Result<Output, Error> {
    Ok(Output { message: format!("Hello, {}!", input.name) })
}

let worker = register_worker("ws://localhost:49134", InitOptions::default());
worker.register_function(
    "greetings::greet",
    RegisterFunction::new_async(greet).description("Greets a user"),
);

Registration metadata stays on the builder, so the no-metadata path remains clean:

worker.register_function(
    "orders::create",
    RegisterFunction::new_async(|input: Value| async move { Ok(input) })
        .metadata(json!({"owner": "billing-team", "priority": "high"})),
);

Untyped handler taking serde_json::Value:

worker.register_function(
    "debug::echo",
    RegisterFunction::new_async(|input: Value| async move { Ok(json!({"echo": input})) }),
);

HTTP-invoked function:

let config = HttpInvocationConfig {
    url: "https://example.com/invoke".into(),
    method: HttpMethod::Post,
    timeout_ms: Some(30_000),
    headers: HashMap::new(),
    auth: None,
};
worker.register_function("ext::lambda", RegisterFunction::http(config));

pub fn register_trigger_type<H, C, R>( &self, trigger_type: RegisterTriggerType<H, C, R>, ) -> TriggerTypeRef<C, R>

where H: TriggerHandler + 'static,

Register a custom trigger type with the engine.

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

Examples

let my_trigger = worker.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, iii_sdk::Error> {
    Ok(serde_json::json!({ "data": req.data }))
});
my_trigger.register_trigger("my::handler", MyConfig { url: "/hook".into() });

pub fn unregister_trigger_type(&self, id: impl Into<String>)

Unregister a previously registered trigger type.

pub fn register_trigger( &self, input: RegisterTriggerInput, ) -> Result<Trigger, Error>

Bind a trigger configuration to a registered function.

Arguments

• input - Trigger registration input with trigger_type, function_id, and config.

Examples

let trigger = worker.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();

pub async fn trigger( &self, request: impl Into<TriggerRequestWithMetadata>, ) -> Result<Value, Error>

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.

Examples

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

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

// Enqueue
let receipt = worker.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?;

// Metadata
worker.trigger(
    TriggerRequest {
        function_id: "audit::write".to_string(),
        payload: json!({"event": "checkout"}),
        action: Some(TriggerAction::Void),
        timeout_ms: None,
    }
    .metadata(json!({"tenant": "acme"})),
).await?;

pub fn get_connection_state(&self) -> IIIConnectionState

Get the current connection state.

Trait Implementations

impl Clone for IIIClient

fn clone(&self) -> IIIClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.