iii-realtime-streams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Realtime Streams

实时流

Comparable to: Socket.io, Pusher, Firebase Realtime

同类工具：Socket.io、Pusher、Firebase Realtime

Key Concepts

核心概念

Use the concepts below when they fit the task. Not every stream setup needs all of them.

StreamModule serves WebSocket connections on port 3112

Clients connect at

ws://host:3112/stream/{stream_name}/{group_id}

stream::set / stream::get / stream::list / stream::delete provide CRUD for stream items
stream::send pushes events to all connected clients in a stream group
```
createStream
```
registers a custom adapter for non-default stream backends
Each stream item is addressed by
```
stream_name
```
,
```
group_id
```
,
```
item_id
```
, and
```
data
```

以下概念适用于对应场景，并非所有流设置都需要用到全部概念。

StreamModule 在3112端口提供WebSocket连接服务

客户端通过

ws://host:3112/stream/{stream_name}/{group_id}

建立连接

stream::set / stream::get / stream::list / stream::delete 提供流项的CRUD操作
stream::send 向流组内所有已连接客户端推送事件
```
createStream
```
为非默认流后端注册自定义适配器
每个流项通过
```
stream_name
```
、
```
group_id
```
、
```
item_id
```
和
```
data
```
进行标识

Architecture

架构

Function → trigger('stream::set', { stream_name, group_id, item_id, data }) → trigger('stream::send', { stream_name, group_id, data }) → StreamModule → WebSocket push → Connected clients at /stream/{stream_name}/{group_id}

iii Primitives Used

使用的iii原语

Primitive	Purpose
`trigger({ function_id: 'stream::set', payload })`	Create or update a stream item
`trigger({ function_id: 'stream::get', payload })`	Read a stream item
`trigger({ function_id: 'stream::list', payload })`	List items in a stream group
`trigger({ function_id: 'stream::delete', payload })`	Remove a stream item
`trigger({ function_id: 'stream::send', payload })`	Push an event to connected clients
`createStream`	Register a custom stream adapter

原语	用途
`trigger({ function_id: 'stream::set', payload })`	创建或更新流项
`trigger({ function_id: 'stream::get', payload })`	读取流项
`trigger({ function_id: 'stream::list', payload })`	列出流组内的项
`trigger({ function_id: 'stream::delete', payload })`	删除流项
`trigger({ function_id: 'stream::send', payload })`	向已连接客户端推送事件
`createStream`	注册自定义流适配器

Reference Implementation

参考实现

See ../references/realtime-streams.js for the full working example — a stream that pushes live updates to WebSocket clients and manages stream items with CRUD operations.

Also available in Python: ../references/realtime-streams.py

Also available in Rust: ../references/realtime-streams.rs

完整工作示例请查看 ../references/realtime-streams.js —— 一个将实时更新推送给WebSocket客户端并通过CRUD操作管理流项的流实现。

同时提供Python版本：../references/realtime-streams.py

以及Rust版本：../references/realtime-streams.rs

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

```
registerWorker(url, { workerName })
```
— worker initialization

trigger({ function_id: 'stream::set', payload: { stream_name, group_id, item_id, data } })

— write stream item

trigger({ function_id: 'stream::send', payload: { stream_name, group_id, data } })

— push event to clients

trigger({ function_id: 'stream::get', payload: { stream_name, group_id, item_id } })

— read stream item

trigger({ function_id: 'stream::list', payload: { stream_name, group_id } })

— list items in group

```
createStream(name, adapter)
```
— custom adapter for specialized backends
```
const logger = new Logger()
```
— structured logging

当相关时，使用此模式的代码通常包含以下内容：

```
registerWorker(url, { workerName })
```
—— 工作进程初始化

trigger({ function_id: 'stream::set', payload: { stream_name, group_id, item_id, data } })

—— 写入流项

trigger({ function_id: 'stream::send', payload: { stream_name, group_id, data } })

—— 向客户端推送事件

trigger({ function_id: 'stream::get', payload: { stream_name, group_id, item_id } })

—— 读取流项

trigger({ function_id: 'stream::list', payload: { stream_name, group_id } })

—— 列出组内的项

```
createStream(name, adapter)
```
—— 为专用后端配置自定义适配器
```
const logger = new Logger()
```
—— 结构化日志

Adapting This Pattern

模式适配

Use the adaptations below when they apply to the task.

Name streams after your domain (e.g.

chat-messages

dashboard-metrics

notifications

)

Use
```
group_id
```
to partition streams per user, room, or tenant
Combine with
```
iii-state-reactions
```
to push a stream event whenever state changes
Use
```
createStream
```
when the default adapter does not fit (e.g. custom persistence or fan-out logic)

当适用时，可采用以下适配方式：

根据业务领域命名流（例如
```
chat-messages
```
、
```
dashboard-metrics
```
、
```
notifications
```
）
使用
```
group_id
```
按用户、房间或租户对流进行分区
结合
```
iii-state-reactions
```
，在状态变化时推送流事件
当默认适配器不适用时（例如自定义持久化或扇出逻辑），使用
```
createStream
```

Engine Configuration

引擎配置

StreamModule must be enabled in iii-config.yaml with a port and adapter (KvStore or Redis). See ../references/iii-config.yaml for the full annotated config reference.

必须在iii-config.yaml中启用StreamModule，并配置端口和适配器（KvStore或Redis）。完整带注释的配置参考请查看 ../references/iii-config.yaml。

Pattern Boundaries

模式边界

If the task is about persistent key-value data without real-time push, prefer
```
iii-state-management
```
.
If the task needs reactive triggers on state changes (server-side), prefer
```
iii-state-reactions
```
.
Stay with
```
iii-realtime-streams
```
when the primary need is pushing live updates to connected clients.

如果任务涉及持久化键值数据但无需实时推送，建议使用
```
iii-state-management
```
。
如果任务需要基于状态变化的服务器端响应式触发器，建议使用
```
iii-state-reactions
```
。
当核心需求是向已连接客户端推送实时更新时，使用
```
iii-realtime-streams
```
。

When to Use

使用场景

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

当任务核心是iii引擎中的
```
iii-realtime-streams
```
时，使用此技能。
当请求直接要求此模式或等效实现时触发。

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.

切勿将此技能作为无关任务的通用备选方案。
当更特定的iii技能更合适时，不得应用此技能。
在应用此技能中的示例前，务必验证环境和安全约束。