OpenParable
Skip to content
← Back to skills

Iii Pubsub

Development
iii-pubsub

Iii Pubsub is an Agent Skill for development published in the iii-hq/iii repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Fire-and-forget topic pub/sub: broadcast an event with `publish` and every matching `subscribe` trigger receives it. Use for real-time notifications where missed events are acceptable.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/iii-hq/iii/blob/HEAD/engine/src/workers/pubsub/skills/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/iii-pubsub, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.

Functions

  • publish — broadcast an event to a topic; every subscribe trigger on that exact topic receives the raw data. Empty topic returns topic_not_set.

Reactive triggers

Bind a subscribe trigger when a function should run every time publish broadcasts to a configured topic. The handler receives the raw data value from the publish call directly — no envelope. Multiple triggers can subscribe to the same topic; each gets an independent copy (true fan-out).

Reach for it when:

  • A domain event from one part of the system should kick off side effects elsewhere without the publisher knowing the consumers.
  • You want cross-instance fan-out via the redis adapter.

If subscribers must reliably process every event with retries and dead-letter handling, use iii-queue's durable:subscriber instead — subscribe is fire-and-forget.

How to bind

  1. Register a handler: iii.registerFunction('notifications::on-order-shipped', handler).
  2. Register the trigger:
iii.registerTrigger({
  type: 'subscribe',
  function_id: 'notifications::on-order-shipped',
  config: {
    topic: 'orders.shipped',  // required, non-empty. Exact match only — no wildcards.
  },
})

The handler receives the published data unchanged, with no topic field; if one handler serves multiple topics, embed the topic inside data at publish time. The handler's return value is ignored and there is no retry.

For the published payload shape, call iii get function info on publish or the handler function id.