Quickstart

Build your first III application in Rust

Create a new project

cargo new my-iii-app
cd my-iii-app

Install dependencies

Add to Cargo.toml:

[dependencies]
iii-sdk = "0.4.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

Connect to III Engine

Create a connection to the III Engine:

use iii_sdk::III;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create III client with engine address
    let iii = III::new("ws://localhost:49134");
    
    // Connect to the engine
    iii.connect().await?;
    
    println!("Connected to III Engine");
    
    // Keep the application running
    tokio::signal::ctrl_c().await?;
    Ok(())
}

Register a function

Register a function that can be called by other workers:

use iii_sdk::{III, IIIError};
use serde_json::{json, Value};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let iii = III::new("ws://localhost:49134");
    
    // Register a simple echo function
    iii.register_function("echo", |input: Value| async move {
        Ok(json!({
            "message": "Echo received",
            "data": input
        }))
    });
    
    iii.connect().await?;
    println!("Function 'echo' registered");
    
    tokio::signal::ctrl_c().await?;
    Ok(())
}

Call a function

Call functions registered by other workers:

use iii_sdk::III;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let iii = III::new("ws://localhost:49134");
    iii.connect().await?;
    
    // Call the echo function
    let result = iii.call("echo", json!({
        "message": "Hello from Rust!"
    })).await?;
    
    println!("Result: {}", result);
    Ok(())
}

Access context in functions

Use the context API to access logging and metadata:

use iii_sdk::{III, get_context};
use serde_json::{json, Value};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let iii = III::new("ws://localhost:49134");
    
    iii.register_function("process", |input: Value| async move {
        let ctx = get_context();
        ctx.logger.info("Processing request", None);
        
        // Process the input
        let result = json!({
            "status": "processed",
            "input": input
        });
        
        ctx.logger.info("Request completed", Some(result.clone()));
        Ok(result)
    });
    
    iii.connect().await?;
    tokio::signal::ctrl_c().await?;
    Ok(())
}

Register a trigger

Triggers automatically invoke functions based on events:

use iii_sdk::III;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let iii = III::new("ws://localhost:49134");
    
    // Register a function
    iii.register_function("on_event", |input| async move {
        println!("Triggered with: {:?}", input);
        Ok(json!({ "status": "ok" }))
    });
    
    // Register a trigger that calls this function
    let _trigger = iii.register_trigger(
        "http",
        "on_event",
        json!({
            "path": "/webhook",
            "method": "POST"
        })
    )?;
    
    iii.connect().await?;
    println!("Trigger registered");
    
    tokio::signal::ctrl_c().await?;
    Ok(())
}

Next Steps

Client API

Learn about the III struct and connection management

Functions

Deep dive into function registration and handlers

Triggers

Set up event-driven function invocations

Telemetry

Enable distributed tracing and metrics