iii-channels

Channels

Comparable to: Unix pipes, gRPC streaming, WebSocket data streams

Key Concepts

Use the concepts below when they fit the task. Not every worker needs channels.

• A Channel is a WebSocket-backed binary stream between two endpoints (writer and reader)
• createChannel() returns a writer/reader pair plus serializable refs that can be passed to other workers
• StreamChannelRef is a serializable reference (channel_id, access_key, direction) that can be included in function payloads
• Writers send binary data (chunked into 64KB frames) and text messages
• Readers consume binary chunks via readAll() or receive text messages via callbacks
• Consumers must construct a reader from a serializable StreamChannelRef (e.g., ChannelReader::new(...)) rather than using the producer-side reader object returned by createChannel()
• Channels work cross-worker and cross-language — a Python writer can stream to a Rust reader

Architecture

A function creates a channel via createChannel(), receiving a writer and reader pair. The writer ref or reader ref is passed to another function (potentially in a different worker/language) via a trigger payload. The engine brokers the WebSocket connection between the two endpoints. Binary data flows directly between workers through the engine's channel endpoint.

iii Primitives Used

Primitive	Purpose
createChannel(bufferSize?)	Create a channel, returns writer + reader pair
ChannelWriter.write(data)	Send binary data (chunked into 64KB frames)
ChannelWriter.sendMessage(msg)	Send a text message through the channel
ChannelWriter.close()	Close the writer end
ChannelReader.readAll()	Read entire stream into a single buffer
ChannelReader.onMessage(callback)	Register callback for text messages
StreamChannelRef	Serializable reference to pass between workers

Reference Implementation

• TypeScript: ../references/channels.js
• Python: ../references/channels.py
• Rust: ../references/channels.rs

Each reference shows the same patterns (channel creation, binary streaming, text messages, cross-function handoff) in its respective language.

Common Patterns

Code using this pattern commonly includes, when relevant:

• const channel = await iii.createChannel() — create a channel pair (producer access)
• channel.writer.stream.write(buffer) / channel.writer.write(data) — send binary data
• channel.writer.sendMessage(JSON.stringify({ type: 'metadata', ... })) — send text metadata
• channel.writer.close() — signal end of stream
• Pass channel.readerRef or channel.writerRef in trigger payloads for cross-worker streaming
• Consumer must reconstruct the reader from the ref: e.g., new ChannelReader(iii.address, readerRef)
• const data = await reader.readAll() — read entire stream (consumer behavior)
• reader.onMessage(msg => { ... }) — handle text messages (consumer behavior)

Adapting This Pattern

Use the adaptations below when they apply to the task.

• Use channels for large data transfers that shouldn't be serialized into JSON payloads
• Pass readerRef to a processing function and writerRef to a producing function for pipeline patterns
• Use text messages for metadata/signaling alongside binary data streams
• Set bufferSize when the reader may be slower than the writer to apply backpressure
• Channels work cross-language — a TypeScript producer can stream to a Rust consumer

Pattern Boundaries

• For key-value state persistence, prefer iii-state-management.
• For stream CRUD (named streams with groups/keys), prefer iii-realtime-streams.
• For pub/sub messaging, prefer triggers with subscribe type.
• Stay with iii-channels when the primary problem is binary data streaming between workers.

When to Use

• Use this skill when the task is primarily about iii-channels in the iii engine.
• Triggers when the request directly asks for this pattern or an equivalent implementation.

Boundaries

• Never use this skill as a generic fallback for unrelated tasks.
• You must not apply this skill when a more specific iii skill is a better fit.
• Always verify environment and safety constraints before applying examples from this skill.