iii-pubsub

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pub/Sub

发布/订阅（Pub/Sub）

iii-pubsub

is for real-time broadcast inside an iii deployment. It is not the durable queue system.

iii-pubsub

用于iii部署环境内的实时广播，它并非持久化队列系统。

Install

安装

bash

iii worker add iii-pubsub

bash

iii worker add iii-pubsub

Core Model

核心模型

Producers call
```
publish
```
with
```
{ topic, data }
```
.
Subscribers register trigger type
```
subscribe
```
with
```
{ topic }
```
.
Subscriber handlers receive the raw
```
data
```
value, not an envelope.
Delivery is best-effort broadcast. Use
```
iii-queue
```
for retries, FIFO, and DLQ.

生产者调用
```
publish
```
方法，传入参数
```
{ topic, data }
```
。
订阅者注册类型为
```
subscribe
```
的触发器，配置参数
```
{ topic }
```
。
订阅者处理器接收原始的
```
data
```
值，而非封装信封。
交付采用“尽力而为”的广播方式。如需重试、FIFO排序和死信队列（DLQ）功能，请使用
```
iii-queue
```
。

Example

示例

typescript

import { registerWorker, TriggerAction } from 'iii-sdk'

const iii = registerWorker('ws://localhost:49134')

iii.registerFunction('notifications::on-order-shipped', async (data) => {
  return { seen: data.orderId }
})

iii.registerTrigger({
  type: 'subscribe',
  function_id: 'notifications::on-order-shipped',
  config: { topic: 'orders.shipped' },
})

await iii.trigger({
  function_id: 'publish',
  payload: {
    topic: 'orders.shipped',
    data: { orderId: 'ord_123' },
  },
  action: TriggerAction.Void(),
})

typescript

import { registerWorker, TriggerAction } from 'iii-sdk'

const iii = registerWorker('ws://localhost:49134')

iii.registerFunction('notifications::on-order-shipped', async (data) => {
  return { seen: data.orderId }
})

iii.registerTrigger({
  type: 'subscribe',
  function_id: 'notifications::on-order-shipped',
  config: { topic: 'orders.shipped' },
})

await iii.trigger({
  function_id: 'publish',
  payload: {
    topic: 'orders.shipped',
    data: { orderId: 'ord_123' },
  },
  action: TriggerAction.Void(),
})

Configuration

配置

yaml

workers:
  - name: iii-pubsub
    config:
      adapter:
        name: local

Use

adapter.name: redis

with

redis_url

when multiple engine instances need to receive the same topic events.

yaml

workers:
  - name: iii-pubsub
    config:
      adapter:
        name: local

当多个引擎实例需要接收相同主题事件时，请使用

adapter.name: redis

并配置

redis_url

。

Pub/Sub vs Queue

发布/订阅（Pub/Sub）与队列对比

Need	Use
Notify every live subscriber now	`iii-pubsub`
Retry failed subscribers	`iii-queue` topic mode
Direct async function call with retries	`TriggerAction.Enqueue({ queue })`
Dead-letter and redrive	`iii-queue`
Strict ordering	`iii-queue` FIFO

需求	使用工具
立即通知所有在线订阅者	`iii-pubsub`
重试失败的订阅者	`iii-queue` 主题模式
带重试的直接异步函数调用	`TriggerAction.Enqueue({ queue })`
死信处理与重驱动	`iii-queue`
严格排序	`iii-queue` FIFO

When to Use

使用场景

Use this skill when the task mentions pub/sub, broadcasting, topics, non-durable fanout, live notifications, or fire-and-forget event distribution.

当任务涉及发布/订阅、广播、主题、非持久化扇出、实时通知或“即发即弃”事件分发时，请使用此技能。

Boundaries

使用边界

Do not use pub/sub for guaranteed delivery.
Do not use
```
iii::durable::publish
```
when the request explicitly needs non-durable pub/sub.
Do not generate removed service APIs or stream adapter SDK APIs.

不要将发布/订阅用于需要保证交付的场景。
当请求明确需要非持久化发布/订阅时，请勿使用
```
iii::durable::publish
```
。
请勿生成已移除的服务API或流适配器SDK API。