edda-framework 0.13.0__tar.gz → 0.14.1__tar.gz

{edda_framework-0.13.0 → edda_framework-0.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.13.0
+Version: 0.14.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.13.0 → edda_framework-0.14.1}/edda/app.py

@@ -583,7 +583,6 @@ class EddaApp:
                 auto_resume_stale_workflows_periodically(
                     self.storage,
                     self.replay_engine,
-                    self.worker_id,
                     interval=60,
                 ),
                 name="leader_stale_workflow_resume",
@@ -628,7 +627,6 @@ class EddaApp:
                 auto_resume_stale_workflows_periodically(
                     self.storage,
                     self.replay_engine,
-                    self.worker_id,
                     interval=60,
                 ),
                 name="leader_stale_workflow_resume",
@@ -1411,7 +1409,8 @@ class EddaApp:
         from growing indefinitely with orphaned messages (messages that were
         published but never received by any subscriber).
 
-        Uses system-level locking to ensure only one pod executes cleanup at a time.
+        Important: This task should only be run by a single worker (e.g., via leader
+        election). It does not perform its own distributed coordination.
 
         Args:
             interval: Cleanup interval in seconds (default: 3600 = 1 hour)
@@ -1422,27 +1421,13 @@ class EddaApp:
         """
         while True:
             try:
-                # Add jitter to prevent thundering herd in multi-pod deployments
+                # Add jitter to prevent thundering herd
                 jitter = random.uniform(0, interval * 0.3)
                 await asyncio.sleep(interval + jitter)
 
-                # Try to acquire global lock for this task
-                lock_acquired = await self.storage.try_acquire_system_lock(
-                    lock_name="cleanup_old_messages",
-                    worker_id=self.worker_id,
-                    timeout_seconds=interval,
-                )
-
-                if not lock_acquired:
-                    # Another pod is handling this task
-                    continue
-
-                try:
-                    deleted_count = await self.storage.cleanup_old_channel_messages(retention_days)
-                    if deleted_count > 0:
-                        logger.info("Cleaned up %d old channel messages", deleted_count)
-                finally:
-                    await self.storage.release_system_lock("cleanup_old_messages", self.worker_id)
+                deleted_count = await self.storage.cleanup_old_channel_messages(retention_days)
+                if deleted_count > 0:
+                    logger.info("Cleaned up %d old channel messages", deleted_count)
             except Exception as e:
                 logger.error("Error cleaning up old messages: %s", e, exc_info=True)
 

{edda_framework-0.13.0 → edda_framework-0.14.1}/edda/channels.py

@@ -129,6 +129,24 @@ class WaitForTimerException(Exception):
         super().__init__(f"Waiting for timer: {timer_id}")
 
 
+class ChannelModeConflictError(Exception):
+    """
+    Raised when subscribing with a different mode than the channel's established mode.
+
+    A channel's mode is locked when the first subscription is created. Subsequent
+    subscriptions must use the same mode.
+    """
+
+    def __init__(self, channel: str, existing_mode: str, requested_mode: str) -> None:
+        self.channel = channel
+        self.existing_mode = existing_mode
+        self.requested_mode = requested_mode
+        super().__init__(
+            f"Channel '{channel}' is already configured as '{existing_mode}' mode. "
+            f"Cannot subscribe with '{requested_mode}' mode."
+        )
+
+
 # =============================================================================
 # Subscription Functions
 # =============================================================================
@@ -150,6 +168,10 @@ async def subscribe(
               - "competing": Each message goes to only one subscriber (work queue pattern)
               - "direct": Receive messages sent via send_to() to this instance
 
+    Raises:
+        ChannelModeConflictError: If the channel is already configured with a different mode
+        ValueError: If mode is not 'broadcast', 'competing', or 'direct'
+
     The "direct" mode is syntactic sugar that subscribes to "channel:instance_id" internally,
     allowing simpler code when receiving direct messages:
 
@@ -204,6 +226,11 @@ async def subscribe(
             f"Invalid subscription mode: {mode}. Must be 'broadcast', 'competing', or 'direct'"
         )
 
+    # Check for mode conflict
+    existing_mode = await ctx.storage.get_channel_mode(actual_channel)
+    if existing_mode is not None and existing_mode != actual_mode:
+        raise ChannelModeConflictError(channel, existing_mode, mode)
+
     await ctx.storage.subscribe_to_channel(ctx.instance_id, actual_channel, actual_mode)
 
 

{edda_framework-0.13.0 → edda_framework-0.14.1}/edda/locking.py

@@ -192,7 +192,6 @@ async def _refresh_lock_periodically(
 
 async def cleanup_stale_locks_periodically(
     storage: StorageProtocol,
-    worker_id: str,
     interval: int = 60,
 ) -> None:
     """
@@ -204,49 +203,37 @@ async def cleanup_stale_locks_periodically(
     Note: This function only cleans up locks without resuming workflows.
     For automatic workflow resumption, use auto_resume_stale_workflows_periodically().
 
-    Uses system-level locking to ensure only one pod executes cleanup at a time.
+    Important: This function should only be run by a single worker (e.g., via leader
+    election). It does not perform its own distributed coordination.
 
     Example:
         >>> asyncio.create_task(
-        ...     cleanup_stale_locks_periodically(storage, worker_id, interval=60)
+        ...     cleanup_stale_locks_periodically(storage, interval=60)
         ... )
 
     Args:
         storage: Storage backend
-        worker_id: Unique identifier for this worker (for global lock coordination)
         interval: Cleanup interval in seconds (default: 60)
     """
     with suppress(asyncio.CancelledError):
         while True:
-            # Add jitter to prevent thundering herd in multi-pod deployments
+            # Add jitter to prevent thundering herd
             jitter = random.uniform(0, interval * 0.3)
             await asyncio.sleep(interval + jitter)
 
-            # Try to acquire global lock for this task
-            lock_acquired = await storage.try_acquire_system_lock(
-                lock_name="cleanup_stale_locks",
-                worker_id=worker_id,
-                timeout_seconds=interval,
-            )
-
-            if not lock_acquired:
-                # Another pod is handling this task
-                continue
-
             try:
                 # Clean up stale locks
                 workflows = await storage.cleanup_stale_locks()
 
                 if len(workflows) > 0:
                     logger.info("Cleaned up %d stale locks", len(workflows))
-            finally:
-                await storage.release_system_lock("cleanup_stale_locks", worker_id)
+            except Exception as e:
+                logger.error("Failed to cleanup stale locks: %s", e, exc_info=True)
 
 
 async def auto_resume_stale_workflows_periodically(
     storage: StorageProtocol,
     replay_engine: Any,
-    worker_id: str,
     interval: int = 60,
 ) -> None:
     """
@@ -255,39 +242,27 @@ async def auto_resume_stale_workflows_periodically(
     This combines lock cleanup with automatic workflow resumption, ensuring
     that workflows interrupted by worker crashes are automatically recovered.
 
-    Uses system-level locking to ensure only one pod executes this task at a time,
-    preventing duplicate workflow execution (CRITICAL for safety).
+    Important: This function should only be run by a single worker (e.g., via leader
+    election). It does not perform its own distributed coordination.
 
     Example:
         >>> asyncio.create_task(
         ...     auto_resume_stale_workflows_periodically(
-        ...         storage, replay_engine, worker_id, interval=60
+        ...         storage, replay_engine, interval=60
         ...     )
         ... )
 
     Args:
         storage: Storage backend
         replay_engine: ReplayEngine instance for resuming workflows
-        worker_id: Unique identifier for this worker (for global lock coordination)
         interval: Cleanup interval in seconds (default: 60)
     """
     with suppress(asyncio.CancelledError):
         while True:
-            # Add jitter to prevent thundering herd in multi-pod deployments
+            # Add jitter to prevent thundering herd
             jitter = random.uniform(0, interval * 0.3)
             await asyncio.sleep(interval + jitter)
 
-            # Try to acquire global lock for this task
-            lock_acquired = await storage.try_acquire_system_lock(
-                lock_name="auto_resume_stale_workflows",
-                worker_id=worker_id,
-                timeout_seconds=interval,
-            )
-
-            if not lock_acquired:
-                # Another pod is handling this task
-                continue
-
             try:
                 # Clean up stale locks and get workflows to resume
                 workflows_to_resume = await storage.cleanup_stale_locks()
@@ -369,8 +344,8 @@ async def auto_resume_stale_workflows_periodically(
                                 e,
                                 exc_info=True,
                             )
-            finally:
-                await storage.release_system_lock("auto_resume_stale_workflows", worker_id)
+            except Exception as e:
+                logger.error("Failed to cleanup stale locks: %s", e, exc_info=True)
 
 
 class LockNotAcquiredError(Exception):

{edda_framework-0.13.0 → edda_framework-0.14.1}/edda/storage/protocol.py

@@ -990,6 +990,18 @@ class StorageProtocol(Protocol):
         """
         ...
 
+    async def get_channel_mode(self, channel: str) -> str | None:
+        """
+        Get the mode for a channel (from any existing subscription).
+
+        Args:
+            channel: Channel name
+
+        Returns:
+            The mode ('broadcast' or 'competing') or None if no subscriptions exist
+        """
+        ...
+
     async def register_channel_receive_and_release_lock(
         self,
         instance_id: str,

{edda_framework-0.13.0 → edda_framework-0.14.1}/edda/storage/sqlalchemy_storage.py

@@ -3170,6 +3170,26 @@ class SQLAlchemyStorage:
                 "cursor_message_id": subscription.cursor_message_id,
             }
 
+    async def get_channel_mode(self, channel: str) -> str | None:
+        """
+        Get the mode for a channel (from any existing subscription).
+
+        Args:
+            channel: Channel name
+
+        Returns:
+            The mode ('broadcast' or 'competing') or None if no subscriptions exist
+        """
+        session = self._get_session_for_operation()
+        async with self._session_scope(session) as session:
+            result = await session.execute(
+                select(ChannelSubscription.mode)
+                .where(ChannelSubscription.channel == channel)
+                .limit(1)
+            )
+            row = result.scalar_one_or_none()
+            return row
+
     async def register_channel_receive_and_release_lock(
         self,
         instance_id: str,

{edda_framework-0.13.0 → edda_framework-0.14.1}/pyproject.toml

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

edda_framework-0.14.1/tests/test_channel_mode_locking.py

@@ -0,0 +1,201 @@
+"""
+Tests for channel mode locking functionality.
+
+Ensures that once a channel is subscribed with a specific mode (broadcast/competing),
+subsequent subscriptions with a different mode are rejected with ChannelModeConflictError.
+"""
+
+import pytest
+import pytest_asyncio
+
+from edda.channels import ChannelModeConflictError, subscribe
+from edda.context import WorkflowContext
+
+
+@pytest.mark.asyncio
+class TestChannelModeLocking:
+    """Test suite for channel mode locking."""
+
+    @pytest_asyncio.fixture
+    async def workflow_instances(self, sqlite_storage, create_test_instance):
+        """Create multiple workflow instances for testing."""
+        instances = []
+        for i in range(1, 4):
+            instance_id = f"mode-lock-test-{i}"
+            await create_test_instance(
+                instance_id=instance_id,
+                workflow_name="test_workflow",
+                owner_service="test-service",
+                input_data={"test": True},
+            )
+            await sqlite_storage.update_instance_status(instance_id, "running")
+            instances.append(instance_id)
+        return instances
+
+    async def test_broadcast_then_competing_raises_error(self, sqlite_storage, workflow_instances):
+        """Test that subscribing with competing mode after broadcast raises error."""
+        ctx1 = WorkflowContext(
+            instance_id=workflow_instances[0],
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=False,
+        )
+
+        # Subscribe with broadcast mode first
+        await subscribe(ctx1, "test-channel-1", mode="broadcast")
+
+        # Verify mode was stored
+        mode = await sqlite_storage.get_channel_mode("test-channel-1")
+        assert mode == "broadcast"
+
+        # Try to subscribe with competing mode - should fail
+        ctx2 = WorkflowContext(
+            instance_id=workflow_instances[1],
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=False,
+        )
+
+        with pytest.raises(ChannelModeConflictError) as exc_info:
+            await subscribe(ctx2, "test-channel-1", mode="competing")
+
+        assert exc_info.value.channel == "test-channel-1"
+        assert exc_info.value.existing_mode == "broadcast"
+        assert exc_info.value.requested_mode == "competing"
+
+    async def test_competing_then_broadcast_raises_error(self, sqlite_storage, workflow_instances):
+        """Test that subscribing with broadcast mode after competing raises error."""
+        ctx1 = WorkflowContext(
+            instance_id=workflow_instances[0],
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=False,
+        )
+
+        # Subscribe with competing mode first
+        await subscribe(ctx1, "test-channel-2", mode="competing")
+
+        # Verify mode was stored
+        mode = await sqlite_storage.get_channel_mode("test-channel-2")
+        assert mode == "competing"
+
+        # Try to subscribe with broadcast mode - should fail
+        ctx2 = WorkflowContext(
+            instance_id=workflow_instances[1],
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=False,
+        )
+
+        with pytest.raises(ChannelModeConflictError) as exc_info:
+            await subscribe(ctx2, "test-channel-2", mode="broadcast")
+
+        assert exc_info.value.channel == "test-channel-2"
+        assert exc_info.value.existing_mode == "competing"
+        assert exc_info.value.requested_mode == "broadcast"
+
+    async def test_same_mode_subscription_allowed(self, sqlite_storage, workflow_instances):
+        """Test that multiple subscriptions with the same mode are allowed."""
+        # Subscribe first instance with broadcast
+        ctx1 = WorkflowContext(
+            instance_id=workflow_instances[0],
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=False,
+        )
+        await subscribe(ctx1, "test-channel-3", mode="broadcast")
+
+        # Subscribe second instance with same mode - should succeed
+        ctx2 = WorkflowContext(
+            instance_id=workflow_instances[1],
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=False,
+        )
+        await subscribe(ctx2, "test-channel-3", mode="broadcast")
+
+        # Subscribe third instance with same mode - should succeed
+        ctx3 = WorkflowContext(
+            instance_id=workflow_instances[2],
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=False,
+        )
+        await subscribe(ctx3, "test-channel-3", mode="broadcast")
+
+        # All three should be subscribed
+        sub1 = await sqlite_storage.get_channel_subscription(
+            workflow_instances[0], "test-channel-3"
+        )
+        sub2 = await sqlite_storage.get_channel_subscription(
+            workflow_instances[1], "test-channel-3"
+        )
+        sub3 = await sqlite_storage.get_channel_subscription(
+            workflow_instances[2], "test-channel-3"
+        )
+
+        assert sub1 is not None
+        assert sub2 is not None
+        assert sub3 is not None
+
+    async def test_different_channels_independent_modes(self, sqlite_storage, workflow_instances):
+        """Test that different channels can have different modes."""
+        ctx1 = WorkflowContext(
+            instance_id=workflow_instances[0],
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=False,
+        )
+
+        # Channel A with broadcast
+        await subscribe(ctx1, "channel-a", mode="broadcast")
+
+        # Channel B with competing - should succeed (different channel)
+        await subscribe(ctx1, "channel-b", mode="competing")
+
+        # Verify modes
+        mode_a = await sqlite_storage.get_channel_mode("channel-a")
+        mode_b = await sqlite_storage.get_channel_mode("channel-b")
+
+        assert mode_a == "broadcast"
+        assert mode_b == "competing"
+
+    async def test_get_channel_mode_returns_none_for_new_channel(self, sqlite_storage):
+        """Test that get_channel_mode returns None for channels with no subscriptions."""
+        mode = await sqlite_storage.get_channel_mode("nonexistent-channel")
+        assert mode is None
+
+    async def test_error_message_is_informative(self, sqlite_storage, workflow_instances):
+        """Test that ChannelModeConflictError has a clear message."""
+        ctx1 = WorkflowContext(
+            instance_id=workflow_instances[0],
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=False,
+        )
+        await subscribe(ctx1, "msg-test-channel", mode="broadcast")
+
+        ctx2 = WorkflowContext(
+            instance_id=workflow_instances[1],
+            workflow_name="test_workflow",
+            storage=sqlite_storage,
+            worker_id="worker-1",
+            is_replaying=False,
+        )
+
+        with pytest.raises(ChannelModeConflictError) as exc_info:
+            await subscribe(ctx2, "msg-test-channel", mode="competing")
+
+        error_msg = str(exc_info.value)
+        assert "msg-test-channel" in error_msg
+        assert "broadcast" in error_msg
+        assert "competing" in error_msg