angzarr_client.router.runtime

Typed runtime routers produced by Router.build().

Five kind-specific runtime routers: command handler, saga, process manager, projector, and upcaster. Each carries a name and a list of (cls, factory) pairs; dispatch delegates to the matching function in dispatch.py, which calls factory() per request to obtain a fresh handler instance.

No public constructors: users reach these types only through Router(...).build(). Constructors are conventionally private (leading underscore on internal factories). Tests construct through the builder.

Attributes

S
Factory

Classes

CommandHandlerRouter	Runtime router dispatching commands to registered @command_handler instances.
SagaRouter	Runtime router dispatching events to registered @saga instances.
ProcessManagerRouter	Runtime router dispatching events to registered @process_manager instances.
ProjectorRouter	Runtime router fanning events out to registered @projector instances.
UpcasterRouter	Runtime router transforming events through registered @upcaster instances.

Module Contents

angzarr_client.router.runtime.S

angzarr_client.router.runtime.Factory

class angzarr_client.router.runtime.CommandHandlerRouter(factories: list[Factory])

Bases: _BuiltRouterBase, Generic[S]

Runtime router dispatching commands to registered @command_handler instances.

property name: str

Domain this router serves (read from the first registered handler’s @command_handler(domain=...) metadata).

@command_handler has no name attribute, so the domain is the natural identifier. Mirrors Rust’s CommandHandlerRouter::name() (runtime.rs:625-633).

dispatch(request)

Route a ContextualCommand to the matching @handles method.

supports_handle_fact() → bool

Audit #45: True if any registered handler declares at least one @handles_fact method. The gRPC adapter uses this as the gate for the HandleFact RPC — False → return UNIMPLEMENTED without entering dispatch.

Implemented as pure metadata read on the registered classes; no factory invocation, no per-request work.

supports_replay() → bool

Audit #45: True if any registered handler opted in via @command_handler(supports_replay=True). The gRPC adapter uses this as the gate for the Replay RPC.

Replay is a generic state-rebuild operation — the framework implements it from the existing @applies machinery, so the opt-in is just an explicit acknowledgement that the aggregate’s state type is proto-serializable (replay round-trips state via Any).

dispatch_fact(request)

Route a FactRequest to matching @handles_fact methods.

Caller is responsible for gating via supports_handle_fact() before invoking this — the gRPC adapter does so.

dispatch_replay(request)

Replay events on top of a base snapshot to compute final state.

Caller is responsible for gating via supports_replay() before invoking this — the gRPC adapter does so.

class angzarr_client.router.runtime.SagaRouter(factories: list[Factory])

Bases: _BuiltRouterBase

Runtime router dispatching events to registered @saga instances.

dispatch(request)

Route a SagaHandleRequest to all matching @handles methods.

output_domains() → list[str]

Domains this router emits commands to.

Read from each registered handler class’s __angzarr_meta__. Default is empty — only sagas (target) and process managers (targets) override.

sync_output_domains() → list[str]

Audit #74: subset of output_domains() that the registered handlers ever address with sync mode (SIMPLE / CASCADE / DECISION / ISOLATED). Drives readiness probing — only sync targets need their coordinator reachable for traffic to be safe. Default empty; saga / PM routers override.

has_async_outputs() → bool

Audit #74: True if any registered handler emits to at least one async target — i.e. ever publishes through the async bus rather than synchronously calling a downstream coordinator. Drives whether the readiness supervisor includes a BusProbe. Default False (CH / Projector / Upcaster never cross-emit).

class angzarr_client.router.runtime.ProcessManagerRouter(factories: list[Factory])

Bases: _BuiltRouterBase, Generic[S]

Runtime router dispatching events to registered @process_manager instances.

dispatch(request)

Route a ProcessManagerHandleRequest to matching handlers.

output_domains() → list[str]

Domains this router emits commands to.

Read from each registered handler class’s __angzarr_meta__. Default is empty — only sagas (target) and process managers (targets) override.

sync_output_domains() → list[str]

Audit #74: subset of output_domains() that the registered handlers ever address with sync mode (SIMPLE / CASCADE / DECISION / ISOLATED). Drives readiness probing — only sync targets need their coordinator reachable for traffic to be safe. Default empty; saga / PM routers override.

has_async_outputs() → bool

Audit #74: True if any registered handler emits to at least one async target — i.e. ever publishes through the async bus rather than synchronously calling a downstream coordinator. Drives whether the readiness supervisor includes a BusProbe. Default False (CH / Projector / Upcaster never cross-emit).

class angzarr_client.router.runtime.ProjectorRouter(factories: list[Factory])

Bases: _BuiltRouterBase

Runtime router fanning events out to registered @projector instances.

dispatch(events)

Fan out each event in the book to matching @handles methods.

class angzarr_client.router.runtime.UpcasterRouter(factories: list[Factory])

Bases: _BuiltRouterBase

Runtime router transforming events through registered @upcaster instances.

dispatch(request)

Transform each event in request.events via matching @upcasts methods.