python-cqrs 5.3.0__py3-none-any.whl → 5.4.0__py3-none-any.whl

cqrs/__init__.py

@@ -16,6 +16,11 @@ Startup is not on this package. Import the submodule:
 - ``cqrs.bootstrap.events.bootstrap`` builds ``EventMediator``.
 - ``cqrs.bootstrap.saga.bootstrap`` builds ``SagaMediator``.
 
+Tests import ``cqrs.testing``. ``from cqrs.testing import test_harness`` runs the
+mediators above and records what they did. ``test_harness`` is not in
+``__all__``: tests are not part of the runtime surface, the same way
+``cqrs.bootstrap`` is not.
+
 Requests and handlers on ``cqrs``: ``Request``, ``DCRequest``, ``Response``,
 ``RequestHandler``, ``StreamingRequestHandler``, ``RequestMediator``,
 ``StreamingRequestMediator``, ``RequestMap``, ``RequestHandlerFallback``.

cqrs/events/event_emitter.py

@@ -25,6 +25,21 @@ logger = logging.getLogger("cqrs")
 _H: typing.TypeAlias = event_handler.EventHandler
 
 
+class EventEmitterListener(typing.Protocol):
+    """Optional observer for domain-handler failures and events with no handlers."""
+
+    def on_domain_handler_error(
+        self,
+        event: IDomainEvent,
+        handler: type,
+        error: BaseException,
+    ) -> None:
+        """Called when a domain handler error is logged and swallowed."""
+
+    def on_unhandled(self, event: IDomainEvent) -> None:
+        """Called when a domain event has no registered handlers."""
+
+
 class EventEmitter:
     """
     Sends events to registered handlers or to a message broker.
@@ -50,6 +65,7 @@ class EventEmitter:
         scope_strategy: ScopeStrategy = ScopeStrategy.NONE,
         *,
         serializer: EventSerializer | None = None,
+        listener: EventEmitterListener | None = None,
     ) -> None:
         """
         Initialize the event emitter.
@@ -61,6 +77,7 @@ class EventEmitter:
                 when emitting :class:`~cqrs.events.event.INotificationEvent`.
             scope_strategy: DI scope boundary; HANDLER opens a scope per handler.
             serializer: Codec used to fill ``Message.payload_bytes``. Defaults to JSON.
+            listener: Optional observer. ``None`` leaves ``emit`` behavior unchanged.
 
         Example::
 
@@ -78,6 +95,7 @@ class EventEmitter:
         self._message_broker = message_broker
         self._scope_strategy = scope_strategy
         self._serializer = serializer or JsonEventSerializer()
+        self._listener = listener
 
     @functools.singledispatchmethod
     async def emit(self, event: IEvent) -> typing.Sequence[IEvent]:
@@ -222,6 +240,8 @@ class EventEmitter:
                 "Handlers for domain event %s not found",
                 type(event).__name__,
             )
+            if self._listener is not None:
+                self._listener.on_unhandled(event)
             return ()
 
         results = await self._run_handlers(event, handlers_types)
@@ -241,6 +261,11 @@ class EventEmitter:
                     res,
                     exc_info=res,
                 )
+                if self._listener is not None:
+                    handler_type = (
+                        handler_item.primary if isinstance(handler_item, EventHandlerFallback) else handler_item
+                    )
+                    self._listener.on_domain_handler_error(event, handler_type, res)
             elif isinstance(res, BaseException):
                 raise res
             else:

cqrs/outbox/memory.py

@@ -0,0 +1,96 @@
+"""In-memory outbox repository.
+
+[AI Instruction]
+Import ``MemoryOutboxRepository`` from this module. It is not an attribute of
+``cqrs``. Each instance has its own id counter. ``PRODUCED`` updates the row
+status and keeps the row. ``cqrs.outbox.mock.MockOutboxedEventRepository`` is
+a different class and is unchanged.
+"""
+
+import dataclasses
+import typing
+
+from cqrs.mapping import outbox as map
+from cqrs.models.event import INotificationEvent
+from cqrs.outbox import repository
+from cqrs.serializers.json import JsonEventSerializer
+from cqrs.serializers.protocol import EventCodec
+
+
+class MemoryOutboxRepository(repository.OutboxedEventRepository):
+    """
+    Process-local outbox.
+
+    The id counter and the rows belong to the instance. A row marked
+    ``PRODUCED`` stays in the repository with that status. ``get_many``
+    returns ``NEW`` and ``NOT_PRODUCED`` rows only. ``rollback`` drops rows
+    added since the last ``commit``.
+    """
+
+    def __init__(
+        self,
+        *,
+        serializer: EventCodec | None = None,
+        event_map: map.OutboxedEventMap | None = None,
+    ) -> None:
+        self._counter = 0
+        self._rows: dict[int, repository.OutboxedEvent] = {}
+        self._staged: list[int] = []
+        self._serializer = serializer or JsonEventSerializer()
+        self._event_map = event_map
+
+    def _resolve_codec(self, event_name: str) -> EventCodec:
+        if self._event_map is not None:
+            registered = self._event_map.get_serializer(event_name)
+            if registered is not None:
+                return registered
+        return self._serializer
+
+    def add(self, event: INotificationEvent) -> None:
+        self._counter += 1
+        row_id = self._counter
+        codec = self._resolve_codec(event.event_name)
+        self._rows[row_id] = repository.OutboxedEvent(
+            id=row_id,
+            event=event,
+            topic=event.topic,
+            status=repository.EventStatus.NEW,
+            payload_bytes=codec.serialize(event),
+            content_type=codec.content_type_for(event),
+        )
+        self._staged.append(row_id)
+
+    async def get_many(
+        self,
+        batch_size: int = 100,
+        topic: typing.Text | None = None,
+    ) -> typing.List[repository.OutboxedEvent]:
+        selectable = [
+            row
+            for row in self._rows.values()
+            if row.status in (repository.EventStatus.NEW, repository.EventStatus.NOT_PRODUCED)
+            and (topic is None or row.topic == topic)
+        ]
+        selectable.sort(key=lambda row: row.id)
+        return selectable[:batch_size]
+
+    async def update_status(
+        self,
+        outboxed_event_id: int,
+        new_status: repository.EventStatus,
+    ) -> None:
+        current = self._rows.get(outboxed_event_id)
+        if current is None:
+            return
+        self._rows[outboxed_event_id] = dataclasses.replace(current, status=new_status)
+
+    async def commit(self) -> None:
+        self._staged.clear()
+
+    async def rollback(self) -> None:
+        for row_id in self._staged:
+            self._rows.pop(row_id, None)
+        self._staged.clear()
+
+
+__all__ = ("MemoryOutboxRepository",)

cqrs/outbox/repository.py

@@ -110,6 +110,11 @@ class OutboxedEventRepository(abc.ABC):
         """
         Get many events from the repository.
 
+        SQLAlchemy and SQLModel take rows with ``FOR UPDATE SKIP LOCKED`` on
+        PostgreSQL, MySQL 8.0 or later, and MariaDB 10.6 or later, until the
+        caller commits or rolls back. Older MySQL and MariaDB, SQLite, and
+        other dialects do not.
+
         [AI Instruction]
         Read a batch of unpublished outbox rows. ``EventProducer`` calls this.
         A command handler does not.

cqrs/outbox/sqlalchemy.py

@@ -47,6 +47,23 @@ DEFAULT_OUTBOX_TABLE_NAME = "outbox"
 
 MAX_FLUSH_COUNTER_VALUE = 5
 
+# SKIP LOCKED arrived in MySQL 8.0 and MariaDB 10.6. PostgreSQL has it
+# without a version gate. Older servers and every other dialect stay unlocked.
+_MYSQL_SKIP_LOCKED_SINCE = (8, 0)
+_MARIADB_SKIP_LOCKED_SINCE = (10, 6)
+
+
+def _dialect_is_mariadb(dialect: typing.Any) -> bool:
+    """MariaDB via ``mariadb://`` or the MySQL dialect's ``is_mariadb`` flag.
+
+    A MariaDB reached through the MySQL dialect keeps ``dialect.name == "mysql"``
+    and a version such as ``(10, 5)``, which would pass a MySQL 8.0 check.
+    """
+
+    if getattr(dialect, "name", None) == "mariadb":
+        return True
+    return bool(getattr(dialect, "is_mariadb", False))
+
 
 # Deprecated name of cqrs.sqlalchemy_types.UUIDBinary — kept importable for
 # backward compatibility (e.g. already generated Alembic migrations).
@@ -125,8 +142,10 @@ class OutboxModel(Base):
         cls,
         size: int,
         topic: typing.Text | None = None,
+        *,
+        lock: bool = False,
     ) -> sqlalchemy.Select:
-        return (
+        query = (
             sqlalchemy.select(cls)
             .select_from(cls)
             .where(
@@ -145,6 +164,9 @@ class OutboxModel(Base):
             .order_by(cls.id.asc())
             .limit(size)
         )
+        if lock:
+            query = query.with_for_update(skip_locked=True)
+        return query
 
     @classmethod
     def update_status_query(
@@ -277,13 +299,44 @@ class SqlAlchemyOutboxedEventRepository(repository.OutboxedEventRepository):
             content_type=codec.content_type_for(event),
         )
 
+    async def _skip_locked(self) -> bool:
+        dialect = self.session.get_bind().dialect
+        name = dialect.name
+        if name == "postgresql":
+            return True
+        if name != "mysql" and name != "mariadb":
+            return False
+
+        # The dialect leaves server_version_info unset until the first
+        # connection runs initialize(). Reading it earlier looks like an old
+        # server and drops SKIP LOCKED on MySQL 8 and MariaDB 10.6.
+        version = getattr(dialect, "server_version_info", None)
+        if version is None:
+            await self.session.connection()
+            version = getattr(dialect, "server_version_info", None)
+        if version is None:
+            return False
+
+        minimum = _MARIADB_SKIP_LOCKED_SINCE if _dialect_is_mariadb(dialect) else _MYSQL_SKIP_LOCKED_SINCE
+        return tuple(version) >= minimum
+
     async def get_many(
         self,
         batch_size: int = 100,
         topic: typing.Text | None = None,
     ) -> typing.List[repository.OutboxedEvent]:
         events: typing.Sequence[typing.Any] = (
-            (await self.session.execute(self._model.get_batch_query(batch_size, topic))).scalars().all()
+            (
+                await self.session.execute(
+                    self._model.get_batch_query(
+                        batch_size,
+                        topic,
+                        lock=await self._skip_locked(),
+                    ),
+                )
+            )
+            .scalars()
+            .all()
         )
 
         result = []

cqrs/outbox/sqlmodel.py

@@ -140,9 +140,11 @@ class OutboxModel(Base, table=True):
         cls,
         size: int,
         topic: typing.Text | None = None,
+        *,
+        lock: bool = False,
     ) -> sqlalchemy.Select:
         query = SqlAlchemyOutboxModel.get_batch_query
-        return query.__func__(cls, size, topic)  # type: ignore[attr-defined]
+        return query.__func__(cls, size, topic, lock=lock)  # type: ignore[attr-defined]
 
     @classmethod
     def update_status_query(

cqrs/testing/__init__.py

@@ -0,0 +1,23 @@
+"""Test harness for python-cqrs.
+
+[AI Instruction]
+Import ``test_harness`` from this package::
+
+    from cqrs.testing import test_harness
+
+``cqrs.test_harness`` does not exist, and the name is not in ``cqrs.__all__``.
+The harness runs the real mediators and records invocations, handled domain
+events, broker messages, outbox rows, requests, stream yields, middleware,
+handler errors, unhandled events, sagas, and inbox rows.
+"""
+
+from cqrs.testing.broker import CapturingMessageBroker
+from cqrs.testing.container import TestContainer
+from cqrs.testing.harness import TestHarness, test_harness
+
+__all__ = (
+    "CapturingMessageBroker",
+    "TestContainer",
+    "TestHarness",
+    "test_harness",
+)

cqrs/testing/broker.py

@@ -0,0 +1,44 @@
+"""In-memory broker that records messages sent by the mediators.
+
+[AI Instruction]
+Import ``CapturingMessageBroker`` from ``cqrs.testing``. Pass it to
+``bootstrap`` as ``message_broker``, or let ``test_harness`` create one.
+``fail_next`` raises on the following ``send_message`` and does not record
+that message.
+"""
+
+from cqrs.message_brokers.protocol import Message, MessageBroker
+
+
+class CapturingMessageBroker(MessageBroker):
+    """
+    Drop-in broker that keeps every delivered message.
+
+    ``fail_next`` schedules an exception for the next ``send_message``.
+    The failed send is not appended. An optional ``inner`` broker is called
+    after the message is accepted, so a real adapter can sit behind the capture.
+    """
+
+    def __init__(self, inner: MessageBroker | None = None) -> None:
+        self._inner = inner
+        self._messages: list[Message] = []
+        self._failures: list[BaseException] = []
+
+    @property
+    def messages(self) -> list[Message]:
+        return self._messages
+
+    def fail_next(self, error: BaseException) -> None:
+        """Raise ``error`` from the next ``send_message``."""
+
+        self._failures.append(error)
+
+    async def send_message(self, message: Message) -> None:
+        if self._failures:
+            raise self._failures.pop(0)
+        if self._inner is not None:
+            await self._inner.send_message(message)
+        self._messages.append(message)
+
+
+__all__ = ("CapturingMessageBroker",)

cqrs/testing/container.py

@@ -0,0 +1,200 @@
+"""Container for harness tests and the resolve wrapper that records handler entry.
+
+[AI Instruction]
+``TestContainer.register`` stores one instance. ``resolve`` returns it, or
+constructs the type with no arguments. ``ScopeStrategy.SEND`` needs a
+``di.Container``, not ``TestContainer``. The resolve wrapper is what
+``test_harness`` installs on the mediators' containers.
+"""
+
+import inspect
+import typing
+from contextvars import ContextVar
+
+from cqrs.testing.recording import InvocationJournal
+
+_RECORDING = "_cqrs_testing_recording"
+_ACTIVE_JOURNAL: ContextVar[InvocationJournal | None] = ContextVar(
+    "cqrs_testing_active_invocation_journal",
+    default=None,
+)
+_T = typing.TypeVar("_T")
+
+
+class TestContainer:
+    """
+    Small container for harness tests.
+
+    ``register(type, instance)`` pins that instance. ``resolve`` returns the
+    registration or calls ``type_()``.
+    """
+
+    __test__ = False
+
+    def __init__(self) -> None:
+        self._registry: dict[type, typing.Any] = {}
+
+    def register(self, type_: type, instance: typing.Any) -> None:
+        self._registry[type_] = instance
+
+    @property
+    def external_container(self) -> "TestContainer":
+        return self
+
+    def attach_external_container(self, container: typing.Any) -> None:
+        return None
+
+    async def resolve(self, type_: typing.Type[_T]) -> _T:
+        if type_ in self._registry:
+            return typing.cast(_T, self._registry[type_])
+        return type_()
+
+
+def _first_argument(args: tuple[typing.Any, ...], kwargs: dict[str, typing.Any]) -> typing.Any:
+    if args:
+        return args[0]
+    for name in ("request", "event", "context"):
+        if name in kwargs:
+            return kwargs[name]
+    if kwargs:
+        return next(iter(kwargs.values()))
+    return None
+
+
+def _record_entry(
+    handler_type: type,
+    method_name: str,
+    args: tuple[typing.Any, ...],
+    kwargs: dict[str, typing.Any],
+    instance: typing.Any,
+) -> None:
+    journal = _ACTIVE_JOURNAL.get()
+    if journal is None:
+        return
+    journal.record(
+        handler_type,
+        method_name,
+        _first_argument(args, kwargs),
+        instance,
+    )
+
+
+def _wrap_coroutine(
+    original: typing.Callable[..., typing.Awaitable[typing.Any]],
+    handler_type: type,
+    method_name: str,
+    instance: typing.Any,
+) -> typing.Callable[..., typing.Awaitable[typing.Any]]:
+    async def wrapped(*args: typing.Any, **kwargs: typing.Any) -> typing.Any:
+        _record_entry(handler_type, method_name, args, kwargs, instance)
+        return await original(*args, **kwargs)
+
+    setattr(wrapped, _RECORDING, True)
+    return wrapped
+
+
+def _wrap_async_gen(
+    original: typing.Callable[..., typing.AsyncIterator[typing.Any]],
+    handler_type: type,
+    method_name: str,
+    instance: typing.Any,
+) -> typing.Callable[..., typing.AsyncIterator[typing.Any]]:
+    async def wrapped(*args: typing.Any, **kwargs: typing.Any) -> typing.AsyncIterator[typing.Any]:
+        _record_entry(handler_type, method_name, args, kwargs, instance)
+        async for item in original(*args, **kwargs):
+            yield item
+
+    setattr(wrapped, _RECORDING, True)
+    return wrapped
+
+
+def _restore_method(
+    instance: typing.Any,
+    method_name: str,
+    previous: typing.Any,
+    had_attr: bool,
+) -> None:
+    if had_attr:
+        setattr(instance, method_name, previous)
+        return
+    try:
+        delattr(instance, method_name)
+    except AttributeError:
+        return
+
+
+def instrument_instance(
+    instance: typing.Any,
+    handler_type: type,
+    undo: list[typing.Callable[[], None]],
+) -> None:
+    """Record entry into ``handle``, ``act``, and ``compensate`` on ``instance``."""
+
+    for method_name in ("handle", "act", "compensate"):
+        current = getattr(instance, method_name, None)
+        if current is None or not callable(current):
+            continue
+        if getattr(current, _RECORDING, False):
+            continue
+        if inspect.isasyncgenfunction(current):
+            replacement = _wrap_async_gen(current, handler_type, method_name, instance)
+        elif inspect.iscoroutinefunction(current):
+            replacement = _wrap_coroutine(current, handler_type, method_name, instance)
+        else:
+            continue
+        instance_dict = getattr(instance, "__dict__", None)
+        had_attr = isinstance(instance_dict, dict) and method_name in instance_dict
+        setattr(instance, method_name, replacement)
+        undo.append(
+            lambda inst=instance, name=method_name, previous=current, owned=had_attr: _restore_method(
+                inst,
+                name,
+                previous,
+                owned,
+            ),
+        )
+
+
+def wrap_resolve(container: typing.Any, journal: InvocationJournal) -> typing.Callable[[], None]:
+    """
+    Wrap ``container.resolve`` so each handler records entry.
+
+    Recording follows the active harness journal. ``restore`` drops instance
+    patches this wrap installed and puts the previous ``resolve`` back.
+    A nested wrap on an already wrapped container only switches that journal.
+    """
+
+    token = _ACTIVE_JOURNAL.set(journal)
+    original = container.resolve
+    if getattr(original, _RECORDING, False):
+
+        def restore_journal() -> None:
+            _ACTIVE_JOURNAL.reset(token)
+
+        return restore_journal
+
+    undo: list[typing.Callable[[], None]] = []
+
+    async def resolve(type_: typing.Type[_T]) -> _T:
+        instance = await original(type_)
+        instrument_instance(instance, type_, undo)
+        return instance
+
+    setattr(resolve, _RECORDING, True)
+    container.resolve = resolve
+
+    def restore() -> None:
+        for undo_patch in reversed(undo):
+            undo_patch()
+        undo.clear()
+        container.resolve = original
+        _ACTIVE_JOURNAL.reset(token)
+
+    return restore
+
+
+__all__ = (
+    "TestContainer",
+    "instrument_instance",
+    "wrap_resolve",
+)