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

python_saga_orchestrator-0.6.0/Makefile

@@ -0,0 +1,16 @@
+.PHONY: format tests lint
+
+lint: format
+test: tests
+
+
+format:
+	@ruff format .
+	@ruff check . --fix
+
+tests:
+	docker compose up \
+		--build \
+		--abort-on-container-exit \
+		--exit-code-from tests
+	docker compose down -v

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

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

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

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

{python_saga_orchestrator-0.5.0 → python_saga_orchestrator-0.6.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.5.0'
-__version_tuple__ = version_tuple = (0, 5, 0)
+__version__ = version = '0.6.0'
+__version_tuple__ = version_tuple = (0, 6, 0)
 
 __commit_id__ = commit_id = None

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

@@ -261,23 +261,17 @@ class SagaEngine(Generic[ModelT, HistoryModelT]):
                     return NotifyResult.DUPLICATE
 
                 expected_types: tuple[str, ...] = context.awaiting_event_types
-                expected_type: str | None = context.awaiting_event_type
-                if normalized_event is None and (
-                    expected_type is not None
-                    or (
-                        isinstance(expected_types, (list, tuple))
-                        and len(expected_types) > 0
-                    )
-                ):
+
+                if normalized_event is None and expected_types:
                     self._append_notify_log(
                         saga=saga,
                         event=normalized_event,
                         result=NotifyResult.EVENT_TYPE_MISMATCH,
                     )
                     return NotifyResult.EVENT_TYPE_MISMATCH
+
                 if (
                     normalized_event is not None
-                    and isinstance(expected_types, (list, tuple))
                     and expected_types
                     and normalized_event.event_type not in expected_types
                 ):
@@ -287,17 +281,6 @@ class SagaEngine(Generic[ModelT, HistoryModelT]):
                         result=NotifyResult.EVENT_TYPE_MISMATCH,
                     )
                     return NotifyResult.EVENT_TYPE_MISMATCH
-                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: str | None = context.awaiting_correlation_id
                 if (
@@ -497,16 +480,17 @@ class SagaEngine(Generic[ModelT, HistoryModelT]):
 
     def _is_waiting_for_events(self, saga) -> bool:
         """Проверяет, ожидает ли сага внешних событий."""
-        context = saga.context
-        return bool(context.awaiting_event_type or context.awaiting_event_types)
+        context: SagaContext = saga.context
+        return bool(context.awaiting_event_types or context.awaiting_correlation_id)
 
     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.last_error = (
+            f"Timed out waiting for event(s): {context.awaiting_event_types}"
+        )
         saga.deadline_at = None
         saga.step_execution_token = uuid.uuid4()
 
@@ -528,6 +512,7 @@ class SagaEngine(Generic[ModelT, HistoryModelT]):
                 skipped=False,
             )
         )
+        context.clear_awaiting_state()
 
     async def get_snapshot(self, saga_id: UUID) -> SagaSnapshot:
         """Return the snapshot view of one saga."""
@@ -612,6 +597,7 @@ class SagaEngine(Generic[ModelT, HistoryModelT]):
                     step_def,
                     now=datetime.now(UTC),
                 )
+                saga.context.clear_awaiting_state()
 
         await self._drive(saga_id)
 
@@ -623,12 +609,13 @@ class SagaEngine(Generic[ModelT, HistoryModelT]):
                 if saga.status not in {
                     SagaStatus.SUSPENDED,
                     SagaStatus.FAILED,
+                    SagaStatus.TIMEOUT,
                     SagaStatus.COMPENSATING,
                     SagaStatus.COMPENSATING_SUSPENDED,
                 }:
                     raise SagaStateError(
                         "Cannot start compensation unless saga is suspended, failed, "
-                        f"or already compensating (status={saga.status})"
+                        f"timed out, or already compensating (status={saga.status})"
                     )
                 if saga.current_step_index <= 0:
                     raise SagaStateError(
@@ -639,6 +626,7 @@ class SagaEngine(Generic[ModelT, HistoryModelT]):
                 saga.retry_counter = 0
                 saga.step_execution_token = uuid.uuid4()
                 saga.deadline_at = datetime.now(UTC) + self._execution_lease
+                saga.context.clear_awaiting_state()
 
         await self._run_compensation(saga_id)
 
@@ -679,6 +667,7 @@ class SagaEngine(Generic[ModelT, HistoryModelT]):
                 saga.deadline_at = None
                 saga.last_error = error_message
                 saga.step_execution_token = uuid.uuid4()
+                saga.context.clear_awaiting_state()
 
     async def skip_step(
         self,
@@ -731,7 +720,7 @@ class SagaEngine(Generic[ModelT, HistoryModelT]):
                 saga.context.save_step_output(
                     step_def.step_id, output_model.model_dump(mode="json")
                 )
-
+                saga.context.clear_awaiting_state()
                 saga.current_step_index += 1
                 saga.retry_counter = 0
                 saga.last_error = None

{python_saga_orchestrator-0.5.0 → python_saga_orchestrator-0.6.0}/saga_orchestrator/domain/models/context.py

@@ -78,7 +78,6 @@ class SagaContext(BaseModel):
     )  # For idempotency
 
     # -- Awaiting state --
-    awaiting_event_type: str | None = None
     awaiting_event_types: tuple[str, ...] = Field(default_factory=tuple)
     awaiting_correlation_id: str | None = None
     awaiting_until: str | None = None  # ISO 8601 format
@@ -111,12 +110,10 @@ class SagaContext(BaseModel):
         until: str | None,
     ) -> None:
         self.awaiting_event_types = event_types
-        self.awaiting_event_type = event_types[0] if event_types else None
         self.awaiting_correlation_id = correlation_id
         self.awaiting_until = until
 
     def clear_awaiting_state(self) -> None:
-        self.awaiting_event_type = None
         self.awaiting_event_types = ()
         self.awaiting_correlation_id = None
         self.awaiting_until = None

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

@@ -334,6 +334,21 @@ class WaitingWithTimeoutStep(BaseStep[StartInput, StartOutput]):
         )
 
 
+class RetryWaitInput(BaseModel):
+    value: int
+    event_type: str | None = None
+
+
+class RetryWaitStep(BaseStep[RetryWaitInput, StartOutput]):
+    async def execute(self, inp: RetryWaitInput) -> StepAwaitEvent | StartOutput:
+        if inp.event_type is None:
+            return StepAwaitEvent(
+                event_types=("some.event",),
+                until=timedelta(milliseconds=10),
+            )
+        return StartOutput(value=inp.value + 1)
+
+
 class SagaStartedEvent(BaseModel):
     saga_id: uuid.UUID
     initial_value: int

{python_saga_orchestrator-0.5.0 → python_saga_orchestrator-0.6.0}/tests/integration/test_context_persistence.py

@@ -7,6 +7,7 @@ import pytest
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 
+from saga_orchestrator import SagaStateMixin
 from saga_orchestrator.domain.models.context import SagaContext
 from saga_orchestrator.domain.models.enums import SagaStepPhase, SagaStepStatus
 from tests.integration.helpers import StartInput
@@ -70,12 +71,16 @@ async def test_top_level_attribute_change_is_persisted(session_maker):
 
     async with session_maker() as session:
         saga = await session.get(IntegrationSagaState, saga_id)
-        saga.context.awaiting_event_type = new_awaiting_type
+        saga.context.awaiting_event_types = (new_awaiting_type,)
         await session.commit()
 
     async with session_maker() as session:
-        reloaded_saga = await session.get(IntegrationSagaState, saga_id)
-        assert reloaded_saga.context.awaiting_event_type == new_awaiting_type
+        reloaded_saga: SagaStateMixin | None = await session.get(
+            IntegrationSagaState, saga_id
+        )
+        assert reloaded_saga is not None
+        assert len(reloaded_saga.context.awaiting_event_types) == 1
+        assert new_awaiting_type in reloaded_saga.context.awaiting_event_types
 
 
 @pytest.mark.asyncio

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

@@ -5,7 +5,13 @@ from datetime import timedelta
 
 import pytest
 
-from saga_orchestrator import SagaAdmin, SagaBuilder, SagaStepPhase, SagaStepStatus
+from saga_orchestrator import (
+    SagaAdmin,
+    SagaAdminSnapshot,
+    SagaBuilder,
+    SagaStepPhase,
+    SagaStepStatus,
+)
 from saga_orchestrator.core.orchestrator import SagaOrchestrator
 from saga_orchestrator.domain.exceptions import ActiveSagaAlreadyExistsError
 from saga_orchestrator.domain.models import ExponentialRetry
@@ -17,6 +23,7 @@ from tests.integration.helpers import (
     ActivateQueueStep,
     AddOneStep,
     AlwaysFailStep,
+    CompensatingStep,
     FailsOnceStep,
     FlakyStep,
     HttpInput,
@@ -25,6 +32,8 @@ from tests.integration.helpers import (
     RecoverableStep,
     ReserveQueueInput,
     ReserveQueueStep,
+    RetryWaitInput,
+    RetryWaitStep,
     StartInput,
     WaitingWithTimeoutStep,
 )
@@ -308,10 +317,12 @@ async def test_three_step_http_and_queue_style_flow(session_maker):
         aggregation_id="agg-http-queue-3",
     )
 
-    state_after_start = await admin.get_saga(saga_id)
+    state_after_start: SagaAdminSnapshot = await admin.get_saga(saga_id)
     assert state_after_start.status == SagaStatus.SUSPENDED
     assert state_after_start.current_step_index == 1
-    assert state_after_start.context.awaiting_event_type == "reserve.success"
+    assert len(state_after_start.context.awaiting_event_types) == 2
+    assert "reserve.success" in state_after_start.context.awaiting_event_types
+    assert "reserve.failed" in state_after_start.context.awaiting_event_types
 
     processed = await dispatcher.run_once(limit=10)
     assert processed == 1
@@ -323,11 +334,11 @@ async def test_three_step_http_and_queue_style_flow(session_maker):
     reserve_token = (await admin.get_saga(saga_id)).step_execution_token
     await orchestrator.notify(
         saga_id=saga_id,
-        token=reserve_token,  # type: ignore[arg-type]
+        token=reserve_token,
         event=NotifyEvent(
             event_id="evt-reserve-1",
             event_type="reserve.success",
-            correlation_id=first_headers["correlation_id"],  # type: ignore[index]
+            correlation_id=first_headers["correlation_id"],
             payload={"reservation_id": "res-200"},
         ),
     )
@@ -335,7 +346,9 @@ async def test_three_step_http_and_queue_style_flow(session_maker):
     state_after_reserve = await admin.get_saga(saga_id)
     assert state_after_reserve.status == SagaStatus.SUSPENDED
     assert state_after_reserve.current_step_index == 2
-    assert state_after_reserve.context.awaiting_event_type == "activate.success"
+    assert len(state_after_start.context.awaiting_event_types) == 2
+    assert "activate.success" in state_after_reserve.context.awaiting_event_types
+    assert "activate.failed" in state_after_reserve.context.awaiting_event_types
 
     processed = await dispatcher.run_once(limit=10)
     assert processed == 1
@@ -347,11 +360,11 @@ async def test_three_step_http_and_queue_style_flow(session_maker):
     activate_token = (await admin.get_saga(saga_id)).step_execution_token
     await orchestrator.notify(
         saga_id=saga_id,
-        token=activate_token,  # type: ignore[arg-type]
+        token=activate_token,
         event=NotifyEvent(
             event_id="evt-activate-1",
             event_type="activate.success",
-            correlation_id=second_headers["correlation_id"],  # type: ignore[index]
+            correlation_id=second_headers["correlation_id"],
             payload={"deployment_id": "dep-200"},
         ),
     )
@@ -446,3 +459,109 @@ async def test_timed_out_status_on_await_event_deadline(session_maker):
     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
+
+    assert state_after.context.awaiting_event_types == ()
+    assert state_after.context.awaiting_correlation_id is None
+    assert state_after.context.awaiting_until is None
+
+
+@pytest.mark.asyncio
+async def test_compensate_after_timeout_resolves_deadlock(session_maker):
+    """
+    Проверяет возможность запуска компенсации для саги, зависшей со статусом TIMEOUT.
+    Убеждается, что админ может спасти сагу без правки БД.
+    """
+    first_step = CompensatingStep()
+    builder = SagaBuilder()
+    ref = builder.add_step(
+        step=first_step,
+        input_map=lambda ctx: StartInput(value=ctx.initial_data["value"]),
+    )
+    builder.add_step(
+        step=WaitingWithTimeoutStep(),
+        depends_on=ref,
+        input_map=lambda out: StartInput(value=out.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("comp-timeout", builder.build())
+
+    saga_id = await orchestrator.start(
+        saga_name="comp-timeout",
+        initial_data={"value": 1},
+        aggregation_id="agg-comp-timeout",
+    )
+
+    await asyncio.sleep(0.1)
+    await orchestrator.run_due()
+
+    state = await admin.get_saga(saga_id)
+    assert state.status == SagaStatus.TIMEOUT
+
+    await admin.compensate_step(saga_id)
+
+    final_state = await admin.get_saga(saga_id)
+    assert final_state.status == SagaStatus.COMPENSATED
+    assert first_step.compensated is True
+
+
+@pytest.mark.asyncio
+async def test_retry_after_timeout_processes_successfully(session_maker):
+    """
+    Проверяет успешный ретрай саги после таймаута. Убеждается, что нет мгновенного
+    повторного таймаута из-за старого неочищенного кеша ожидания.
+    """
+
+    builder = SagaBuilder()
+    builder.add_step(
+        step=RetryWaitStep(),
+        input_map=lambda ctx: RetryWaitInput(
+            value=ctx.initial_data["value"],
+            event_type=ctx.latest_event_type,
+        ),
+    )
+
+    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-timeout", builder.build())
+
+    saga_id = await orchestrator.start(
+        saga_name="retry-timeout",
+        initial_data={"value": 1},
+        aggregation_id="agg-retry-timeout",
+    )
+
+    await asyncio.sleep(0.1)
+    await orchestrator.run_due()
+    state1 = await admin.get_saga(saga_id)
+    assert state1.status == SagaStatus.TIMEOUT
+
+    await admin.retry_step(saga_id)
+    state2 = await admin.get_saga(saga_id)
+
+    assert state2.status == SagaStatus.SUSPENDED
+    assert state2.context.awaiting_event_types == ("some.event",)
+
+    await orchestrator.notify(
+        saga_id=saga_id,
+        token=state2.step_execution_token,
+        event=NotifyEvent(
+            event_id="evt-retry-123", event_type="some.event", payload={"value": 42}
+        ),
+    )
+
+    final_state = await admin.get_saga(saga_id)
+    assert final_state.status == SagaStatus.COMPLETED

{python_saga_orchestrator-0.5.0 → python_saga_orchestrator-0.6.0}/tests/integration/test_notification_flow.py

@@ -5,7 +5,7 @@ from datetime import timedelta
 
 import pytest
 
-from saga_orchestrator import SagaAdmin, SagaBuilder
+from saga_orchestrator import SagaAdmin, SagaAdminSnapshot, SagaBuilder
 from saga_orchestrator.core.orchestrator import SagaOrchestrator
 from saga_orchestrator.domain.models import ExponentialRetry
 from saga_orchestrator.domain.models.enums import SagaStatus
@@ -94,12 +94,13 @@ async def test_await_event_configures_wait_contract(session_maker):
         ),
     )
 
-    state_after = await admin.get_saga(saga_id)
+    state_after: SagaAdminSnapshot = await admin.get_saga(saga_id)
     assert state_after.status == SagaStatus.SUSPENDED
     assert state_after.step_execution_token == new_token
     assert state_after.step_execution_token != state_before.step_execution_token
     assert state_after.deadline_at is None
-    assert state_after.context.awaiting_event_type == "model.approved"
+    assert len(state_after.context.awaiting_event_types) == 1
+    assert "model.approved" in state_after.context.awaiting_event_types
     assert state_after.context.awaiting_correlation_id == "corr-await"
     assert state_after.context.awaiting_until == "2999-01-01T00:00:00+00:00"
 

python_saga_orchestrator-0.5.0/Makefile

@@ -1,12 +0,0 @@
-.PHONY: format tests lint
-
-lint: format
-test: tests
-
-
-format:
-	@ruff format .
-	@ruff check . --fix
-
-tests:
-	@docker compose up --build --abort-on-container-exit