iii

https://iii.dev/docs
Admin
iii turns distributed backend complexity into a simple set of real-time, interoperable primitives...
Tokens:80,384
Snippets:1,062
Trust Score:4.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install the Node.js SDK

Source: https://iii.dev/docs/0-13-0/sdk-reference/node-sdk

Install the iii Node.js SDK using npm.

```bash
npm install iii-sdk
```

--------------------------------

### Start the iii engine with default configuration

Source: https://iii.dev/docs/0-13-0/using-iii/engine

Use this command to launch the iii engine with a predefined set of default workers. This is convenient for initial setup or quick testing without needing a custom configuration file.

```bash
iii --use-default-config
```

--------------------------------

### Install the Browser SDK

Source: https://iii.dev/docs/0-13-0/sdk-reference/browser-sdk

Install the iii-browser-sdk package using npm.

```bash
npm install iii-browser-sdk
```

--------------------------------

### Install the iii Python SDK

Source: https://iii.dev/docs/0-13-0/sdk-reference/python-sdk

Install the SDK using pip. The SDK is imported as `iii`.

```bash
pip install iii-sdk
```

--------------------------------

### Verify iii Installation

Source: https://iii.dev/docs/0-13-0/install

Run this command after installation to check if iii is installed correctly. It should output the installed version number.

```bash
iii --version
```

--------------------------------

### Install the iii Engine

Source: https://iii.dev/docs/0-13-0/install

Use this command to download and install the iii engine script.

```bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh
```

--------------------------------

### Install Rust SDK

Source: https://iii.dev/docs/0-13-0/sdk-reference/rust-sdk

Add the iii-sdk crate to your Cargo project to begin using the SDK.

```bash
cargo add iii-sdk
```

--------------------------------

### Launch the iii Console

Source: https://iii.dev/docs/next/using-iii/console

Starts the iii console UI. Open http://127.0.0.1:3113 in your browser after launching.

```bash
iii console
```

--------------------------------

### Get Help for iii CLI

Source: https://iii.dev/docs/0-13-0/using-iii/cli

Lists iii's flags and available subcommands. Use this to explore the CLI's capabilities.

```bash
iii --help            #lists iii's flags and available subcommands
iii subcommand --help #lists the specific actions each sucommand accepts
```

--------------------------------

### Start Docker Compose Stack

Source: https://iii.dev/docs/0-13-0/using-iii/deployment

Command to start the iii services defined in the docker-compose.yml file in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Launch Console

Source: https://iii.dev/docs/0-13-0/using-iii/console

Starts the iii engine and then launches the console in a separate terminal. Use --use-default-config for a scratch instance or run `iii` to load a configuration file.

```bash
iii --use-default-config

# In another terminal, launch the console.
iii console
```

--------------------------------

### Worker Manifest Configuration

Source: https://iii.dev/docs/0-13-0/creating-workers/workers

Defines the worker's name, runtime environment, and scripts for installation and starting.

```yaml
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"
```

--------------------------------

### Start the iii Engine

Source: https://iii.dev/docs/0-13-0/quickstart

Launches the iii engine, which acts as the central communication hub for workers. Ensure the config.yaml file is present in the current directory.

```bash
iii --config config.yaml
```

--------------------------------

### Add a Worker to the Project

Source: https://iii.dev/docs/0-13-0/using-iii/workers-registry

Demonstrates adding a worker to your project using the 'iii worker add' command. It shows examples for adding from the registry name, a local path, or a Docker/OCI image.

```bash
iii worker add iii-state                # registry name
iii worker add ./workers/my-worker      # local path
iii worker add ghcr.io/org/worker:tag   # Docker or OCI image
```

--------------------------------

### Basic engine configuration structure

Source: https://iii.dev/docs/0-13-0/using-iii/engine

Defines the `workers` section in `config.yaml`, listing workers by name and their specific configurations. This example shows an HTTP worker and a state worker using a file-based adapter.

```yaml
workers:
  - name: iii-http
    config:
      port: 3111
      host: 127.0.0.1

  - name: iii-state
    config:
      adapter:
        name: kv
        config:
          store_method: file_based
          file_path: ./data/state_store.db
```

--------------------------------

### Control individual worker states

Source: https://iii.dev/docs/0-13-0/using-iii/workers

Manually manage the lifecycle of specific workers. Use 'start' to initiate a worker, 'stop' to halt it, and 'restart' to perform a stop-then-start operation.

```bash
iii worker start <name>     # start one worker
```

```bash
iii worker stop <name>      # stop one worker
```

```bash
iii worker restart <name>   # stop then start
```

--------------------------------

### Nginx Reverse Proxy Configuration

Source: https://iii.dev/docs/0-13-0/using-iii/deployment

Example Nginx configuration for setting up a reverse proxy to handle SSL and route traffic to the iii engine's API, WebSocket, and stream services. Includes configuration for WebSocket upgrades.

```nginx
server {
    listen 443 ssl;
    server_name your-domain.com;

    location /api/ {
        proxy_pass http://127.0.0.1:3111;
    }

    location /ws {
        proxy_pass http://127.0.0.1:49134;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /stream/ {
        proxy_pass http://127.0.0.1:3112;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location / {
        proxy_pass http://127.0.0.1:3111;
    }
}
```

--------------------------------

### Synchronize Workers from Lockfile

Source: https://iii.dev/docs/next/using-iii/workers

Installs workers exactly as specified in the iii.lock file. This ensures consistent installations across different environments.

```bash
iii worker sync
```

--------------------------------

### Pinning a Specific Worker Version

Source: https://iii.dev/docs/0-13-0/using-iii/workers

Install a specific version of a worker by appending '@<version>' to the registry name. This ensures reproducible deployments by recording the pin in 'iii.lock'.

```bash
iii worker add iii-state@1.2.0
```

--------------------------------

### Caddy Reverse Proxy Configuration

Source: https://iii.dev/docs/0-13-0/using-iii/deployment

Example Caddy configuration to route traffic to different iii engine services based on URL paths. This configuration handles API, stream, and WebSocket traffic.

```plaintext
your-domain.com {
    handle /api/* {
        reverse_proxy 127.0.0.1:3111
    }
    handle /stream/* {
        reverse_proxy 127.0.0.1:3112
    }
    handle /ws {
        reverse_proxy 127.0.0.1:49134
    }
    handle {
        reverse_proxy 127.0.0.1:3111
    }
}
```

--------------------------------

### Register Worker in Node.js/TypeScript

Source: https://iii.dev/docs/0-13-0/creating-workers/workers

Connects a worker to the iii engine using the III_URL environment variable. Ensure the 'iii-sdk' is installed.

```typescript
import { registerWorker } from "iii-sdk";

const worker = registerWorker(process.env.III_URL);
```

--------------------------------

### Verify Worker Configuration Drift

Source: https://iii.dev/docs/next/using-iii/workers

Reports any discrepancies between the workers defined in config.yaml and those pinned in iii.lock. This helps identify potential inconsistencies in your worker setup.

```bash
iii worker verify
```

--------------------------------

### Dispatch HTTP Event to Bound Function (Rust)

Source: https://iii.dev/docs/next/creating-workers/triggers

Use the Rust SDK to dispatch an HTTP event to a bound function. This example assumes the handler has a locked `bindings` map and handles potential errors.

```rust
use iii_sdk::TriggerRequest;
use serde_json::json;

// Inside the worker's HTTP listener, after matching method+path to an
// entry in the handler's `bindings` map from the declare-trigger-type example:
let binding = handler.bindings.lock().unwrap().get(&matched_trigger_id).cloned();
if let Some(binding) = binding {
    worker
        .trigger(TriggerRequest {
            function_id: binding.function_id.clone(),
            payload: json!({ "method": method, "headers": headers, "body": body }),
            action: None,
            timeout_ms: None,
        })
        .await?;
}
```

--------------------------------

### Synchronizing Workers from Lockfile

Source: https://iii.dev/docs/0-13-0/using-iii/workers

Install workers exactly as specified in the 'iii.lock' file. The '--frozen' flag is used in CI environments to verify the lockfile without making changes.

```bash
iii worker sync            # install workers exactly from iii.lock
iii worker sync --frozen   # CI form: verify the lockfile without mutating local files
```

--------------------------------

### TriggerAction

Source: https://iii.dev/docs/sdk-reference/node-sdk

Runtime constants used to produce the value for the `action` field in `trigger` requests. Examples include `TriggerAction.Void()` for fire-and-forget and `TriggerAction.Enqueue({ queue: "math" })` for routing through iii-queue.

```APIDOC
## TriggerAction

### Description
`TriggerAction` is a runtime const that produces the value passed to `trigger`'s `action` field.

### Usage Examples
```typescript
TriggerAction.Void();                       // fire-and-forget
TriggerAction.Enqueue({ queue: "math" });   // route through iii-queue
```

### Underlying Type
The underlying type is the discriminated union `{ type: "enqueue"; queue: string } | { type: "void" }`, exported as `TriggerActionType`.
```

--------------------------------

### Frozen Worker Synchronization for CI

Source: https://iii.dev/docs/next/using-iii/workers

This command is used in CI environments to verify the lockfile without making any changes to local files. It ensures that the installed workers match the versions specified in iii.lock.

```bash
iii worker sync --frozen
```

--------------------------------

### Add Python Worker

Source: https://iii.dev/docs/0-13-0/quickstart

Adds a local Python worker to the iii project. This command registers the worker with the engine and starts its execution. It may use cached dependencies if available.

```bash
iii worker add ./workers/math-worker
```

--------------------------------

### Initialize iii Project

Source: https://iii.dev/docs/0-13-0/quickstart

Scaffolds a new iii project with a specified template and navigates into the project directory. This is the first step in setting up a new iii application.

```bash
iii project init quickstart --template quickstart
cd quickstart
```

--------------------------------

### Engine configuration with environment variable expansion

Source: https://iii.dev/docs/0-13-0/using-iii/engine

Illustrates how to use environment variables for dynamic configuration values in `config.yaml`. This allows for flexible settings like ports and hosts that can change per environment.

```yaml
workers:
  - name: iii-http
    config:
      port: ${HTTP_PORT:3111}
      host: ${HTTP_HOST:127.0.0.1}
```

--------------------------------

### Scaffold a new worker

Source: https://iii.dev/docs/creating-workers/workers

Initializes a new standalone worker project. Use the `--language` flag to specify the desired language and skip the interactive prompt.

```bash
iii worker init my-worker

iii worker init my-worker --language typescript
```

--------------------------------

### List Console Flags

Source: https://iii.dev/docs/0-13-0/using-iii/console

To list every flag the binary accepts, including their defaults, run this command. The corresponding environment variables share the same set; each flag's help text names the env var that overrides it.

```bash
iii console --help
```

--------------------------------

### Migrate Function Registration with Options

Source: https://iii.dev/docs/next/changelog/0-16-0/align-rust-register-function-with-signature

When providing options like descriptions, chain the `.description()` method after `RegisterFunction::new` or `RegisterFunction::new_async`.

```rust
register_function_with("id", sync_handler, RegisterFunctionOptions { description: Some("d".into()), ..Default::default() })
```

```rust
register_function("id", RegisterFunction::new(sync_handler).description("d"))
```

```rust
register_function_with("id", async_handler, RegisterFunctionOptions { description: Some("d".into()), ..Default::default() })
```

```rust
register_function("id", RegisterFunction::new_async(async_handler).description("d"))
```

--------------------------------

### Verifying Lockfile Drift

Source: https://iii.dev/docs/0-13-0/using-iii/workers

Report any discrepancies between the 'config.yaml' and 'iii.lock' files.

```bash
iii worker verify          # report drift between config.yaml and iii.lock
```

--------------------------------

### Channel Runtime Flow Diagram

Source: https://iii.dev/docs/0-13-0/understanding-iii/channels

Illustrates the sequence of operations for creating and using channels between a producer function, the iii engine, and a consumer function.

```mermaid
sequenceDiagram theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    participant A as Producer function
    participant Engine
    participant B as Consumer function

    A->>Engine: createChannel()
    Engine-->>A: writer, reader, writerRef, readerRef
    A->>Engine: trigger B with readerRef
    Engine->>B: invoke B with reader ref
    A->>Engine: writer sends chunks
    Engine->>B: reader receives chunks
    A->>Engine: writer closes
    Engine->>B: reader ends
```

--------------------------------

### Subscribe to Worker and Function Discovery Events (Rust)

Source: https://iii.dev/docs/next/creating-workers/workers

Utilize the `iii_sdk` to register functions that handle worker and function discovery events. Ensure correct deserialization of event data using `serde` and `schemars`.

```rust
use iii_sdk::{RegisterFunction, RegisterTriggerInput};
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::{Value, json};

#[derive(Deserialize, JsonSchema)]
struct WorkersAvailable { event: String, worker_id: String }

#[derive(Deserialize, JsonSchema)]
struct FunctionsAvailable { event: String, functions: Vec<Value> }

worker.register_function(RegisterFunction::new_async(
    "discovery::on-workers",
    |input: WorkersAvailable| async move {
        if input.event == "worker_connected" {
            // A Worker just joined the registry; its Functions are callable now.
        }
        Ok::<_, String>(())
    },
));
worker.register_trigger(RegisterTriggerInput {
    trigger_type: "engine::workers-available".into(),
    function_id: "discovery::on-workers".into(),
    config: json!({}),
    metadata: None,
})?;

worker.register_function(RegisterFunction::new_async(
    "discovery::on-functions",
    |input: FunctionsAvailable| async move {
        // `functions` is the full snapshot after the change.
        let _count = input.functions.len();
        Ok::<_, String>(())
    },
));
worker.register_trigger(RegisterTriggerInput {
    trigger_type: "engine::functions-available".into(),
    function_id: "discovery::on-functions".into(),
    config: json!({}),
    metadata: None,
})?;
```

--------------------------------

### Add TypeScript Worker

Source: https://iii.dev/docs/0-13-0/quickstart

Adds a local TypeScript worker to the iii project. Similar to adding a Python worker, this registers the worker and starts its process, potentially using cached dependencies.

```bash
iii worker add ./workers/caller-worker
```

--------------------------------

### Channel Runtime Flow Diagram

Source: https://iii.dev/docs/next/understanding-iii/channels

Illustrates the sequence of operations for creating and using channels between a producer and a consumer function via the engine. This diagram shows how refs are passed and data chunks are streamed.

```mermaid
sequenceDiagram
    participant A as Producer function
    participant Engine
    participant B as Consumer function

    A->>Engine: createChannel()
    Engine-->>A: writer, reader, writerRef, readerRef
    A->>Engine: trigger B with readerRef
    Engine->>B: invoke B with reader ref
    A->>Engine: writer sends chunks
    Engine->>B: reader receives chunks
    A->>Engine: writer closes
    Engine->>B: reader ends
```

--------------------------------

### Subscribe to Worker and Function Discovery Events (Python)

Source: https://iii.dev/docs/next/creating-workers/workers

Implement asynchronous functions to process worker and function availability events. Use `worker.register_function` and `worker.register_trigger` to set up the event handlers.

```python
async def on_workers(data: dict) -> None:
    if data["event"] == "worker_connected":
        # A Worker just joined the registry; its Functions are callable now.
        pass

worker.register_function("discovery::on-workers", on_workers)
worker.register_trigger({
    "type": "engine::workers-available",
    "function_id": "discovery::on-workers",
    "config": {},
})

async def on_functions(data: dict) -> None:
    # `functions` is the full snapshot after the change.
    ids = [f["function_id"] for f in data.get("functions", [])]

worker.register_function("discovery::on-functions", on_functions)
worker.register_trigger({
    "type": "engine::functions-available",
    "function_id": "discovery::on-functions",
    "config": {},
})
```

--------------------------------

### Register Functions in Rust SDK

Source: https://iii.dev/docs/changelog/index

Use the single `register_function` entry point in the Rust SDK. It accepts handlers and optional metadata via constructors like `new`, `new_async`, and `http`.

```rust
iii.register_function("greet", RegisterFunction::new(greet));
iii.register_function(
    "http::fetch",
    RegisterFunction::new_async(fetch).description("Fetches a URL"),
);
iii.register_function(
    "ext::lambda",
    RegisterFunction::http(http_config),
);
```

--------------------------------

### Create a Channel in Python

Source: https://iii.dev/docs/0-13-0/using-iii/channels

Initializes a channel for streaming data between functions. It provides local writer and reader streams along with serializable references.

```python
channel = iii_client.create_channel()

# channel.writer
# channel.reader
# channel.writer_ref
# channel.reader_ref
```

--------------------------------

### Create a Channel in Rust

Source: https://iii.dev/docs/0-13-0/using-iii/channels

Sets up a channel for inter-function data streaming in Rust. It includes local writer and reader streams and their corresponding serializable references.

```rust
let channel = iii.create_channel(None).await?;

// channel.writer
// channel.reader
// channel.writer_ref
// channel.reader_ref
```

--------------------------------

### Rust SDK: Registering Functions with `RegisterFunction` Constructors

Source: https://iii.dev/docs/next/changelog/0-16-0/align-rust-register-function-with-signature

Demonstrates the three constructors for `RegisterFunction`: `new` for synchronous handlers, `new_async` for asynchronous handlers, and `http` for HTTP-invoked functions. Schemas are auto-extracted for `new` and `new_async`, while `http` requires explicit schema definition via builder methods.

```rust
iii.register_function("greet", RegisterFunction::new(greet));

iii.register_function(
    "http::fetch",
    RegisterFunction::new_async(fetch).description("Fetches a URL"),
);
iii.register_function(
    "echo",
    RegisterFunction::new_async(|input: Value| async move { Ok(input) })
);

iii.register_function(
    "ext::lambda",
    RegisterFunction::http(http_config).description("Proxies to a Lambda"),
);
```

--------------------------------

### List all workers in the project

Source: https://iii.dev/docs/0-13-0/using-iii/workers

Displays all workers declared in your project's config.yaml, along with their current operational status. Useful for monitoring the state of your project's workers.

```bash
iii worker list
```

--------------------------------

### Migrate Register Function with Async Handler and Options

Source: https://iii.dev/docs/changelog/0-16-0/align-rust-register-function-with-signature

Update `register_function_with("id", async_handler, RegisterFunctionOptions { description: Some("d".into()), ..Default::default() })` to `register_function("id", RegisterFunction::new_async(async_handler).description("d"))`.

```rust
register_function_with("id", async_handler, RegisterFunctionOptions { description: Some("d".into()), ..Default::default() })
```

```rust
register_function("id", RegisterFunction::new_async(async_handler).description("d"))
```

--------------------------------

### Migrate Register Function with Sync Handler and Options

Source: https://iii.dev/docs/changelog/0-16-0/align-rust-register-function-with-signature

Change `register_function_with("id", sync_handler, RegisterFunctionOptions { description: Some("d".into()), ..Default::default() })` to `register_function("id", RegisterFunction::new(sync_handler).description("d"))`.

```rust
register_function_with("id", sync_handler, RegisterFunctionOptions { description: Some("d".into()), ..Default::default() })
```

```rust
register_function("id", RegisterFunction::new(sync_handler).description("d"))
```

--------------------------------

### Rust SDK: Register Function Constructors

Source: https://iii.dev/docs/changelog/0-16-0/align-rust-register-function-with-signature

Demonstrates the three constructors for `RegisterFunction`: `new` for synchronous functions, `new_async` for asynchronous functions, and `http` for HTTP-invoked functions. Schemas are auto-extracted for `new` and `new_async` unless overridden.

```rust
iii.register_function("greet", RegisterFunction::new(greet));

iii.register_function(
    "http::fetch",
    RegisterFunction::new_async(fetch).description("Fetches a URL"),
);
iii.register_function(
    "echo",
    RegisterFunction::new_async(|input: Value| async move { Ok(input) }),
);

iii.register_function(
    "ext::lambda",
    RegisterFunction::http(http_config).description("Proxies to a Lambda"),
);
```

--------------------------------

### Migrate iii sandbox commands to iii trigger

Source: https://iii.dev/docs/changelog/index

Replace 'iii sandbox' subcommands with 'iii trigger' for creating, executing, and stopping sandboxes. Use 'jq' for parsing sandbox IDs.

```bash
# before
iii sandbox create python --idle-timeout 300
iii sandbox exec "$SB" -- python3 -c 'print(2+2)'
iii sandbox stop "$SB"

# after
SB=$(iii trigger sandbox::create image=python idle_timeout_secs=300 | jq -r .sandbox_id)
iii trigger sandbox::exec sandbox_id="$SB" cmd=python3 args='["-c","print(2+2)"]'
iii trigger sandbox::stop sandbox_id="$SB"
```

--------------------------------

### Generate Docker Assets

Source: https://iii.dev/docs/0-13-0/using-iii/deployment

Use this command to generate Dockerfile, docker-compose.yml, and .env files for a new or existing iii project. Re-running the generator will not overwrite existing files.

```bash
iii project generate-docker
```

--------------------------------

### Rust Observability Imports

Source: https://iii.dev/docs/changelog/index

Import observability primitives like Logger, OtelConfig, init_otel, with_span, and execute_traced_request from the `iii-observability` crate in Rust. This replaces imports from `iii_sdk`.

```rust
// Before (Rust)
use iii_sdk::{Logger, OtelConfig, init_otel, with_span, execute_traced_request};

// After (Rust)
use iii_observability::{Logger, OtelConfig, init_otel, with_span, execute_traced_request};
```

--------------------------------

### registerWorker

Source: https://iii.dev/docs/next/sdk-reference/node-sdk

Connect a worker to a running iii engine and return its handle. Pass the engine's SDK WebSocket URL (e.g. `process.env.III_URL`) as `address`. `options` configures worker identity, timeouts, reconnection, and OpenTelemetry. The returned `ISdk` carries every method below.

```APIDOC
## registerWorker

### Description
Connect a worker to a running iii engine and return its handle.

### Signature
```typescript
function registerWorker(address: string, options?: InitOptions): ISdk;
```

### Parameters
#### Path Parameters
- **address** (string) - Required - The engine's SDK WebSocket URL.
- **options** (InitOptions) - Optional - Configuration for worker identity, timeouts, reconnection, and OpenTelemetry.
```

--------------------------------

### Migrate iii_fn and iii_async_fn

Source: https://iii.dev/docs/changelog/0-16-0/align-rust-register-function-with-signature

Update `iii_fn(f)` to `RegisterFunction::new(f)` and `iii_async_fn(f)` to `RegisterFunction::new_async(f)`.

```rust
iii_fn(f)
```

```rust
RegisterFunction::new(f)
```

```rust
iii_async_fn(f)
```

```rust
RegisterFunction::new_async(f)
```

--------------------------------

### Simplify Sandbox Operations

Source: https://iii.dev/docs/changelog/index

Compares the previous four-step process for sandbox operations with the new single-call meta-function. The sandbox is automatically stopped unless `keep_sandbox: true` is specified.

```bash
# before (4 calls)
SB=$(iii trigger sandbox::create image=python | jq -r .sandbox_id)
iii trigger sandbox::fs::write sandbox_id="$SB" path=/workspace/run.py content='print(2+2)'
iii trigger sandbox::exec sandbox_id="$SB" cmd=python3 args='["/workspace/run.py"]'
iii trigger sandbox::stop sandbox_id="$SB"

# after (1 call)
iii trigger sandbox::run --json '{"image":"python","code":"print(2+2)"}'
```

--------------------------------

### Inspect Worker Status and Logs

Source: https://iii.dev/docs/next/using-iii/workers

Provides tools to check a worker's configuration, sandbox state, and logs, or to execute commands within its environment.

```bash
iii worker status <name>
```

```bash
iii worker logs <name>
```

```bash
iii worker exec <name> -- <command>
```

--------------------------------

### Migrate Async Register Function with Description

Source: https://iii.dev/docs/changelog/0-16-0/align-rust-register-function-with-signature

Update `register_function(RegisterFunction::new_async("id", f).description("d"))` to `register_function("id", RegisterFunction::new_async(f).description("d"))`.

```rust
register_function(RegisterFunction::new_async("id", f).description("d"))
```

```rust
register_function("id", RegisterFunction::new_async(f).description("d"))
```

--------------------------------

### Trigger actions

Source: https://iii.dev/docs/0-13-0/sdk-reference/python-sdk

Use `TriggerAction.Void()` for fire-and-forget actions or `TriggerAction.Enqueue(queue='...')` to route through iii-queue.

```python
TriggerAction.Void()                  # fire-and-forget; returns TriggerActionVoid()
TriggerAction.Enqueue(queue="math")   # route through iii-queue; returns TriggerActionEnqueue(...)
```

--------------------------------

### Migrate Untyped and Simple Function Registrations

Source: https://iii.dev/docs/next/changelog/0-16-0/align-rust-register-function-with-signature

Replace `RegisterFunction::untyped` with `RegisterFunction::new_async`. Simple `iii_fn` and `iii_async_fn` calls should be updated to their respective `RegisterFunction::new` and `RegisterFunction::new_async` equivalents.

```rust
RegisterFunction::untyped(handler)
```

```rust
RegisterFunction::new_async(handler)
```

```rust
iii_fn(f)
```

```rust
RegisterFunction::new(f)
```

```rust
iii_async_fn(f)
```

```rust
RegisterFunction::new_async(f)
```

--------------------------------

### Register a Worker

Source: https://iii.dev/docs/0-13-0/sdk-reference/browser-sdk

Connect a browser tab to a running iii engine and obtain an ISdk handle. The address is the engine's SDK WebSocket URL.

```typescript
function registerWorker(address: string, options?: InitOptions): ISdk;
```

--------------------------------

### Node.js Observability Imports

Source: https://iii.dev/docs/changelog/index

Import observability primitives like Logger, initOtel, and withSpan from the `@iii-dev/observability` package in Node.js. This replaces the older import path from `iii-sdk`.

```typescript
// Before (Node)
import { Logger, initOtel, withSpan } from 'iii-sdk'

// After (Node)
import { Logger, initOtel, withSpan } from '@iii-dev/observability'
```

--------------------------------

### Register a worker

Source: https://iii.dev/docs/0-13-0/sdk-reference/python-sdk

Connect a worker to a running iii engine. The `address` is the engine's SDK WebSocket URL. Options can configure worker identity and reconnection.

```python
def register_worker(address: str, options: InitOptions | None = None) -> III: ...
```

--------------------------------

### Migrate Register Function with HTTP Config and Options

Source: https://iii.dev/docs/changelog/0-16-0/align-rust-register-function-with-signature

Update `register_function_with("id", http_config, RegisterFunctionOptions::default())` to `register_function("id", RegisterFunction::http(http_config))`.

```rust
register_function_with("id", http_config, RegisterFunctionOptions::default())
```

```rust
register_function("id", RegisterFunction::http(http_config))
```

--------------------------------

### Python Telemetry API Migration

Source: https://iii.dev/docs/0-13-0/changelog

Migrate from iii.telemetry to opentelemetry for accessing tracers and meters in Python.

```python
# Before (Python)
from iii.telemetry import get_tracer, get_meter, is_initialized

# After (Python)
from opentelemetry import trace, metrics
tracer = trace.get_tracer("my-service")
meter = metrics.get_meter("my-service")
```

--------------------------------

### Read File Content with Fallback

Source: https://iii.dev/docs/changelog/index

Demonstrates how to read file content, prioritizing an inline `body` field for small text files and falling back to a stream channel for larger files or legacy compatibility. The inline body is limited to 1 MiB.

```typescript
const { content, body } = await trigger({ function_id: 'sandbox::fs::read', payload: { sandbox_id, path } })
const text = body ?? await readChannel(content) // prefer inline body, fall back to stream
```

--------------------------------

### iii trigger command payload formats

Source: https://iii.dev/docs/0-13-0/changelog

Demonstrates the different ways to provide payload data to the 'iii trigger' command, including key-value pairs, JSON, and a combination of both.

```bash
# kv form
iii trigger orders::process amount=149.99 currency=USD

# JSON form
iii trigger orders::process --json '{"amount": 149.99, "currency": "USD"}'

# Combined: --json is the base, kv overrides individual keys
iii trigger orders::process --json '{"amount": 100}' amount=149.99
```

--------------------------------

### Create a Channel in Node.js

Source: https://iii.dev/docs/0-13-0/using-iii/channels

Creates a new channel object with local writer and reader streams, and serializable references for both ends. Use this to initiate a channel for data streaming.

```typescript
const channel = await iii.createChannel();

// channel.writer
// channel.reader
// channel.writerRef
// channel.readerRef
```

--------------------------------

### Register Worker in Python

Source: https://iii.dev/docs/0-13-0/creating-workers/workers

Connects a worker to the iii engine, optionally specifying a worker name. The engine URL is read from the III_URL environment variable.

```python
import os
from iii import register_worker, InitOptions

worker = register_worker(
    os.environ.get("III_URL"),
    InitOptions(worker_name="my-worker"),
)
```

--------------------------------

### Write to Channel in Python

Source: https://iii.dev/docs/creating-workers/channels

Shows how to write byte data and close an asynchronous channel in Python. The writer is accessed from the input dictionary.

```python
async def generate_file(input: dict) -> dict:
    writer = input["writer"]
    await writer.write(b"hello ")
    await writer.write(b"world")
    await writer.close_async()
    return {"ok": True}

worker.register_function("files::generate", generate_file)
```

--------------------------------

### Migrate HTTP Function Registration

Source: https://iii.dev/docs/next/changelog/0-16-0/align-rust-register-function-with-signature

HTTP configurations are now handled by `RegisterFunction::http`. The `RegisterFunctionOptions` struct is no longer used for this purpose.

```rust
register_function_with(RegisterFunctionMessage::with_id("id".into()), http_config)
```

```rust
register_function("id", RegisterFunction::http(http_config))
```

```rust
register_function_with("id", http_config, RegisterFunctionOptions::default())
```

```rust
register_function("id", RegisterFunction::http(http_config))
```

--------------------------------

### Python Observability Imports

Source: https://iii.dev/docs/changelog/index

Import observability primitives like Logger, init_otel, and with_span from the `iii_observability` package in Python. This replaces older imports from `iii` and `iii.telemetry`.

```python
# Before (Python)
from iii import Logger
from iii.telemetry import init_otel, with_span

# After (Python)
from iii_observability import Logger, init_otel, with_span
```

--------------------------------

### Migrate iii sandbox commands to iii trigger

Source: https://iii.dev/docs/0-13-0/changelog

Replace 'iii sandbox' subcommands with 'iii trigger' for creating, executing, and stopping sandboxes. The new commands use a key-value or JSON payload format.

```bash
# before
iii sandbox create python --idle-timeout 300
iii sandbox exec "$SB" -- python3 -c 'print(2+2)'
iii sandbox stop "$SB"

# after
SB=$(iii trigger sandbox::create image=python idle_timeout_secs=300 | jq -r .sandbox_id)
iii trigger sandbox::exec sandbox_id="$SB" cmd=python3 args='["python3", "-c","print(2+2)"]'
iii trigger sandbox::stop sandbox_id="$SB"
```

--------------------------------

### Register Math Add Function (Python)

Source: https://iii.dev/docs/0-13-0/creating-workers/functions

Registers a function with the ID 'math::add' that accepts a dictionary with keys 'a' and 'b' and returns a dictionary with the sum under key 'c'. This enables basic arithmetic operations in Python workers.

```python
import os
from iii import register_worker, InitOptions

worker = register_worker(
    os.environ.get("III_URL"),
    InitOptions(worker_name="math-worker"),
)

def add_handler(payload: dict) -> dict:
    return {"c": payload["a"] + payload["b"]}

worker.register_function("math::add", add_handler)
```

--------------------------------

### Call HTTP Endpoint with Curl

Source: https://iii.dev/docs/0-13-0/quickstart

Makes a POST request to the newly registered HTTP endpoint to trigger the math function.

```bash
curl -X POST http://localhost:3111/math/add-two-numbers \
  -H 'Content-Type: application/json' \
  -d '{"a": 100, "b": 200}'
```

--------------------------------

### Rust Telemetry API Migration

Source: https://iii.dev/docs/0-13-0/changelog

Migrate from iii telemetry accessors to opentelemetry for obtaining meters and using trace types in Rust.

```rust
// Before (Rust)
use iii::{get_tracer, get_meter, SpanKind, SpanStatus};

// After (Rust)
use opentelemetry::global;
use opentelemetry::trace::{SpanKind, Status};
let meter = global::meter("my-service");
```

--------------------------------

### Register HTTP Trigger with Metadata (Python)

Source: https://iii.dev/docs/creating-workers/triggers

Register an HTTP trigger binding and attach custom metadata. The metadata can include tags like team and environment for bookkeeping.

```python
worker.register_trigger({
        "type": "http",
        "function_id": "math::add",
        "config": {"api_path": "/math/add", "http_method": "POST"},
        "metadata": {"team": "platform", "env": "staging"},
    })
```

--------------------------------

### Migrate Register Function with HTTP Config

Source: https://iii.dev/docs/changelog/0-16-0/align-rust-register-function-with-signature

Replace `register_function_with(RegisterFunctionMessage::with_id("id".into()), http_config)` with `register_function("id", RegisterFunction::http(http_config))`.

```rust
register_function_with(RegisterFunctionMessage::with_id("id".into()), http_config)
```

```rust
register_function("id", RegisterFunction::http(http_config))
```

--------------------------------

### Trigger Math Function Again

Source: https://iii.dev/docs/0-13-0/quickstart

Calls the math::add function again to demonstrate the persistent running total.

```bash
iii trigger math::add a=10 b=20
```

--------------------------------

### Write to Channel in Rust

Source: https://iii.dev/docs/creating-workers/channels

Illustrates extracting a writer channel reference and writing byte data in Rust. It handles potential errors during channel operations and requires specific imports.

```rust
use iii_sdk::{ChannelDirection, ChannelWriter, IIIError};
use serde_json::json;

let refs = iii_sdk::extract_channel_refs(&input);
let (_, writer_ref) = refs
    .iter()
    .find(|(k, r)| k == "writer" && matches!(r.direction, ChannelDirection::Write))
    .ok_or_else(|| IIIError::Handler("missing writer channel ref".into()))?;

let writer = ChannelWriter::new(worker.address(), writer_ref);
writer.write(b"hello ").await?;
writer.write(b"world").await?;
writer.close().await?;
Ok(json!({ "ok": true }))
```

--------------------------------

### Migrate Basic Register Function

Source: https://iii.dev/docs/changelog/0-16-0/align-rust-register-function-with-signature

Replace `register_function(RegisterFunction::new("id", f))` with `register_function("id", RegisterFunction::new(f))`.

```rust
register_function(RegisterFunction::new("id", f))
```

```rust
register_function("id", RegisterFunction::new(f))
```

--------------------------------

### Register 'math::add' function in Node.js/TypeScript

Source: https://iii.dev/docs/creating-workers/functions

Register a function with the 'iii-sdk' in Node.js or TypeScript. The function 'math::add' takes two numbers and returns their sum. Ensure the III_URL environment variable is set.

```typescript
import { registerWorker } from "iii-sdk";

const url = process.env.III_URL;
if (!url) throw new Error("III_URL must be set");
const worker = registerWorker(url);

worker.registerFunction("math::add", async (payload: { a: number; b: number }) => {
  return { c: payload.a + payload.b };
});
```

--------------------------------

### engine::trigger-types::list

Source: https://iii.dev/docs/using-iii/functions

Lists all advertised trigger types, including their configuration and call-request schemas.

```APIDOC
## engine::trigger-types::list

### Description
Lists every advertised trigger type along with its config and call-request schemas.
```

--------------------------------

### ChannelReader and ChannelWriter

Source: https://iii.dev/docs/sdk-reference/node-sdk

Runtime classes for interacting with stream WebSockets. `ChannelReader` exposes a Node `Readable` stream and methods for sending/receiving messages. `ChannelWriter` exposes a `Writable` stream and methods for sending messages and closing the channel. Both are constructed with the engine's WS base URL and a `StreamChannelRef`.

```APIDOC
## Channels

### Description
`ChannelReader` and `ChannelWriter` are runtime classes wrapping the engine's stream WebSockets.

### StreamChannelRef Type
`StreamChannelRef` is the type passed between SDK calls to identify a channel:
```typescript
type StreamChannelRef = {
  channel_id: string;
  access_key: string;
  direction: "read" | "write";
};
```

### ChannelReader
Exposes a Node `Readable` plus `.sendMessage()` and `.onMessage()`.

### ChannelWriter
Exposes a `Writable` plus `.sendMessage()`, `.sendChunked()`, and `.close()`.

### Construction
Construct each with the engine's WS base URL and a `StreamChannelRef`.
```

--------------------------------

### Node.js Telemetry API Migration

Source: https://iii.dev/docs/0-13-0/changelog

Migrate from iii-sdk/telemetry to @opentelemetry/api for accessing tracers and meters in Node.js.

```typescript
// Before (Node)
import { getTracer, getMeter, SpanStatusCode } from 'iii-sdk/telemetry'

// After (Node)
import { trace, metrics, SpanStatusCode } from '@opentelemetry/api'
const tracer = trace.getTracer('my-service')
const meter = metrics.getMeter('my-service')
```

--------------------------------

### Math Function Response After Second Call

Source: https://iii.dev/docs/0-13-0/quickstart

The JSON response after the second call to math::add, showing the new sum and the accumulated running total.

```json
{ "c": 30, "running_total": 35 }
```

--------------------------------

### iii trigger command with key-value arguments

Source: https://iii.dev/docs/changelog/index

Use the 'iii trigger' command with key-value pairs for arguments, suitable for simple payloads.

```bash
# kv form
iii trigger orders::process amount=149.99 currency=USD
```

--------------------------------

### Inspect a specific worker

Source: https://iii.dev/docs/0-13-0/using-iii/workers

Provides detailed information about a particular worker, including its configuration, sandbox state, and recent logs. Also allows streaming logs or executing commands within the worker's sandbox.

```bash
iii worker status <name>             # config, sandbox state, recent logs
```

```bash
iii worker logs <name>               # stream the worker's logs
```

```bash
iii worker exec <name> -- <command>  # run a command inside the worker
```

--------------------------------

### TriggerAction Factory

Source: https://iii.dev/docs/0-13-0/sdk-reference/python-sdk

Factory class for trigger actions. Use TriggerAction.Void() for fire-and-forget or TriggerAction.Enqueue(queue='queue_name') to route through iii-queue.

```APIDOC
## TriggerAction Factory

### Description
Factory class with static helpers for creating trigger actions.

### Usage
```python
# Fire-and-forget
TriggerAction.Void()

# Route through iii-queue
TriggerAction.Enqueue(queue="math")
```

### Methods
* **Void()**: Returns `TriggerActionVoid()`.
* **Enqueue(queue: str)**: Returns `TriggerActionEnqueue(...)`. `queue` is a keyword-only argument.
```

--------------------------------

### Register and Unregister a Standard Function (Python)

Source: https://iii.dev/docs/creating-workers/functions

Registers a standard function named 'math::add' using a handler and then unregisters it. Assumes 'add_handler' is defined elsewhere.

```python
add = worker.register_function("math::add", add_handler)

add.unregister()
```

--------------------------------

### registerWorker

Source: https://iii.dev/docs/0-13-0/sdk-reference/browser-sdk

Connects a browser tab to a running iii engine and returns its handle. The returned ISdk object provides access to all other SDK methods.

```APIDOC
## registerWorker

### Description
Connects a browser tab to a running iii engine and returns its handle. The returned ISdk object provides access to all other SDK methods.

### Signature
```typescript
function registerWorker(address: string, options?: InitOptions): ISdk;
```

### Parameters
#### Path Parameters
- **address** (string) - Required - The engine's SDK WebSocket URL.
- **options** (InitOptions) - Optional - Initialization options.
```

--------------------------------

### Register Function with Schemas (Python)

Source: https://iii.dev/docs/0-13-0/creating-workers/functions

Register a function with request and response schemas in Python. Schemas are used for metadata and documentation.

```python
import os
from iii import register_worker, InitOptions

worker = register_worker(
    os.environ.get("III_URL"),
    InitOptions(worker_name="math-worker"),
)

worker.register_function(
    "math::add",
    add_handler,
    request_schema={
        "type": "object",
        "properties": {"a": {"type": "number"}, "b": {"type": "number"}},
        "required": ["a", "b"],
    },
    response_schema={
        "type": "object",
        "properties": {"c": {"type": "number"}},
        "required": ["c"],
    },
)

```

--------------------------------

### Register HTTP Trigger with Metadata (Rust)

Source: https://iii.dev/docs/creating-workers/triggers

Register an HTTP trigger binding and attach custom metadata using Rust. The metadata can include tags like team and environment for bookkeeping.

```rust
use iii_sdk::RegisterTriggerInput;
    use serde_json::json;

    worker.register_trigger(RegisterTriggerInput {
        trigger_type: "http".into(),
        function_id: "math::add".into(),
        config: json!({ "api_path": "/math/add", "http_method": "POST" }),
        metadata: Some(json!({ "team": "platform", "env": "staging" })),
    })?;
```

--------------------------------

### Register Worker in Rust

Source: https://iii.dev/docs/0-13-0/creating-workers/workers

Connects a worker to the iii engine using the III_URL environment variable. The III_URL must be set in the environment.

```rust
use iii_sdk::{InitOptions, register_worker};

let url = std::env::var("III_URL").expect("III_URL must be set");
let worker = register_worker(&url, InitOptions::default());
```

--------------------------------

### Write to Channel in Node.js

Source: https://iii.dev/docs/creating-workers/channels

Demonstrates writing string data and ending a channel stream in Node.js. Requires the ChannelWriter type.

```typescript
import type { ChannelWriter } from "iii-sdk";

worker.registerFunction("files::generate", async (input: { writer: ChannelWriter }) => {
  input.writer.stream.write(Buffer.from("hello "));
  input.writer.stream.end(Buffer.from("world"));
  return { ok: true };
});
```

--------------------------------

### Structured Sandbox Error Response

Source: https://iii.dev/docs/changelog/index

Illustrates the structured error envelope returned by `sandbox::*` functions on failure. Includes error code, type, message, documentation URL, retryability, and a `fix` payload for resubmission.

```json
{
  "code": "S211",
  "type": "FsParentNotFound",
  "message": "parent directory /workspace/a/b does not exist",
  "docs_url": "https://github.com/iii-hq/iii/.../README.md#S211",
  "retryable": false,
  "fix": { "parents": true },
  "fix_note": "merge `fix` into the original request and resubmit: `parents: true` auto-creates missing intermediate directories"
}
```

--------------------------------

### Engine Discovery Functions

Source: https://iii.dev/docs/0-13-0/sdk-reference/engine-sdk

Provides a list of built-in functions for introspection and worker lifecycle management within the engine.

```APIDOC
## Engine Discovery Functions

### Description
Provides a list of built-in functions for introspection and worker lifecycle management within the engine.

### Functions
- **`engine::channels::create`**
  - Purpose: Create a streaming-channel reader / writer pair.
- **`engine::functions::list`**
  - Purpose: List every registered function (filterable by `include_internal`).
- **`engine::workers::list`**
  - Purpose: List every connected worker with metrics.
- **`engine::triggers::list`**
  - Purpose: List every registered trigger (filterable by `include_internal`).
- **`engine::trigger-types::list`**
  - Purpose: List every registered trigger type with its config and call request schemas.
- **`engine::workers::register`**
  - Purpose: Publish the calling worker's metadata (runtime, version, OS, PID, isolation).
```

--------------------------------

### Migrate Function Registration from Tuple Handler

Source: https://iii.dev/docs/next/changelog/0-16-0/align-rust-register-function-with-signature

For handlers passed as a tuple with `RegisterFunctionMessage::with_id`, use `RegisterFunction::new` for synchronous handlers and `RegisterFunction::new_async` for asynchronous handlers.

```rust
register_function((RegisterFunctionMessage::with_id("id".into()), sync_handler))
```

```rust
register_function("id", RegisterFunction::new(sync_handler))
```

```rust
register_function((RegisterFunctionMessage::with_id("id".into()), async_handler))
```

```rust
register_function("id", RegisterFunction::new_async(async_handler))
```

--------------------------------

### register_worker

Source: https://iii.dev/docs/0-13-0/sdk-reference/rust-sdk

Connect a worker to a running iii engine and return its handle. The returned `III` object carries methods for interacting with the engine.

```APIDOC
## register_worker

### Description
Connect a worker to a running iii engine and return its handle. The returned `III` object carries methods for interacting with the engine. Spawned async tasks are driven on the SDK's internal tokio runtime.

### Signature
```rust
pub fn register_worker(address: &str, options: InitOptions) -> III;
```
```

--------------------------------

### engine::channels::create

Source: https://iii.dev/docs/using-iii/functions

Allocates a pair of streaming channel readers and writers. This is typically handled by the SDK's `worker.createChannel()` and rarely called directly.

```APIDOC
## engine::channels::create

### Description
Allocate a streaming channel reader / writer pair. The SDK wraps this as `worker.createChannel()`; rarely called directly.
```

--------------------------------

### Control Worker Start/Stop/Restart

Source: https://iii.dev/docs/next/using-iii/workers

Manually manage the running state of individual workers. The `-y` flag can be used to skip confirmation prompts for stopping workers.

```bash
iii worker start <name>
```

```bash
iii worker stop -y <name>
```

```bash
iii worker restart <name>
```

--------------------------------

### shutdown / shutdown_async

Source: https://iii.dev/docs/0-13-0/sdk-reference/python-sdk

Disconnects from the engine and releases resources. Use `shutdown_async` from within asyncio contexts.

```APIDOC
## shutdown / shutdown_async

### Description
Disconnect from the engine and release resources.

### Method Signatures
```python
def shutdown(self) -> None: ...
async def shutdown_async(self) -> None: ...
```

### Parameters
* **self** - The instance of the worker.
```

--------------------------------

### shutdown

Source: https://iii.dev/docs/0-13-0/sdk-reference/rust-sdk

Disconnect from the engine and release resources. Returns immediately; in-flight tasks are aborted.

```APIDOC
## shutdown

### Description
Disconnect from the engine and release resources. Returns immediately; in-flight tasks are aborted.

### Signature
```rust
pub fn shutdown(&self);
```
```

--------------------------------

### Register Function with Schemas (Rust)

Source: https://iii.dev/docs/0-13-0/creating-workers/functions

Register a function with request and response schemas in Rust. Schemas are used for metadata and documentation.

```rust
use iii_sdk::{InitOptions, RegisterFunction, register_worker};
use serde_json::json;

let url = std::env::var("III_URL").expect("III_URL must be set");
let worker = register_worker(&url, InitOptions::default());

worker.register_function(
    RegisterFunction::new("math::add", |input: AddInput| {
        Ok(serde_json::json!({ "c": input.a + input.b }))
    })
    .request_schema(json!({ 
        "type": "object",
        "properties": { "a": { "type": "number" }, "b": { "type": "number" } },
        "required": ["a", "b"],
    }))
    .response_schema(json!({ 
        "type": "object",
        "properties": { "c": { "type": "number" } },
        "required": ["c"],
    })),
)?;

```

--------------------------------

### register_worker

Source: https://iii.dev/docs/0-13-0/sdk-reference/python-sdk

Connects a worker to a running iii engine and returns its handle. The address is the engine's SDK WebSocket URL, and options configure worker identity and reconnection.

```APIDOC
## register_worker

### Description
Connect a worker to a running iii engine and return its handle.

### Method Signature
```python
def register_worker(address: str, options: InitOptions | None = None) -> III: ...
```

### Parameters
* **address** (str) - The engine's SDK WebSocket URL.
* **options** (InitOptions | None, optional) - Configures worker identity and reconnection.
```

--------------------------------

### Migrate Register Function with Async Handler

Source: https://iii.dev/docs/changelog/0-16-0/align-rust-register-function-with-signature

Update `register_function((RegisterFunctionMessage::with_id("id".into()), async_handler))` to `register_function("id", RegisterFunction::new_async(async_handler))`.

```rust
register_function((RegisterFunctionMessage::with_id("id".into()), async_handler))
```

```rust
register_function("id", RegisterFunction::new_async(async_handler))
```

--------------------------------

### Math Function Response

Source: https://iii.dev/docs/0-13-0/quickstart

The expected JSON response after calling math::add, showing the calculated sum and the updated running total.

```json
{ "c": 5, "running_total": 5 }
```

--------------------------------

### Invoke a registered function asynchronously

Source: https://iii.dev/docs/next/sdk-reference/python-sdk

Asynchronously invoke a registered function. Use this from within 'asyncio' contexts.

```python
async def trigger_async(self, request: dict[str, Any] | TriggerRequest) -> Any: ...
```
Tokens:
Raw