iii-sdk

Rust SDK for the iii engine.

Install

Add to your Cargo.toml:

[dependencies]
iii-sdk = "0.3"
serde_json = "1"
tokio = { version = "1", features = ["full"] }

Hello World

use iii_sdk::{register_worker, InitOptions, TriggerRequest};
use serde_json::{json, Value};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let iii = register_worker("ws://localhost:49134", InitOptions::default());

    iii.register_function("greet", |input: Value| async move {
        let name = input.get("name").and_then(|v| v.as_str()).unwrap_or("world");
        Ok(json!({ "message": format!("Hello, {name}!") }))
    });

    iii.register_trigger("http", "greet", json!({
        "api_path": "/greet",
        "http_method": "POST"
    }))?;

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

    println!("result: {result}");
    Ok(())
}

API

register_worker() spawns a background task that handles WebSocket communication, automatic reconnection, and OpenTelemetry instrumentation.

Registering Functions

use serde_json::{json, Value};

iii.register_function("orders.create", |input: Value| async move {
    let item = input["body"]["item"].as_str().unwrap_or("");
    Ok(json!({ "status_code": 201, "body": { "id": "123", "item": item } }))
});

Registering Triggers

iii.register_trigger("http", "orders.create", json!({
    "api_path": "/orders",
    "http_method": "POST"
}))?;

Invoking Functions

use iii_sdk::{TriggerRequest, TriggerAction};
use serde_json::json;

// Synchronous -- waits for the result
let result = iii.trigger(TriggerRequest {
    function_id: "orders.create".to_string(),
    payload: json!({ "body": { "item": "widget" } }),
    action: None,
    timeout_ms: None,
}).await?;

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

// Async via named queue
iii.trigger(TriggerRequest {
    function_id: "orders.process".to_string(),
    payload: json!({ "order_id": "456" }),
    action: Some(TriggerAction::Enqueue { queue: "payments".to_string() }),
    timeout_ms: None,
}).await?;

Stream Operations

use iii_sdk::{register_worker, InitOptions, TriggerRequest, UpdateBuilder, UpdateOp};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let iii = register_worker("ws://localhost:49134", InitOptions::default());

    // Set a stream item
    iii.trigger(TriggerRequest {
        function_id: "stream::set".into(),
        payload: json!({
            "stream_name": "users",
            "group_id": "active",
            "item_id": "user-1",
            "data": { "status": "online" },
        }),
        action: None,
        timeout_ms: None,
    }).await?;

    // Atomic update with UpdateBuilder
    let ops = UpdateBuilder::new()
        .increment("total", 100)
        .set("status", json!("processing"))
        .build();

    iii.trigger(TriggerRequest {
        function_id: "stream::update".into(),
        payload: json!({
            "stream_name": "orders",
            "group_id": "user-123",
            "item_id": "order-456",
            "ops": ops,
        }),
        action: None,
        timeout_ms: None,
    }).await?;

    Ok(())
}

Logger

use iii_sdk::Logger;

let logger = Logger::new(Some("my-function".to_string()));
logger.info("Processing started", None);

The Logger struct emits OTel LogRecords, falling back to the tracing crate when OTel is not initialized.

Modules

Resources

• Documentation
• iii Engine
• Examples