Functions

Register and handle function invocations

Overview

Functions are the core building blocks of III applications. A function is a piece of code that can be invoked remotely by other workers or triggers.

Registering Functions

register_function

Register a function with the default configuration.

pub fn register_function<F, Fut>(&self, id: impl Into<String>, handler: F)
where
    F: Fn(Value) -> Fut + Send + Sync + 'static,
    Fut: std::future::Future<Output = Result<Value, IIIError>> + Send + 'static

id · impl Into<String> · required

Unique identifier for the function

handler · F · required

Async function that processes input and returns a result. The handler receives a serde_json::Value and must return Result<Value, IIIError>.

Example:

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

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

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

iii.connect().await?;

register_function_with_description

Register a function with a description.

pub fn register_function_with_description<F, Fut>(
    &self,
    id: impl Into<String>,
    description: impl Into<String>,
    handler: F,
)
where
    F: Fn(Value) -> Fut + Send + Sync + 'static,
    Fut: std::future::Future<Output = Result<Value, IIIError>> + Send + 'static

id · impl Into<String> · required

Unique identifier for the function

description · impl Into<String> · required

Human-readable description of what the function does

handler · F · required

Async function handler

Example:

iii.register_function_with_description(
    "user.create",
    "Creates a new user in the system",
    |input: Value| async move {
        // Handler implementation
        Ok(json!({ "id": "user-123" }))
    }
);

register_function_with

Register a function with full configuration options.

pub fn register_function_with<F, Fut>(
    &self,
    message: RegisterFunctionMessage,
    handler: F,
)
where
    F: Fn(Value) -> Fut + Send + Sync + 'static,
    Fut: std::future::Future<Output = Result<Value, IIIError>> + Send + 'static

message · RegisterFunctionMessage · required

Complete function registration message with all metadata

handler · F · required

Async function handler

Example:

use iii_sdk::{III, RegisterFunctionMessage};
use serde_json::json;

let message = RegisterFunctionMessage {
    id: "analytics.track".to_string(),
    description: Some("Track an analytics event".to_string()),
    request_format: Some(json!({
        "type": "object",
        "properties": {
            "event": { "type": "string" },
            "userId": { "type": "string" }
        }
    })),
    response_format: Some(json!({
        "type": "object",
        "properties": {
            "tracked": { "type": "boolean" }
        }
    })),
    metadata: None,
    invocation: None,
};

iii.register_function_with(message, |input| async move {
    // Implementation
    Ok(json!({ "tracked": true }))
});

HTTP Functions

HTTP functions are proxy functions that invoke external HTTP endpoints.

register_http_function

Register a function that proxies to an HTTP endpoint.

pub fn register_http_function(
    &self,
    id: impl Into<String>,
    config: HttpInvocationConfig,
) -> Result<HttpFunctionRef, IIIError>

id · impl Into<String> · required

Unique identifier for the function

config · HttpInvocationConfig · required

HTTP configuration including URL, method, headers, and authentication

HttpFunctionRef · Result<HttpFunctionRef, IIIError>

Reference that can be used to unregister the function

Example:

use iii_sdk::{III, HttpInvocationConfig, HttpMethod};
use std::collections::HashMap;

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

let mut headers = HashMap::new();
headers.insert("Content-Type".to_string(), "application/json".to_string());

let http_fn = iii.register_http_function(
    "external.webhook",
    HttpInvocationConfig {
        url: "https://api.example.com/webhook".to_string(),
        method: HttpMethod::Post,
        timeout_ms: Some(30000),
        headers,
        auth: None,
    }
)?;

iii.connect().await?;

// Later, unregister the function
http_fn.unregister();

Function Context

Every function handler runs within a context that provides logging and tracing capabilities.

Accessing Context

Use get_context() to access the current function’s context:

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

iii.register_function("process", |input: Value| async move {
    let ctx = get_context();
    
    // Log messages
    ctx.logger.info("Processing started", None);
    ctx.logger.debug("Input data", Some(input.clone()));
    
    // Your logic here
    let result = json!({ "status": "completed" });
    
    ctx.logger.info("Processing completed", Some(result.clone()));
    
    Ok(result)
});

Context Structure

The Context struct provides:

pub struct Context {
    pub logger: Logger,
    pub span: Option<tracing::Span>,
}

• logger: Logger instance scoped to the current function
• span: Active tracing span (when otel feature is enabled)

Function Discovery

list_functions

List all registered functions in the engine.

pub async fn list_functions(&self) -> Result<Vec<FunctionInfo>, IIIError>

Vec<FunctionInfo> · Result<Vec<FunctionInfo>, IIIError>

List of all registered functions with their metadata

Example:

let functions = iii.list_functions().await?;

for func in functions {
    println!("Function: {}", func.function_id);
    if let Some(desc) = func.description {
        println!("  Description: {}", desc);
    }
}

on_functions_available

Subscribe to notifications when functions become available.

pub fn on_functions_available<F>(&self, callback: F) -> FunctionsAvailableGuard
where
    F: Fn(Vec<FunctionInfo>) + Send + Sync + 'static

callback · F · required

Callback invoked whenever functions are registered or updated

FunctionsAvailableGuard · FunctionsAvailableGuard

Guard that automatically unsubscribes when dropped

Example:

let _guard = iii.on_functions_available(|functions| {
    println!("Functions updated: {} available", functions.len());
    for func in functions {
        println!("  - {}", func.function_id);
    }
});

// Guard keeps subscription active
// Drops when it goes out of scope

Types

RegisterFunctionMessage

pub struct RegisterFunctionMessage {
    pub id: String,
    pub description: Option<String>,
    pub request_format: Option<Value>,
    pub response_format: Option<Value>,
    pub metadata: Option<Value>,
    pub invocation: Option<HttpInvocationConfig>,
}

HttpInvocationConfig

pub struct HttpInvocationConfig {
    pub url: String,
    pub method: HttpMethod,
    pub timeout_ms: Option<u64>,
    pub headers: HashMap<String, String>,
    pub auth: Option<HttpAuthConfig>,
}

HttpMethod

pub enum HttpMethod {
    Get,
    Post,
    Put,
    Patch,
    Delete,
}

FunctionInfo

pub struct FunctionInfo {
    pub function_id: String,
    pub description: Option<String>,
    pub request_format: Option<Value>,
    pub response_format: Option<Value>,
    pub metadata: Option<Value>,
}

See Also

• Invocation API - Call registered functions
• Context API - Access function context and logging
• Triggers API - Automatically invoke functions based on events