Routing & Endpoints¶

By default, every message is processed inline — synchronously in the caller's context, within the caller's DI scope. No endpoints, no background workers.

Routing lets you override this default. You declare which messages should be dispatched to endpoints — background workers that process messages asynchronously in their own DI scope. The caller enqueues the message and returns immediately.

graph LR
    Bus["bus.send(cmd)"] -->|no route| Inline[Inline Handler]
    Bus -->|routed| EP[Endpoint]
    EP --> Worker[Background Worker]
    Worker --> Handler[Handler in fresh scope]

Default Behavior¶

Without routing configuration, all three dispatch methods execute inline:

1
2
3
4

from waku.messaging import MessagingConfig, MessagingModule

# No endpoints, no routing — everything runs inline.
MessagingModule.register(MessagingConfig())

This is equivalent to calling MessagingModule.register() with no arguments. If your application only needs synchronous, in-process message handling, you can skip the rest of this page.

Local Queue Endpoints¶

A local queue is a buffered, in-process endpoint backed by an anyio memory stream. Messages sent to a local queue are enqueued and return immediately. A background worker task drains the queue and processes each message in a fresh DI scope.

local_queue() creates an endpoint descriptor that MessagingModule uses to construct a live LocalQueueEndpoint during application initialization:

from waku.messaging.endpoints.base import local_queue

entry = local_queue('domain-events')

The string argument is the endpoint URI — a logical name you reference in route declarations.

Per-Type Routing¶

Use route(MessageType).to('endpoint-uri') to route a specific message type to an endpoint:

1
2
3
4
5
6
7
8
9

from waku.messaging import MessagingConfig, MessagingModule
from waku.messaging.endpoints.base import local_queue
from waku.messaging.router import route

config = MessagingConfig(
    endpoints=[local_queue('domain-events')],
    routing=[route(OrderPlaced).to('domain-events')],
)
MessagingModule.register(config)

When bus.publish(OrderPlaced(...)) is called, handlers for OrderPlaced are dispatched to the domain-events endpoint. Handlers not covered by the route still run inline (see Additive Routing).

Module-Level Routing¶

Use route_module(Module).events_to('endpoint-uri') to route all events registered in a module to an endpoint. This is more maintainable than per-type routing when a module owns many event types:

1
2
3
4
5
6
7
8
9

from waku.messaging import MessagingConfig, MessagingModule
from waku.messaging.endpoints.base import local_queue
from waku.messaging.router import route_module

config = MessagingConfig(
    endpoints=[local_queue('domain-events')],
    routing=[route_module(PaymentModule).events_to('domain-events')],
)
MessagingModule.register(config)

Every event type bound via MessagingExtension().bind_event(...) inside PaymentModule is routed to the domain-events endpoint.

Additive Routing¶

When an event has handlers in multiple modules and only some are routed, publish() does both:

1. Runs non-routed handlers inline (synchronously in the caller's scope).
2. Dispatches to endpoints for routed handlers (asynchronously).

This means routing is additive — it never silences inline handlers that were not routed.

graph TD
    Publish["bus.publish(OrderPlaced)"] --> Check{Routed?}
    Check -->|Module A handler routed| EP[Endpoint]
    EP --> WorkerA[Worker: Module A handler]
    Check -->|Module B handler not routed| InlineB[Inline: Module B handler]

Consider an example where OrderPlaced has handlers in two modules:

• Module A — handler is routed to a local queue endpoint.
• Module B — handler has no route, so it runs inline.

When you call bus.publish(OrderPlaced(...)), Module B's handler executes immediately in the caller's scope, while Module A's handler is enqueued for background processing.

Routing Precedence¶

Routes are evaluated in this order:

Routes are additive — if both a per-type and a module-level route match, the message is dispatched to all matching endpoints. When no route matches, the message runs inline.

Endpoint Lifecycle¶

Endpoints are managed automatically by EndpointLifecycleExtension, which is registered internally by MessagingModule. You do not need to start or stop endpoints manually.

Endpoints start after all modules have been initialized and stop in reverse order during shutdown.

Method Semantics with Routing¶

Each dispatch method interacts with routing differently:

Further reading¶

• Message Bus — setup, interfaces, and dispatch methods
• Message Context — correlation tracking across message chains
• Pipeline Behaviors — cross-cutting middleware for request handling
• Events — event definitions, handlers, and publishers