---
question: When do I publish and when do I enqueue on the bus?
kind: overview
---

# Message bus

The bus moves bytes between the parts of a project. It is NATS, the broker the engine and every module connect to, with two delivery models: **publish** reaches every subscriber that is listening, **enqueue** hands each message to exactly one worker and keeps it until one takes it. The event service broadcasts through it, and so does the triple store.

A module calls the broker directly through `self.engine.services.bus`, the SDK's `BusClient`: its messages do not pass through the engine. Publishing and consuming are Python only. Super admins can browse the JetStream streams and their stored messages in Nexus, under System › Data › Bus. How the engine uses NATS as a whole is on [Message bus](/capabilities/get-started/nats) in Get started.

<!-- matrix -->

## Backend

| Model | On the broker |
|---|---|
| Publish | Core NATS subject `<topic>.<routing_key>` |
| Enqueue | A JetStream stream per topic (`naas-abi-<hash>`), one durable consumer per topic and routing key |

The engine's own `services.bus` is `nats_jetstream` on `nats.nats_url`. Leave the `bus:` block out, or keep it only for `emit_message_events`, with `nats_jetstream` on the same URL; any other adapter fails at start. The keys are on the [Configuration Reference](/capabilities/get-started/configuration#message-bus).

## Key concepts

- **Topic and routing key.** Every call names a topic and a routing key; the payload is `bytes`. A subscriber's routing key is a pattern: `.` separates segments, `*` matches one, a trailing `#` matches the rest. `#` alone matches everything on the topic.
- **Publish is live only.** Nothing is kept for a subscriber that was not connected. Use it to notify.
- **One model per topic.** Do not `publish` and `enqueue` on the same topic. A topic's work-queue stream captures `<topic>.>`, so once a queue exists, plain publishes on that topic are stored and handed to its workers.
- **Enqueue is durable.** A message waits until one worker takes it, across restarts. Workers on the same topic and routing key share it: each message goes to one of them.
- **Queue streams.** `enqueue` and `dequeue` need the topic's stream. Logged in as the broker user `module`, a module may not create streams: on a topic whose stream the engine has not created, both raise `StreamNotCreated` (`naas_abi_sdk.streams`). For work a module must do once, a [module job](/capabilities/build/modules/module-jobs) runs on the jobs stream the engine prepares.
- **At least once.** A worker can see a message twice, after a crash or a missing acknowledgement. Make the work safe to repeat.
- **Large payloads.** A payload above the broker limit travels as a claim check in the `abi_claim_checks` object store, up to 256 MiB, and is read back before the receiver sees it. It expires after 7 days, so a queued item must be consumed within that time.
- **Events.** `services.bus.emit_message_events: true` records a `BusMessagePublished` or `BusMessageEnqueued` event for every message the engine's bus sends. A module's messages go straight to the broker and record none.
- **Dependency.** A module declares `"bus"` in `ModuleDependencies(services=(...))`. The attribute is `self.engine.services.bus`.
