python-saga-orchestrator 0.1.3__py3-none-any.whl → 0.2.3.dev0__py3-none-any.whl

{python_saga_orchestrator-0.1.3.dist-info → python_saga_orchestrator-0.2.3.dev0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-saga-orchestrator
-Version: 0.1.3
+Version: 0.2.3.dev0
 Summary: Lightweight embedded saga orchestrator for asyncio Python services
 Author-email: Maxim Vasilyev <mayxis@inbox.ru>
 License-Expression: MIT
@@ -51,6 +51,7 @@ Unlike external workflow platforms, this library runs inside your service and st
 - persisted saga state through `SagaStateMixin`
 - runtime execution through `SagaOrchestrator` and `SagaEngine`
 - retry, timeout, recovery, and compensation
+- async queue-style steps through `StepAwaitEvent` and `notify(...)`
 - administrative operations through `SagaAdmin`
 - PostgreSQL-first reliability using `SELECT ... FOR UPDATE`
 
@@ -136,11 +137,13 @@ Your SQLAlchemy model inherits `SagaStateMixin` to store:
 ## Quick start
 
 ```python
+import uuid
 from datetime import timedelta
 
 from pydantic import BaseModel
+from sqlalchemy import ForeignKey
 from sqlalchemy.ext.asyncio import async_sessionmaker
-from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
 
 from saga_orchestrator import (
     BaseStep,
@@ -149,6 +152,7 @@ from saga_orchestrator import (
     SagaBuilder,
     SagaOrchestrator,
     SagaStateMixin,
+    SagaStepHistoryMixin,
 )
 
 
@@ -156,9 +160,24 @@ class Base(DeclarativeBase):
     pass
 
 
+class OrderSagaHistory(Base, SagaStepHistoryMixin):
+    __tablename__ = "order_saga_history"
+
+    saga_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("order_saga_state.id", ondelete="CASCADE"),
+        index=True,
+    )
+
+
 class OrderSagaState(Base, SagaStateMixin):
     __tablename__ = "order_saga_state"
 
+    step_history: Mapped[list[OrderSagaHistory]] = relationship(
+        "OrderSagaHistory",
+        cascade="all, delete-orphan",
+        order_by="OrderSagaHistory.id",
+    )
+
 
 class ReserveInput(BaseModel):
     order_id: str
@@ -211,15 +230,20 @@ def build_order_saga():
 
 
 def setup_saga(
-        session_maker: async_sessionmaker,
-) -> tuple[SagaOrchestrator[OrderSagaState], SagaAdmin[OrderSagaState]]:
-    orchestrator = SagaOrchestrator[OrderSagaState](
+    session_maker: async_sessionmaker,
+) -> tuple[
+    SagaOrchestrator[OrderSagaState, OrderSagaHistory], 
+    SagaAdmin[OrderSagaState, OrderSagaHistory]
+]:
+    orchestrator = SagaOrchestrator[OrderSagaState, OrderSagaHistory](
         model_class=OrderSagaState,
+        history_model_class=OrderSagaHistory,
         session_maker=session_maker,
     )
     orchestrator.register("create_order_v1", build_order_saga())
 
-    admin = SagaAdmin[OrderSagaState](engine=orchestrator.engine)
+    admin = SagaAdmin[OrderSagaState, OrderSagaHistory](engine=orchestrator.engine)
+    
     return orchestrator, admin
 ```
 
@@ -277,6 +301,23 @@ token = await orchestrator.await_event(
 
 The event payload is stored in saga context and can be used by root-step `input_map` functions through `InputContext`.
 
+For distributed consumers, use transactional inbox ingestion first, then process inbox rows:
+
+```python
+stored = await orchestrator.ingest_event(
+    aggregation_id="order-123",
+    event={
+        "event_id": "evt-123",
+        "event_type": "payment.completed",
+        "correlation_id": "corr-123",
+        "payload": {"payment_id": "pay-1"},
+    },
+)
+
+if stored:
+    await orchestrator.run_inbox_due(limit=100)
+```
+
 ## Administrative operations
 
 Get the full persisted state:
@@ -334,6 +375,7 @@ A runnable end-to-end example is available in:
 - [`examples/retry_recovery.py`](./examples/retry_recovery.py)
 - [`examples/compensation_flow.py`](./examples/compensation_flow.py)
 - [`examples/admin_skip.py`](./examples/admin_skip.py)
+- [`examples/http_and_queue.py`](./examples/http_and_queue.py)
 
 These examples demonstrate:
 - basic model deployment

python_saga_orchestrator-0.2.3.dev0.dist-info/RECORD

@@ -0,0 +1,47 @@
+python_saga_orchestrator-0.2.3.dev0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+saga_orchestrator/__init__.py,sha256=FG7zoYhCzpZC_JEsy3ebDraH2ZZ9q3IGIjTGKqBzcF4,2836
+saga_orchestrator/_version.py,sha256=b8lE-OZpo51B0ODVlQA6zcNoIpJ5YIH4JrzxWeFFTE0,533
+saga_orchestrator/admin/__init__.py,sha256=TKwKTM7IieI4nlMAbJ0O0OI0KPKfwbclVffNjRtIyAg,80
+saga_orchestrator/admin/api.py,sha256=u_eLELUlaHpEiuHqweNHzBwSYCtotERAiOxyVtUMe2I,1715
+saga_orchestrator/core/__init__.py,sha256=EsUqhbO_CgCYZz0yBnf6OUXH3N-_uxMod4A7yGzvbMY,264
+saga_orchestrator/core/builder.py,sha256=5G1kdA9UoMqZy7IT81YGz2FX1xkK9JPBhF9OMGqvrQs,5931
+saga_orchestrator/core/engine.py,sha256=ntloRjKod4zl9iQmt1zEOYBcm8KJPqP1FgDcPN33XPU,59879
+saga_orchestrator/core/orchestrator.py,sha256=5HvesuKh1STx4H2aSH8cQSlaFTmdQ_Y0aFBzuGN-6vw,6197
+saga_orchestrator/core/repository.py,sha256=TWBuhc0lLRpR6O2NvdyqhuD2RxgnLbG_JcKFxfc4yVA,5698
+saga_orchestrator/domain/__init__.py,sha256=ECVisQXiPSwx974Dbei_Ze_6SWqPVaQrTZPj_qESpYA,21
+saga_orchestrator/domain/exceptions/__init__.py,sha256=smKhoR_G-PLtqvDkxgzCzDE7zfoztpUoFc0x4prdX4U,334
+saga_orchestrator/domain/exceptions/saga.py,sha256=GeqxHJkHxobM8e8sVq69skP75_Sklo6mqFS9gFvTx4Y,567
+saga_orchestrator/domain/mixins/__init__.py,sha256=ibsuLmZf0g8zAnQWs2MpDOPA0b0poptpEhMDnmbAXsI,186
+saga_orchestrator/domain/mixins/saga_state.py,sha256=Gc7cozW0dHzKSJoP9-yTusof0H__INQ3BUxBO6Z72l0,2334
+saga_orchestrator/domain/mixins/saga_step_histrory.py,sha256=phB_oue8ksMMtDiNSERP3r_KGIQYMwH7Ahob0NbGD4A,1975
+saga_orchestrator/domain/mixins/types.py,sha256=FlKee4yNq6y1lXX3W_SeE385udNNg-oZqMxqVXZoEpo,2526
+saga_orchestrator/domain/models/__init__.py,sha256=vgUSmwVdPhKNijFZsfmZ7mQZD8DJgCV4s4hMVQZNlwE,853
+saga_orchestrator/domain/models/builder.py,sha256=D3mVYEJT7QJ0e2dNrR2UNHT5xhRK4te6s5WchU57EIA,816
+saga_orchestrator/domain/models/context.py,sha256=a0nNYTW0S73Qk5ln85Ji9_siEe38qlb9GPH8XpL0Gi8,3886
+saga_orchestrator/domain/models/notify.py,sha256=SuZILSFNAWcUQtjL-I_c4K6VFJXXhD5LLLC2KoMq8dw,837
+saga_orchestrator/domain/models/retry.py,sha256=UM2ZrSGKDZRiPMj0qOGp36xiTr78CVKsceXFFxtiOug,1362
+saga_orchestrator/domain/models/saga_snapshot.py,sha256=ysnBVB2rw059pC07Py_xzAA-Bv7d1h6ZZuubM_Fv0_4,867
+saga_orchestrator/domain/models/step.py,sha256=-4hWbH2xZpGSI-xFQYHI1SoucXe4Xyq5vQ3t0DH0rQ4,4854
+saga_orchestrator/domain/models/enums/__init__.py,sha256=IFgCFvhHiQl1MSCN_I_w3O8yR94tZvN5Az8M3V3bXEQ,234
+saga_orchestrator/domain/models/enums/saga_status.py,sha256=Evz7Uy4-KrqGWFkb6RHhONCWLePd5Gjezw5u-FLmxw0,397
+saga_orchestrator/domain/models/enums/saga_step_phase.py,sha256=L73jg8q-IdDXPpMjuMRwhfVZbAMYW_42FkdXNKqwiqI,129
+saga_orchestrator/domain/models/enums/saga_step_status.py,sha256=DZN5qgDorhdFbhI6t6WXAu4xMpj7DE53OJ707wqj4RM,125
+saga_orchestrator/inbox/__init__.py,sha256=uoLytCCT-2-zr369ZpGmQOB_D63fmwjV9T6sCHYGk64,656
+saga_orchestrator/inbox/contracts.py,sha256=unV7h1Eqil6sZhmpGVE_-9c_voRQhYA3KdE63T79s4U,1768
+saga_orchestrator/inbox/dispatcher.py,sha256=O4Zzi5fRAZIUQqlk3oJof6rl7_CPzvqSVQ_Un-1WkOY,4323
+saga_orchestrator/inbox/models.py,sha256=i6ANKTqDTanmpA2hp5V5pky06u5DoHfo2oCWCsTVQUI,2654
+saga_orchestrator/inbox/repository.py,sha256=BdcVlBW9zvM7WrsL2S3Rmihmn-Ri6gr69L8ji7qqip8,5286
+saga_orchestrator/inbox/retry.py,sha256=jTxg6tZBl7Vllt89Yw-QdOSObYWXrZWjAyW36mCJHdg,590
+saga_orchestrator/outbox/__init__.py,sha256=g-isr2D737wMV1Mf_vEPFoS34YE6n6l09iKLLAL86uU,917
+saga_orchestrator/outbox/contracts.py,sha256=KhqIDIDvwA26xu4VQJpU6qg2ySmsRAORestIk1JqpiY,2028
+saga_orchestrator/outbox/dispatcher.py,sha256=BX9WTuTLx1gfu-5jV8_ejpi9nnEilnKLYY_BljJkxC8,3196
+saga_orchestrator/outbox/event.py,sha256=Kj-u_JO55jx3YMTpA9arIvmTgKEAxhH2-WQE1eTi4KU,273
+saga_orchestrator/outbox/factory.py,sha256=_p7XT_ulouBhl9J9fcgWsZkhkjmzkpfIs9m6E55UPdA,1743
+saga_orchestrator/outbox/models.py,sha256=ei8Q1b9NnjAWq5qm0vAIeuj22yWVOFx0UsqGszZA0Q0,2355
+saga_orchestrator/outbox/repository.py,sha256=A3nCi5UOwQT9mlEY03BrLidyO2sFOQGgYcE4pFeY-pA,4786
+saga_orchestrator/outbox/retry.py,sha256=9Ygz3I0HK0r9imTYevBgz14TkAZphKiOSf0grJpH99c,599
+saga_orchestrator/outbox/serialization.py,sha256=CDicJS95CHhLP47XukJAgfm0baZ83daWXQQF3MyczDo,1687
+python_saga_orchestrator-0.2.3.dev0.dist-info/METADATA,sha256=TKDQ42mOx7sTrACtJtxs60bcDE0AhWQNH8JZz-6c7Lo,10293
+python_saga_orchestrator-0.2.3.dev0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_saga_orchestrator-0.2.3.dev0.dist-info/top_level.txt,sha256=XBp_2J8dacJGCoVxIDaUYhSEuOusCN3BD_uhEjBEEBA,18
+python_saga_orchestrator-0.2.3.dev0.dist-info/RECORD,,

saga_orchestrator/__init__.py

@@ -9,7 +9,7 @@ from .domain.exceptions import (
     SagaStateError,
     TypeValidationError,
 )
-from .domain.mixins import SagaStateMixin
+from .domain.mixins import SagaStateMixin, SagaStepHistoryMixin
 from .domain.models import (
     AwaitingEvent,
     BaseStep,
@@ -24,11 +24,26 @@ from .domain.models import (
     SagaAdminSnapshot,
     SagaDefinition,
     SagaSnapshot,
+    StepAwaitEvent,
     StepDefinition,
     StepInputMap,
     StepRef,
 )
-from .domain.models.enums import SagaStatus
+from .domain.models.enums import SagaStatus, SagaStepPhase, SagaStepStatus
+from .inbox import (
+    ClaimedInboxMessage,
+    FixedInboxRetry,
+    InboxDispatcher,
+    InboxMessageMixin,
+    InboxProcessor,
+    InboxProcessOutcome,
+    InboxProcessStatus,
+    InboxRepository,
+    InboxRetryPolicy,
+    InboxStatus,
+    InboxWriteMessage,
+    InboxWriter,
+)
 from .outbox import (
     ClaimedOutboxMessage,
     DefaultOutboxMessageFactory,
@@ -51,11 +66,23 @@ __all__ = [
     "ActiveSagaAlreadyExistsError",
     "AwaitingEvent",
     "BaseStep",
+    "ClaimedInboxMessage",
     "ClaimedOutboxMessage",
     "DefaultOutboxMessageFactory",
     "ExponentialRetry",
+    "FixedInboxRetry",
     "FixedOutboxDispatchRetry",
     "FixedRetry",
+    "InboxDispatcher",
+    "InboxMessageMixin",
+    "InboxProcessOutcome",
+    "InboxProcessStatus",
+    "InboxProcessor",
+    "InboxRepository",
+    "InboxRetryPolicy",
+    "InboxStatus",
+    "InboxWriteMessage",
+    "InboxWriter",
     "InputContext",
     "JsonOutboxSerializer",
     "NotifyEvent",
@@ -85,9 +112,13 @@ __all__ = [
     "SagaRepository",
     "SagaSnapshot",
     "SagaStateError",
+    "SagaStepHistoryMixin",
     "SagaStateMixin",
     "SagaStatus",
+    "SagaStepStatus",
+    "SagaStepPhase",
     "StepDefinition",
+    "StepAwaitEvent",
     "StepInputMap",
     "StepRef",
     "TypeValidationError",

saga_orchestrator/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.3.dev0'
+__version_tuple__ = version_tuple = (0, 2, 3, 'dev0')
+
+__commit_id__ = commit_id = None

saga_orchestrator/admin/api.py

@@ -7,17 +7,19 @@ from pydantic import BaseModel
 
 from ..core.engine import SagaEngine
 from ..domain.mixins import SagaStateMixin
+from ..domain.mixins.saga_step_histrory import SagaStepHistoryMixin
 from ..domain.models import SagaAdminSnapshot
 
 ModelT = TypeVar("ModelT", bound=SagaStateMixin)
+HistoryModelT = TypeVar("HistoryModelT", bound=SagaStepHistoryMixin)
 
 
-class SagaAdmin(Generic[ModelT]):
+class SagaAdmin(Generic[ModelT, HistoryModelT]):
     """Provide administrative operations for persisted saga instances."""
 
     def __init__(
         self,
-        engine: SagaEngine[ModelT],
+        engine: SagaEngine[ModelT, HistoryModelT],
     ) -> None:
         """Initialize the admin API facade."""
         self._engine = engine

saga_orchestrator/core/builder.py

@@ -11,6 +11,9 @@ from ..domain.models import (
     BaseStep,
     InputContext,
     NoRetry,
+    OnFailedMap,
+    OnStartMap,
+    OnTerminalStateMap,
     OutboxMap,
     RetryPolicy,
     SagaDefinition,
@@ -28,6 +31,11 @@ class SagaBuilder:
         self._steps: list[StepDefinition[Any, Any]] = []
         self._compensate_on_failure = compensate_on_failure
 
+        self._on_start_map: OnStartMap | None = None
+        self._on_completed_map: OnTerminalStateMap | None = None
+        self._on_failed_map: OnFailedMap | None = None
+        self._on_compensated_map: OnTerminalStateMap | None = None
+
     def add_step(
         self,
         *,
@@ -62,6 +70,34 @@ class SagaBuilder:
         self._steps.append(definition)
         return StepRef(step_id=normalized_step_id, output_model=step.output_model)
 
+    def on_start(self, on_start_map: OnStartMap) -> SagaBuilder:
+        """Define actions to be taken when the saga starts."""
+        if not callable(on_start_map):
+            raise SagaDefinitionError("on_start_map must be callable")
+        self._on_start_map = on_start_map
+        return self
+
+    def on_completed(self, on_completed_map: OnTerminalStateMap) -> SagaBuilder:
+        """Define actions to be taken when the saga completes successfully."""
+        if not callable(on_completed_map):
+            raise SagaDefinitionError("on_completed_map must be callable")
+        self._on_completed_map = on_completed_map
+        return self
+
+    def on_failed(self, on_failed_map: OnFailedMap) -> SagaBuilder:
+        """Define actions to be taken when the saga fails."""
+        if not callable(on_failed_map):
+            raise SagaDefinitionError("on_failed_map must be callable")
+        self._on_failed_map = on_failed_map
+        return self
+
+    def on_compensated(self, on_compensated_map: OnTerminalStateMap) -> SagaBuilder:
+        """Define actions to be taken when the saga is fully compensated."""
+        if not callable(on_compensated_map):
+            raise SagaDefinitionError("on_compensated_map must be callable")
+        self._on_compensated_map = on_compensated_map
+        return self
+
     def build(self) -> SagaDefinition:
         """Return the final saga definition."""
         if not self._steps:
@@ -69,6 +105,10 @@ class SagaBuilder:
         return SagaDefinition(
             steps=tuple(self._steps),
             compensate_on_failure=self._compensate_on_failure,
+            on_start_map=self._on_start_map,
+            on_completed_map=self._on_completed_map,
+            on_failed_map=self._on_failed_map,
+            on_compensated_map=self._on_compensated_map,
         )
 
     @staticmethod