| name | iii-pubsub |
| description | Broadcast fire-and-forget events through the iii-pubsub worker. Use when publishing topic events to multiple subscribers without queue persistence, retries, FIFO ordering, or dead-letter handling. |
Pub/Sub
iii-pubsub is for real-time broadcast inside an iii deployment. It is not the durable queue system.
Install
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.
Example
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
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.
Pub/Sub vs Queue
| 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 |
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.