用途:iii-stream 是 iii 框架中的实时流 worker,把实时数据按 stream_name -> group_id -> item_id 三级结构存入所配置的适配器,并提供两套接口:CRUD 形式的 stream::* 函数命名空间,以及响应式触发器(stream、stream:join、stream:leave),在数据变化和 WebSocket 订阅者连接/断开时触发。响应式后端通过把处理器绑定到触发器实现,而非轮询。
主要能力:写入会持久化新值,在派生任务上派发匹配的 stream 触发器(fire-and-forget,调用先返回),并向订阅该 (stream_name, group_id) 的所有 WebSocket 客户端广播变更。stream:join 触发器兼作授权闸门:处理器返回 { unauthorized: true } 会在任何数据流动前拒绝订阅。可配合 worker 的 auth_function 配置,在每次 WebSocket 握手时运行一次,并把上下文值写入每个 join/leave 事件。函数包括 stream::set、stream::update(原子有序 set/merge/increment/decrement/append/remove)、stream::delete、stream::send(不持久化的瞬时事件)、stream::get、stream::list、stream::list_groups、stream::list_all。
使用方式:注册处理器 iii.registerFunction('presence::on-change', handler),再注册触发器 iii.registerTrigger({ type: 'stream', function_id: 'presence::on-change', config: { stream_name: 'presence', group_id: 'room-1', item_id: 'user-123' } })。stream 需要非空 stream_name,group_id/item_id 留空即通配;stream:join 与 stream:leave 不接受配置字段,在处理器内按事件分支。适配器可选 kv(默认,内存或文件,仅单实例)或 redis(多实例实时扇出必需)。浏览器订阅使用 Browser SDK(iii-browser-sdk)。
适用场景:数据变化需触发派生投影、审计日志或通知;需在服务端对 WebSocket 订阅授权;需对订阅者连接/断开做在线计数、限流桶或审计;需对条目做原子部分更新。
限制:不是通用键值存储,作用域/键值请用独立 state worker;默认 kv 适配器不跨进程扇出;stream:leave 不是授权闸门,其返回值被忽略;触发器处理器在写入返回后运行,失败不回滚写入也不反馈给调用方;直接连接流端口已弃用,建议用 Browser SDK。