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

{python_saga_orchestrator-0.1.1/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.1
+Version: 0.1.3
 Summary: Lightweight embedded saga orchestrator for asyncio Python services
 Author-email: Maxim Vasilyev <mayxis@inbox.ru>
 License-Expression: MIT
@@ -263,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

{python_saga_orchestrator-0.1.1 → python_saga_orchestrator-0.1.3}/README.md

@@ -229,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

{python_saga_orchestrator-0.1.1 → 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.1"
+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.1 → 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.1
+Version: 0.1.3
 Summary: Lightweight embedded saga orchestrator for asyncio Python services
 Author-email: Maxim Vasilyev <mayxis@inbox.ru>
 License-Expression: MIT
@@ -263,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

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

@@ -21,8 +21,18 @@ 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/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/retry.py
+saga_orchestrator/outbox/serialization.py

{python_saga_orchestrator-0.1.1 → python_saga_orchestrator-0.1.3}/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,14 +29,50 @@ from .domain.models import (
     StepRef,
 )
 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.1 → python_saga_orchestrator-0.1.3}/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.1 → python_saga_orchestrator-0.1.3}/saga_orchestrator/core/engine.py

@@ -13,13 +13,21 @@ 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.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)
@@ -33,6 +41,10 @@ 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."""
@@ -40,6 +52,20 @@ class SagaEngine(Generic[ModelT]):
         self._session_maker = session_maker
         self._execution_lease = execution_lease
         self._repository = SagaRepository(model_class)
+        self._outbox_repository: OutboxRepository[OutboxMessageMixin] | None = 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
@@ -47,6 +73,16 @@ 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
+
+    @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:
@@ -102,21 +138,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 +251,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 +610,31 @@ 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_writer is None:
+                            raise SagaStateError(
+                                "outbox_map is configured for step "
+                                f"'{step_def.step_id}', but outbox writer is not configured in SagaEngine"
+                            )
+                        outbox_events = (
+                            step_def.outbox_map(step_input, step_output) or []
+                        )
+                        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",
@@ -697,6 +888,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.1 → python_saga_orchestrator-0.1.3}/saga_orchestrator/core/orchestrator.py

@@ -8,7 +8,18 @@ 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.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
 
@@ -23,12 +34,20 @@ 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."""
         self._engine = SagaEngine(
             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,
         )
 
@@ -42,6 +61,16 @@ 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
+
+    @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)
@@ -63,11 +92,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.1 → python_saga_orchestrator-0.1.3}/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",