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

cqrs/__init__.py

@@ -46,6 +46,14 @@ Outbox on ``cqrs``: ``OutboxedEventRepository``, ``OutboxedEventMap``,
 the ``sqlmodel`` extra. Codecs on ``cqrs``: ``JsonEventSerializer``,
 ``ProtobufEventSerializer`` (extra ``protobuf``).
 
+Inbox on ``cqrs``: ``InboxRepository``, ``InboxMessage``, ``InboxStatus``,
+``InboxMessageMap``, ``InboxProcessor``. ``SqlAlchemyInboxRepository`` and
+``rebind_inbox_model`` are lazy and need the ``sqlalchemy`` extra.
+``SqlModelInboxRepository`` is lazy and needs the ``sqlmodel`` extra.
+Presentation calls ``add`` with a batch. ``InboxProcessor`` reads rows and
+calls the mediator that is already registered. FastAPI and FastStream are
+not imported here.
+
 Brokers are not on ``cqrs``. Kafka is
 ``cqrs.adapters.kafka.kafka_producer_factory`` plus
 ``cqrs.message_brokers.kafka.KafkaMessageBroker`` (extra ``kafka``). AMQP is
@@ -79,6 +87,11 @@ if typing.TYPE_CHECKING:
     )
     from cqrs.models.pydantic import PydanticRequest
     from cqrs.models.pydantic import PydanticResponse
+    from cqrs.inbox.sqlalchemy import (
+        SqlAlchemyInboxRepository,
+        rebind_inbox_model,
+    )
+    from cqrs.inbox.sqlmodel import SqlModelInboxRepository
     from cqrs.outbox.sqlalchemy import (
         SqlAlchemyOutboxedEventRepository,
         rebind_outbox_model,
@@ -126,6 +139,9 @@ from cqrs.mediators import (
     SagaMediator,
     StreamingRequestMediator,
 )
+from cqrs.inbox.map import InboxMessageMap
+from cqrs.inbox.processor import InboxProcessor
+from cqrs.inbox.repository import InboxMessage, InboxRepository, InboxStatus
 from cqrs.mapping.outbox import OutboxedEventMap
 from cqrs.outbox.repository import (
     EventStatus,
@@ -202,6 +218,13 @@ __all__ = (
     "OutboxedEventRepository",
     "SqlAlchemyOutboxedEventRepository",
     "SqlModelOutboxedEventRepository",
+    "InboxRepository",
+    "InboxMessage",
+    "InboxStatus",
+    "InboxMessageMap",
+    "InboxProcessor",
+    "SqlAlchemyInboxRepository",
+    "SqlModelInboxRepository",
     "EventProducer",
     "EventSerializer",
     "EventCodec",
@@ -220,6 +243,7 @@ __all__ = (
     "Compressor",
     "ZlibCompressor",
     "rebind_outbox_model",
+    "rebind_inbox_model",
     "Saga",
     "SagaStepHandler",
     "SagaStepResult",
@@ -252,6 +276,11 @@ _LAZY_SQLALCHEMY = {
         "SqlAlchemyOutboxedEventRepository",
     ),
     "rebind_outbox_model": ("cqrs.outbox.sqlalchemy", "rebind_outbox_model"),
+    "SqlAlchemyInboxRepository": (
+        "cqrs.inbox.sqlalchemy",
+        "SqlAlchemyInboxRepository",
+    ),
+    "rebind_inbox_model": ("cqrs.inbox.sqlalchemy", "rebind_inbox_model"),
     "DialectAwareType": ("cqrs.sqlalchemy_types", "DialectAwareType"),
     "DialectTypeHandler": ("cqrs.sqlalchemy_types", "DialectTypeHandler"),
     "UUIDBinary": ("cqrs.sqlalchemy_types", "UUIDBinary"),
@@ -265,6 +294,10 @@ _LAZY_SQLMODEL = {
         "cqrs.outbox.sqlmodel",
         "SqlModelOutboxedEventRepository",
     ),
+    "SqlModelInboxRepository": (
+        "cqrs.inbox.sqlmodel",
+        "SqlModelInboxRepository",
+    ),
 }
 
 

cqrs/inbox/__init__.py

@@ -0,0 +1,21 @@
+"""
+Transactional inbox.
+
+[AI Instruction]
+Import ``InboxRepository``, ``InboxMessage``, ``InboxStatus``,
+``InboxMessageMap``, and ``InboxProcessor`` from ``cqrs``. SQLAlchemy and
+SQLModel repositories are lazy. Presentation calls ``add``. A worker calls
+``InboxProcessor``.
+"""
+
+from cqrs.inbox.map import InboxMessageMap
+from cqrs.inbox.processor import InboxProcessor
+from cqrs.inbox.repository import InboxMessage, InboxRepository, InboxStatus
+
+__all__ = (
+    "InboxMessage",
+    "InboxMessageMap",
+    "InboxProcessor",
+    "InboxRepository",
+    "InboxStatus",
+)

cqrs/inbox/map.py

@@ -0,0 +1,201 @@
+"""
+Name registry for inbox messages.
+
+[AI Instruction]
+Register each request or event name before ``InboxRepository.add``. JSON is
+the default codec. A second ``register`` of the same name raises ``KeyError``.
+Prefer an instance when tests must not share the process-global map.
+"""
+
+import functools
+import typing
+
+import orjson
+
+from cqrs.inbox.repository import InboxEntry
+from cqrs.models.event import IEvent
+from cqrs.models.request import IRequest
+
+_KT = typing.TypeVar("_KT")
+
+
+class _JsonMessageSerializer:
+    """JSON codec. Wire format is ``orjson.dumps(message.to_dict())``."""
+
+    def serialize(self, message: InboxEntry) -> bytes:
+        return orjson.dumps(message.to_dict())
+
+    def deserialize(self, payload: bytes, message_type: typing.Type[_KT]) -> _KT:
+        data = orjson.loads(payload)
+        if not isinstance(data, dict):
+            raise TypeError("inbox payload must be a JSON object")
+        return message_type.from_dict(**data)  # type: ignore[attr-defined]
+
+
+class MessageCodec(typing.Protocol):
+    """Serialize and deserialize one inbox message type."""
+
+    def serialize(self, message: InboxEntry) -> bytes: ...
+
+    def deserialize(self, payload: bytes, message_type: typing.Type[typing.Any]) -> typing.Any: ...
+
+
+class _bind_self_or_singleton:
+    """Class access binds the process singleton; instance access binds that map."""
+
+    def __init__(self, func: typing.Callable) -> None:
+        self.func = func
+
+    def __get__(
+        self,
+        obj: typing.Any,
+        objtype: type | None = None,
+    ) -> typing.Callable:
+        target = obj if obj is not None else objtype._singleton()  # type: ignore[union-attr]
+        return functools.partial(self.func, target)
+
+
+def message_name(message: InboxEntry) -> str:
+    """
+    Name stored with the row.
+
+    Notification events use ``event_name``, the same string the outbox stores.
+    Requests and domain events use the class name.
+    """
+
+    event_name = getattr(message, "event_name", None)
+    if isinstance(event_name, str) and event_name:
+        return event_name
+    return type(message).__name__
+
+
+def _type_matches(message_type: type, registered: typing.Any) -> bool:
+    registered_origin = typing.get_origin(registered) or registered
+    if message_type is registered:
+        return True
+    if typing.get_origin(registered) is not None and message_type is registered_origin:
+        return True
+    if isinstance(registered, type) and issubclass(message_type, registered):
+        return True
+    return False
+
+
+class InboxMessageMap:
+    """
+    Registry of inbox message names to request or event types.
+
+    Class-level ``register`` / ``get`` use a process-global singleton.
+    ``InboxMessageMap()`` creates an isolated registry.
+
+    [AI Instruction]
+    Tell the inbox which Python type belongs to a message name. Register
+    before the repository reads or writes that message. JSON is the default.
+    A second registration of the same name raises ``KeyError``. Requests and
+    domain events are registered under the class name. Notification events
+    are registered under ``event_name``.
+    """
+
+    _instance: typing.ClassVar["InboxMessageMap | None"] = None
+
+    def __init__(self) -> None:
+        self._entries: typing.Dict[str, typing.Tuple[typing.Any, MessageCodec | None]] = {}
+
+    @classmethod
+    def _singleton(cls) -> "InboxMessageMap":
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @_bind_self_or_singleton
+    def register(
+        self,
+        message_name_: str,
+        message_type: typing.Type[InboxEntry],
+        serializer: MessageCodec | None = None,
+    ) -> None:
+        """
+        Bind ``message_name_`` to a request or event class.
+
+        [AI Instruction]
+        Call once at startup. A second registration of the same name raises
+        ``KeyError``. Omit ``serializer`` for JSON.
+        """
+
+        if message_name_ in self._entries:
+            raise KeyError(f"Message {message_name_} already registered")
+        self._entries[message_name_] = (message_type, serializer)
+
+    @_bind_self_or_singleton
+    def get(self, message_name_: str) -> typing.Any | None:
+        """Return the registered type, or ``None`` when the name is unknown."""
+
+        entry = self._entries.get(message_name_)
+        if entry is None:
+            return None
+        return entry[0]
+
+    @_bind_self_or_singleton
+    def get_serializer(self, message_name_: str) -> MessageCodec | None:
+        """Return the codec registered for this name, or ``None`` for JSON."""
+
+        entry = self._entries.get(message_name_)
+        if entry is None:
+            return None
+        return entry[1]
+
+    @_bind_self_or_singleton
+    def deserialize(self, message_name_: str, payload: bytes) -> InboxEntry:
+        """
+        Rebuild a request or event from stored bytes.
+
+        [AI Instruction]
+        ``InboxProcessor`` calls this. An unknown name raises ``KeyError``
+        and does not return a message.
+        """
+
+        entry = self._entries.get(message_name_)
+        if entry is None:
+            raise KeyError(f"Unknown message name {message_name_}")
+        message_type, serializer = entry
+        codec = serializer or _JsonMessageSerializer()
+        return codec.deserialize(payload, message_type)
+
+    @_bind_self_or_singleton
+    def payload_for(self, message: InboxEntry) -> typing.Tuple[str, bytes]:
+        """
+        Return ``(message_name, payload)`` for a registered message.
+
+        Raises ``TypeError`` when the name is missing or the instance type
+        does not match the registration.
+        """
+
+        if not isinstance(message, (IRequest, IEvent)):
+            raise TypeError(f"Unsupported inbox message type {type(message)}")
+        name = message_name(message)
+        registered = self.get(name)
+        if registered is None:
+            raise TypeError(f"Unknown message name for {name}")
+        if not _type_matches(type(message), registered):
+            raise TypeError(
+                f"Message type {type(message)} does not match registered type {registered}",
+            )
+        codec = self.get_serializer(name) or _JsonMessageSerializer()
+        return name, codec.serialize(message)
+
+
+def resolve_message_map(
+    message_map: "InboxMessageMap | None",
+) -> InboxMessageMap:
+    """Use the given instance, or the process singleton when ``message_map`` is omitted."""
+
+    if message_map is None or message_map is InboxMessageMap:
+        return InboxMessageMap._singleton()
+    return message_map
+
+
+__all__ = (
+    "InboxMessageMap",
+    "MessageCodec",
+    "message_name",
+    "resolve_message_map",
+)

cqrs/inbox/memory.py

@@ -0,0 +1,110 @@
+"""In-memory inbox repository for unit tests."""
+
+import contextlib
+import dataclasses
+import datetime
+import typing
+
+from cqrs.inbox.map import InboxMessageMap, resolve_message_map
+from cqrs.inbox.repository import (
+    MAX_FLUSH_COUNTER_VALUE,
+    InboxEntry,
+    InboxMessage,
+    InboxRepository,
+    InboxStatus,
+)
+
+
+class MemoryInboxRepository(InboxRepository):
+    """
+    Process-local inbox.
+
+    ``add`` is visible to ``get_many`` on this instance before ``commit``,
+    matching a session that has flushed and not committed. ``rollback``
+    restores the last ``commit``. ``nested`` snapshots the rows and restores
+    them when the block raises.
+    """
+
+    def __init__(self, message_map: InboxMessageMap | None = None) -> None:
+        self._message_map = resolve_message_map(message_map)
+        self._rows: typing.List[InboxMessage] = []
+        self._checkpoint: typing.List[InboxMessage] = []
+        self._next_id = 1
+
+    async def add(
+        self,
+        messages: typing.Sequence[typing.Tuple[str, InboxEntry]],
+    ) -> typing.List[bool]:
+        if not messages:
+            return []
+        stored = {(row.message_id, row.message_name) for row in self._rows}
+        results: typing.List[bool] = []
+        for message_id, message in messages:
+            name, payload = self._message_map.payload_for(message)
+            key = (message_id, name)
+            if key in stored:
+                results.append(False)
+                continue
+            self._rows.append(
+                InboxMessage(
+                    id=self._next_id,
+                    message_id=message_id,
+                    message_name=name,
+                    status=InboxStatus.NEW,
+                    flush_counter=0,
+                    created_at=datetime.datetime.now(),
+                    payload=payload,
+                ),
+            )
+            self._next_id += 1
+            stored.add(key)
+            results.append(True)
+        return results
+
+    async def get_many(self, batch_size: int = 100) -> typing.List[InboxMessage]:
+        selectable = [
+            row
+            for row in self._rows
+            if row.status in (InboxStatus.NEW, InboxStatus.NOT_PROCESSED)
+            and row.flush_counter < MAX_FLUSH_COUNTER_VALUE
+        ]
+        selectable.sort(key=lambda row: row.id)
+        return selectable[:batch_size]
+
+    async def update_status(self, row_id: int, new_status: InboxStatus) -> None:
+        for index, row in enumerate(self._rows):
+            if row.id != row_id:
+                continue
+            flush_counter = row.flush_counter
+            if new_status is InboxStatus.NOT_PROCESSED:
+                flush_counter += 1
+            self._rows[index] = dataclasses.replace(
+                row,
+                status=new_status,
+                flush_counter=flush_counter,
+            )
+            return
+
+    def nested(self) -> contextlib.AbstractAsyncContextManager[None]:
+        return self._nested()
+
+    @contextlib.asynccontextmanager
+    async def _nested(self) -> typing.AsyncIterator[None]:
+        snapshot = [dataclasses.replace(row) for row in self._rows]
+        next_id = self._next_id
+        try:
+            yield
+        except BaseException:
+            self._rows = snapshot
+            self._next_id = next_id
+            raise
+
+    async def commit(self) -> None:
+        self._checkpoint = [dataclasses.replace(row) for row in self._rows]
+
+    async def rollback(self) -> None:
+        self._rows = [dataclasses.replace(row) for row in self._checkpoint]
+        self._next_id = max((row.id for row in self._rows), default=0) + 1
+
+
+__all__ = ("MemoryInboxRepository",)

cqrs/inbox/processor.py

@@ -0,0 +1,116 @@
+"""
+Read inbox rows and hand them to the mediator that is already registered.
+
+[AI Instruction]
+Run ``InboxProcessor`` in a worker process. It does not replace
+``repository.add`` in a route or a subscriber. ``process`` does not commit.
+The worker commits the business rows and the status together.
+"""
+
+import functools
+import logging
+import typing
+
+from cqrs.inbox.map import InboxMessageMap
+from cqrs.inbox.repository import InboxMessage, InboxRepository, InboxStatus
+from cqrs.models.event import IEvent
+from cqrs.models.request import IRequest
+
+logger = logging.getLogger("cqrs")
+
+
+class InboxProcessor:
+    """
+    Deserialize one inbox row and send it through an existing mediator.
+
+    A ``Request`` goes to ``RequestMediator.send``. An event goes to
+    ``EventMediator.send``. Each row has its own savepoint: success stores
+    ``processed`` inside that savepoint, and a failure stores ``not_processed``
+    on the outer transaction after the savepoint rolls back.
+
+    [AI Instruction]
+    Construct it with the repository for this batch's session, the same
+    ``InboxMessageMap`` that repository uses, and the mediators bootstrap
+    already built. The caller owns the session and the commit. Do not add a
+    handler whose only job is to write the inbox row. The handler that
+    ``send`` runs must not call ``session.commit``.
+    """
+
+    def __init__(
+        self,
+        repository: InboxRepository,
+        message_map: InboxMessageMap,
+        request_mediator: typing.Any | None = None,
+        event_mediator: typing.Any | None = None,
+    ) -> None:
+        self.repository = repository
+        self._map = message_map
+        self._request_mediator = request_mediator
+        self._event_mediator = event_mediator
+
+    async def batch_generator(
+        self,
+        batch_size: int = 100,
+    ) -> typing.AsyncIterator[typing.List[InboxMessage]]:
+        """
+        Yield batches until the caller stops the loop.
+
+        [AI Instruction]
+        Poll forever. Each yield is one ``get_many`` result from the
+        repository passed to ``__init__``. Process every row, then let the
+        caller commit. This generator does not commit and does not end on
+        an empty batch.
+        """
+
+        while True:
+            yield await self.repository.get_many(batch_size=batch_size)
+
+    async def process(self, row: InboxMessage) -> None:
+        """
+        Run one row.
+
+        [AI Instruction]
+        Call this for each row from ``get_many``. The repository is the one
+        passed to ``__init__``. A handler exception rolls back that row's
+        business writes and leaves neighbors in the batch untouched.
+        ``not_processed`` increments ``flush_counter``. The row stays
+        selectable until the counter reaches five.
+        """
+
+        try:
+            message = self._map.deserialize(row.message_name, row.payload)
+            async with self.repository.nested():
+                await self._dispatch(message)
+                await self.repository.update_status(row.id, InboxStatus.PROCESSED)
+        except Exception:
+            logger.exception(
+                "inbox row %s (%s) failed",
+                row.id,
+                row.message_name,
+            )
+            await self.repository.update_status(row.id, InboxStatus.NOT_PROCESSED)
+
+    @typing.overload
+    async def _dispatch(self, message: IRequest) -> None: ...
+
+    @typing.overload
+    async def _dispatch(self, message: IEvent) -> None: ...
+
+    @functools.singledispatchmethod
+    async def _dispatch(self, message: typing.Any) -> None:
+        raise TypeError(f"Unsupported inbox message type {type(message)}")
+
+    @_dispatch.register(IRequest)  # pyright: ignore[reportFunctionMemberAccess]
+    async def _dispatch_request(self, message: IRequest) -> None:
+        if self._request_mediator is None:
+            raise RuntimeError("RequestMediator is not configured")
+        await self._request_mediator.send(message)
+
+    @_dispatch.register(IEvent)  # pyright: ignore[reportFunctionMemberAccess]
+    async def _dispatch_event(self, message: IEvent) -> None:
+        if self._event_mediator is None:
+            raise RuntimeError("EventMediator is not configured")
+        await self._event_mediator.send(message)
+
+
+__all__ = ("InboxProcessor",)

cqrs/inbox/repository.py

@@ -0,0 +1,149 @@
+"""
+Transactional inbox repository protocol.
+
+[AI Instruction]
+Presentation calls ``add`` with a batch of ``(message_id, message)`` and
+does not commit inside ``add``. A separate process uses ``get_many`` and
+``InboxProcessor``. There is no handler and no middleware whose only job
+is to insert the inbox row.
+"""
+
+import abc
+import contextlib
+import dataclasses
+import datetime
+import enum
+import sys
+import typing
+
+from cqrs.models.event import IEvent
+from cqrs.models.request import IRequest
+
+if sys.version_info >= (3, 11):
+    StrEnum = enum.StrEnum  # novm
+else:
+
+    class StrEnum(str, enum.Enum):  # type: ignore[misc]
+        """Compatible StrEnum for Python 3.10."""
+
+        def __str__(self) -> str:
+            return self.value
+
+
+class InboxStatus(StrEnum):
+    """
+    Lifecycle of one inbox row.
+
+    Presentation inserts ``NEW``. ``InboxProcessor`` moves a row to
+    ``PROCESSED`` when the mediator finishes and to ``NOT_PROCESSED`` when
+    that attempt raises. ``NOT_PROCESSED`` increments ``flush_counter``.
+    After five failures the row leaves ``get_many``.
+    """
+
+    NEW = "new"
+    PROCESSED = "processed"
+    NOT_PROCESSED = "not_processed"
+
+
+MAX_FLUSH_COUNTER_VALUE = 5
+
+InboxEntry = typing.Union[IRequest, IEvent]
+
+
+@dataclasses.dataclass(frozen=True)
+class InboxMessage:
+    """
+    One stored inbox row, returned by ``get_many``.
+
+    Application code does not construct it. ``payload`` is the bytes written
+    by ``add``. ``InboxProcessor`` deserializes them through ``InboxMessageMap``.
+    """
+
+    id: int
+    message_id: str
+    message_name: str
+    status: InboxStatus
+    flush_counter: int
+    created_at: datetime.datetime
+    payload: bytes
+
+
+class InboxRepository(abc.ABC):
+    """
+    [AI Instruction]
+    Store a command or an event before a worker runs it. ``add`` always takes
+    a batch and returns ``list[bool]`` of the same length. ``True`` means the
+    row was inserted. ``False`` means ``(message_id, message_name)`` is already
+    stored, including earlier in this batch. An empty batch returns ``[]``.
+    ``add`` does not commit. The caller commits that session. ``get_many`` and
+    ``InboxProcessor.process`` run later, on their own session.
+    """
+
+    @abc.abstractmethod
+    async def add(
+        self,
+        messages: typing.Sequence[typing.Tuple[str, InboxEntry]],
+    ) -> typing.List[bool]:
+        """
+        Insert a batch. One message is a batch of one element.
+
+        [AI Instruction]
+        Pass ``[(message_id, request_or_event)]``. Register every message name
+        on the ``InboxMessageMap`` this repository uses before ``add``. A
+        duplicate key returns ``False`` and does not abort the outer
+        transaction. Do not commit here.
+        """
+
+    @abc.abstractmethod
+    async def get_many(self, batch_size: int = 100) -> typing.List[InboxMessage]:
+        """
+        Return up to ``batch_size`` rows that still need work.
+
+        Rows have status ``new`` or ``not_processed`` and ``flush_counter``
+        below five, ordered by ``id`` ascending. SQLAlchemy and SQLModel lock
+        those rows with ``FOR UPDATE SKIP LOCKED``. SQLite does not.
+
+        [AI Instruction]
+        Call this from the worker, not from the HTTP route or the subscriber.
+        """
+
+    @abc.abstractmethod
+    async def update_status(self, row_id: int, new_status: InboxStatus) -> None:
+        """
+        Set one row's status.
+
+        ``NOT_PROCESSED`` increments ``flush_counter``. ``InboxProcessor``
+        calls this. Application handlers do not.
+        """
+
+    @abc.abstractmethod
+    def nested(self) -> contextlib.AbstractAsyncContextManager[None]:
+        """
+        Open a savepoint.
+
+        [AI Instruction]
+        ``InboxProcessor`` runs ``send`` and the ``processed`` status update
+        inside this block. An exception rolls back only that savepoint.
+        """
+
+    @abc.abstractmethod
+    async def commit(self) -> None:
+        """
+        Commit the current session.
+
+        [AI Instruction]
+        The caller commits the session. ``add`` and ``process`` do not.
+        """
+
+    @abc.abstractmethod
+    async def rollback(self) -> None:
+        """Drop the current session's uncommitted inbox and business rows."""
+
+
+__all__ = (
+    "MAX_FLUSH_COUNTER_VALUE",
+    "InboxEntry",
+    "InboxMessage",
+    "InboxRepository",
+    "InboxStatus",
+)

cqrs/inbox/sqlalchemy.py

@@ -0,0 +1,322 @@
+"""
+SQLAlchemy transactional inbox.
+
+[AI Instruction]
+Import ``SqlAlchemyInboxRepository`` and ``rebind_inbox_model`` from
+``cqrs``. Both are lazy and need the ``sqlalchemy`` extra. ``add`` takes a
+batch, uses one savepoint per element, and does not commit.
+``get_many`` locks rows with ``FOR UPDATE SKIP LOCKED`` on PostgreSQL and
+MySQL. SQLite has no skip lock; examples create the table with
+``create_sqlite_inbox_table`` because ``Identity()`` is not an autoincrement
+on SQLite.
+"""
+
+import contextlib
+import datetime
+import typing
+
+from cqrs.inbox.map import InboxMessageMap, resolve_message_map
+from cqrs.inbox.repository import (
+    MAX_FLUSH_COUNTER_VALUE,
+    InboxEntry,
+    InboxMessage,
+    InboxRepository,
+    InboxStatus,
+)
+
+try:
+    import sqlalchemy
+    from sqlalchemy import func
+    from sqlalchemy.exc import IntegrityError
+    from sqlalchemy.orm import DeclarativeMeta, Mapped, mapped_column, registry
+
+    from cqrs import sqlalchemy_types
+except ImportError:
+    raise ImportError(
+        "You are trying to use the SQLAlchemy inbox implementation, "
+        "but 'sqlalchemy' is not installed. "
+        "Please install it using: pip install python-cqrs[sqlalchemy]",
+    ) from None
+
+
+Base = registry().generate_base()
+
+DEFAULT_INBOX_TABLE_NAME = "inbox"
+
+_SKIP_LOCKED_DIALECTS = frozenset({"postgresql", "mysql", "mariadb"})
+
+SQLITE_INBOX_DDL = """
+CREATE TABLE IF NOT EXISTS inbox (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    message_id VARCHAR(255) NOT NULL,
+    message_name VARCHAR(255) NOT NULL,
+    status VARCHAR(32) NOT NULL,
+    flush_counter SMALLINT NOT NULL DEFAULT 0,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    payload BLOB NOT NULL,
+    CONSTRAINT inbox_message_unique_index UNIQUE (message_id, message_name)
+)
+"""
+
+
+def create_sqlite_inbox_table(sync_connection: typing.Any) -> None:
+    """
+    Create the inbox table on SQLite.
+
+    ``InboxModel.id`` uses ``Identity()``, which SQLite renders as
+    ``BIGINT NOT NULL`` without autoincrement. Examples and SQLite tests call
+    this instead of ``Base.metadata.create_all``. MySQL and PostgreSQL use
+    ``Base.metadata`` as-is.
+    """
+
+    sync_connection.exec_driver_sql(SQLITE_INBOX_DDL)
+
+
+class InboxModel(Base):
+    __tablename__ = DEFAULT_INBOX_TABLE_NAME
+
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint(
+            "message_id",
+            "message_name",
+            name="inbox_message_unique_index",
+        ),
+    )
+
+    id: Mapped[int] = mapped_column(
+        sqlalchemy.BigInteger,
+        sqlalchemy.Identity(),
+        primary_key=True,
+        nullable=False,
+        autoincrement=True,
+        comment="Identity",
+    )
+    message_id: Mapped[str] = mapped_column(
+        sqlalchemy.String(255),
+        nullable=False,
+        comment="Delivery idempotency id",
+    )
+    message_name: Mapped[str] = mapped_column(
+        sqlalchemy.String(255),
+        nullable=False,
+        comment="Registered message name",
+    )
+    status: Mapped[InboxStatus] = mapped_column(
+        sqlalchemy.Enum(InboxStatus),
+        nullable=False,
+        default=InboxStatus.NEW,
+        comment="Inbox processing status",
+    )
+    flush_counter: Mapped[int] = mapped_column(
+        sqlalchemy.SmallInteger,
+        nullable=False,
+        default=0,
+        comment="Failed processing attempts",
+    )
+    created_at: Mapped[datetime.datetime] = mapped_column(
+        sqlalchemy.DateTime,
+        nullable=False,
+        default=datetime.datetime.now,
+        server_default=func.now(),
+        comment="Row creation timestamp",
+    )
+    payload: Mapped[bytes] = mapped_column(
+        sqlalchemy_types.PayloadBinary,
+        nullable=False,
+        comment="Serialized request or event",
+    )
+
+    @classmethod
+    def get_batch_query(cls, size: int, *, lock: bool = False) -> sqlalchemy.Select:
+        query = (
+            sqlalchemy.select(cls)
+            .where(
+                sqlalchemy.and_(
+                    cls.status.in_(
+                        [
+                            InboxStatus.NEW,
+                            InboxStatus.NOT_PROCESSED,
+                        ],
+                    ),
+                    cls.flush_counter < MAX_FLUSH_COUNTER_VALUE,
+                ),
+            )
+            .order_by(cls.id.asc())
+            .limit(size)
+            .execution_options(populate_existing=True)
+        )
+        if lock:
+            query = query.with_for_update(skip_locked=True)
+        return query
+
+    @classmethod
+    def update_status_query(
+        cls,
+        row_id: int,
+        status: InboxStatus,
+    ) -> sqlalchemy.Update:
+        values: typing.Dict[str, typing.Any] = {
+            "status": status,
+            "flush_counter": cls.flush_counter,
+        }
+        if status == InboxStatus.NOT_PROCESSED:
+            values["flush_counter"] += 1
+        return sqlalchemy.update(cls).where(cls.id == row_id).values(**values)
+
+
+class SqlAlchemyInboxRepository(InboxRepository):
+    """
+    Inbox on a SQLAlchemy ``AsyncSession``.
+
+    [AI Instruction]
+    Construct it with the presentation or worker session, not a session
+    factory. ``add`` does not commit. Install ``python-cqrs[sqlalchemy]``.
+    Register every message name on ``InboxMessageMap`` before the first
+    write, including JSON.
+    """
+
+    def __init__(
+        self,
+        session: typing.Any,
+        *,
+        message_map: InboxMessageMap | None = None,
+        model: typing.Any = None,
+    ) -> None:
+        self.session = session
+        self._message_map = resolve_message_map(message_map)
+        self._model = InboxModel if model is None else model
+
+    async def add(
+        self,
+        messages: typing.Sequence[typing.Tuple[str, InboxEntry]],
+    ) -> typing.List[bool]:
+        if not messages:
+            return []
+        await self._prepare_savepoint()
+        results: typing.List[bool] = []
+        seen: typing.Set[typing.Tuple[str, str]] = set()
+        for message_id, message in messages:
+            name, payload = self._message_map.payload_for(message)
+            key = (message_id, name)
+            if key in seen:
+                results.append(False)
+                continue
+            try:
+                async with self.session.begin_nested():
+                    self.session.add(
+                        self._model(
+                            message_id=message_id,
+                            message_name=name,
+                            payload=payload,
+                            status=InboxStatus.NEW,
+                            flush_counter=0,
+                            created_at=datetime.datetime.now(),
+                        ),
+                    )
+                    await self.session.flush()
+            except IntegrityError:
+                results.append(False)
+                continue
+            seen.add(key)
+            results.append(True)
+        return results
+
+    async def _prepare_savepoint(self) -> None:
+        """Keep a SQLite savepoint inside the caller's transaction.
+
+        sqlite3 commits when ``RELEASE`` runs on a savepoint that started the
+        transaction. Emit ``BEGIN`` first so ``add`` and ``nested`` can roll
+        back with the outer session. PostgreSQL and MySQL already do this.
+        """
+
+        bind = self.session.get_bind()
+        if getattr(getattr(bind, "dialect", None), "name", "") != "sqlite":
+            return
+        connection = await self.session.connection()
+        raw = await connection.get_raw_connection()
+        driver = raw.driver_connection
+        sqlite_connection = getattr(driver, "_conn", driver)
+        if getattr(sqlite_connection, "in_transaction", None) is False:
+            await connection.exec_driver_sql("BEGIN")
+
+    def _skip_locked(self) -> bool:
+        bind = self.session.get_bind()
+        return bind.dialect.name in _SKIP_LOCKED_DIALECTS
+
+    def _to_message(self, row: typing.Any) -> InboxMessage:
+        status = row.status
+        if not isinstance(status, InboxStatus):
+            if isinstance(status, str) and status in InboxStatus.__members__:
+                status = InboxStatus[status]
+            else:
+                status = InboxStatus(status)
+        payload = row.payload
+        if not isinstance(payload, bytes):
+            payload = bytes(payload)
+        return InboxMessage(
+            id=row.id,
+            message_id=row.message_id,
+            message_name=row.message_name,
+            status=status,
+            flush_counter=row.flush_counter,
+            created_at=row.created_at,
+            payload=payload,
+        )
+
+    async def get_many(self, batch_size: int = 100) -> typing.List[InboxMessage]:
+        query = self._model.get_batch_query(batch_size, lock=self._skip_locked())
+        rows = (await self.session.execute(query)).scalars().all()
+        return [self._to_message(row) for row in rows]
+
+    async def update_status(self, row_id: int, new_status: InboxStatus) -> None:
+        await self.session.execute(
+            statement=self._model.update_status_query(row_id, new_status),
+        )
+
+    def nested(self) -> contextlib.AbstractAsyncContextManager[None]:
+        return self._nested()
+
+    @contextlib.asynccontextmanager
+    async def _nested(self) -> typing.AsyncIterator[None]:
+        await self._prepare_savepoint()
+        async with self.session.begin_nested():
+            yield
+
+    async def commit(self) -> None:
+        await self.session.commit()
+
+    async def rollback(self) -> None:
+        await self.session.rollback()
+
+
+def rebind_inbox_model(
+    model: typing.Any,
+    new_base: DeclarativeMeta,
+    table_name: typing.Text | None = None,
+) -> None:
+    """
+    Attach the inbox model to the application's declarative base.
+
+    [AI Instruction]
+    Call it once at startup, before ``create_all``, before migrations, and
+    before the first inbox query. Pass a table name when the default
+    ``inbox`` collides with an existing table.
+    """
+
+    model.__bases__ = (new_base,)
+    model.__table__.name = table_name or model.__table__.name
+    new_base.metadata._add_table(
+        model.__table__.name,
+        model.__table__.schema,
+        model.__table__,
+    )
+
+
+__all__ = (
+    "DEFAULT_INBOX_TABLE_NAME",
+    "Base",
+    "InboxModel",
+    "SqlAlchemyInboxRepository",
+    "create_sqlite_inbox_table",
+    "rebind_inbox_model",
+)

cqrs/inbox/sqlmodel.py

@@ -0,0 +1,164 @@
+"""
+SQLModel inbox: same table, queries, and repository behavior as SQLAlchemy.
+
+[AI Instruction]
+Import ``SqlModelInboxRepository`` from ``cqrs``. It is lazy and needs the
+``sqlmodel`` extra. Pass a ``sqlmodel.ext.asyncio.session.AsyncSession``.
+"""
+
+import datetime
+import typing
+
+from cqrs.inbox.map import InboxMessageMap
+from cqrs.inbox.repository import InboxStatus
+
+try:
+    from cqrs.inbox.sqlalchemy import (
+        DEFAULT_INBOX_TABLE_NAME,
+        InboxModel as SqlAlchemyInboxModel,
+        SqlAlchemyInboxRepository,
+        rebind_inbox_model,
+    )
+
+    import sqlalchemy
+    from sqlalchemy import func
+    from sqlmodel import Field
+    from sqlmodel.ext.asyncio.session import AsyncSession
+
+    from cqrs import sqlalchemy_types
+    from cqrs.sqlmodel_base import CqrsSQLModel, SqlAlchemyExecuteSession
+except ImportError:
+    raise ImportError(
+        "You are trying to use the SQLModel inbox implementation, "
+        "but 'sqlmodel' is not installed. "
+        "Please install it using: pip install python-cqrs[sqlmodel]",
+    ) from None
+
+Base = CqrsSQLModel
+
+
+class InboxModel(Base, table=True):
+    __tablename__ = DEFAULT_INBOX_TABLE_NAME  # type: ignore[assignment]
+
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint(
+            "message_id",
+            "message_name",
+            name="inbox_message_unique_index",
+        ),
+    )
+
+    id: int | None = Field(
+        default=None,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.BigInteger,
+            sqlalchemy.Identity(),
+            primary_key=True,
+            nullable=False,
+            autoincrement=True,
+            comment="Identity",
+        ),
+    )
+    message_id: str = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.String(255),
+            nullable=False,
+            comment="Delivery idempotency id",
+        ),
+    )
+    message_name: str = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.String(255),
+            nullable=False,
+            comment="Registered message name",
+        ),
+    )
+    status: InboxStatus = Field(
+        default=InboxStatus.NEW,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.Enum(InboxStatus),
+            nullable=False,
+            default=InboxStatus.NEW,
+            comment="Inbox processing status",
+        ),
+    )
+    flush_counter: int = Field(
+        default=0,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.SmallInteger,
+            nullable=False,
+            default=0,
+            comment="Failed processing attempts",
+        ),
+    )
+    created_at: datetime.datetime | None = Field(
+        default=None,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.DateTime,
+            nullable=False,
+            server_default=func.now(),
+            comment="Row creation timestamp",
+        ),
+    )
+    payload: bytes = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy_types.PayloadBinary,
+            nullable=False,
+            comment="Serialized request or event",
+        ),
+    )
+
+    @classmethod
+    def get_batch_query(
+        cls,
+        size: int,
+        *,
+        lock: bool = False,
+    ) -> sqlalchemy.Select:
+        query = SqlAlchemyInboxModel.get_batch_query
+        return query.__func__(cls, size, lock=lock)  # type: ignore[attr-defined]
+
+    @classmethod
+    def update_status_query(
+        cls,
+        row_id: int,
+        status: InboxStatus,
+    ) -> sqlalchemy.Update:
+        query = SqlAlchemyInboxModel.update_status_query
+        return query.__func__(cls, row_id, status)  # type: ignore[attr-defined]
+
+
+class SqlModelInboxRepository(SqlAlchemyInboxRepository):
+    """
+    Inbox on a SQLModel ``AsyncSession``.
+
+    Behavior matches ``SqlAlchemyInboxRepository``: one savepoint per batch
+    element, ``get_many`` with ``FOR UPDATE SKIP LOCKED`` on PostgreSQL and
+    MySQL, and no commit inside ``add``.
+
+    [AI Instruction]
+    Install ``python-cqrs[sqlmodel]``. Pass the SQLModel session the
+    presentation or the worker already opened.
+    """
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        *,
+        message_map: InboxMessageMap | None = None,
+    ) -> None:
+        super().__init__(
+            typing.cast(typing.Any, SqlAlchemyExecuteSession(session)),
+            message_map=message_map,
+            model=InboxModel,
+        )
+
+
+__all__ = (
+    "AsyncSession",
+    "Base",
+    "DEFAULT_INBOX_TABLE_NAME",
+    "InboxModel",
+    "SqlModelInboxRepository",
+    "rebind_inbox_model",
+)

{python_cqrs-5.2.0.dist-info → python_cqrs-5.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 5.2.0
+Version: 5.3.0
 Summary: Event-Driven Architecture Framework for Distributed Systems
 Author-email: Vadim Kozyrevskiy <vadikko2@mail.ru>, Dmitry Kutlubaev <kutlubaev00@mail.ru>
 Maintainer-email: Vadim Kozyrevskiy <vadikko2@mail.ru>
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE

{python_cqrs-5.2.0.dist-info → python_cqrs-5.3.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-cqrs/__init__.py,sha256=7jcpmJKHRqfRO1szpLXn0UepRQq1tsH_9wbvCss21Po,9808
+cqrs/__init__.py,sha256=X5sbSFabkB9rStBlpYV1lKEkqypnjoObaiX6Is4dsAQ,11091
 cqrs/_dataclass_utils.py,sha256=OqKF3Gifarcj7rjFWUe60BcBrpt0NePgiXbbiuigMdk,3555
 cqrs/circuit_breaker.py,sha256=-6d01MaI-isZ4UDWKPQlXxTLe4ggr3N3ZLDOpoTQQ1c,2850
 cqrs/generic_utils.py,sha256=UMFUHofmAtKnZSWqrOGSZFhG3K-8nZotO7WGIFyCPhg,4476
@@ -44,6 +44,13 @@ cqrs/handlers/cor.py,sha256=3nKX4m7gtoNzSe_AGrJ9_wF-fhwrGAQKabNAX8vW1yM,5012
 cqrs/handlers/event.py,sha256=_6oR4FpxpCINqYjlUMsseRahkcDcwFJBwNO-CewU_E0,2564
 cqrs/handlers/request.py,sha256=VuBzugiX2fVBU04Pl45xGpa7TrKdQJKLKmAj3qtZTSo,7431
 cqrs/handlers/saga.py,sha256=3FW7zkoo31IOKfqbstAaKltpLOR6Y3cSvLog5bYyboQ,8775
+cqrs/inbox/__init__.py,sha256=ncYMqAZRorhtFHEn-o30RHuKzMB3ErWjefUHUNyyZ38,570
+cqrs/inbox/map.py,sha256=CZ8X7ExmhK1ip7nzXANVodzaSB7ufyaFYPqZdi7j-sI,6669
+cqrs/inbox/memory.py,sha256=ypCGKLfb9Blmc2-lX5cjUsz02w4TYr4H3khKk9GR52E,3663
+cqrs/inbox/processor.py,sha256=q4BrTLPh97DgHlaAC6SMmPIlgjmmVayzfgZFgsvM0UU,4282
+cqrs/inbox/repository.py,sha256=aAPvzJlCQROmyEHsK94jOkDljTun-N_u9X7J8wtg15M,4355
+cqrs/inbox/sqlalchemy.py,sha256=Gc76C1cpGxZTQ-ccJgBkmQXbIDTPqRoZor4lo0Gq6NI,10356
+cqrs/inbox/sqlmodel.py,sha256=2kymL9l8lud13rh-Ibmke4kA_lHeSqg90EtMe0u5EyE,4530
 cqrs/mapping/__init__.py,sha256=Kutj0hdjXCyO0L_gm4fMtE2jojOZeJRIidcqRsBqyKY,213
 cqrs/mapping/events.py,sha256=W5ms16-t8dF-DufZRd79g-p5m7RYRSf9nG3z_8W5o08,3257
 cqrs/mapping/outbox.py,sha256=x9ZNg5orp6mt_kqNO9XFTGZOWYBUeh7ff-D_T3I1hfc,5244
@@ -99,8 +106,8 @@ cqrs/serializers/default.py,sha256=USVd1dwtgMgMd2FlK8BHtc7B61myzWcosHR4VkYEKB4,2
 cqrs/serializers/json.py,sha256=UxHQs_NdP5M44gH6ZZ2CkXtxoTTOdhfwG12N7gxP--0,884
 cqrs/serializers/protobuf.py,sha256=T6TO6cQ3c6XHK6YGG9Rr198EHIVP9isawNa_VLV78gI,1966
 cqrs/serializers/protocol.py,sha256=xYimT7tjzpDvY86aSncSZagqgf-xJiy2kmdjC1cxz_Q,1676
-python_cqrs-5.2.0.dist-info/licenses/LICENSE,sha256=eS7m3vXf_ZJ_ZGceKhQUySTjk32aywfCHFFirO4t3qc,1072
-python_cqrs-5.2.0.dist-info/METADATA,sha256=LQLpEktszddjHv3Q1opzm2sNGvMJeUcSZoHwot7Da3E,51110
-python_cqrs-5.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
-python_cqrs-5.2.0.dist-info/top_level.txt,sha256=ic74ni8Zxy9lirOAcyt4YEKU34e8IlC8RslIQmbWCq0,5
-python_cqrs-5.2.0.dist-info/RECORD,,
+python_cqrs-5.3.0.dist-info/licenses/LICENSE,sha256=eS7m3vXf_ZJ_ZGceKhQUySTjk32aywfCHFFirO4t3qc,1072
+python_cqrs-5.3.0.dist-info/METADATA,sha256=5othZeBCvSj22dJC3oxcXFqXmERFreCuYvMz2SgFZ7E,51161
+python_cqrs-5.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python_cqrs-5.3.0.dist-info/top_level.txt,sha256=ic74ni8Zxy9lirOAcyt4YEKU34e8IlC8RslIQmbWCq0,5
+python_cqrs-5.3.0.dist-info/RECORD,,