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.

iii-stream serves WebSocket connections on the configured stream port (default 3112)

Clients connect at

ws://host:{stream_port}/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 identified by
```
stream_name
```
,
```
group_id
```
, and
```
item_id
```
;
```
data
```
is the item payload

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

iii-stream 在配置的流端口（默认3112）上提供WebSocket连接服务

客户端通过

ws://host:{stream_port}/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 }) → iii-stream → 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

使用该模式的代码通常包含以下内容（按需使用）：

```
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)
```
—— 为特定后端注册自定义适配器

Browser Clients

浏览器客户端

For browser-side WebSocket connections, use

iii-browser-sdk

instead of the Node SDK. See

iii-browser-sdk

skill for setup details. Stream authentication via literals is supported.

浏览器端的WebSocket连接请使用

iii-browser-sdk

而非Node SDK。设置详情请查看

iii-browser-sdk

技能。支持通过字面量进行流认证。

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

引擎配置

iii-stream 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 中启用iii-stream，并配置端口和适配器（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.

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