Channels - iii

Channels move large or binary payloads between iii workers without putting the data in a JSON function payload. Use one when the payload is expected to be large (files, images, datasets), above roughly 16 MB, intended to be streamed (audio, video), or you want incremental progress updates during long-running work. For small JSON, stick with a regular worker.trigger(...) call.

For the underlying model (how channels are addressed, multiplexed, and torn down), see Channels architecture.

Payload size

iii itself doesn’t enforce a maximum trigger-payload size. The effective ceiling comes from whichever WebSocket library the engine and the calling SDK use, and each has its own defaults for the per-frame and per-message size. The smallest common per-frame default sits around 16 MB, which is the practical line at which you should switch to a channel. The libraries iii currently relies on:

Engine (axum on top of tokio-tungstenite ). See WebSocketConfig for max_frame_size and max_message_size.
Node SDK (ws). See the maxPayload option.
Python SDK (websockets). See the max_size option.
Rust SDK (tokio-tungstenite) See WebSocketConfig, same as the engine.

These are library defaults and can shift between dependency versions; iii doesn’t publish a hard guaranteed cap. 16 MB is a safe default to follow.

Using channels

A channel is created by one worker and has two local stream ends: writer and reader; plus two serializable refs (writerRef / readerRef) that can be handed to another function. The subsections below cover the local-end API: creating a channel, writing bytes into its writer, and reading bytes from its reader.

Create a channel

worker.createChannel() returns a channel with two local stream objects and two serializable refs: writer and reader are the local stream ends, and writerRef / readerRef are the tokens you pass to another function so it can read or write the other end.

Node / TypeScript
Python
Rust

const channel = await worker.createChannel();

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

channel = iii_client.create_channel()

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

let channel = worker.create_channel(None).await?;

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

Write to a channel

Write the payload to the local writer and close it when finished. The bytes flow through the engine to whichever worker holds the matching reader.

Node / TypeScript
Python
Rust

const channel = await worker.createChannel();

channel.writer.stream.end(Buffer.from("file contents"));

channel = await iii_client.create_channel_async()

await channel.writer.write(b"file contents")
await channel.writer.close_async()

let channel = worker.create_channel(None).await?;

channel.writer.write(b"file contents").await?;
channel.writer.close().await?;

Read from a channel

Read the local reader until the other end closes. The bytes arrive in the order they were written by whichever worker holds the matching writer.

Node / TypeScript
Python
Rust

const channel = await worker.createChannel();

let bytes = 0;
for await (const chunk of channel.reader.stream) {
  bytes += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
}

channel = await iii_client.create_channel_async()

bytes_total = 0
async for chunk in channel.reader:
    bytes_total += len(chunk)

let channel = worker.create_channel(None).await?;

let mut bytes = 0;
while let Some(chunk) = channel.reader.next_binary().await? {
    bytes += chunk.len();
}

Using channels across functions

A channel only becomes useful once both ends are owned by different code paths. Typically one function that holds the local writer / reader and another that receives the matching ref in its payload. The two subsections below cover that handoff: first how to send a ref alongside a normal trigger call, then how the receiving function turns it back into a live stream to read or write.

Pass a channel ref to another function

Pass the readerRef (or writerRef) as part of a normal function invocation. The receiving function uses the ref to read from (or write to) the channel.

Node / TypeScript
Python
Rust

const result = await worker.trigger({
  function_id: "files::process",
  payload: {
    filename: "report.csv",
    reader: channel.readerRef,
  },
});

result = await iii_client.trigger_async({
    "function_id": "files::process",
    "payload": {
        "filename": "report.csv",
        "reader": channel.reader_ref.model_dump(),
    },
})

use iii_sdk::TriggerRequest;
use serde_json::json;

let result = worker
    .trigger(TriggerRequest {
        function_id: "files::process".to_string(),
        payload: json!({
            "filename": "report.csv",
            "reader": channel.reader_ref,
        }),
        action: None,
        timeout_ms: None,
    })
    .await?;

Node and Python deserialize incoming channel refs into live ChannelReader / ChannelWriter objects before the handler runs, so the ref arrives ready to iterate or write to. Rust receives the ref in JSON and reconstructs the reader or writer explicitly with ChannelReader::new(...) or ChannelWriter::new(...).

Read from a channel ref

Node / TypeScript
Python
Rust

import type { ChannelReader } from "iii-sdk";

worker.registerFunction("files::process", async (input: { reader: ChannelReader }) => {
  let bytes = 0;
  for await (const chunk of input.reader.stream) {
    bytes += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
  }
  return { bytes };
});

async def process_file(input: dict) -> dict:
    reader = input["reader"]
    total = 0
    async for chunk in reader:
        total += len(chunk)
    return {"bytes": total}

worker.register_function("files::process", process_file)

use iii_sdk::{ChannelDirection, ChannelReader, IIIError};
use serde_json::json;

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

let reader = ChannelReader::new(worker.address(), reader_ref);
let mut bytes = 0;
while let Some(chunk) = reader.next_binary().await? {
    bytes += chunk.len();
}
Ok(json!({ "bytes": bytes }))

Write to a channel ref

Node / TypeScript
Python
Rust

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 };
});

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)

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 }))

For the per-language channel API surface, see the SDK reference: Node, Python, and Rust.

​Payload size

​Using channels

​Create a channel

​Write to a channel

​Read from a channel

​Using channels across functions

​Pass a channel ref to another function

​Read from a channel ref

​Write to a channel ref

Payload size

Using channels

Create a channel

Write to a channel

Read from a channel

Using channels across functions

Pass a channel ref to another function

Read from a channel ref

Write to a channel ref