iii-pubsub

The iii-pubsub worker is topic-based publish/subscribe messaging. Publish an event to a named topic with the publish function and every registered subscribe trigger whose topic matches is invoked with the raw payload — no envelope, no persistence, no retries. It is fire-and-forget broadcast: subscribers receive each event as it arrives, and a subscriber that is offline simply misses it.

The worker exposes one callable function (publish, registered with the bare function id "publish" — no namespace prefix) and one trigger type (subscribe). Two adapters: local (default; in-memory broadcast channels; only delivers to subscribers in this engine process; no external dependency) and redis (redis_url: ${REDIS_URL:redis://localhost:6379}; uses Redis Pub/Sub so events propagate across multiple engine instances).

When to Use

• Real-time notifications consumers may miss without consequence — UI live updates, ephemeral signals, telemetry mirroring.
• Loose coupling where an event source should not know about its consumers.
• Cross-instance fan-out of ephemeral events (configure the redis adapter).

Boundaries

• No persistence, ordering, or retries — a subscriber that is down misses events permanently. Use iii-queue (topic mode, durable:subscriber) when every consumer must process every event.
• Topic matching is exact string equality; there are no wildcards or hierarchical patterns. Register one trigger per topic.
• An empty topic is rejected: publish returns topic_not_set, and a subscribe trigger registered with an empty topic never fires.
• For key/value or stream change reactivity, use iii-state or iii-stream instead — iii-pubsub carries discrete events, not state.