edda-framework 0.9.0__tar.gz → 0.9.1__tar.gz

{edda_framework-0.9.0 → edda_framework-0.9.1}/.github/workflows/docs.yml

@@ -23,11 +23,11 @@ jobs:
         with:
           python-version: "3.11"
 
-      - name: Install Zensical
-        run: pip install zensical
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
 
       - name: Build documentation
-        run: zensical build --clean
+        run: uv run --with zensical --with mkdocstrings-python -- zensical build --clean
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v4

{edda_framework-0.9.0 → edda_framework-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.9.0
+Version: 0.9.1
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme

{edda_framework-0.9.0 → edda_framework-0.9.1}/docs/core-features/messages.md

@@ -517,6 +517,7 @@ async def process_order(ctx: WorkflowContext, order_id: str):
 ```
 
 **Behavior:**
+
 - If the activity **succeeds**: Message is published after commit
 - If the activity **fails**: Message is **NOT** published (rollback)
 
@@ -538,6 +539,7 @@ async def process_job(ctx: WorkflowContext, channel: str):
 ```
 
 **Behavior:**
+
 - If the activity **succeeds**: Message claim is committed, message is processed
 - If the activity **fails**: Message claim is rolled back, message returns to queue
 

{edda_framework-0.9.0 → edda_framework-0.9.1}/docs/index.md

@@ -26,7 +26,7 @@ Edda is a lightweight durable execution framework for Python that runs as a **li
 - 📦 **Transactional Outbox**: Reliable event publishing with guaranteed delivery
 - ☁️ **CloudEvents Support**: Native support for CloudEvents protocol
 - ⏱️ **Event & Timer Waiting**: Free up worker resources while waiting for events or timers, resume on any available worker
-- 📬 **Message Passing**: Actor-model style workflow-to-workflow communication with groups for fan-out (Erlang pg style)
+- 📬 **Message Passing**: Channel-based messaging (broadcast/competing modes) and direct workflow-to-workflow communication
 
 ## Use Cases
 

{edda_framework-0.9.0 → edda_framework-0.9.1}/edda/app.py

@@ -709,7 +709,6 @@ class EddaApp:
             instance_id = subscription["instance_id"]
             channel = subscription["channel"]
             timeout_at = subscription["timeout_at"]
-            created_at = subscription["created_at"]
 
             # Lock-First pattern: Try to acquire the lock before processing
             # If we can't get the lock, another worker is processing this workflow
@@ -777,48 +776,28 @@ class EddaApp:
                 # 2. Remove message subscription
                 await self.storage.remove_message_subscription(instance_id, channel)
 
-                # 3. Fail the workflow with TimeoutError
-                import traceback
-
-                # Get timeout_seconds from timeout_at and created_at
-                # Handle both datetime objects and ISO strings
-                try:
-                    timeout_dt = (
-                        timeout_at
-                        if isinstance(timeout_at, dt_type)
-                        else dt_type.fromisoformat(str(timeout_at))
-                    )
-                    created_dt = (
-                        created_at
-                        if isinstance(created_at, dt_type)
-                        else dt_type.fromisoformat(str(created_at))
+                # 3. Resume workflow (lock already held - distributed coroutine pattern)
+                # The workflow will replay and receive() will raise TimeoutError from cached history
+                workflow_name = subscription.get("workflow_name")
+                if not workflow_name:
+                    logger.warning(
+                        "No workflow_name in subscription for %s, skipping",
+                        instance_id,
                     )
-                    # Calculate the original timeout duration (timeout_at - created_at)
-                    timeout_seconds = int((timeout_dt - created_dt).total_seconds())
-                except Exception:
-                    timeout_seconds = 0  # Fallback
+                    continue
 
-                error = TimeoutError(
-                    f"Message on channel '{channel}' did not arrive within {timeout_seconds} seconds"
-                )
-                stack_trace = "".join(
-                    traceback.format_exception(type(error), error, error.__traceback__)
-                )
+                if self.replay_engine is None:
+                    logger.error("Replay engine not initialized")
+                    continue
 
-                # Update workflow status to failed with error details
-                await self.storage.update_instance_status(
-                    instance_id,
-                    "failed",
-                    {
-                        "error_message": str(error),
-                        "error_type": "TimeoutError",
-                        "stack_trace": stack_trace,
-                    },
+                await self.replay_engine.resume_by_name(
+                    instance_id, workflow_name, already_locked=True
                 )
 
                 logger.debug(
-                    "Marked workflow %s as failed due to message timeout",
+                    "Resumed workflow %s after message timeout on channel '%s'",
                     instance_id,
+                    channel,
                 )
 
             except Exception as e:

{edda_framework-0.9.0 → edda_framework-0.9.1}/edda/context.py

@@ -217,6 +217,14 @@ class WorkflowContext:
                 # Cache the timer result for wait_timer replay
                 # Timer returns None, so we cache the result field
                 self._history_cache[activity_id] = event_data.get("result")
+            elif event_type == "MessageTimeout":
+                # Cache the timeout error for receive() replay
+                # This allows TimeoutError to be raised and caught in workflow code
+                self._history_cache[activity_id] = {
+                    "_error": True,
+                    "error_type": event_data.get("error_type", "TimeoutError"),
+                    "error_message": event_data.get("error_message", "Message timeout"),
+                }
 
         self._history_loaded = True
 

{edda_framework-0.9.0 → edda_framework-0.9.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "edda-framework"
-version = "0.9.0"
+version = "0.9.1"
 description = "Lightweight Durable Execution Framework"
 authors = [
     { name = "Yasushi Itoh", email = "6240399+i2y@users.noreply.github.com" }

edda_framework-0.9.1/tests/test_receive_timeout.py

@@ -0,0 +1,217 @@
+"""
+Tests for receive() timeout handling.
+
+Tests verify that:
+1. TimeoutError is raised during replay when history contains timeout error
+2. Workflow can catch TimeoutError with try/except
+3. _check_expired_message_subscriptions() resumes workflow instead of failing it
+"""
+
+import pytest
+import pytest_asyncio
+
+from edda.channels import receive, subscribe
+from edda.context import WorkflowContext
+
+
+@pytest.mark.asyncio
+class TestReceiveTimeoutReplay:
+    """Test that receive() raises TimeoutError during replay when history contains timeout."""
+
+    @pytest_asyncio.fixture
+    async def workflow_instance(self, sqlite_storage, create_test_instance):
+        """Create a workflow instance for testing."""
+        instance_id = "test-timeout-instance-001"
+        await create_test_instance(
+            instance_id=instance_id,
+            workflow_name="test_workflow",
+            owner_service="test-service",
+            input_data={"test": "data"},
+        )
+        await sqlite_storage.update_instance_status(instance_id, "running")
+        return instance_id
+
+    async def test_receive_raises_timeout_error_during_replay(
+        self, sqlite_storage, workflow_instance
+    ):
+        """Test that receive() raises TimeoutError when replaying a timeout event."""
+        # Record a timeout error in history (simulating what _check_expired_message_subscriptions does)
+        await sqlite_storage.append_history(
+            instance_id=workflow_instance,
+            activity_id="receive_payment:1",
+            event_type="MessageTimeout",
+            event_data={
+                "_error": True,
+                "error_type": "TimeoutError",
+                "error_message": "Message on channel 'payment' did not arrive within timeout",
+                "channel": "payment",
+                "timeout_at": "2025-01-01T00:00:00+00:00",
+            },
+        )
+
+        # Create context in replay mode
+        ctx = WorkflowContext(
+            instance_id=workflow_instance,
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=True,
+        )
+
+        # Subscribe first (required before receive)
+        await subscribe(ctx, "payment", mode="broadcast")
+
+        # Load history to populate cache with the timeout error
+        await ctx._load_history()
+
+        # Reset activity counter after subscribe
+        ctx._activity_call_counters.clear()
+
+        # receive() should raise TimeoutError from cached history
+        with pytest.raises(TimeoutError) as exc_info:
+            await receive(ctx, channel="payment", message_id="receive_payment:1")
+
+        assert "did not arrive within timeout" in str(exc_info.value)
+
+    async def test_receive_timeout_can_be_caught_in_workflow(
+        self, sqlite_storage, workflow_instance
+    ):
+        """Test that TimeoutError can be caught with try/except in workflow code."""
+        # Record a timeout error in history
+        await sqlite_storage.append_history(
+            instance_id=workflow_instance,
+            activity_id="receive_approval:1",
+            event_type="MessageTimeout",
+            event_data={
+                "_error": True,
+                "error_type": "TimeoutError",
+                "error_message": "Message on channel 'approval' did not arrive within 60 seconds",
+                "channel": "approval",
+            },
+        )
+
+        # Create context in replay mode
+        ctx = WorkflowContext(
+            instance_id=workflow_instance,
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=True,
+        )
+
+        await subscribe(ctx, "approval", mode="broadcast")
+
+        # Load history to populate cache with the timeout error
+        await ctx._load_history()
+
+        ctx._activity_call_counters.clear()
+
+        # Simulate workflow code that catches TimeoutError
+        timeout_caught = False
+        try:
+            await receive(ctx, channel="approval", message_id="receive_approval:1")
+        except TimeoutError:
+            timeout_caught = True
+
+        assert timeout_caught is True
+
+    async def test_receive_timeout_with_generic_error_type(self, sqlite_storage, workflow_instance):
+        """Test that non-TimeoutError errors are also re-raised during replay."""
+        # Record a timeout event but with a different error type (not TimeoutError)
+        # This tests that receive() properly handles various error types from MessageTimeout events
+        await sqlite_storage.append_history(
+            instance_id=workflow_instance,
+            activity_id="receive_data:1",
+            event_type="MessageTimeout",
+            event_data={
+                "_error": True,
+                "error_type": "ValueError",
+                "error_message": "Invalid message format",
+                "channel": "data",
+            },
+        )
+
+        # Create context in replay mode
+        ctx = WorkflowContext(
+            instance_id=workflow_instance,
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=True,
+        )
+
+        await subscribe(ctx, "data", mode="broadcast")
+
+        # Load history to populate cache with the error
+        await ctx._load_history()
+
+        ctx._activity_call_counters.clear()
+
+        # Should raise generic Exception for non-TimeoutError
+        with pytest.raises(Exception) as exc_info:
+            await receive(ctx, channel="data", message_id="receive_data:1")
+
+        assert "ValueError" in str(exc_info.value)
+        assert "Invalid message format" in str(exc_info.value)
+
+
+@pytest.mark.asyncio
+class TestCheckExpiredMessageSubscriptions:
+    """Test that _check_expired_message_subscriptions resumes workflow."""
+
+    @pytest_asyncio.fixture
+    async def workflow_instance(self, sqlite_storage, create_test_instance):
+        """Create a workflow instance for testing."""
+        instance_id = "test-timeout-workflow-001"
+        await create_test_instance(
+            instance_id=instance_id,
+            workflow_name="timeout_test_workflow",
+            owner_service="test-service",
+            input_data={"test": "data"},
+        )
+        await sqlite_storage.update_instance_status(instance_id, "waiting_for_message")
+        return instance_id
+
+    async def test_find_expired_message_subscriptions_returns_workflow_name(
+        self, sqlite_storage, workflow_instance
+    ):
+        """Test that find_expired_message_subscriptions returns workflow_name."""
+        from datetime import UTC, datetime, timedelta
+
+        # Subscribe and set timeout in the past
+        await sqlite_storage.subscribe_to_channel(
+            workflow_instance, "test_channel", mode="broadcast"
+        )
+
+        # Manually set timeout_at to past (simulating expired timeout)
+        # This requires direct SQL since subscribe_to_channel doesn't set timeout
+        from sqlalchemy import text
+
+        past_time = datetime.now(UTC) - timedelta(seconds=60)
+        async with sqlite_storage.engine.begin() as conn:
+            await conn.execute(
+                text(
+                    """
+                    UPDATE channel_subscriptions
+                    SET timeout_at = :timeout_at, activity_id = :activity_id
+                    WHERE instance_id = :instance_id AND channel = :channel
+                    """
+                ),
+                {
+                    "timeout_at": past_time,
+                    "activity_id": "receive_test_channel:1",
+                    "instance_id": workflow_instance,
+                    "channel": "test_channel",
+                },
+            )
+
+        # Find expired subscriptions
+        expired = await sqlite_storage.find_expired_message_subscriptions()
+
+        # Should find our expired subscription with workflow_name
+        assert len(expired) >= 1
+        our_sub = next((s for s in expired if s["instance_id"] == workflow_instance), None)
+        assert our_sub is not None
+        assert our_sub["workflow_name"] == "timeout_test_workflow"
+        assert our_sub["channel"] == "test_channel"
+        assert our_sub["activity_id"] == "receive_test_channel:1"

{edda_framework-0.9.0 → edda_framework-0.9.1}/uv.lock

@@ -668,7 +668,7 @@ wheels = [
 
 [[package]]
 name = "edda-framework"
-version = "0.9.0"
+version = "0.9.1"
 source = { editable = "." }
 dependencies = [
     { name = "a2wsgi" },