cqrs-eda
Wires a python-cqrs domain event, notification, transactional outbox, and transactional inbox, and runs independent domain handlers concurrently. Use when a fact stays in this process, must reach another service, must survive at-least-once delivery, or when handler order does not matter.
Event-driven delivery
Read cqrs-setup before writing these types. This file builds the feature that skill already picked: a domain event, a notification, the outbox, the inbox, or parallel domain handlers.
The package is already installed. Do not add an install step.
Put the types in app/events.py. Keep the handler in app/handlers.py and the registration in app/bootstrap.py.
Steps
- A fact inside this process is a
cqrs.DomainEvent. A fact for another service is acqrs.NotificationEventwith keyword-onlyevent_name,topic, andpayload. A dataclass payload is for a message this process builds. - For a domain event, append it on the handler
eventsproperty. Register eachcqrs.EventHandlerwithdomain_events_mapperoncqrs.bootstrap.requests.bootstrap.EventMap.bindappends, so several handlers may listen. The mediator emitseventsafterhandlereturns and beforesendreturns. Keep those handlers idempotent when the command can be retried. WithScopeStrategy.SENDthey run one after another on the command session. Independent handlers are the parallel section below. - For a notification that may be lost, append the
NotificationEventoneventsand pass a realmessage_brokerto bootstrap. The default broker drops the message. Use this for a metric or a best-effort signal. - For a notification that must commit with the business row, leave
eventsempty for that notification. In the handler,session.addthe business row andrepository.addthe notification on the same session.await repository.commit()commits both when this handler is not the one an inbox worker sends. A handler the inbox worker sends must not commit. The worker commits the business rows, the outbox rows, and the inbox status together. A separate process runscqrs.EventProducer, then commits the repository so status updates stick. Registerevent_nameon anOutboxedEventMapbefore the first read or write. A second registration of the same name raisesKeyError. Prefercqrs.SqlAlchemyOutboxedEventRepositorywithpython-cqrs[sqlalchemy], orcqrs.outbox.sqlmodel.SqlModelOutboxedEventRepositorywithpython-cqrs[sqlmodel]. Use one storage extra for the process. - For an inbox, presentation calls
InboxRepository.addwith a batch of(message_id, message)and the caller commits.addreturnslist[bool].Truemeans inserted.Falsemeans(message_id, message_name)is already stored, including earlier in the same batch. An empty batch returns[]. Ack, or HTTP 202, happens after that commit. AFalseis still ack or 202. Another process constructsInboxProcessorwith the repository for that batch session, theInboxMessageMap, and the mediators.processtakes the row. It sends aRequestthroughRequestMediatoror an event throughEventMediator. The handler is the one already registered. The processor does not commit. The worker commits the business rows and the status together. Requests and domain events register under the class name. Notification events register underevent_name. - Events that arrive from a broker and must finish before ack use
cqrs.bootstrap.events.bootstrapandawait mediator.send(event)onEventMediator. That path is not the inbox. The inbox is the path that only stores the message and runs it later.
Where the calls live
The command handler writes the business row and, when the fact must leave the process, the outbox row. It does not publish. It may append a DomainEvent for an in-process reaction. It does not append the same notification it already passed to repository.add.
domain_events_mapper belongs on cqrs.bootstrap.requests.bootstrap, next to commands_mapper. Broker facts that must run to completion before ack use a separate EventMediator from cqrs.bootstrap.events.bootstrap.
The publisher process owns EventProducer. After each batch it commits the outbox repository. Rows that fail until flush_counter reaches five leave the selectable batch. Inspect those rows. The producer will not yield them again. On PostgreSQL, MySQL 8.0 or later, and MariaDB 10.6 or later, get_many holds the batch with FOR UPDATE SKIP LOCKED until that commit or a rollback.
Presentation owns add and the commit. The worker owns get_many, InboxProcessor.process, and a later commit. Do not share one session between them. open_scope is only when the presentation transaction also writes another row. A plain add does not need it.
SqlAlchemyInboxRepository needs python-cqrs[sqlalchemy]. SqlModelInboxRepository needs python-cqrs[sqlmodel]. Both are lazy on cqrs. Register message names on an InboxMessageMap instance when tests must not share the process-global map. The same rule applies to OutboxedEventMap. JSON is the default codec.
A request-handler exception in the worker rolls back only that row's savepoint. not_processed increments flush_counter. After five failures the row leaves get_many. A domain-handler exception is logged and does not fail send, so the inbox can still mark the row processed. Do not use a domain event on an inbox request for a reaction that must cause a retry.
How the four differ
A domain event finishes before send returns. A notification on events is a best-effort publish. An outbox row commits with the business row and is published later. An inbox row commits before the handler runs, so a repeat delivery does not insert a second row. A crash after the handler runs and before the status commit can run that handler again. Effects outside the worker transaction must be idempotent.
One command may do two of these. The short shape appends OrderPlaced for this process and stores OrderCreated in the outbox. The inbox function only accepts PlaceOrder from outside. It does not call the mediator.
Parallel domain handlers
Use this when domain handlers do not share a session and the order of those handlers does not matter. Skip it when ScopeStrategy.SEND is the application's strategy, or when the handlers write one session. cqrs-setup already has that pair. This section only turns the flag on.
concurrent_event_handle_enable=True is valid only with cqrs.ScopeStrategy.HANDLER or cqrs.ScopeStrategy.NONE. Never set it with ScopeStrategy.SEND. Bootstrap raises ValueError because those handlers would share one unit of work.
- Keep the command and its
cqrs.DomainEventas the domain-event steps above. Severalcqrs.EventHandlerclasses may bind to one event.EventMap.bindappends. - Choose
cqrs.ScopeStrategy.HANDLERorcqrs.ScopeStrategy.NONE.HANDLERopens a new scope per event handler.NONEleaves the session to the handler. - Pass
concurrent_event_handle_enable=Trueandmax_concurrent_event_handlerstogether on the samecqrs.bootstrap.requests.bootstrapcall. The limit is how many handlers may run at once. Set it above 1 only when the handlers are independent. The same pair is valid oncqrs.bootstrap.requests.bootstrap_streamingwhen a stream emits domain events. - Leave the flag off when handlers must see the command's session or must run in a fixed order.
The default is
concurrent_event_handle_enable=False. Handlers then run one after another.
The command handler still runs alone. Parallelism starts after handle returns, when the mediator emits events. Handlers must not write one session. Under HANDLER each handler's scope is its own. Under NONE the handler opens and closes whatever it needs, and it must not borrow the command's session.
Pass the same scope_strategy the rest of this mediator already uses. Do not build a second mediator only to flip the flag. max_concurrent_event_handlers is a cap, not a promise that every handler starts at once.
Do not use parallel handlers as a saga. There is no compensation here. A flow that must undo a finished step is cqrs-saga. Do not use them to publish a notification reliably. That path is the outbox above. Do not depend on handler order.
Short shape: assets/parallel_handlers.py.
Full example: examples/streaming/streaming_handler_parallel_events.py.
How to test
Assert a domain event on handled. It is not on published. Assert a notification on published. It is not on handled. Parallel handlers are both on invocations. Do not assert their order. An outbox row is on outbox and stays off published until produce_available. After process_available, an inbox command is on requests and an inbox event is on invocations. A duplicate add returns [False]. Detail is cqrs-testing.
Do not
- Publish with
broker.sendnext tosession.commit(). A crash between those writes loses the message. Write the outbox row instead. - Call
mediator.sendin the route or subscriber that only accepts work. Store the inbox row, commit, then ack. - Use a domain event for email or HTTP to another service. The caller of
sendwaits for every domain handler. - Use the outbox to compensate a later step. That path is
cqrs-saga. - Call
EventProducerfrom the request handler. The handler only writes the row. - Share one outbox repository across concurrent requests. The repository holds the request session.
- Register the event type only in the publisher. The writer and the publisher resolve
event_namethrough the map they were given. - Ack before the inbox session commits. An exception before that commit must leave the message for another delivery.
- Set
concurrent_event_handle_enable=TruewithScopeStrategy.SEND.
Delivery notes: references/delivery.md.
Short shape: assets/order_created.py.
Full examples: examples/events/domain_event_handler.py, examples/outbox/fastapi_outbox.py.
- Downloads
- Security audit
- Pass
- Last updated
- 1w ago
- Current version
- v1.0.5
- License
- MIT-0
