edda-framework 0.12.0__tar.gz → 0.14.0__tar.gz

{edda_framework-0.12.0 → edda_framework-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.12.0
+Version: 0.14.0
 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.12.0 → edda_framework-0.14.0}/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.12.0 → edda_framework-0.14.0}/edda/replay.py

@@ -368,16 +368,22 @@ class ReplayEngine:
                     traceback.format_exception(type(error), error, error.__traceback__)
                 )
 
-                # Mark as failed with detailed error information
-                await ctx._update_status(
-                    "failed",
-                    {
-                        "error_message": str(error),
-                        "error_type": type(error).__name__,
-                        "stack_trace": stack_trace,
-                    },
+                error_data = {
+                    "error_message": str(error),
+                    "error_type": type(error).__name__,
+                    "stack_trace": stack_trace,
+                }
+
+                await self.storage.append_history(
+                    instance_id=instance_id,
+                    activity_id="workflow_failed",
+                    event_type="WorkflowFailed",
+                    event_data=error_data,
                 )
 
+                # Mark as failed with detailed error information
+                await ctx._update_status("failed", error_data)
+
                 # Call hook: workflow failed
                 if self.hooks and hasattr(self.hooks, "on_workflow_failed"):
                     await self.hooks.on_workflow_failed(instance_id, workflow_name, error)
@@ -576,15 +582,21 @@ class ReplayEngine:
                 traceback.format_exception(type(error), error, error.__traceback__)
             )
 
-            # Mark as failed with detailed error information
-            await ctx._update_status(
-                "failed",
-                {
-                    "error_message": str(error),
-                    "error_type": type(error).__name__,
-                    "stack_trace": stack_trace,
-                },
+            error_data = {
+                "error_message": str(error),
+                "error_type": type(error).__name__,
+                "stack_trace": stack_trace,
+            }
+
+            await self.storage.append_history(
+                instance_id=instance_id,
+                activity_id="workflow_failed",
+                event_type="WorkflowFailed",
+                event_data=error_data,
             )
+
+            # Mark as failed with detailed error information
+            await ctx._update_status("failed", error_data)
             raise
 
     async def resume_by_name(
@@ -775,15 +787,21 @@ class ReplayEngine:
                     traceback.format_exception(type(error), error, error.__traceback__)
                 )
 
-                await ctx._update_status(
-                    "failed",
-                    {
-                        "error_message": str(error),
-                        "error_type": type(error).__name__,
-                        "stack_trace": stack_trace,
-                    },
+                error_data = {
+                    "error_message": str(error),
+                    "error_type": type(error).__name__,
+                    "stack_trace": stack_trace,
+                }
+
+                await self.storage.append_history(
+                    instance_id=new_instance_id,
+                    activity_id="workflow_failed",
+                    event_type="WorkflowFailed",
+                    event_data=error_data,
                 )
 
+                await ctx._update_status("failed", error_data)
+
                 if self.hooks and hasattr(self.hooks, "on_workflow_failed"):
                     await self.hooks.on_workflow_failed(new_instance_id, workflow_name, error)
 

{edda_framework-0.12.0 → edda_framework-0.14.0}/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.12.0 → edda_framework-0.14.0}/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.12.0 → edda_framework-0.14.0}/edda/viewer_ui/app.py

@@ -309,6 +309,10 @@ def start_viewer(edda_app: EddaApp, port: int = 8080, reload: bool = False) -> N
                     all_workflows = service.get_all_workflows()
                     workflow_names = list(all_workflows.keys())
 
+                    workflow_select: Any = None
+                    params_container: Any = None
+                    param_fields: dict[str, Any] = {}
+
                     if not workflow_names:
                         ui.label("No workflows registered").classes("text-red-500")
                         ui.button("Close", on_click=start_dialog.close)
@@ -323,9 +327,6 @@ def start_viewer(edda_app: EddaApp, port: int = 8080, reload: bool = False) -> N
                         # Container for dynamic parameter fields
                         params_container = ui.column().classes("w-full mb-4")
 
-                        # Store input field references
-                        param_fields: dict[str, Any] = {}
-
                     # Factory functions for creating field managers with proper closures
                     # These must be defined outside the loop to avoid closure issues
 
@@ -778,6 +779,8 @@ def start_viewer(edda_app: EddaApp, port: int = 8080, reload: bool = False) -> N
 
                     def update_parameter_fields() -> None:
                         """Update parameter input fields based on selected workflow."""
+                        if workflow_select is None or params_container is None:
+                            return
                         selected_workflow = workflow_select.value
                         if not selected_workflow:
                             return
@@ -1106,13 +1109,17 @@ def start_viewer(edda_app: EddaApp, port: int = 8080, reload: bool = False) -> N
                     update_parameter_fields()
 
                     # Update fields when workflow selection changes
-                    workflow_select.on_value_change(lambda _: update_parameter_fields())
+                    if workflow_select is not None:
+                        workflow_select.on_value_change(lambda _: update_parameter_fields())
 
                     # Action buttons
                     with ui.row().classes("w-full gap-2"):
 
                         async def handle_start() -> None:
                             """Handle workflow start."""
+                            if workflow_select is None:
+                                ui.notify("No workflows available", type="negative")
+                                return
                             try:
                                 selected_workflow = workflow_select.value
                                 if not selected_workflow:

{edda_framework-0.12.0 → edda_framework-0.14.0}/pyproject.toml

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

{edda_framework-0.12.0 → edda_framework-0.14.0}/schema/README.md

@@ -48,6 +48,10 @@ dbmate status   # Check migration status
 dbmate down     # Rollback latest migration
 ```
 
+## Documentation
+
+- [Column Values Reference](docs/column-values.md) - Standard values for database columns across all implementations
+
 ## License
 
 MIT

edda_framework-0.14.0/schema/docs/column-values.md

@@ -0,0 +1,91 @@
+# Database Column Values Reference
+
+This document defines the standard values for database columns that must be consistent across all Durax framework implementations (Edda/Python, Romancy/Go, etc.).
+
+## workflow_instances.status
+
+| Value | Description |
+|-------|-------------|
+| `running` | Workflow is actively executing |
+| `completed` | Workflow finished successfully |
+| `failed` | Workflow failed with an error |
+| `cancelled` | Workflow was cancelled by user |
+| `waiting_for_event` | Workflow is waiting for an external event (via `wait_event`) |
+| `waiting_for_timer` | Workflow is waiting for a timer to expire (via `sleep`/`sleep_until`) |
+| `waiting_for_message` | Workflow is waiting for a channel message (via `receive`) |
+| `recurred` | Workflow completed one iteration and is ready to restart (Erlang-style tail recursion) |
+| `compensating` | Workflow is executing compensation handlers |
+
+## workflow_history.event_type
+
+All event types use **PascalCase** for cross-language consistency.
+
+| Value | Description |
+|-------|-------------|
+| `ActivityCompleted` | An activity finished successfully |
+| `ActivityFailed` | An activity failed with an error |
+| `EventReceived` | An external event was received (via `wait_event`) |
+| `TimerExpired` | A timer expired (via `sleep`/`sleep_until`) |
+| `ChannelMessageReceived` | A channel message was received (via `receive`) |
+| `MessageTimeout` | A channel message receive timed out |
+| `CompensationExecuted` | A compensation handler executed successfully |
+| `CompensationFailed` | A compensation handler failed |
+| `WorkflowFailed` | The workflow failed (recorded before status update) |
+| `WorkflowCancelled` | The workflow was cancelled |
+
+## workflow_history.data_type
+
+| Value | Description |
+|-------|-------------|
+| `json` | Event data is stored as JSON text in `event_data` column |
+| `binary` | Event data is stored as raw bytes in `event_data_binary` column |
+
+## channel_subscriptions.mode
+
+| Value | Description |
+|-------|-------------|
+| `broadcast` | All subscribers receive a copy of each message |
+| `competing` | Only one subscriber receives each message (work queue pattern) |
+
+## channel_messages.data_type
+
+| Value | Description |
+|-------|-------------|
+| `json` | Message data is stored as JSON text in `data` column |
+| `binary` | Message data is stored as raw bytes in `data_binary` column |
+
+## outbox_events.status
+
+| Value | Description |
+|-------|-------------|
+| `pending` | Event is waiting to be published |
+| `processing` | Event is currently being processed by the relayer |
+| `published` | Event was successfully published |
+| `failed` | Event publishing failed after all retries |
+| `invalid` | Event is malformed and cannot be published |
+| `expired` | Event expired before it could be published |
+
+## workflow_instances.framework
+
+| Value | Description |
+|-------|-------------|
+| `python` | Workflow is managed by Edda (Python) |
+| `go` | Workflow is managed by Romancy (Go) |
+
+This column enables cross-language interoperability: any framework can deliver messages to workflows managed by other frameworks, while each framework only processes (replays/resumes) its own workflows.
+
+---
+
+## Cross-Language Compatibility Notes
+
+1. **Event type naming**: Always use PascalCase (e.g., `ActivityCompleted`, not `activity_completed`)
+
+2. **Message delivery**: Any framework can deliver channel messages to any workflow, regardless of the target workflow's framework. The delivering framework:
+   - Acquires a lock on the target workflow
+   - Records the message in `workflow_history` with the correct `event_type`
+   - Updates the workflow status to `running`
+   - Releases the lock
+
+3. **Workflow processing**: Each framework only processes workflows where `framework` matches its own identifier. This ensures correct replay behavior.
+
+4. **Activity IDs**: Both frameworks use the format `{activity_name}:{counter}` for deterministic replay (e.g., `fetch_data:1`, `receive_orders:2`).

edda_framework-0.14.0/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