python-saga-orchestrator 0.1.2__tar.gz → 0.1.3__tar.gz

{python_saga_orchestrator-0.1.2/python_saga_orchestrator.egg-info → python_saga_orchestrator-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-saga-orchestrator
-Version: 0.1.2
+Version: 0.1.3
 Summary: Lightweight embedded saga orchestrator for asyncio Python services
 Author-email: Maxim Vasilyev <mayxis@inbox.ru>
 License-Expression: MIT

{python_saga_orchestrator-0.1.2 → python_saga_orchestrator-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-saga-orchestrator"
-version = "0.1.2"
+version = "0.1.3"
 description = "Lightweight embedded saga orchestrator for asyncio Python services"
 readme = "README.md"
 requires-python = ">=3.12"

{python_saga_orchestrator-0.1.2 → python_saga_orchestrator-0.1.3/python_saga_orchestrator.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-saga-orchestrator
-Version: 0.1.2
+Version: 0.1.3
 Summary: Lightweight embedded saga orchestrator for asyncio Python services
 Author-email: Maxim Vasilyev <mayxis@inbox.ru>
 License-Expression: MIT

{python_saga_orchestrator-0.1.2 → python_saga_orchestrator-0.1.3}/python_saga_orchestrator.egg-info/SOURCES.txt

@@ -28,7 +28,11 @@ saga_orchestrator/domain/models/step.py
 saga_orchestrator/domain/models/enums/__init__.py
 saga_orchestrator/domain/models/enums/saga_status.py
 saga_orchestrator/outbox/__init__.py
+saga_orchestrator/outbox/contracts.py
 saga_orchestrator/outbox/dispatcher.py
 saga_orchestrator/outbox/event.py
+saga_orchestrator/outbox/factory.py
 saga_orchestrator/outbox/models.py
-saga_orchestrator/outbox/repository.py
+saga_orchestrator/outbox/repository.py
+saga_orchestrator/outbox/retry.py
+saga_orchestrator/outbox/serialization.py

{python_saga_orchestrator-0.1.2 → python_saga_orchestrator-0.1.3}/saga_orchestrator/__init__.py

@@ -30,31 +30,49 @@ from .domain.models import (
 )
 from .domain.models.enums import SagaStatus
 from .outbox import (
+    ClaimedOutboxMessage,
+    DefaultOutboxMessageFactory,
+    FixedOutboxDispatchRetry,
+    JsonOutboxSerializer,
     OutboxDispatcher,
+    OutboxDispatchRetryPolicy,
     OutboxEvent,
+    OutboxMessageFactory,
     OutboxMessageMixin,
     OutboxPublisher,
     OutboxRepository,
+    OutboxSerializer,
     OutboxStatus,
+    OutboxWriteMessage,
+    OutboxWriter,
 )
 
 __all__ = [
     "ActiveSagaAlreadyExistsError",
     "AwaitingEvent",
     "BaseStep",
+    "ClaimedOutboxMessage",
+    "DefaultOutboxMessageFactory",
     "ExponentialRetry",
+    "FixedOutboxDispatchRetry",
     "FixedRetry",
     "InputContext",
+    "JsonOutboxSerializer",
     "NotifyEvent",
     "NotifyResult",
     "NoRetry",
     "OutboxDispatcher",
+    "OutboxDispatchRetryPolicy",
     "OutboxEvent",
+    "OutboxMessageFactory",
     "OutboxMap",
     "OutboxMessageMixin",
     "OutboxPublisher",
     "OutboxRepository",
+    "OutboxSerializer",
     "OutboxStatus",
+    "OutboxWriteMessage",
+    "OutboxWriter",
     "RetryPolicy",
     "SagaAdmin",
     "SagaAdminSnapshot",

{python_saga_orchestrator-0.1.2 → python_saga_orchestrator-0.1.3}/saga_orchestrator/core/engine.py

@@ -23,8 +23,11 @@ from ..domain.models import (
     StepDefinition,
 )
 from ..domain.models.enums import SagaStatus
-from ..outbox.models import OutboxMessageMixin, OutboxStatus
+from ..outbox.contracts import OutboxWriter
+from ..outbox.factory import DefaultOutboxMessageFactory, OutboxMessageFactory
+from ..outbox.models import OutboxMessageMixin
 from ..outbox.repository import OutboxRepository
+from ..outbox.serialization import JsonOutboxSerializer, OutboxSerializer
 from .repository import SagaRepository
 
 ModelT = TypeVar("ModelT", bound=SagaStateMixin)
@@ -39,6 +42,9 @@ class SagaEngine(Generic[ModelT]):
         model_class: type[ModelT],
         session_maker: async_sessionmaker[AsyncSession],
         outbox_model_class: type[OutboxMessageMixin] | None = None,
+        outbox_writer: OutboxWriter | None = None,
+        outbox_serializer: OutboxSerializer | None = None,
+        outbox_message_factory: OutboxMessageFactory | None = None,
         execution_lease: timedelta = timedelta(minutes=5),
     ) -> None:
         """Initialize the engine dependencies and execution lease."""
@@ -46,10 +52,20 @@ class SagaEngine(Generic[ModelT]):
         self._session_maker = session_maker
         self._execution_lease = execution_lease
         self._repository = SagaRepository(model_class)
-        self._outbox_model_class = outbox_model_class
         self._outbox_repository: OutboxRepository[OutboxMessageMixin] | None = None
-        if outbox_model_class is not None:
+        if outbox_writer is not None:
+            self._outbox_writer: OutboxWriter | None = outbox_writer
+        elif outbox_model_class is not None:
             self._outbox_repository = OutboxRepository(outbox_model_class)
+            self._outbox_writer = self._outbox_repository
+        else:
+            self._outbox_writer = None
+        self._outbox_serializer = outbox_serializer or JsonOutboxSerializer(
+            normalize=self._serialize_value
+        )
+        self._outbox_message_factory = (
+            outbox_message_factory or DefaultOutboxMessageFactory()
+        )
         self._registry: dict[str, SagaDefinition] = {}
 
     @property
@@ -62,6 +78,11 @@ class SagaEngine(Generic[ModelT]):
         """Return the outbox repository used by the engine."""
         return self._outbox_repository
 
+    @property
+    def outbox_writer(self) -> OutboxWriter | None:
+        """Return the outbox writer used by the engine."""
+        return self._outbox_writer
+
     def register(self, name: str, saga_definition: SagaDefinition) -> None:
         """Register a saga definition under a runtime name."""
         if name in self._registry:
@@ -590,38 +611,30 @@ class SagaEngine(Generic[ModelT]):
 
                 if error is None and step_output is not None:
                     if step_def.outbox_map is not None:
-                        if (
-                            self._outbox_model_class is None
-                            or self._outbox_repository is None
-                        ):
+                        if self._outbox_writer is None:
                             raise SagaStateError(
                                 "outbox_map is configured for step "
-                                f"'{step_def.step_id}', but outbox_model_class is not configured in SagaEngine"
+                                f"'{step_def.step_id}', but outbox writer is not configured in SagaEngine"
                             )
                         outbox_events = (
                             step_def.outbox_map(step_input, step_output) or []
                         )
-                        now = datetime.now(UTC)
-                        outbox_messages = [
-                            self._outbox_model_class(
-                                saga_id=saga.id,
-                                aggregation_id=saga.aggregation_id,
-                                step_id=step_def.step_id,
-                                trace_id=saga.trace_id,
-                                topic=event.topic,
-                                message_key=event.key,
-                                payload=self._serialize_value(event.payload),
-                                headers=self._serialize_value(event.headers),
-                                status=OutboxStatus.PENDING,
-                                next_attempt_at=now,
-                            )
-                            for event in outbox_events
-                        ]
-                        if outbox_messages:
-                            await self._outbox_repository.create_many(
-                                session,
-                                outbox_messages,
+                        if outbox_events:
+                            now = datetime.now(UTC)
+                            outbox_messages = (
+                                self._outbox_message_factory.build_messages(
+                                    saga_id=saga.id,
+                                    aggregation_id=saga.aggregation_id,
+                                    step_id=step_def.step_id,
+                                    trace_id=saga.trace_id,
+                                    step_input=step_input,
+                                    step_output=step_output,
+                                    events=outbox_events,
+                                    now=now,
+                                    serializer=self._outbox_serializer,
+                                )
                             )
+                            await self._outbox_writer.save(session, outbox_messages)
                     saga.step_history.append(
                         self._history_entry(
                             phase="execute",

{python_saga_orchestrator-0.1.2 → python_saga_orchestrator-0.1.3}/saga_orchestrator/core/orchestrator.py

@@ -15,8 +15,11 @@ from ..domain.models import (
     SagaDefinition,
     SagaSnapshot,
 )
+from ..outbox.contracts import OutboxWriter
+from ..outbox.factory import OutboxMessageFactory
 from ..outbox.models import OutboxMessageMixin
 from ..outbox.repository import OutboxRepository
+from ..outbox.serialization import OutboxSerializer
 from .engine import SagaEngine
 from .repository import SagaRepository
 
@@ -32,6 +35,9 @@ class SagaOrchestrator(Generic[ModelT]):
         model_class: type[ModelT],
         session_maker: async_sessionmaker[AsyncSession],
         outbox_model_class: type[OutboxMessageMixin] | None = None,
+        outbox_writer: OutboxWriter | None = None,
+        outbox_serializer: OutboxSerializer | None = None,
+        outbox_message_factory: OutboxMessageFactory | None = None,
         execution_lease: timedelta = timedelta(minutes=5),
     ) -> None:
         """Initialize the orchestrator facade."""
@@ -39,6 +45,9 @@ class SagaOrchestrator(Generic[ModelT]):
             model_class=model_class,
             session_maker=session_maker,
             outbox_model_class=outbox_model_class,
+            outbox_writer=outbox_writer,
+            outbox_serializer=outbox_serializer,
+            outbox_message_factory=outbox_message_factory,
             execution_lease=execution_lease,
         )
 
@@ -57,6 +66,11 @@ class SagaOrchestrator(Generic[ModelT]):
         """Return the outbox repository used by the engine."""
         return self._engine.outbox_repository
 
+    @property
+    def outbox_writer(self) -> OutboxWriter | None:
+        """Return the outbox writer used by the engine."""
+        return self._engine.outbox_writer
+
     def register(self, name: str, saga_definition: SagaDefinition) -> None:
         """Register a saga definition under a runtime name."""
         self._engine.register(name, saga_definition)

python_saga_orchestrator-0.1.3/saga_orchestrator/outbox/__init__.py

@@ -0,0 +1,33 @@
+"""Outbox module."""
+
+from .contracts import (
+    ClaimedOutboxMessage,
+    OutboxPublisher,
+    OutboxWriteMessage,
+    OutboxWriter,
+)
+from .dispatcher import OutboxDispatcher
+from .event import OutboxEvent
+from .factory import DefaultOutboxMessageFactory, OutboxMessageFactory
+from .models import OutboxMessageMixin, OutboxStatus
+from .repository import OutboxRepository
+from .retry import FixedOutboxDispatchRetry, OutboxDispatchRetryPolicy
+from .serialization import JsonOutboxSerializer, OutboxSerializer
+
+__all__ = [
+    "ClaimedOutboxMessage",
+    "DefaultOutboxMessageFactory",
+    "FixedOutboxDispatchRetry",
+    "JsonOutboxSerializer",
+    "OutboxDispatcher",
+    "OutboxEvent",
+    "OutboxMessageFactory",
+    "OutboxMessageMixin",
+    "OutboxPublisher",
+    "OutboxRepository",
+    "OutboxStatus",
+    "OutboxWriteMessage",
+    "OutboxWriter",
+    "OutboxDispatchRetryPolicy",
+    "OutboxSerializer",
+]

python_saga_orchestrator-0.1.3/saga_orchestrator/outbox/contracts.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Protocol
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .models import OutboxStatus
+
+
+@dataclass(frozen=True)
+class OutboxWriteMessage:
+    """Represent one outbox message ready to be persisted."""
+
+    saga_id: UUID
+    aggregation_id: str
+    step_id: str
+    trace_id: str
+    topic: str
+    payload: dict[str, Any]
+    key: str | None = None
+    headers: dict[str, Any] = field(default_factory=dict)
+    status: OutboxStatus = OutboxStatus.PENDING
+    next_attempt_at: datetime | None = None
+
+
+@dataclass(frozen=True)
+class ClaimedOutboxMessage:
+    """Represent one claimed outbox message ready to be dispatched."""
+
+    id: UUID
+    topic: str
+    payload: dict[str, Any]
+    key: str | None = None
+    headers: dict[str, Any] = field(default_factory=dict)
+    attempts: int = 0
+
+
+class OutboxWriter(Protocol):
+    """Define persistence operations required by engine and dispatcher."""
+
+    async def save(
+        self,
+        session: AsyncSession,
+        messages: Sequence[OutboxWriteMessage],
+    ) -> None: ...
+
+    async def claim_due(
+        self,
+        session: AsyncSession,
+        *,
+        now: datetime,
+        limit: int,
+    ) -> list[ClaimedOutboxMessage]: ...
+
+    async def mark_sent(
+        self,
+        session: AsyncSession,
+        message_id: UUID,
+        *,
+        sent_at: datetime,
+    ) -> bool: ...
+
+    async def mark_failed(
+        self,
+        session: AsyncSession,
+        message_id: UUID,
+        *,
+        error: str,
+        next_attempt_at: datetime,
+    ) -> bool: ...
+
+
+class OutboxPublisher(Protocol):
+    """Define transport publish operation for outbox dispatch."""
+
+    async def publish(
+        self,
+        *,
+        topic: str,
+        payload: dict[str, Any],
+        key: str | None = None,
+        headers: dict[str, Any] | None = None,
+    ) -> None: ...

python_saga_orchestrator-0.1.3/saga_orchestrator/outbox/dispatcher.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import TypeVar
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from .contracts import OutboxPublisher, OutboxWriter
+from .models import OutboxMessageMixin
+from .repository import OutboxRepository
+from .retry import FixedOutboxDispatchRetry, OutboxDispatchRetryPolicy
+from .serialization import JsonOutboxSerializer, OutboxSerializer
+
+OutboxModelT = TypeVar("OutboxModelT", bound=OutboxMessageMixin)
+
+
+class OutboxDispatcher:
+    """Dispatch outbox rows to an external transport."""
+
+    def __init__(
+        self,
+        *,
+        session_maker: async_sessionmaker[AsyncSession],
+        publisher: OutboxPublisher,
+        writer: OutboxWriter | None = None,
+        model_class: type[OutboxModelT] | None = None,
+        serializer: OutboxSerializer | None = None,
+        retry_policy: OutboxDispatchRetryPolicy | None = None,
+        failure_backoff: timedelta = timedelta(seconds=30),
+    ) -> None:
+        self._session_maker = session_maker
+        self._publisher = publisher
+        if writer is None:
+            if model_class is None:
+                raise ValueError("Either writer or model_class must be provided")
+            self._writer: OutboxWriter = OutboxRepository(model_class)
+        else:
+            self._writer = writer
+        self._serializer = serializer or JsonOutboxSerializer()
+        self._retry_policy = retry_policy or FixedOutboxDispatchRetry(
+            delay=failure_backoff
+        )
+
+    async def run_once(self, *, limit: int = 100) -> int:
+        """Claim due outbox messages and attempt to publish them once."""
+        now = datetime.now(UTC)
+
+        async with self._session_maker() as session:
+            async with session.begin():
+                claimed = await self._writer.claim_due(
+                    session,
+                    now=now,
+                    limit=limit,
+                )
+
+        for message in claimed:
+            try:
+                await self._publisher.publish(
+                    topic=message.topic,
+                    payload=self._serializer.deserialize_payload(message.payload),
+                    key=message.key,
+                    headers=self._serializer.deserialize_headers(message.headers),
+                )
+            except Exception as exc:  # noqa: BLE001
+                delay = self._retry_policy.next_delay(message.attempts + 1, exc)
+                async with self._session_maker() as session:
+                    async with session.begin():
+                        await self._writer.mark_failed(
+                            session,
+                            message.id,
+                            error=repr(exc),
+                            next_attempt_at=datetime.now(UTC) + delay,
+                        )
+                continue
+
+            async with self._session_maker() as session:
+                async with session.begin():
+                    await self._writer.mark_sent(
+                        session,
+                        message.id,
+                        sent_at=datetime.now(UTC),
+                    )
+
+        return len(claimed)

python_saga_orchestrator-0.1.3/saga_orchestrator/outbox/factory.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import datetime
+from typing import Protocol
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from .contracts import OutboxWriteMessage
+from .event import OutboxEvent
+from .serialization import OutboxSerializer
+
+
+class OutboxMessageFactory(Protocol):
+    """Define conversion from step outbox events to persisted outbox messages."""
+
+    def build_messages(
+        self,
+        *,
+        saga_id: UUID,
+        aggregation_id: str,
+        step_id: str,
+        trace_id: str,
+        step_input: BaseModel,
+        step_output: BaseModel,
+        events: Sequence[OutboxEvent],
+        now: datetime,
+        serializer: OutboxSerializer,
+    ) -> list[OutboxWriteMessage]: ...
+
+
+class DefaultOutboxMessageFactory:
+    """Build default outbox messages from mapped step events."""
+
+    def build_messages(
+        self,
+        *,
+        saga_id: UUID,
+        aggregation_id: str,
+        step_id: str,
+        trace_id: str,
+        step_input: BaseModel,
+        step_output: BaseModel,
+        events: Sequence[OutboxEvent],
+        now: datetime,
+        serializer: OutboxSerializer,
+    ) -> list[OutboxWriteMessage]:
+        return [
+            OutboxWriteMessage(
+                saga_id=saga_id,
+                aggregation_id=aggregation_id,
+                step_id=step_id,
+                trace_id=trace_id,
+                topic=event.topic,
+                key=event.key,
+                payload=serializer.serialize_payload(event.payload),
+                headers=serializer.serialize_headers(event.headers),
+                next_attempt_at=now,
+            )
+            for event in events
+        ]

python_saga_orchestrator-0.1.3/saga_orchestrator/outbox/repository.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from typing import Generic, TypeVar
+from uuid import UUID
+
+from sqlalchemy import Select, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .contracts import ClaimedOutboxMessage, OutboxWriteMessage
+from .models import OutboxMessageMixin, OutboxStatus
+
+OutboxModelT = TypeVar("OutboxModelT", bound=OutboxMessageMixin)
+
+
+class OutboxRepository(Generic[OutboxModelT]):
+    """Provide persistence operations for outbox rows."""
+
+    def __init__(self, model_class: type[OutboxModelT]) -> None:
+        self.model_class = model_class
+
+    async def create_many(
+        self,
+        session: AsyncSession,
+        messages: list[OutboxModelT],
+    ) -> None:
+        session.add_all(messages)
+        await session.flush()
+
+    async def save(
+        self,
+        session: AsyncSession,
+        messages: Sequence[OutboxWriteMessage],
+    ) -> None:
+        if not messages:
+            return
+        rows = [
+            self.model_class(
+                saga_id=message.saga_id,
+                aggregation_id=message.aggregation_id,
+                step_id=message.step_id,
+                trace_id=message.trace_id,
+                topic=message.topic,
+                message_key=message.key,
+                payload=message.payload,
+                headers=message.headers,
+                status=message.status,
+                next_attempt_at=message.next_attempt_at or datetime.now(UTC),
+            )
+            for message in messages
+        ]
+        await self.create_many(session, rows)
+
+    async def due_for_dispatch(
+        self,
+        session: AsyncSession,
+        *,
+        now: datetime,
+        limit: int,
+    ) -> list[OutboxModelT]:
+        stmt: Select[tuple[OutboxModelT]] = (
+            select(self.model_class)
+            .where(
+                self.model_class.status.in_(
+                    (OutboxStatus.PENDING, OutboxStatus.FAILED),
+                ),
+                self.model_class.next_attempt_at <= now,
+            )
+            .order_by(
+                self.model_class.next_attempt_at.asc(),
+                self.model_class.created_at.asc(),
+            )
+            .limit(limit)
+        )
+        if self._supports_skip_locked(session):
+            stmt = stmt.with_for_update(skip_locked=True)
+        else:
+            stmt = stmt.with_for_update(nowait=False)
+        result = await session.execute(stmt)
+        return list(result.scalars().all())
+
+    async def claim_due(
+        self,
+        session: AsyncSession,
+        *,
+        now: datetime,
+        limit: int,
+    ) -> list[ClaimedOutboxMessage]:
+        due = await self.due_for_dispatch(session, now=now, limit=limit)
+        claimed: list[ClaimedOutboxMessage] = []
+        for message in due:
+            message.status = OutboxStatus.DISPATCHING
+            claimed.append(
+                ClaimedOutboxMessage(
+                    id=message.id,
+                    topic=message.topic,
+                    payload=message.payload,
+                    key=message.message_key,
+                    headers=message.headers,
+                    attempts=message.attempts,
+                )
+            )
+        return claimed
+
+    async def get_for_update(
+        self,
+        session: AsyncSession,
+        message_id: UUID,
+    ) -> OutboxModelT | None:
+        stmt: Select[tuple[OutboxModelT]] = (
+            select(self.model_class)
+            .where(self.model_class.id == message_id)
+            .with_for_update(nowait=False)
+        )
+        result = await session.execute(stmt)
+        return result.scalar_one_or_none()
+
+    async def mark_sent(
+        self,
+        session: AsyncSession,
+        message_id: UUID,
+        *,
+        sent_at: datetime,
+    ) -> bool:
+        row = await self.get_for_update(session, message_id)
+        if row is None or row.status != OutboxStatus.DISPATCHING:
+            return False
+        row.status = OutboxStatus.SENT
+        row.sent_at = sent_at
+        row.last_error = None
+        return True
+
+    async def mark_failed(
+        self,
+        session: AsyncSession,
+        message_id: UUID,
+        *,
+        error: str,
+        next_attempt_at: datetime,
+    ) -> bool:
+        row = await self.get_for_update(session, message_id)
+        if row is None or row.status != OutboxStatus.DISPATCHING:
+            return False
+        row.status = OutboxStatus.FAILED
+        row.attempts += 1
+        row.last_error = error
+        row.next_attempt_at = next_attempt_at
+        return True
+
+    @staticmethod
+    def _supports_skip_locked(session: AsyncSession) -> bool:
+        bind = session.get_bind()
+        return bind is not None and bind.dialect.name == "postgresql"

python_saga_orchestrator-0.1.3/saga_orchestrator/outbox/retry.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Protocol
+
+
+class OutboxDispatchRetryPolicy(Protocol):
+    """Define scheduling of the next outbox dispatch attempt after failure."""
+
+    def next_delay(self, attempt: int, error: Exception) -> timedelta: ...
+
+
+class FixedOutboxDispatchRetry:
+    """Return a fixed delay for each failed dispatch attempt."""
+
+    def __init__(self, *, delay: timedelta = timedelta(seconds=30)) -> None:
+        self._delay = delay
+
+    def next_delay(self, attempt: int, error: Exception) -> timedelta:
+        return self._delay

python_saga_orchestrator-0.1.3/saga_orchestrator/outbox/serialization.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Protocol
+
+
+class OutboxSerializer(Protocol):
+    """Define serialization and deserialization for outbox payload and headers."""
+
+    def serialize_payload(self, payload: Any) -> dict[str, Any]: ...
+
+    def serialize_headers(self, headers: Any) -> dict[str, Any]: ...
+
+    def deserialize_payload(self, payload: Any) -> dict[str, Any]: ...
+
+    def deserialize_headers(self, headers: Any) -> dict[str, Any]: ...
+
+
+class JsonOutboxSerializer:
+    """Serialize payload and headers into JSON-compatible dictionaries."""
+
+    def __init__(self, *, normalize: Callable[[Any], Any] | None = None) -> None:
+        self._normalize = normalize
+
+    def serialize_payload(self, payload: Any) -> dict[str, Any]:
+        return self._to_dict(payload, field_name="payload")
+
+    def serialize_headers(self, headers: Any) -> dict[str, Any]:
+        if headers is None:
+            return {}
+        return self._to_dict(headers, field_name="headers")
+
+    def deserialize_payload(self, payload: Any) -> dict[str, Any]:
+        return self._to_dict(payload, field_name="payload")
+
+    def deserialize_headers(self, headers: Any) -> dict[str, Any]:
+        if headers is None:
+            return {}
+        return self._to_dict(headers, field_name="headers")
+
+    def _to_dict(self, value: Any, *, field_name: str) -> dict[str, Any]:
+        normalized = self._normalize(value) if self._normalize is not None else value
+        if isinstance(normalized, dict):
+            return normalized
+        raise TypeError(
+            f"Outbox {field_name} must serialize to dict, got {type(value)!r}"
+        )

python_saga_orchestrator-0.1.2/saga_orchestrator/outbox/__init__.py

@@ -1,15 +0,0 @@
-"""Outbox module."""
-
-from .dispatcher import OutboxDispatcher, OutboxPublisher
-from .event import OutboxEvent
-from .models import OutboxMessageMixin, OutboxStatus
-from .repository import OutboxRepository
-
-__all__ = [
-    "OutboxDispatcher",
-    "OutboxEvent",
-    "OutboxMessageMixin",
-    "OutboxPublisher",
-    "OutboxRepository",
-    "OutboxStatus",
-]

python_saga_orchestrator-0.1.2/saga_orchestrator/outbox/dispatcher.py

@@ -1,95 +0,0 @@
-from __future__ import annotations
-
-from datetime import UTC, datetime, timedelta
-from typing import Any, Protocol, TypeVar
-from uuid import UUID
-
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
-
-from .models import OutboxMessageMixin, OutboxStatus
-from .repository import OutboxRepository
-
-OutboxModelT = TypeVar("OutboxModelT", bound=OutboxMessageMixin)
-
-
-class OutboxPublisher(Protocol):
-    async def publish(
-        self,
-        *,
-        topic: str,
-        payload: dict[str, Any],
-        key: str | None = None,
-        headers: dict[str, Any] | None = None,
-    ) -> None: ...
-
-
-class OutboxDispatcher:
-    """Dispatch outbox rows to an external transport."""
-
-    def __init__(
-        self,
-        *,
-        session_maker: async_sessionmaker[AsyncSession],
-        model_class: type[OutboxModelT],
-        publisher: OutboxPublisher,
-        failure_backoff: timedelta = timedelta(seconds=30),
-    ) -> None:
-        self._session_maker = session_maker
-        self._repository = OutboxRepository(model_class)
-        self._publisher = publisher
-        self._failure_backoff = failure_backoff
-
-    async def run_once(self, *, limit: int = 100) -> int:
-        """Claim due outbox messages and attempt to publish them once."""
-        now = datetime.now(UTC)
-        claimed: list[tuple[UUID, str, dict[str, Any], str | None, dict[str, Any]]] = []
-
-        async with self._session_maker() as session:
-            async with session.begin():
-                due = await self._repository.due_for_dispatch(
-                    session,
-                    now=now,
-                    limit=limit,
-                )
-                for message in due:
-                    message.status = OutboxStatus.DISPATCHING
-                    claimed.append(
-                        (
-                            message.id,
-                            message.topic,
-                            message.payload,
-                            message.message_key,
-                            message.headers,
-                        )
-                    )
-
-        for message_id, topic, payload, key, headers in claimed:
-            try:
-                await self._publisher.publish(
-                    topic=topic,
-                    payload=payload,
-                    key=key,
-                    headers=headers,
-                )
-            except Exception as exc:  # noqa: BLE001
-                async with self._session_maker() as session:
-                    async with session.begin():
-                        row = await self._repository.get_for_update(session, message_id)
-                        if row is None or row.status != OutboxStatus.DISPATCHING:
-                            continue
-                        row.status = OutboxStatus.FAILED
-                        row.attempts += 1
-                        row.last_error = repr(exc)
-                        row.next_attempt_at = datetime.now(UTC) + self._failure_backoff
-                continue
-
-            async with self._session_maker() as session:
-                async with session.begin():
-                    row = await self._repository.get_for_update(session, message_id)
-                    if row is None or row.status != OutboxStatus.DISPATCHING:
-                        continue
-                    row.status = OutboxStatus.SENT
-                    row.sent_at = datetime.now(UTC)
-                    row.last_error = None
-
-        return len(claimed)

python_saga_orchestrator-0.1.2/saga_orchestrator/outbox/repository.py

@@ -1,73 +0,0 @@
-from __future__ import annotations
-
-from datetime import datetime
-from typing import Generic, TypeVar
-from uuid import UUID
-
-from sqlalchemy import Select, select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from .models import OutboxMessageMixin, OutboxStatus
-
-OutboxModelT = TypeVar("OutboxModelT", bound=OutboxMessageMixin)
-
-
-class OutboxRepository(Generic[OutboxModelT]):
-    """Provide persistence operations for outbox rows."""
-
-    def __init__(self, model_class: type[OutboxModelT]) -> None:
-        self.model_class = model_class
-
-    async def create_many(
-        self,
-        session: AsyncSession,
-        messages: list[OutboxModelT],
-    ) -> None:
-        session.add_all(messages)
-        await session.flush()
-
-    async def due_for_dispatch(
-        self,
-        session: AsyncSession,
-        *,
-        now: datetime,
-        limit: int,
-    ) -> list[OutboxModelT]:
-        stmt: Select[tuple[OutboxModelT]] = (
-            select(self.model_class)
-            .where(
-                self.model_class.status.in_(
-                    (OutboxStatus.PENDING, OutboxStatus.FAILED),
-                ),
-                self.model_class.next_attempt_at <= now,
-            )
-            .order_by(
-                self.model_class.next_attempt_at.asc(),
-                self.model_class.created_at.asc(),
-            )
-            .limit(limit)
-        )
-        if self._supports_skip_locked(session):
-            stmt = stmt.with_for_update(skip_locked=True)
-        else:
-            stmt = stmt.with_for_update(nowait=False)
-        result = await session.execute(stmt)
-        return list(result.scalars().all())
-
-    async def get_for_update(
-        self,
-        session: AsyncSession,
-        message_id: UUID,
-    ) -> OutboxModelT | None:
-        stmt: Select[tuple[OutboxModelT]] = (
-            select(self.model_class)
-            .where(self.model_class.id == message_id)
-            .with_for_update(nowait=False)
-        )
-        result = await session.execute(stmt)
-        return result.scalar_one_or_none()
-
-    @staticmethod
-    def _supports_skip_locked(session: AsyncSession) -> bool:
-        bind = session.get_bind()
-        return bind is not None and bind.dialect.name == "postgresql"