python-saga-orchestrator 0.3.0__tar.gz → 0.5.0__tar.gz

{python_saga_orchestrator-0.3.0 → python_saga_orchestrator-0.5.0}/PKG-INFO

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

{python_saga_orchestrator-0.3.0 → python_saga_orchestrator-0.5.0}/python_saga_orchestrator.egg-info/PKG-INFO

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

{python_saga_orchestrator-0.3.0 → python_saga_orchestrator-0.5.0}/saga_orchestrator/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.0'
-__version_tuple__ = version_tuple = (0, 3, 0)
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
 
 __commit_id__ = commit_id = None

{python_saga_orchestrator-0.3.0 → python_saga_orchestrator-0.5.0}/saga_orchestrator/core/engine.py

@@ -444,43 +444,91 @@ class SagaEngine(Generic[ModelT, HistoryModelT]):
 
         async with self._session_maker() as session:
             async with session.begin():
-                due_running = await self._repository.due_running(
+                sagas_running = await self._repository.due_running(
                     session, now=now, limit=limit
                 )
-                remaining = max(limit - len(due_running), 0)
-                due_suspended = await self._repository.due_suspended(
-                    session, now=now, limit=remaining
+                limit = max(0, limit - len(sagas_running))
+
+                sagas_suspended = await self._repository.due_suspended(
+                    session, now=now, limit=limit
                 )
-                remaining -= len(due_suspended)
-                due_compensating = await self._repository.due_compensating(
-                    session, now=now, limit=remaining
+                limit = max(0, limit - len(sagas_suspended))
+
+                sagas_compensating = await self._repository.due_compensating(
+                    session, now=now, limit=limit
                 )
-                remaining -= len(due_compensating)
+                limit = max(0, limit - len(sagas_compensating))
 
-                due_compensating_suspended = (
+                sagas_comp_suspended = (
                     await self._repository.due_compensating_suspended(
-                        session, now=now, limit=max(remaining, 0)
+                        session, now=now, limit=limit
                     )
                 )
 
-                for saga in [*due_running, *due_suspended]:
-                    saga.status = SagaStatus.RUNNING
-                    saga.step_execution_token = uuid.uuid4()
-                    saga.deadline_at = now + self._execution_lease
+                for saga in sagas_running:
+                    self._prepare_saga_for_resume(saga, SagaStatus.RUNNING, now)
                     ready_ids.append(saga.id)
 
-                for saga in [*due_compensating, *due_compensating_suspended]:
-                    saga.status = SagaStatus.COMPENSATING
-                    saga.step_execution_token = uuid.uuid4()
-                    saga.deadline_at = now + self._execution_lease
+                for saga in sagas_suspended:
+                    if self._is_waiting_for_events(saga):
+                        self._handle_saga_timeout(saga, now)
+                    else:
+                        self._prepare_saga_for_resume(saga, SagaStatus.RUNNING, now)
+                        ready_ids.append(saga.id)
+
+                for saga in [*sagas_compensating, *sagas_comp_suspended]:
+                    self._prepare_saga_for_resume(saga, SagaStatus.COMPENSATING, now)
                     compensation_ids.append(saga.id)
 
         for saga_id in ready_ids:
             await self._drive(saga_id)
         for saga_id in compensation_ids:
             await self._run_compensation(saga_id)
+
         return len(ready_ids) + len(compensation_ids)
 
+    def _prepare_saga_for_resume(
+        self, saga, status: "SagaStatus", now: datetime
+    ) -> None:
+        """Устанавливает общие поля для продолжения работы саги."""
+        saga.status = status
+        saga.step_execution_token = uuid.uuid4()
+        saga.deadline_at = now + self._execution_lease
+
+    def _is_waiting_for_events(self, saga) -> bool:
+        """Проверяет, ожидает ли сага внешних событий."""
+        context = saga.context
+        return bool(context.awaiting_event_type or context.awaiting_event_types)
+
+    def _handle_saga_timeout(self, saga, now: datetime) -> None:
+        """логика обработки таймаута ожидания событий."""
+        context = saga.context
+        event_types = context.awaiting_event_types or context.awaiting_event_type
+
+        saga.status = SagaStatus.TIMEOUT
+        saga.last_error = f"Timed out waiting for event(s): {event_types}"
+        saga.deadline_at = None
+        saga.step_execution_token = uuid.uuid4()
+
+        definition = self._registry[context.saga_name]
+        step_def = definition.steps[saga.current_step_index]
+
+        saga.step_history.append(
+            self._history_model_class(
+                timestamp=now,
+                phase=SagaStepPhase.EXECUTE,
+                status=SagaStepStatus.TIMEOUT,
+                step_id=step_def.step_id,
+                step_name=type(step_def.step).__name__,
+                attempt=saga.retry_counter + 1,
+                token=saga.step_execution_token,
+                input={"_system": "timeout"},
+                output=None,
+                error=saga.last_error,
+                skipped=False,
+            )
+        )
+
     async def get_snapshot(self, saga_id: UUID) -> SagaSnapshot:
         """Return the snapshot view of one saga."""
         async with self._session_maker() as session:
@@ -533,7 +581,11 @@ class SagaEngine(Generic[ModelT, HistoryModelT]):
         async with self._session_maker() as session:
             async with session.begin():
                 saga = await self._repository.get_for_update(session, saga_id)
-                if saga.status not in {SagaStatus.SUSPENDED, SagaStatus.FAILED}:
+                if saga.status not in {
+                    SagaStatus.SUSPENDED,
+                    SagaStatus.FAILED,
+                    SagaStatus.TIMEOUT,
+                }:
                     raise SagaStateError(
                         f"Cannot retry step when saga status is {saga.status}"
                     )
@@ -595,9 +647,37 @@ class SagaEngine(Generic[ModelT, HistoryModelT]):
         async with self._session_maker() as session:
             async with session.begin():
                 saga = await self._repository.get_for_update(session, saga_id)
+                error_message = saga.last_error or "Aborted by admin"
+
+                try:
+                    saga_name = saga.context.saga_name
+                    definition = self._registry[saga_name]
+                    step_def = definition.steps[saga.current_step_index]
+                    step_id = step_def.step_id
+                    step_name = type(step_def.step).__name__
+                except (KeyError, IndexError):
+                    step_id = "__unknown__"
+                    step_name = "Unknown"
+
+                saga.step_history.append(
+                    self._history_model_class(
+                        timestamp=datetime.now(UTC),
+                        phase=SagaStepPhase.EXECUTE,
+                        status=SagaStepStatus.ERROR,
+                        step_id=step_id,
+                        step_name=step_name,
+                        attempt=saga.retry_counter + 1,
+                        token=saga.step_execution_token,
+                        input={"_admin": "abort"},
+                        output=None,
+                        error=error_message,
+                        skipped=True,
+                    )
+                )
+
                 saga.status = SagaStatus.FAILED
                 saga.deadline_at = None
-                saga.last_error = saga.last_error or "Aborted by admin"
+                saga.last_error = error_message
                 saga.step_execution_token = uuid.uuid4()
 
     async def skip_step(

{python_saga_orchestrator-0.3.0 → python_saga_orchestrator-0.5.0}/saga_orchestrator/core/repository.py

@@ -139,7 +139,7 @@ class SagaRepository(Generic[ModelT]):
     ) -> list[ModelT]:
         """Return due saga rows for one status ordered by deadline."""
         stmt = (
-            select(self.model_class)
+            self._base_query()
             .where(
                 self.model_class.status == status,
                 self.model_class.deadline_at.is_not(None),

{python_saga_orchestrator-0.3.0 → python_saga_orchestrator-0.5.0}/saga_orchestrator/domain/mixins/saga_step_histrory.py

@@ -4,7 +4,7 @@ import uuid
 from datetime import datetime
 from typing import Any
 
-from sqlalchemy import Boolean, DateTime, Enum, Integer, String, Text
+from sqlalchemy import Boolean, DateTime, Enum, Integer, String, Text, func
 from sqlalchemy.dialects.postgresql import UUID
 from sqlalchemy.orm import Mapped, declarative_mixin, declared_attr, mapped_column
 
@@ -43,3 +43,13 @@ class SagaStepHistoryMixin:
 
     error: Mapped[str | None] = mapped_column(Text, nullable=True)
     skipped: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+
+    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.3.0 → python_saga_orchestrator-0.5.0}/saga_orchestrator/domain/models/enums/saga_status.py

@@ -11,6 +11,7 @@ class SagaStatus(BaseStrEnum):
     COMPLETED = auto()
     COMPENSATING_SUSPENDED = auto()
     COMPENSATED = auto()
+    TIMEOUT = auto()
 
     @property
     def is_terminal(self) -> bool:

{python_saga_orchestrator-0.3.0 → python_saga_orchestrator-0.5.0}/saga_orchestrator/domain/models/enums/saga_step_status.py

@@ -7,3 +7,4 @@ class SagaStepStatus(BaseStrEnum):
     SUCCESS = auto()
     ERROR = auto()
     WAITING = auto()
+    TIMEOUT = auto()

{python_saga_orchestrator-0.3.0 → python_saga_orchestrator-0.5.0}/tests/integration/helpers.py

@@ -324,7 +324,14 @@ class WaitingStep(BaseStep[NextInput, NextOutput]):
         raise RuntimeError("pending approval")
 
 
-# --- Hook Helper Models & Functions ---
+class WaitingWithTimeoutStep(BaseStep[StartInput, StartOutput]):
+    """Шаг, который всегда ждет события с небольшим таймаутом."""
+
+    async def execute(self, inp: StartInput) -> StepAwaitEvent | StartOutput:
+        return StepAwaitEvent(
+            event_types=("some.event",),
+            until=timedelta(milliseconds=10),
+        )
 
 
 class SagaStartedEvent(BaseModel):

{python_saga_orchestrator-0.3.0 → python_saga_orchestrator-0.5.0}/tests/integration/test_admin_api.py

@@ -1,5 +1,3 @@
-# tests/integration/test_admin_api.py
-
 from __future__ import annotations
 
 import asyncio
@@ -7,7 +5,7 @@ from datetime import timedelta
 
 import pytest
 
-from saga_orchestrator import SagaAdmin, SagaBuilder
+from saga_orchestrator import SagaAdmin, SagaBuilder, SagaStepStatus
 from saga_orchestrator.core.orchestrator import SagaOrchestrator
 from saga_orchestrator.domain.exceptions import SagaStateError
 from saga_orchestrator.domain.models import ExponentialRetry
@@ -23,6 +21,7 @@ from tests.integration.helpers import (
     StartInput,
     StartOutput,
     WaitingStep,
+    WaitingWithTimeoutStep,
 )
 from tests.integration.models import IntegrationSagaHistory, IntegrationSagaState
 
@@ -307,3 +306,91 @@ async def test_can_retry_step_on_forward_failure_without_compensation(session_ma
     state_after = await admin.get_saga(saga_id)
     assert state_after.status == SagaStatus.COMPLETED
     assert fails_once_step.calls == 2
+
+
+@pytest.mark.asyncio
+async def test_admin_abort_adds_history_entry(session_maker):
+    """
+    Проверяет, что вызов admin.abort() добавляет запись об ошибке в историю шага.
+    """
+    builder = SagaBuilder()
+    builder.add_step(
+        step=WaitingWithTimeoutStep(),
+        input_map=lambda ctx: StartInput(value=ctx.initial_data["value"]),
+        retry_policy=ExponentialRetry(max_attempts=1, base_delay=timedelta(hours=1)),
+    )
+
+    orchestrator = SagaOrchestrator[IntegrationSagaState, IntegrationSagaHistory](
+        model_class=IntegrationSagaState,
+        history_model_class=IntegrationSagaHistory,
+        session_maker=session_maker,
+    )
+    admin = SagaAdmin[IntegrationSagaState, IntegrationSagaHistory](
+        engine=orchestrator.engine
+    )
+    orchestrator.register("abort-test", builder.build())
+
+    saga_id = await orchestrator.start(
+        saga_name="abort-test",
+        initial_data={"value": 1},
+        aggregation_id="agg-abort-test",
+    )
+
+    state_before = await admin.get_saga(saga_id)
+    assert state_before.status == SagaStatus.SUSPENDED
+    assert len(state_before.step_history) == 1
+    await admin.abort(saga_id)
+
+    state_after = await admin.get_saga(saga_id)
+    assert state_after.status == SagaStatus.FAILED
+    assert state_after.last_error == "Aborted by admin"
+    assert len(state_after.step_history) == 2
+
+    abort_entry = state_after.step_history[-1]
+    assert abort_entry.status == SagaStepStatus.ERROR
+    assert abort_entry.error == "Aborted by admin"
+    assert abort_entry.skipped is True
+    assert abort_entry.input == {"_admin": "abort"}
+
+
+@pytest.mark.asyncio
+async def test_admin_retry_step_from_timed_out_status(session_maker):
+    """
+    Проверяет, что можно перезапустить шаг из статуса TIMEOUT.
+    """
+    builder = SagaBuilder()
+    builder.add_step(
+        step=WaitingWithTimeoutStep(),
+        input_map=lambda ctx: StartInput(value=ctx.initial_data["value"]),
+    )
+
+    orchestrator = SagaOrchestrator[IntegrationSagaState, IntegrationSagaHistory](
+        model_class=IntegrationSagaState,
+        history_model_class=IntegrationSagaHistory,
+        session_maker=session_maker,
+    )
+    admin = SagaAdmin[IntegrationSagaState, IntegrationSagaHistory](
+        engine=orchestrator.engine
+    )
+    orchestrator.register("retry-from-timeout", builder.build())
+
+    saga_id = await orchestrator.start(
+        saga_name="retry-from-timeout",
+        initial_data={"value": 1},
+        aggregation_id="agg-retry-from-timeout",
+    )
+    await asyncio.sleep(0.1)
+    await orchestrator.run_due()
+
+    state_before = await admin.get_saga(saga_id)
+    assert state_before.status == SagaStatus.TIMEOUT
+    assert len(state_before.step_history) == 2
+    assert state_before.step_history[0].status == SagaStepStatus.WAITING
+    assert state_before.step_history[1].status == SagaStepStatus.TIMEOUT
+    await admin.retry_step(saga_id)
+    state_after = await admin.get_saga(saga_id)
+    assert state_after.status == SagaStatus.SUSPENDED
+    assert state_after.retry_counter == 0
+
+    assert len(state_after.step_history) == 3
+    assert state_after.step_history[2].status == SagaStepStatus.WAITING

{python_saga_orchestrator-0.3.0 → python_saga_orchestrator-0.5.0}/tests/integration/test_core_flow.py

@@ -5,7 +5,7 @@ from datetime import timedelta
 
 import pytest
 
-from saga_orchestrator import SagaAdmin, SagaBuilder
+from saga_orchestrator import SagaAdmin, SagaBuilder, SagaStepPhase, SagaStepStatus
 from saga_orchestrator.core.orchestrator import SagaOrchestrator
 from saga_orchestrator.domain.exceptions import ActiveSagaAlreadyExistsError
 from saga_orchestrator.domain.models import ExponentialRetry
@@ -26,6 +26,7 @@ from tests.integration.helpers import (
     ReserveQueueInput,
     ReserveQueueStep,
     StartInput,
+    WaitingWithTimeoutStep,
 )
 from tests.integration.models import (
     IntegrationOutboxMessage,
@@ -398,3 +399,50 @@ async def test_get_snapshot_returns(session_maker):
     assert snapshot.current_step_index == 1
     assert snapshot.deadline_at is None
     assert snapshot.last_error is None
+
+
+@pytest.mark.asyncio
+async def test_timed_out_status_on_await_event_deadline(session_maker):
+    """
+    Проверяет, что сага переходит в статус TIMEOUT, если истекает время ожидания события.
+    """
+    builder = SagaBuilder()
+    builder.add_step(
+        step=WaitingWithTimeoutStep(),
+        input_map=lambda ctx: StartInput(value=ctx.initial_data["value"]),
+    )
+
+    orchestrator = SagaOrchestrator[IntegrationSagaState, IntegrationSagaHistory](
+        model_class=IntegrationSagaState,
+        history_model_class=IntegrationSagaHistory,
+        session_maker=session_maker,
+    )
+    admin = SagaAdmin[IntegrationSagaState, IntegrationSagaHistory](
+        engine=orchestrator.engine
+    )
+    orchestrator.register("await-timeout", builder.build())
+    saga_id = await orchestrator.start(
+        saga_name="await-timeout",
+        initial_data={"value": 1},
+        aggregation_id="agg-await-timeout",
+    )
+
+    state_before = await admin.get_saga(saga_id)
+    assert state_before.status == SagaStatus.SUSPENDED
+    assert state_before.deadline_at is not None
+
+    await asyncio.sleep(0.1)
+    resumed = await orchestrator.run_due()
+    assert resumed == 0
+    state_after = await admin.get_saga(saga_id)
+    assert state_after.status == SagaStatus.TIMEOUT
+    assert "Timed out waiting for event" in state_after.last_error
+    assert state_after.deadline_at is None
+
+    assert len(state_after.step_history) == 2
+    assert state_after.step_history[0].status == SagaStepStatus.WAITING
+    assert state_after.step_history[0].phase == SagaStepPhase.EXECUTE
+    assert not state_after.step_history[0].error
+    assert state_after.step_history[1].status == SagaStepStatus.TIMEOUT
+    assert state_after.step_history[1].phase == SagaStepPhase.EXECUTE
+    assert "Timed out" in state_after.step_history[1].error