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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-saga-orchestrator
-Version: 0.1.0
+Version: 0.1.2
 Summary: Lightweight embedded saga orchestrator for asyncio Python services
 Author-email: Maxim Vasilyev <mayxis@inbox.ru>
 License-Expression: MIT
@@ -60,16 +60,28 @@ Requirements:
 - Python 3.12+
 - PostgreSQL for production-grade execution semantics
 
-Install from source:
+Install from PyPI:
+
+```bash
+pip install python-saga-orchestrator
+```
+
+Or with `uv`:
+
+```bash
+uv pip install python-saga-orchestrator
+```
+
+Install from the repository source:
 
 ```bash
 pip install .
 ```
 
-Or install development dependencies:
+For local development:
 
 ```bash
-pip install .[dev]
+pip install '.[dev]'
 ```
 
 ## Core concepts
@@ -251,6 +263,18 @@ accepted = await orchestrator.notify(
 )
 ```
 
+Configure explicit event expectations through a public API:
+
+```python
+token = await orchestrator.await_event(
+    saga_id=saga_id,
+    event=AwaitingEvent(
+        event_type="model.approved",
+        correlation_id="corr-123",
+    ),
+)
+```
+
 The event payload is stored in saga context and can be used by root-step `input_map` functions through `InputContext`.
 
 ## Administrative operations
@@ -306,9 +330,13 @@ SQLite may be sufficient for local experiments, but PostgreSQL should be used fo
 
 A runnable end-to-end example is available in:
 
-- [`test.py`](./test.py)
+- [`examples/llm_deploy.py`](./examples/llm_deploy.py)
+- [`examples/retry_recovery.py`](./examples/retry_recovery.py)
+- [`examples/compensation_flow.py`](./examples/compensation_flow.py)
+- [`examples/admin_skip.py`](./examples/admin_skip.py)
 
-It demonstrates:
+These examples demonstrate:
+- basic model deployment
 - retry and recovery through `run_due()`
 - compensation after failure
 - admin-driven step skipping

{python_saga_orchestrator-0.1.0 → python_saga_orchestrator-0.1.2}/README.md

@@ -26,16 +26,28 @@ Requirements:
 - Python 3.12+
 - PostgreSQL for production-grade execution semantics
 
-Install from source:
+Install from PyPI:
+
+```bash
+pip install python-saga-orchestrator
+```
+
+Or with `uv`:
+
+```bash
+uv pip install python-saga-orchestrator
+```
+
+Install from the repository source:
 
 ```bash
 pip install .
 ```
 
-Or install development dependencies:
+For local development:
 
 ```bash
-pip install .[dev]
+pip install '.[dev]'
 ```
 
 ## Core concepts
@@ -217,6 +229,18 @@ accepted = await orchestrator.notify(
 )
 ```
 
+Configure explicit event expectations through a public API:
+
+```python
+token = await orchestrator.await_event(
+    saga_id=saga_id,
+    event=AwaitingEvent(
+        event_type="model.approved",
+        correlation_id="corr-123",
+    ),
+)
+```
+
 The event payload is stored in saga context and can be used by root-step `input_map` functions through `InputContext`.
 
 ## Administrative operations
@@ -272,9 +296,13 @@ SQLite may be sufficient for local experiments, but PostgreSQL should be used fo
 
 A runnable end-to-end example is available in:
 
-- [`test.py`](./test.py)
+- [`examples/llm_deploy.py`](./examples/llm_deploy.py)
+- [`examples/retry_recovery.py`](./examples/retry_recovery.py)
+- [`examples/compensation_flow.py`](./examples/compensation_flow.py)
+- [`examples/admin_skip.py`](./examples/admin_skip.py)
 
-It demonstrates:
+These examples demonstrate:
+- basic model deployment
 - retry and recovery through `run_due()`
 - compensation after failure
 - admin-driven step skipping

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-saga-orchestrator
-Version: 0.1.0
+Version: 0.1.2
 Summary: Lightweight embedded saga orchestrator for asyncio Python services
 Author-email: Maxim Vasilyev <mayxis@inbox.ru>
 License-Expression: MIT
@@ -60,16 +60,28 @@ Requirements:
 - Python 3.12+
 - PostgreSQL for production-grade execution semantics
 
-Install from source:
+Install from PyPI:
+
+```bash
+pip install python-saga-orchestrator
+```
+
+Or with `uv`:
+
+```bash
+uv pip install python-saga-orchestrator
+```
+
+Install from the repository source:
 
 ```bash
 pip install .
 ```
 
-Or install development dependencies:
+For local development:
 
 ```bash
-pip install .[dev]
+pip install '.[dev]'
 ```
 
 ## Core concepts
@@ -251,6 +263,18 @@ accepted = await orchestrator.notify(
 )
 ```
 
+Configure explicit event expectations through a public API:
+
+```python
+token = await orchestrator.await_event(
+    saga_id=saga_id,
+    event=AwaitingEvent(
+        event_type="model.approved",
+        correlation_id="corr-123",
+    ),
+)
+```
+
 The event payload is stored in saga context and can be used by root-step `input_map` functions through `InputContext`.
 
 ## Administrative operations
@@ -306,9 +330,13 @@ SQLite may be sufficient for local experiments, but PostgreSQL should be used fo
 
 A runnable end-to-end example is available in:
 
-- [`test.py`](./test.py)
+- [`examples/llm_deploy.py`](./examples/llm_deploy.py)
+- [`examples/retry_recovery.py`](./examples/retry_recovery.py)
+- [`examples/compensation_flow.py`](./examples/compensation_flow.py)
+- [`examples/admin_skip.py`](./examples/admin_skip.py)
 
-It demonstrates:
+These examples demonstrate:
+- basic model deployment
 - retry and recovery through `run_due()`
 - compensation after failure
 - admin-driven step skipping

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

@@ -21,8 +21,14 @@ saga_orchestrator/domain/mixins/__init__.py
 saga_orchestrator/domain/mixins/saga_state.py
 saga_orchestrator/domain/models/__init__.py
 saga_orchestrator/domain/models/builder.py
+saga_orchestrator/domain/models/notify.py
 saga_orchestrator/domain/models/retry.py
 saga_orchestrator/domain/models/saga_snapshot.py
 saga_orchestrator/domain/models/step.py
 saga_orchestrator/domain/models/enums/__init__.py
-saga_orchestrator/domain/models/enums/saga_status.py
+saga_orchestrator/domain/models/enums/saga_status.py
+saga_orchestrator/outbox/__init__.py
+saga_orchestrator/outbox/dispatcher.py
+saga_orchestrator/outbox/event.py
+saga_orchestrator/outbox/models.py
+saga_orchestrator/outbox/repository.py

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

@@ -11,11 +11,15 @@ from .domain.exceptions import (
 )
 from .domain.mixins import SagaStateMixin
 from .domain.models import (
+    AwaitingEvent,
     BaseStep,
     ExponentialRetry,
     FixedRetry,
     InputContext,
     NoRetry,
+    NotifyEvent,
+    NotifyResult,
+    OutboxMap,
     RetryPolicy,
     SagaAdminSnapshot,
     SagaDefinition,
@@ -25,16 +29,32 @@ from .domain.models import (
     StepRef,
 )
 from .domain.models.enums import SagaStatus
-
-__version__ = "0.1.0"
+from .outbox import (
+    OutboxDispatcher,
+    OutboxEvent,
+    OutboxMessageMixin,
+    OutboxPublisher,
+    OutboxRepository,
+    OutboxStatus,
+)
 
 __all__ = [
     "ActiveSagaAlreadyExistsError",
+    "AwaitingEvent",
     "BaseStep",
     "ExponentialRetry",
     "FixedRetry",
     "InputContext",
+    "NotifyEvent",
+    "NotifyResult",
     "NoRetry",
+    "OutboxDispatcher",
+    "OutboxEvent",
+    "OutboxMap",
+    "OutboxMessageMixin",
+    "OutboxPublisher",
+    "OutboxRepository",
+    "OutboxStatus",
     "RetryPolicy",
     "SagaAdmin",
     "SagaAdminSnapshot",
@@ -53,5 +73,4 @@ __all__ = [
     "StepInputMap",
     "StepRef",
     "TypeValidationError",
-    "__version__",
 ]

{python_saga_orchestrator-0.1.0 → python_saga_orchestrator-0.1.2}/saga_orchestrator/core/builder.py

@@ -11,6 +11,7 @@ from ..domain.models import (
     BaseStep,
     InputContext,
     NoRetry,
+    OutboxMap,
     RetryPolicy,
     SagaDefinition,
     StepDefinition,
@@ -35,11 +36,14 @@ class SagaBuilder:
         timeout: timedelta | None = None,
         retry_policy: RetryPolicy | None = None,
         depends_on: StepRef[Any] | None = None,
+        outbox_map: OutboxMap[Any, Any] | None = None,
         step_id: str | None = None,
     ) -> StepRef[Any]:
         """Add one step definition and return a reference to its output."""
         if not callable(input_map):
             raise SagaDefinitionError("input_map must be callable")
+        if outbox_map is not None and not callable(outbox_map):
+            raise SagaDefinitionError("outbox_map must be callable")
         self.validate_input_map_types(input_map, step.input_model, depends_on)
 
         normalized_step_id = step_id or f"step_{len(self._steps)}"
@@ -53,6 +57,7 @@ class SagaBuilder:
             timeout=timeout,
             retry_policy=retry_policy or NoRetry(),
             depends_on=depends_on,
+            outbox_map=outbox_map,
         )
         self._steps.append(definition)
         return StepRef(step_id=normalized_step_id, output_model=step.output_model)

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

@@ -13,13 +13,18 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 from ..domain.exceptions import SagaDefinitionError, SagaStateError
 from ..domain.mixins import SagaStateMixin
 from ..domain.models import (
+    AwaitingEvent,
     InputContext,
+    NotifyEvent,
+    NotifyResult,
     SagaAdminSnapshot,
     SagaDefinition,
     SagaSnapshot,
     StepDefinition,
 )
 from ..domain.models.enums import SagaStatus
+from ..outbox.models import OutboxMessageMixin, OutboxStatus
+from ..outbox.repository import OutboxRepository
 from .repository import SagaRepository
 
 ModelT = TypeVar("ModelT", bound=SagaStateMixin)
@@ -33,6 +38,7 @@ class SagaEngine(Generic[ModelT]):
         *,
         model_class: type[ModelT],
         session_maker: async_sessionmaker[AsyncSession],
+        outbox_model_class: type[OutboxMessageMixin] | None = None,
         execution_lease: timedelta = timedelta(minutes=5),
     ) -> None:
         """Initialize the engine dependencies and execution lease."""
@@ -40,6 +46,10 @@ 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:
+            self._outbox_repository = OutboxRepository(outbox_model_class)
         self._registry: dict[str, SagaDefinition] = {}
 
     @property
@@ -47,6 +57,11 @@ class SagaEngine(Generic[ModelT]):
         """Return the repository used by the engine."""
         return self._repository
 
+    @property
+    def outbox_repository(self) -> OutboxRepository[OutboxMessageMixin] | None:
+        """Return the outbox repository used by the engine."""
+        return self._outbox_repository
+
     def register(self, name: str, saga_definition: SagaDefinition) -> None:
         """Register a saga definition under a runtime name."""
         if name in self._registry:
@@ -102,21 +117,110 @@ class SagaEngine(Generic[ModelT]):
         return saga_id
 
     async def notify(
-        self, *, saga_id: UUID, token: UUID, event: Any | None = None
+        self,
+        *,
+        saga_id: UUID,
+        token: UUID,
+        event: NotifyEvent | dict[str, Any] | Any | None = None,
     ) -> bool:
         """Resume a suspended saga when the provided execution token matches."""
+        result = await self.notify_detailed(
+            saga_id=saga_id,
+            token=token,
+            event=event,
+        )
+        return result == NotifyResult.ACCEPTED
+
+    async def notify_detailed(
+        self,
+        *,
+        saga_id: UUID,
+        token: UUID,
+        event: NotifyEvent | dict[str, Any] | Any | None = None,
+    ) -> NotifyResult:
+        """Resume a suspended saga and return a detailed notify outcome."""
+        normalized_event, idempotency_key = self._normalize_notify_event(event)
+
         async with self._session_maker() as session:
             async with session.begin():
                 saga = await self._repository.get_for_update(session, saga_id)
                 if saga.status != SagaStatus.SUSPENDED:
-                    return False
+                    self._append_notify_log(
+                        saga=saga,
+                        event=normalized_event,
+                        result=NotifyResult.NOT_SUSPENDED,
+                    )
+                    return NotifyResult.NOT_SUSPENDED
                 if saga.step_execution_token != token:
                     logger.info("Ignoring stale notify for saga_id=%s", saga_id)
-                    return False
-                if event is not None:
+                    self._append_notify_log(
+                        saga=saga,
+                        event=normalized_event,
+                        result=NotifyResult.STALE_TOKEN,
+                    )
+                    return NotifyResult.STALE_TOKEN
+
+                processed_ids = saga.context.setdefault("processed_event_ids", [])
+                if idempotency_key is not None and idempotency_key in processed_ids:
+                    self._append_notify_log(
+                        saga=saga,
+                        event=normalized_event,
+                        result=NotifyResult.DUPLICATE,
+                    )
+                    return NotifyResult.DUPLICATE
+
+                expected_type = saga.context.get("awaiting_event_type")
+                if (
+                    expected_type is not None
+                    and normalized_event is not None
+                    and normalized_event.event_type != expected_type
+                ):
+                    self._append_notify_log(
+                        saga=saga,
+                        event=normalized_event,
+                        result=NotifyResult.EVENT_TYPE_MISMATCH,
+                    )
+                    return NotifyResult.EVENT_TYPE_MISMATCH
+
+                expected_correlation = saga.context.get("awaiting_correlation_id")
+                if (
+                    expected_correlation is not None
+                    and normalized_event is not None
+                    and normalized_event.correlation_id != expected_correlation
+                ):
+                    self._append_notify_log(
+                        saga=saga,
+                        event=normalized_event,
+                        result=NotifyResult.CORRELATION_MISMATCH,
+                    )
+                    return NotifyResult.CORRELATION_MISMATCH
+
+                awaiting_until = self._parse_iso_datetime(
+                    saga.context.get("awaiting_until")
+                )
+                if awaiting_until is not None and datetime.now(UTC) > awaiting_until:
+                    self._append_notify_log(
+                        saga=saga,
+                        event=normalized_event,
+                        result=NotifyResult.EXPIRED,
+                    )
+                    return NotifyResult.EXPIRED
+
+                if normalized_event is not None:
                     events = saga.context.setdefault("events", [])
-                    events.append(self._serialize_value(event))
-                    saga.context["latest_event"] = self._serialize_value(event)
+                    events.append(self._serialize_value(normalized_event.payload))
+                    saga.context["latest_event"] = self._serialize_value(
+                        normalized_event.payload
+                    )
+                    saga.context["latest_event_meta"] = self._serialize_value(
+                        normalized_event.model_dump(mode="json")
+                    )
+                    if idempotency_key is not None:
+                        processed_ids.append(idempotency_key)
+
+                saga.context.pop("awaiting_event_type", None)
+                saga.context.pop("awaiting_correlation_id", None)
+                saga.context.pop("awaiting_until", None)
                 saga.status = SagaStatus.RUNNING
                 step_def = self._registry[saga.context["saga_name"]].steps[
                     saga.current_step_index
@@ -126,9 +230,50 @@ class SagaEngine(Generic[ModelT]):
                     now=datetime.now(UTC),
                 )
                 saga.step_execution_token = uuid.uuid4()
+                self._append_notify_log(
+                    saga=saga,
+                    event=normalized_event,
+                    result=NotifyResult.ACCEPTED,
+                )
 
         await self._drive(saga_id)
-        return True
+        return NotifyResult.ACCEPTED
+
+    async def await_event(
+        self,
+        *,
+        saga_id: UUID,
+        event: AwaitingEvent,
+    ) -> UUID:
+        """Configure a suspended saga to wait for a specific external event."""
+        async with self._session_maker() as session:
+            async with session.begin():
+                saga = await self._repository.get_for_update(session, saga_id)
+                if saga.status != SagaStatus.SUSPENDED:
+                    raise SagaStateError(
+                        "Cannot configure external wait unless saga is suspended "
+                        f"(status={saga.status.value})"
+                    )
+
+                if event.event_type is None:
+                    saga.context.pop("awaiting_event_type", None)
+                else:
+                    saga.context["awaiting_event_type"] = event.event_type
+
+                if event.correlation_id is None:
+                    saga.context.pop("awaiting_correlation_id", None)
+                else:
+                    saga.context["awaiting_correlation_id"] = event.correlation_id
+
+                if event.until is None:
+                    saga.context.pop("awaiting_until", None)
+                else:
+                    saga.context["awaiting_until"] = event.until.isoformat()
+
+                # External event waits should not be auto-resumed by run_due.
+                saga.deadline_at = None
+                saga.step_execution_token = uuid.uuid4()
+                return saga.step_execution_token
 
     async def run_due(self, *, limit: int = 100) -> int:
         """Resume due running, suspended, and compensating sagas."""
@@ -444,6 +589,39 @@ class SagaEngine(Generic[ModelT]):
                     return False
 
                 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
+                        ):
+                            raise SagaStateError(
+                                "outbox_map is configured for step "
+                                f"'{step_def.step_id}', but outbox_model_class 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,
+                            )
                     saga.step_history.append(
                         self._history_entry(
                             phase="execute",
@@ -471,7 +649,11 @@ class SagaEngine(Generic[ModelT]):
                         saga.status = SagaStatus.COMPLETED
                     return saga.status == SagaStatus.RUNNING
 
-                assert error is not None
+                if error is None:
+                    raise SagaStateError(
+                        "Step finalization expected either a successful output "
+                        "or an execution error"
+                    )
                 saga.step_history.append(
                     self._history_entry(
                         phase="execute",
@@ -693,6 +875,60 @@ class SagaEngine(Generic[ModelT]):
             return [self._serialize_value(item) for item in value]
         return value
 
+    def _normalize_notify_event(
+        self,
+        event: NotifyEvent | dict[str, Any] | Any | None,
+    ) -> tuple[NotifyEvent | None, str | None]:
+        if event is None:
+            return None, None
+        if isinstance(event, NotifyEvent):
+            return event, event.event_id
+        if isinstance(event, dict):
+            envelope_keys = {
+                "event_id",
+                "event_type",
+                "correlation_id",
+                "payload",
+                "source",
+                "occurred_at",
+            }
+            if any(key in event for key in envelope_keys):
+                notify_event = NotifyEvent.model_validate(event)
+                return notify_event, notify_event.event_id
+            return NotifyEvent(payload=self._serialize_value(event)), None
+        return NotifyEvent(payload=self._serialize_value(event)), None
+
+    @staticmethod
+    def _parse_iso_datetime(value: Any) -> datetime | None:
+        if not isinstance(value, str):
+            return None
+        normalized = value.replace("Z", "+00:00")
+        try:
+            parsed = datetime.fromisoformat(normalized)
+        except ValueError:
+            return None
+        if parsed.tzinfo is None:
+            return parsed.replace(tzinfo=UTC)
+        return parsed
+
+    def _append_notify_log(
+        self,
+        *,
+        saga: ModelT,
+        event: NotifyEvent | None,
+        result: NotifyResult,
+    ) -> None:
+        inbox = saga.context.setdefault("notify_inbox", [])
+        inbox.append(
+            {
+                "timestamp": datetime.now(UTC).isoformat(),
+                "result": result.value,
+                "event_id": event.event_id if event is not None else None,
+                "event_type": event.event_type if event is not None else None,
+                "correlation_id": (event.correlation_id if event is not None else None),
+            }
+        )
+
     def _history_entry(
         self,
         *,

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

@@ -8,7 +8,15 @@ from pydantic import BaseModel
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
 from ..domain.mixins import SagaStateMixin
-from ..domain.models import SagaDefinition, SagaSnapshot
+from ..domain.models import (
+    AwaitingEvent,
+    NotifyEvent,
+    NotifyResult,
+    SagaDefinition,
+    SagaSnapshot,
+)
+from ..outbox.models import OutboxMessageMixin
+from ..outbox.repository import OutboxRepository
 from .engine import SagaEngine
 from .repository import SagaRepository
 
@@ -23,12 +31,14 @@ class SagaOrchestrator(Generic[ModelT]):
         *,
         model_class: type[ModelT],
         session_maker: async_sessionmaker[AsyncSession],
+        outbox_model_class: type[OutboxMessageMixin] | None = None,
         execution_lease: timedelta = timedelta(minutes=5),
     ) -> None:
         """Initialize the orchestrator facade."""
         self._engine = SagaEngine(
             model_class=model_class,
             session_maker=session_maker,
+            outbox_model_class=outbox_model_class,
             execution_lease=execution_lease,
         )
 
@@ -42,6 +52,11 @@ class SagaOrchestrator(Generic[ModelT]):
         """Return the repository used by the engine."""
         return self._engine.repository
 
+    @property
+    def outbox_repository(self) -> OutboxRepository[OutboxMessageMixin] | None:
+        """Return the outbox repository used by the engine."""
+        return self._engine.outbox_repository
+
     def register(self, name: str, saga_definition: SagaDefinition) -> None:
         """Register a saga definition under a runtime name."""
         self._engine.register(name, saga_definition)
@@ -63,11 +78,38 @@ class SagaOrchestrator(Generic[ModelT]):
         )
 
     async def notify(
-        self, *, saga_id: UUID, token: UUID, event: Any | None = None
+        self,
+        *,
+        saga_id: UUID,
+        token: UUID,
+        event: NotifyEvent | dict[str, Any] | Any | None = None,
     ) -> bool:
         """Resume a suspended saga when the provided execution token matches."""
         return await self._engine.notify(saga_id=saga_id, token=token, event=event)
 
+    async def notify_detailed(
+        self,
+        *,
+        saga_id: UUID,
+        token: UUID,
+        event: NotifyEvent | dict[str, Any] | Any | None = None,
+    ) -> NotifyResult:
+        """Resume a suspended saga and return a detailed notify outcome."""
+        return await self._engine.notify_detailed(
+            saga_id=saga_id,
+            token=token,
+            event=event,
+        )
+
+    async def await_event(
+        self,
+        *,
+        saga_id: UUID,
+        event: AwaitingEvent,
+    ) -> UUID:
+        """Configure a suspended saga to wait for an external event."""
+        return await self._engine.await_event(saga_id=saga_id, event=event)
+
     async def run_due(self, *, limit: int = 100) -> int:
         """Resume due running, suspended, and compensating sagas."""
         return await self._engine.run_due(limit=limit)

{python_saga_orchestrator-0.1.0 → python_saga_orchestrator-0.1.2}/saga_orchestrator/domain/models/__init__.py

@@ -1,12 +1,23 @@
 """Domain models module."""
 
 from .builder import SagaDefinition
+from .notify import AwaitingEvent, NotifyEvent, NotifyResult
 from .retry import ExponentialRetry, FixedRetry, NoRetry, RetryPolicy
 from .saga_snapshot import SagaAdminSnapshot, SagaSnapshot
-from .step import BaseStep, InputContext, StepDefinition, StepInputMap, StepRef
+from .step import (
+    BaseStep,
+    InputContext,
+    OutboxMap,
+    StepDefinition,
+    StepInputMap,
+    StepRef,
+)
 
 __all__ = [
     "SagaDefinition",
+    "AwaitingEvent",
+    "NotifyEvent",
+    "NotifyResult",
     "RetryPolicy",
     "NoRetry",
     "FixedRetry",
@@ -15,6 +26,7 @@ __all__ = [
     "SagaSnapshot",
     "StepRef",
     "InputContext",
+    "OutboxMap",
     "StepInputMap",
     "StepDefinition",
     "BaseStep",

python_saga_orchestrator-0.1.2/saga_orchestrator/domain/models/notify.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class NotifyResult(str, Enum):
+    ACCEPTED = "ACCEPTED"
+    NOT_SUSPENDED = "NOT_SUSPENDED"
+    STALE_TOKEN = "STALE_TOKEN"
+    DUPLICATE = "DUPLICATE"
+    EVENT_TYPE_MISMATCH = "EVENT_TYPE_MISMATCH"
+    CORRELATION_MISMATCH = "CORRELATION_MISMATCH"
+    EXPIRED = "EXPIRED"
+
+
+class NotifyEvent(BaseModel):
+    event_id: str | None = None
+    event_type: str | None = None
+    correlation_id: str | None = None
+    payload: Any = None
+    source: str | None = None
+    occurred_at: datetime | None = None
+
+
+class AwaitingEvent(BaseModel):
+    event_type: str | None = None
+    correlation_id: str | None = None
+    until: datetime | None = None

{python_saga_orchestrator-0.1.0 → python_saga_orchestrator-0.1.2}/saga_orchestrator/domain/models/step.py

@@ -8,6 +8,7 @@ from typing import Any, Generic, TypeAlias, TypeVar, get_type_hints
 
 from pydantic import BaseModel
 
+from ...outbox.event import OutboxEvent
 from ..exceptions import TypeValidationError
 from .retry import RetryPolicy
 
@@ -33,6 +34,7 @@ class InputContext:
 
 RootInputMap: TypeAlias = Callable[[InputContext], InputModelT | dict[str, Any]]
 StepInputMap: TypeAlias = RootInputMap | Callable[[Any], InputModelT | dict[str, Any]]
+OutboxMap: TypeAlias = Callable[[InputModelT, OutputModelT], list[OutboxEvent] | None]
 
 
 @dataclass
@@ -43,6 +45,7 @@ class StepDefinition(Generic[InputModelT, OutputModelT]):
     timeout: timedelta | None
     retry_policy: RetryPolicy
     depends_on: StepRef[Any] | None = None
+    outbox_map: OutboxMap[InputModelT, OutputModelT] | None = None
 
     @property
     def input_model(self) -> type[InputModelT]:

python_saga_orchestrator-0.1.2/saga_orchestrator/outbox/__init__.py

@@ -0,0 +1,15 @@
+"""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

@@ -0,0 +1,95 @@
+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/event.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class OutboxEvent:
+    topic: str
+    payload: dict[str, Any]
+    key: str | None = None
+    headers: dict[str, Any] = field(default_factory=dict)

python_saga_orchestrator-0.1.2/saga_orchestrator/outbox/models.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from sqlalchemy import JSON, DateTime
+from sqlalchemy import Enum as SqlEnum
+from sqlalchemy import Integer, String, Text, func
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.ext.mutable import MutableDict
+from sqlalchemy.orm import Mapped, declarative_mixin, mapped_column
+
+
+def _json_type() -> JSON:
+    return JSON().with_variant(JSONB, "postgresql")
+
+
+class OutboxStatus(str, Enum):
+    PENDING = "PENDING"
+    DISPATCHING = "DISPATCHING"
+    SENT = "SENT"
+    FAILED = "FAILED"
+
+
+@declarative_mixin
+class OutboxMessageMixin:
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    saga_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), index=True)
+    aggregation_id: Mapped[str] = mapped_column(String(255), index=True)
+    step_id: Mapped[str] = mapped_column(String(255), index=True)
+    trace_id: Mapped[str] = mapped_column(String(255), index=True)
+    topic: Mapped[str] = mapped_column(String(255), nullable=False)
+    message_key: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    payload: Mapped[dict[str, Any]] = mapped_column(
+        MutableDict.as_mutable(_json_type()),
+        default=dict,
+    )
+    headers: Mapped[dict[str, Any]] = mapped_column(
+        MutableDict.as_mutable(_json_type()),
+        default=dict,
+    )
+    status: Mapped[OutboxStatus] = mapped_column(
+        SqlEnum(OutboxStatus),
+        default=OutboxStatus.PENDING,
+        index=True,
+    )
+    attempts: Mapped[int] = mapped_column(Integer, default=0)
+    next_attempt_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        index=True,
+    )
+    last_error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    sent_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )

python_saga_orchestrator-0.1.2/saga_orchestrator/outbox/repository.py

@@ -0,0 +1,73 @@
+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"