Iii Core Primitives

Core Primitives

iii has three top-level primitives:

• Function: a named unit of work such as orders::validate
• Trigger: an event source bound to a function
• Worker: a process that connects to the engine and executes functions

Use :: in function IDs, leading slashes in HTTP api_path, and expression for cron config.

Function Registration

Register local handlers when you control the implementation. Register HTTP-invoked functions when iii should call an existing external endpoint.

Functions and triggers can carry metadata for ownership, discovery, and generated skills. Do not put secrets in metadata.

Workers and Registry

A worker is any process that connects to the engine and registers functions or trigger types. There are two common paths:

The public worker registry at workers.iii.dev is for installable workers such as HTTP, state, queue, pub/sub, cron, database, shell, console, rbac-proxy, and other capability workers. (iii-sandbox and iii-observability are engine-owned and are not added through the registry.) Those workers may ship their own function-level skills; do not duplicate every capability as a top-level iii skill.

Worker Manifest

Use iii.worker.yaml when iii should start a local worker project:

yamlCopy code
name: math-worker
runtime:
  kind: python
  package_manager: pip
  entry: math_worker.py
scripts:
  install: "pip install -r requirements.txt"
  start: "python math_worker.py"

The manifest describes how to start the process. Once running, the WebSocket connection and function registrations are what make the worker part of iii.

Live Engine Registry

The engine keeps a live registry of connected workers, registered functions, triggers, and trigger types. Read it through the built-in discovery functions:

For topology changes, bind triggers to engine::workers-available or engine::functions-available.

Built-In Trigger Shapes

Add condition_function_id to built-in trigger config when the handler should only run if a boolean condition function returns true.

Invocation Modes

Use enqueue for work that must complete with retries. Use void for analytics, notifications, and other non-critical side effects.

Namespaces

Every worker registers in a namespace: the namespace init option, else III_NAMESPACE, else the engine's default. Compose sets III_NAMESPACE to its daemon's namespace for every worker it starts, so all workers in one worker-compose.yaml share a namespace and call each other by bare function id. Engine-owned functions (engine::*, configuration::*, stream::*) live in default; engine::* resolves there implicitly, the others need namespace: "default" on the call from a namespaced worker. Routing is strict and ids are never prefixed with a namespace. From the CLI, iii trigger -n <namespace> <function> selects it. Details and per-language examples are in iii-sdk-reference.

Code Examples

TypeScript

typescriptCopy code
import { registerWorker, TriggerAction } from "iii-sdk";

const iii = registerWorker("ws://localhost:49134", { workerName: "orders-worker" });

iii.registerFunction("orders::validate", async (order) => {
  if (!order.id) throw new Error("missing order id");
  return { ...order, valid: true };
});

iii.registerFunction("orders::process", async (order) => {
  const validated = await iii.trigger({ function_id: "orders::validate", payload: order });
  await iii.trigger({
    function_id: "orders::charge",
    payload: validated,
    action: TriggerAction.Enqueue({ queue: "payments" }),
  });
  return { accepted: true, orderId: validated.id };
});

iii.registerTrigger({
  type: "http",
  function_id: "orders::process",
  config: { api_path: "/orders", http_method: "POST" },
});

Python

pythonCopy code
from iii import register_worker

iii = register_worker("ws://localhost:49134")

def validate(order):
    if not order.get("id"):
        raise ValueError("missing order id")
    return {**order, "valid": True}

def process(order):
    validated = iii.trigger({"function_id": "orders::validate", "payload": order})
    iii.trigger({
        "function_id": "orders::charge",
        "payload": validated,
        "action": {"type": "enqueue", "queue": "payments"},
    })
    return {"accepted": True, "orderId": validated["id"]}

iii.register_function("orders::validate", validate)
iii.register_function("orders::process", process)
iii.register_trigger({
    "type": "http",
    "function_id": "orders::process",
    "config": {"api_path": "/orders", "http_method": "POST"},
})

Rust

rustCopy code
use iii_sdk::{register_worker, InitOptions, RegisterFunction, TriggerAction};
use iii_sdk::protocol::{RegisterTriggerInput, TriggerRequest};
use serde_json::json;

let iii = register_worker("ws://127.0.0.1:49134", InitOptions::default());

iii.register_function("orders::validate", RegisterFunction::new(|order: serde_json::Value| {
    if order["id"].is_null() {
        return Err("missing order id".into());
    }
    Ok(json!({ "valid": true, "order": order }))
}))?;

let process_client = iii.clone();
iii.register_function("orders::process", RegisterFunction::new_async(move |order: serde_json::Value| {
    let iii = process_client.clone();
    async move {
        let validated = iii.trigger(TriggerRequest::new("orders::validate", order)).await?;
        iii.trigger(TriggerRequest {
            function_id: "orders::charge".into(),
            payload: validated.clone(),
            action: Some(TriggerAction::Enqueue { queue: "payments".into() }),
            timeout_ms: None,
        }).await?;
        Ok(json!({ "accepted": true, "order": validated }))
    }
}))?;

iii.register_trigger(RegisterTriggerInput {
    trigger_type: "http".into(),
    function_id: "orders::process".into(),
    config: json!({ "api_path": "/orders", "http_method": "POST" }),
    metadata: None,
})?;

Advanced Primitive Patterns

• Custom triggers: use registerTriggerType({ id, description }, handler) when the event source is not built in. Keep listener setup in registerTrigger and cleanup in unregisterTrigger.
• Channels: use createChannel() for binary or streaming data that should not be serialized into JSON payloads. Pass readerRef or writerRef through a function payload.
• HTTP-invoked functions: use HttpInvocationConfig for legacy APIs, third-party endpoints, or immutable services. Use environment variable names for auth fields, not raw secrets.
• Schemas: Rust can derive request/response schemas with schemars::JsonSchema; Python can use type hints or Pydantic; Node can pass JSON Schema manually.

When to Use

• Use this skill for function registration, trigger binding, trigger payload shapes, invocation mode decisions, worker creation, worker registry access, trigger conditions, custom trigger types, channels, and HTTP-invoked functions.
• Use this when a task spans TypeScript, Python, or Rust examples for the same iii primitive.

Boundaries

• For engine ports, adapters, engine-owned workers, RBAC (rbac-proxy), and deployment config, use iii-engine-config.
• For SDK-specific package exports and language caveats, use iii-sdk-reference.
• For complete backend designs such as workflows, CQRS, agentic systems, and reactive apps, use iii-architecture-patterns.
• For failed invocations, timeouts, RBAC denials, and retryability, use iii-error-handling.
• Worker-backed capability details live with the worker docs, not as top-level iii skills.