iii-channels

通道

类似于：Unix 管道、gRPC 流式传输、WebSocket 数据流

核心概念

在适合任务的情况下使用以下概念。并非每个 worker 都需要通道。

• Channel 是两个端点（写入端和读取端）之间由 WebSocket 支持的二进制流
• createChannel() 会返回一对写入端和读取端，以及可序列化的引用，这些引用可以传递给其他 worker
• StreamChannelRef 是可序列化的引用（channel_id、access_key、direction），可以包含在函数 payload 中
• 写入端发送二进制数据（分块为 64KB 帧）和文本消息
• 读取端通过 readAll() 读取二进制块，或通过回调接收文本消息
• 消费者必须根据可序列化的 StreamChannelRef 构造读取端（例如 ChannelReader::new(...)），而不是使用 createChannel() 返回的生产者侧读取端对象
• 通道支持跨 worker 和跨语言使用——Python 写入端可以向 Rust 读取端传输数据

架构

函数通过 createChannel() 创建通道，并获得一对写入端和读取端。写入端引用或读取端引用会通过触发 payload 传递给另一个函数（可能位于不同的 worker 或使用不同的语言）。引擎会在两个端点之间代理 WebSocket 连接。二进制数据通过引擎的通道端点直接在 worker 之间流动。

iii 使用的原语

原语	用途
createChannel(bufferSize?)	创建通道，返回一对写入端和读取端
ChannelWriter.write(data)	发送二进制数据（分块为 64KB 帧）
ChannelWriter.sendMessage(msg)	通过通道发送文本消息
ChannelWriter.close()	关闭写入端
ChannelReader.readAll()	将整个流读取到单个缓冲区
ChannelReader.onMessage(callback)	注册文本消息回调
StreamChannelRef	用于在 worker 之间传递的可序列化引用

参考实现

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

每个参考实现都使用各自的语言展示相同的模式（创建通道、二进制流式传输、文本消息、跨函数移交）。

常见模式

使用此模式的代码通常会在相关情况下包含：

• const channel = await iii.createChannel() — 创建一对通道端点（生产者访问）
• channel.writer.stream.write(buffer) / channel.writer.write(data) — 发送二进制数据
• channel.writer.sendMessage(JSON.stringify({ type: 'metadata', ... })) — 发送文本元数据
• channel.writer.close() — 发出流结束信号
• 在触发 payload 中传递 channel.readerRef 或 channel.writerRef，以便跨 worker 流式传输
• 消费者必须根据引用重新构造读取端：例如 new ChannelReader(iii.address, readerRef)
• const data = await reader.readAll() — 读取整个流（消费者行为）
• reader.onMessage(msg => { ... }) — 处理文本消息（消费者行为）

调整此模式

在适用时使用以下调整方式。

• 对于不应序列化到 JSON payload 中的大型数据传输，请使用通道
• 对于管道模式，将 readerRef 传递给处理函数，将 writerRef 传递给生成函数
• 使用文本消息在二进制数据流旁传递元数据或信号
• 如果读取端可能比写入端慢，请设置 bufferSize 以施加背压
• 通道支持跨语言使用——TypeScript 生产者可以向 Rust 消费者传输数据

模式边界

• 对于键值状态持久化，优先使用 iii-state-management。
• 对于流的 CRUD 操作（带名称的流以及组/键），优先使用 iii-realtime-streams。
• 对于发布/订阅消息，优先使用 subscribe 类型的触发器。
• 当主要问题是在工作进程之间流式传输二进制数据时，使用 iii-channels。

适用场景

• 当任务主要涉及 iii 引擎中的 iii-channels 时，使用此技能。
• 当请求直接要求使用此模式或实现等效方案时，触发此技能。

边界

• 切勿将此技能用作处理无关任务的通用兜底方案。
• 如果有更具体的 iii 技能更适合，切勿应用此技能。
• 应用此技能中的示例前，务必核实环境和安全限制。