python-saga-orchestrator 0.1.0__py3-none-any.whl

python_saga_orchestrator-0.1.0.dist-info/METADATA

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: python-saga-orchestrator
+Version: 0.1.0
+Summary: Lightweight embedded saga orchestrator for asyncio Python services
+Author-email: Maxim Vasilyev <mayxis@inbox.ru>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mdvasilyev/python-saga-orchestrator
+Project-URL: Issues, https://github.com/mdvasilyev/python-saga-orchestrator/issues
+Keywords: saga,orchestration,asyncio,sqlalchemy,distributed-transactions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: greenlet>=3.3.2
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: sqlalchemy>=2.0.48
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: pytest>=8.3.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
+Requires-Dist: ruff>=0.12.0; extra == "dev"
+Requires-Dist: twine>=6.1.0; extra == "dev"
+Dynamic: license-file
+
+# python-saga-orchestrator
+
+Lightweight embedded saga orchestration for `asyncio` Python services.
+
+The library implements the Saga pattern for long-running business processes that:
+- span multiple steps,
+- call external systems,
+- need retry and compensation,
+- must survive worker crashes and process restarts.
+
+Unlike external workflow platforms, this library runs inside your service and stores saga state in your application's database through SQLAlchemy.
+
+## What it provides
+
+- typed step definitions with `Pydantic` models
+- saga construction with `SagaBuilder` and `StepRef`
+- persisted saga state through `SagaStateMixin`
+- runtime execution through `SagaOrchestrator` and `SagaEngine`
+- retry, timeout, recovery, and compensation
+- administrative operations through `SagaAdmin`
+- PostgreSQL-first reliability using `SELECT ... FOR UPDATE`
+
+## Installation
+
+Requirements:
+- Python 3.12+
+- PostgreSQL for production-grade execution semantics
+
+Install from source:
+
+```bash
+pip install .
+```
+
+Or install development dependencies:
+
+```bash
+pip install .[dev]
+```
+
+## Core concepts
+
+### `BaseStep`
+
+Each saga step is a class with:
+- `execute(inp) -> out`
+- optional `compensate(inp, out) -> None`
+
+Steps are regular Python objects. In practice they are created once at application startup and reused.
+
+### `SagaBuilder`
+
+`SagaBuilder` creates an immutable `SagaDefinition`.  
+Each added step includes:
+- the step object
+- `input_map`
+- optional timeout
+- retry policy
+- optional dependency on a previous step via `StepRef`
+
+### `SagaStateMixin`
+
+Your SQLAlchemy model inherits `SagaStateMixin` to store:
+- current status
+- current step index
+- execution token
+- context
+- step history
+- deadline
+- retry counter
+
+### `SagaOrchestrator`
+
+`SagaOrchestrator` is the public runtime API used by application code:
+- `register(...)`
+- `start(...)`
+- `notify(...)`
+- `run_due(...)`
+- `get_snapshot(...)`
+
+### `SagaAdmin`
+
+`SagaAdmin` exposes operational controls:
+- `get_saga(...)`
+- `retry_step(...)`
+- `skip_step(...)`
+- `compensate_step(...)`
+- `abort(...)`
+
+## Quick start
+
+```python
+from datetime import timedelta
+
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase
+
+from saga_orchestrator import (
+    BaseStep,
+    ExponentialRetry,
+    SagaAdmin,
+    SagaBuilder,
+    SagaOrchestrator,
+    SagaStateMixin,
+)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class OrderSagaState(Base, SagaStateMixin):
+    __tablename__ = "order_saga_state"
+
+
+class ReserveInput(BaseModel):
+    order_id: str
+
+
+class ReserveOutput(BaseModel):
+    reservation_id: str
+
+
+class ChargeInput(BaseModel):
+    reservation_id: str
+
+
+class ChargeOutput(BaseModel):
+    payment_id: str
+
+
+class ReserveInventoryStep(BaseStep[ReserveInput, ReserveOutput]):
+    async def execute(self, inp: ReserveInput) -> ReserveOutput:
+        return ReserveOutput(reservation_id=f"res-{inp.order_id}")
+
+    async def compensate(self, inp: ReserveInput, out: ReserveOutput) -> None:
+        return None
+
+
+class ChargePaymentStep(BaseStep[ChargeInput, ChargeOutput]):
+    async def execute(self, inp: ChargeInput) -> ChargeOutput:
+        return ChargeOutput(payment_id=f"pay-{inp.reservation_id}")
+
+
+def build_order_saga():
+    builder = SagaBuilder()
+
+    reserve_ref = builder.add_step(
+        step=ReserveInventoryStep(),
+        input_map=lambda ctx: ReserveInput(order_id=ctx.initial_data["order_id"]),
+    )
+
+    builder.add_step(
+        step=ChargePaymentStep(),
+        depends_on=reserve_ref,
+        input_map=lambda out: ChargeInput(reservation_id=out.reservation_id),
+        retry_policy=ExponentialRetry(
+            max_attempts=3,
+            base_delay=timedelta(seconds=5),
+        ),
+    )
+
+    return builder.build()
+
+
+def setup_saga(
+        session_maker: async_sessionmaker,
+) -> tuple[SagaOrchestrator[OrderSagaState], SagaAdmin[OrderSagaState]]:
+    orchestrator = SagaOrchestrator[OrderSagaState](
+        model_class=OrderSagaState,
+        session_maker=session_maker,
+    )
+    orchestrator.register("create_order_v1", build_order_saga())
+
+    admin = SagaAdmin[OrderSagaState](engine=orchestrator.engine)
+    return orchestrator, admin
+```
+
+Start a saga:
+
+```python
+orchestrator, admin = setup_saga(session_maker)
+
+saga_id = await orchestrator.start(
+    saga_name="create_order_v1",
+    initial_data={"order_id": "order-123"},
+    aggregation_id="order-123",
+)
+```
+
+## Recovery model
+
+The library persists enough state to recover work after failures:
+
+- `RUNNING` sagas with expired execution leases can be reclaimed
+- `SUSPENDED` sagas with expired retry deadlines can be resumed
+- `COMPENSATING` sagas can continue rollback after a crash
+
+The recovery entry point is:
+
+```python
+await orchestrator.run_due(limit=100)
+```
+
+In production this should be called by a background worker or scheduled job.
+
+## Notifications and external events
+
+Use `notify(...)` when a suspended saga should resume because of an external signal:
+
+```python
+accepted = await orchestrator.notify(
+    saga_id=saga_id,
+    token=current_token,
+    event={"approved": True},
+)
+```
+
+The event payload is stored in saga context and can be used by root-step `input_map` functions through `InputContext`.
+
+## Administrative operations
+
+Get the full persisted state:
+
+```python
+snapshot = await admin.get_saga(saga_id)
+print(snapshot.status)
+print(snapshot.step_history)
+```
+
+Retry the current failed step:
+
+```python
+await admin.retry_step(saga_id)
+```
+
+Skip the current suspended step:
+
+```python
+await admin.skip_step(
+    saga_id,
+    mock_output={"payment_id": "manual-payment"},
+)
+```
+
+Start compensation manually:
+
+```python
+await admin.compensate_step(saga_id)
+```
+
+Abort the saga:
+
+```python
+await admin.abort(saga_id)
+```
+
+## Persistence expectations
+
+The library is PostgreSQL-first.
+
+Important implementation details:
+- state transitions are performed inside database transactions
+- mutating reads use `SELECT ... FOR UPDATE`
+- JSON state is stored in `context` and `step_history`
+- `step_execution_token` is used to reject stale events and stale step completions
+
+SQLite may be sufficient for local experiments, but PostgreSQL should be used for integration testing and production use.
+
+## Example workflow
+
+A runnable end-to-end example is available in:
+
+- [`test.py`](./test.py)
+
+It demonstrates:
+- retry and recovery through `run_due()`
+- compensation after failure
+- admin-driven step skipping
+
+## Running tests
+
+Run unit tests:
+
+```bash
+pytest -q tests/unit
+```
+
+Run PostgreSQL integration tests:
+
+```bash
+export TEST_DATABASE_URL='postgresql+asyncpg://postgres:postgres@localhost:5432/saga_test_db'
+pytest -q tests/integration
+```
+
+The integration fixture creates an isolated schema per test, so it does not require a dedicated empty database schema.
+
+## Current limitations
+
+- the implementation is optimized for sequential saga execution, not parallel DAG execution
+- PostgreSQL is the intended reliability target
+- tracing integration is not implemented yet
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

python_saga_orchestrator-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+python_saga_orchestrator-0.1.0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+saga_orchestrator/__init__.py,sha256=MCVa52nGc4FZn7RcZ3zaJ5nIFmc1WfHJjb2jnb7piXI,1227
+saga_orchestrator/admin/__init__.py,sha256=TKwKTM7IieI4nlMAbJ0O0OI0KPKfwbclVffNjRtIyAg,80
+saga_orchestrator/admin/api.py,sha256=zrgNXTBql-1LNz-5JHF64J0vH9xAm6Zv_37KAuC6DO4,1548
+saga_orchestrator/core/__init__.py,sha256=EsUqhbO_CgCYZz0yBnf6OUXH3N-_uxMod4A7yGzvbMY,264
+saga_orchestrator/core/builder.py,sha256=6cEydT1P4TRyIdlie8LTslkeGBwGVeT60cNHqFQk_CQ,3877
+saga_orchestrator/core/engine.py,sha256=JM0jROTVzumjiv01QklapjwSA3ATMpbO00j10sNYzR8,30565
+saga_orchestrator/core/orchestrator.py,sha256=vHzrQvWQ-UwBReveeZ2Ju3H8Gqr2m5nV08XDEQQ96xQ,2729
+saga_orchestrator/core/repository.py,sha256=5a8zZ721dvxI17aqU1hzUTE7tekP_m-6415N9koFGgU,5452
+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=enWzXVKf7BP-sHCuqaOL0zPcmW2CSbKeNUblzECQTx0,105
+saga_orchestrator/domain/mixins/saga_state.py,sha256=AhsA2eRZtAHx16xLNVZp0SXrHIiS--S2U2NAyV6VsrM,1941
+saga_orchestrator/domain/models/__init__.py,sha256=7GGAP7GiC86L1JxyLgyiM7Op3UGLYuKAVbid4HsAerw,525
+saga_orchestrator/domain/models/builder.py,sha256=vUzTTlI-wojTQJh6L2s-r6RyuHuixKYciwM2RieyRqg,262
+saga_orchestrator/domain/models/retry.py,sha256=UM2ZrSGKDZRiPMj0qOGp36xiTr78CVKsceXFFxtiOug,1362
+saga_orchestrator/domain/models/saga_snapshot.py,sha256=4tmgwY1ezAG4Mh6vEVMGAx7f4NbIL71rWIK7dMZjifg,794
+saga_orchestrator/domain/models/step.py,sha256=dRHbvegKGiqRcBY6TpqTnmsTzQArewvZrpedfcGuswU,2752
+saga_orchestrator/domain/models/enums/__init__.py,sha256=tdTz69vzPJDX06TJA03gm2Zk0M96rXGEbY21IPQzJOM,103
+saga_orchestrator/domain/models/enums/saga_status.py,sha256=aSp6mdzaZALxxp1p-NgPD2b8bg2dhEf016iDdjp_Vzw,292
+python_saga_orchestrator-0.1.0.dist-info/METADATA,sha256=1imgMFBbeb1zlxu3CWiOgCK_suEOOGSGHcUQMcsfcHQ,8449
+python_saga_orchestrator-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_saga_orchestrator-0.1.0.dist-info/top_level.txt,sha256=XBp_2J8dacJGCoVxIDaUYhSEuOusCN3BD_uhEjBEEBA,18
+python_saga_orchestrator-0.1.0.dist-info/RECORD,,

python_saga_orchestrator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_saga_orchestrator-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_saga_orchestrator-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+saga_orchestrator

saga_orchestrator/__init__.py

@@ -0,0 +1,57 @@
+"""Public package API for the saga orchestrator library."""
+
+from .admin import SagaAdmin
+from .core import SagaBuilder, SagaEngine, SagaOrchestrator, SagaRepository
+from .domain.exceptions import (
+    ActiveSagaAlreadyExistsError,
+    SagaDefinitionError,
+    SagaNotFoundError,
+    SagaStateError,
+    TypeValidationError,
+)
+from .domain.mixins import SagaStateMixin
+from .domain.models import (
+    BaseStep,
+    ExponentialRetry,
+    FixedRetry,
+    InputContext,
+    NoRetry,
+    RetryPolicy,
+    SagaAdminSnapshot,
+    SagaDefinition,
+    SagaSnapshot,
+    StepDefinition,
+    StepInputMap,
+    StepRef,
+)
+from .domain.models.enums import SagaStatus
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ActiveSagaAlreadyExistsError",
+    "BaseStep",
+    "ExponentialRetry",
+    "FixedRetry",
+    "InputContext",
+    "NoRetry",
+    "RetryPolicy",
+    "SagaAdmin",
+    "SagaAdminSnapshot",
+    "SagaBuilder",
+    "SagaDefinition",
+    "SagaDefinitionError",
+    "SagaEngine",
+    "SagaNotFoundError",
+    "SagaOrchestrator",
+    "SagaRepository",
+    "SagaSnapshot",
+    "SagaStateError",
+    "SagaStateMixin",
+    "SagaStatus",
+    "StepDefinition",
+    "StepInputMap",
+    "StepRef",
+    "TypeValidationError",
+    "__version__",
+]

saga_orchestrator/admin/__init__.py

@@ -0,0 +1,7 @@
+"""Admin module."""
+
+from .api import SagaAdmin
+
+__all__ = [
+    "SagaAdmin",
+]

saga_orchestrator/admin/api.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from ..core.engine import SagaEngine
+from ..domain.mixins import SagaStateMixin
+from ..domain.models import SagaAdminSnapshot
+
+ModelT = TypeVar("ModelT", bound=SagaStateMixin)
+
+
+class SagaAdmin(Generic[ModelT]):
+    """Provide administrative operations for persisted saga instances."""
+
+    def __init__(
+        self,
+        engine: SagaEngine[ModelT],
+    ) -> None:
+        """Initialize the admin API facade."""
+        self._engine = engine
+
+    async def get_saga(self, saga_id: UUID) -> SagaAdminSnapshot:
+        """Return the current persisted state of one saga."""
+        return await self._engine.get_admin_snapshot(saga_id)
+
+    async def retry_step(self, saga_id: UUID) -> None:
+        """Retry the current failed step of a saga."""
+        await self._engine.retry_step(saga_id)
+
+    async def skip_step(
+        self,
+        saga_id: UUID,
+        mock_output: BaseModel | dict[str, Any] | None = None,
+    ) -> None:
+        """Skip the current suspended step using a provided output value."""
+        await self._engine.skip_step(saga_id, mock_output)
+
+    async def compensate_step(self, saga_id: UUID) -> None:
+        """Start or resume compensation for one saga."""
+        await self._engine.compensate_step(saga_id)
+
+    async def abort(self, saga_id: UUID) -> None:
+        """Mark a saga as failed and invalidate its current execution token."""
+        await self._engine.abort(saga_id)

saga_orchestrator/core/__init__.py

@@ -0,0 +1,13 @@
+"""Core module."""
+
+from .builder import SagaBuilder
+from .engine import SagaEngine
+from .orchestrator import SagaOrchestrator
+from .repository import SagaRepository
+
+__all__ = [
+    "SagaBuilder",
+    "SagaEngine",
+    "SagaOrchestrator",
+    "SagaRepository",
+]

saga_orchestrator/core/builder.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import inspect
+from datetime import timedelta
+from typing import Any, Callable, get_type_hints
+
+from pydantic import BaseModel
+
+from ..domain.exceptions import SagaDefinitionError, TypeValidationError
+from ..domain.models import (
+    BaseStep,
+    InputContext,
+    NoRetry,
+    RetryPolicy,
+    SagaDefinition,
+    StepDefinition,
+    StepInputMap,
+    StepRef,
+)
+
+
+class SagaBuilder:
+    """Build a saga definition from ordered step definitions."""
+
+    def __init__(self, *, compensate_on_failure: bool = True) -> None:
+        """Initialize the builder configuration."""
+        self._steps: list[StepDefinition[Any, Any]] = []
+        self._compensate_on_failure = compensate_on_failure
+
+    def add_step(
+        self,
+        *,
+        step: BaseStep[Any, Any],
+        input_map: StepInputMap[Any],
+        timeout: timedelta | None = None,
+        retry_policy: RetryPolicy | None = None,
+        depends_on: StepRef[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")
+        self.validate_input_map_types(input_map, step.input_model, depends_on)
+
+        normalized_step_id = step_id or f"step_{len(self._steps)}"
+        if any(existing.step_id == normalized_step_id for existing in self._steps):
+            raise SagaDefinitionError(f"Duplicate step id: {normalized_step_id}")
+
+        definition = StepDefinition(
+            step_id=normalized_step_id,
+            step=step,
+            input_map=input_map,
+            timeout=timeout,
+            retry_policy=retry_policy or NoRetry(),
+            depends_on=depends_on,
+        )
+        self._steps.append(definition)
+        return StepRef(step_id=normalized_step_id, output_model=step.output_model)
+
+    def build(self) -> SagaDefinition:
+        """Return the final saga definition."""
+        if not self._steps:
+            raise SagaDefinitionError("Saga must contain at least one step")
+        return SagaDefinition(
+            steps=tuple(self._steps),
+            compensate_on_failure=self._compensate_on_failure,
+        )
+
+    @staticmethod
+    def validate_input_map_types(
+        input_map: Callable[[Any], Any],
+        expected_input_model: type[BaseModel],
+        depends_on: StepRef[Any] | None,
+    ) -> None:
+        """Validate the input and return type annotations of ``input_map``."""
+        hints = get_type_hints(input_map)
+        params = list(inspect.signature(input_map).parameters.values())
+
+        if depends_on is not None and params:
+            dep_param_name = params[0].name
+            dep_type = hints.get(dep_param_name)
+            if dep_type is not None and dep_type is not depends_on.output_model:
+                raise TypeValidationError(
+                    "input_map first arg is "
+                    f"'{dep_type}', expected '{depends_on.output_model.__name__}'"
+                )
+        elif depends_on is None and params:
+            context_param_name = params[0].name
+            context_type = hints.get(context_param_name)
+            if context_type is not None and context_type is not InputContext:
+                raise TypeValidationError(
+                    "input_map first arg is "
+                    f"'{context_type}', expected '{InputContext.__name__}'"
+                )
+
+        return_type = hints.get("return")
+        if return_type is None:
+            return
+        if return_type is expected_input_model:
+            return
+        if return_type is dict or return_type is dict[str, Any]:
+            return
+        raise TypeValidationError(
+            "input_map return type "
+            f"'{return_type}' is incompatible with '{expected_input_model.__name__}'"
+        )