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

{edda_framework-0.8.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.8.0 → edda_framework-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.8.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
@@ -65,6 +65,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![Documentation](https://img.shields.io/badge/docs-latest-green.svg)](https://i2y.github.io/edda/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/i2y/edda)
 
 ## Overview
 
@@ -665,72 +666,12 @@ async def order_with_timeout(ctx: WorkflowContext, order_id: str):
 
 **For technical details**, see [Multi-Worker Continuations](local-docs/distributed-coroutines.md).
 
-### Message Passing (Workflow-to-Workflow)
+### Channel-based Messaging
 
-Edda provides actor-model style message passing for direct workflow-to-workflow communication:
+Edda provides channel-based messaging for workflow-to-workflow communication with two delivery modes:
 
 ```python
-from edda import workflow, wait_message, send_message_to, WorkflowContext
-
-# Receiver workflow - waits for approval message
-@workflow
-async def approval_workflow(ctx: WorkflowContext, request_id: str):
-    # Wait for message on "approval" channel
-    msg = await wait_message(ctx, channel="approval")
-
-    if msg.data["approved"]:
-        return {"status": "approved", "approver": msg.data["approver"]}
-    return {"status": "rejected"}
-
-# Sender workflow - sends approval decision
-@workflow
-async def manager_workflow(ctx: WorkflowContext, request_id: str):
-    # Review and make decision
-    decision = await review_request(ctx, request_id)
-
-    # Send message to waiting workflow
-    await send_message_to(
-        ctx,
-        target_instance_id=request_id,
-        channel="approval",
-        data={"approved": decision, "approver": "manager-123"},
-    )
-```
-
-**Group Communication (Erlang pg style)** - for fan-out messaging without knowing receiver instance IDs:
-
-```python
-from edda import workflow, join_group, wait_message, publish_to_group
-
-# Receiver workflow - joins a group and listens
-@workflow
-async def notification_service(ctx: WorkflowContext, service_id: str):
-    # Join group at startup (loose coupling - sender doesn't need to know us)
-    await join_group(ctx, group="order_watchers")
-
-    while True:
-        msg = await wait_message(ctx, channel="order.created")
-        await send_notification(ctx, msg.data)
-
-# Sender workflow - publishes to all group members
-@workflow
-async def order_processor(ctx: WorkflowContext, order_id: str):
-    result = await process_order(ctx, order_id)
-
-    # Broadcast to all watchers (doesn't need to know instance IDs)
-    count = await publish_to_group(
-        ctx,
-        group="order_watchers",
-        channel="order.created",
-        data={"order_id": order_id, "status": "completed"},
-    )
-    print(f"Notified {count} watchers")
-```
-
-**Channel API with Delivery Modes** - subscribe to channels with explicit delivery semantics:
-
-```python
-from edda import workflow, subscribe, receive, publish, WorkflowContext
+from edda import workflow, subscribe, receive, publish, send_to, WorkflowContext
 
 # Job Worker - processes jobs exclusively (competing mode)
 @workflow
@@ -754,8 +695,11 @@ async def notification_handler(ctx: WorkflowContext, handler_id: str):
         await send_notification(ctx, msg.data)
         await ctx.recur(handler_id)
 
-# Publisher - send messages to channel
+# Publish to channel (all subscribers or one competing subscriber)
 await publish(ctx, channel="jobs", data={"task": "send_report"})
+
+# Direct message to specific workflow instance
+await send_to(ctx, instance_id="workflow-123", channel="approval", data={"approved": True})
 ```
 
 **Delivery modes**:
@@ -765,7 +709,7 @@ await publish(ctx, channel="jobs", data={"task": "send_report"})
 **Key features**:
 - **Channel-based messaging**: Messages are delivered to workflows waiting on specific channels
 - **Competing vs Broadcast**: Choose semantics per subscription
-- **Group communication**: Erlang pg-style groups for loose coupling and fan-out
+- **Direct messaging**: `send_to()` for workflow-to-workflow communication
 - **Database-backed**: All messages are persisted for durability
 - **Lock-first delivery**: Safe for multi-worker environments
 

{edda_framework-0.8.0 → edda_framework-0.9.1}/README.md

@@ -7,6 +7,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![Documentation](https://img.shields.io/badge/docs-latest-green.svg)](https://i2y.github.io/edda/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/i2y/edda)
 
 ## Overview
 
@@ -607,72 +608,12 @@ async def order_with_timeout(ctx: WorkflowContext, order_id: str):
 
 **For technical details**, see [Multi-Worker Continuations](local-docs/distributed-coroutines.md).
 
-### Message Passing (Workflow-to-Workflow)
+### Channel-based Messaging
 
-Edda provides actor-model style message passing for direct workflow-to-workflow communication:
+Edda provides channel-based messaging for workflow-to-workflow communication with two delivery modes:
 
 ```python
-from edda import workflow, wait_message, send_message_to, WorkflowContext
-
-# Receiver workflow - waits for approval message
-@workflow
-async def approval_workflow(ctx: WorkflowContext, request_id: str):
-    # Wait for message on "approval" channel
-    msg = await wait_message(ctx, channel="approval")
-
-    if msg.data["approved"]:
-        return {"status": "approved", "approver": msg.data["approver"]}
-    return {"status": "rejected"}
-
-# Sender workflow - sends approval decision
-@workflow
-async def manager_workflow(ctx: WorkflowContext, request_id: str):
-    # Review and make decision
-    decision = await review_request(ctx, request_id)
-
-    # Send message to waiting workflow
-    await send_message_to(
-        ctx,
-        target_instance_id=request_id,
-        channel="approval",
-        data={"approved": decision, "approver": "manager-123"},
-    )
-```
-
-**Group Communication (Erlang pg style)** - for fan-out messaging without knowing receiver instance IDs:
-
-```python
-from edda import workflow, join_group, wait_message, publish_to_group
-
-# Receiver workflow - joins a group and listens
-@workflow
-async def notification_service(ctx: WorkflowContext, service_id: str):
-    # Join group at startup (loose coupling - sender doesn't need to know us)
-    await join_group(ctx, group="order_watchers")
-
-    while True:
-        msg = await wait_message(ctx, channel="order.created")
-        await send_notification(ctx, msg.data)
-
-# Sender workflow - publishes to all group members
-@workflow
-async def order_processor(ctx: WorkflowContext, order_id: str):
-    result = await process_order(ctx, order_id)
-
-    # Broadcast to all watchers (doesn't need to know instance IDs)
-    count = await publish_to_group(
-        ctx,
-        group="order_watchers",
-        channel="order.created",
-        data={"order_id": order_id, "status": "completed"},
-    )
-    print(f"Notified {count} watchers")
-```
-
-**Channel API with Delivery Modes** - subscribe to channels with explicit delivery semantics:
-
-```python
-from edda import workflow, subscribe, receive, publish, WorkflowContext
+from edda import workflow, subscribe, receive, publish, send_to, WorkflowContext
 
 # Job Worker - processes jobs exclusively (competing mode)
 @workflow
@@ -696,8 +637,11 @@ async def notification_handler(ctx: WorkflowContext, handler_id: str):
         await send_notification(ctx, msg.data)
         await ctx.recur(handler_id)
 
-# Publisher - send messages to channel
+# Publish to channel (all subscribers or one competing subscriber)
 await publish(ctx, channel="jobs", data={"task": "send_report"})
+
+# Direct message to specific workflow instance
+await send_to(ctx, instance_id="workflow-123", channel="approval", data={"approved": True})
 ```
 
 **Delivery modes**:
@@ -707,7 +651,7 @@ await publish(ctx, channel="jobs", data={"task": "send_report"})
 **Key features**:
 - **Channel-based messaging**: Messages are delivered to workflows waiting on specific channels
 - **Competing vs Broadcast**: Choose semantics per subscription
-- **Group communication**: Erlang pg-style groups for loose coupling and fan-out
+- **Direct messaging**: `send_to()` for workflow-to-workflow communication
 - **Database-backed**: All messages are persisted for durability
 - **Lock-first delivery**: Safe for multi-worker environments
 

{edda_framework-0.8.0 → edda_framework-0.9.1}/demo_app.py

@@ -1953,19 +1953,17 @@ async def job_worker_workflow(
        - Start this workflow multiple times with different worker_id values
        - Each worker will subscribe to the "jobs" channel in competing mode
 
-    2. Publish jobs to the channel:
+    2. Publish jobs using the job_publisher_workflow:
        curl -X POST http://localhost:8001/ \\
          -H "Content-Type: application/cloudevents+json" \\
          -d '{
            "specversion": "1.0",
-           "type": "job_published",
+           "type": "job_publisher_workflow",
            "source": "demo-client",
            "id": "job-1",
            "datacontenttype": "application/json",
            "data": {
-             "channel": "jobs",
-             "task": "send_report",
-             "user_id": 123
+             "task": "send_report"
            }
          }'
 
@@ -2043,19 +2041,17 @@ async def notification_service_workflow(
        - Start this workflow multiple times with different service_id values
        - Each instance will subscribe to the "notifications" channel
 
-    2. Publish a notification:
+    2. Publish a notification using the notification_publisher_workflow:
        curl -X POST http://localhost:8001/ \\
          -H "Content-Type: application/cloudevents+json" \\
          -d '{
            "specversion": "1.0",
-           "type": "notification_published",
+           "type": "notification_publisher_workflow",
            "source": "demo-client",
            "id": "notification-1",
            "datacontenttype": "application/json",
            "data": {
-             "channel": "notifications",
-             "message": "System maintenance scheduled",
-             "priority": "high"
+             "message": "System maintenance scheduled"
            }
          }'
 

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

@@ -496,6 +496,82 @@ async def temporary_subscriber(ctx: WorkflowContext):
     # Continue with other work...
 ```
 
+## Transactional Message Processing
+
+When using channel-based messaging inside activities, both `publish()` and `receive()` participate in the activity's database transaction.
+
+### Transactional Publish
+
+When `publish()` is called inside an activity, the message is only published **after the transaction commits**:
+
+```python
+@activity  # transactional=True by default
+async def process_order(ctx: WorkflowContext, order_id: str):
+    # Do some work...
+    result = await do_processing(order_id)
+
+    # Message is queued for post-commit delivery
+    await publish(ctx, "order.completed", {"order_id": order_id})
+
+    return result  # Commit: message is now published
+```
+
+**Behavior:**
+
+- If the activity **succeeds**: Message is published after commit
+- If the activity **fails**: Message is **NOT** published (rollback)
+
+This ensures that messages are only sent when the associated business logic succeeds.
+
+### Transactional Receive
+
+When `receive()` is called inside an activity, the message claim is part of the transaction:
+
+```python
+@activity  # transactional=True by default
+async def process_job(ctx: WorkflowContext, channel: str):
+    msg = await receive(ctx, channel)  # Claim is part of transaction
+
+    # Process the message...
+    result = await do_work(msg.data)
+
+    return result  # Commit: claim is finalized
+```
+
+**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
+
+This provides **at-least-once delivery** semantics - if processing fails, the message will be redelivered to another subscriber.
+
+### Recommended Pattern
+
+For reliable message processing, wrap `receive()` calls inside activities:
+
+```python
+@workflow
+async def job_worker(ctx: WorkflowContext, worker_id: str):
+    await subscribe(ctx, "jobs", mode="competing")
+
+    while True:
+        # Process job inside activity for transactional guarantees
+        await process_job(ctx, "jobs", activity_id="process:1")
+        await ctx.recur(worker_id)
+
+@activity
+async def process_job(ctx: WorkflowContext, channel: str):
+    msg = await receive(ctx, channel)  # Part of activity transaction
+
+    # Do work...
+    await execute_task(msg.data)
+
+    # Publish completion notification (also transactional)
+    await publish(ctx, "job.completed", {"job_id": msg.id})
+
+    return {"processed": msg.id}
+```
+
 ## Performance Considerations
 
 ### Database-Backed Durability

{edda_framework-0.8.0 → edda_framework-0.9.1}/docs/core-features/workflows-activities.md

@@ -764,10 +764,10 @@ In long-running loops, every activity adds an entry to the workflow history. Aft
 # ❌ Problematic: History grows forever
 @workflow
 async def notification_service(ctx: WorkflowContext):
-    await join_group(ctx, group="order_watchers")
+    await subscribe(ctx, "order.completed", mode="broadcast")
 
     while True:
-        msg = await wait_message(ctx, channel="order.completed")
+        msg = await receive(ctx, "order.completed")
         await send_notification(ctx, msg.data)
         # After 10,000 iterations: 10,000+ history entries!
 ```
@@ -780,11 +780,11 @@ Use `ctx.recur()` to restart the workflow with fresh history while preserving st
 # ✅ Good: Reset history periodically
 @workflow
 async def notification_service(ctx: WorkflowContext, processed_count: int = 0):
-    await join_group(ctx, group="order_watchers")
+    await subscribe(ctx, "order.completed", mode="broadcast")
 
     count = 0
     while True:
-        msg = await wait_message(ctx, channel="order.completed")
+        msg = await receive(ctx, "order.completed")
         await send_notification(ctx, msg.data, activity_id=f"notify:{msg.id}")
 
         count += 1

{edda_framework-0.8.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.8.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.8.0 → edda_framework-0.9.1}/edda/channels.py

@@ -445,15 +445,40 @@ async def publish(
     message_id = await storage.publish_to_channel(channel, data, full_metadata)
 
     # Wake up waiting subscribers
-    await _wake_waiting_subscribers(
-        storage,
-        channel,
-        message_id,
-        data,
-        full_metadata,
-        target_instance_id=target_instance_id,
-        worker_id=effective_worker_id,
-    )
+    # If in a transaction, defer delivery until after commit to ensure atomicity
+    if storage.in_transaction():
+        # Capture current values for the closure
+        _storage = storage
+        _channel = channel
+        _message_id = message_id
+        _data = data
+        _metadata = full_metadata
+        _target_instance_id = target_instance_id
+        _worker_id = effective_worker_id
+
+        async def deferred_wake() -> None:
+            await _wake_waiting_subscribers(
+                _storage,
+                _channel,
+                _message_id,
+                _data,
+                _metadata,
+                target_instance_id=_target_instance_id,
+                worker_id=_worker_id,
+            )
+
+        storage.register_post_commit_callback(deferred_wake)
+    else:
+        # Not in transaction - deliver immediately
+        await _wake_waiting_subscribers(
+            storage,
+            channel,
+            message_id,
+            data,
+            full_metadata,
+            target_instance_id=target_instance_id,
+            worker_id=effective_worker_id,
+        )
 
     return message_id
 

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

@@ -5,7 +5,7 @@ This module provides the WorkflowContext class for workflow execution,
 managing state, history, and replay during workflow execution.
 """
 
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, Any, cast
 
@@ -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
 
@@ -451,6 +459,33 @@ class WorkflowContext:
         """
         return self.storage.in_transaction()
 
+    def register_post_commit(self, callback: Callable[[], Awaitable[None]]) -> None:
+        """
+        Register a callback to be executed after the current transaction commits.
+
+        The callback will be executed after the top-level transaction commits successfully.
+        If the transaction is rolled back, the callback will NOT be executed.
+        This is useful for deferring side effects (like message delivery) until after
+        the transaction has been committed.
+
+        Args:
+            callback: An async function to call after commit.
+
+        Raises:
+            RuntimeError: If not in a transaction.
+
+        Example:
+            async with ctx.transaction():
+                # Save order to database
+                await ctx.storage.append_history(...)
+
+                # Defer message delivery until after commit
+                async def deliver_notifications():
+                    await notify_subscribers(order_id)
+                ctx.register_post_commit(deliver_notifications)
+        """
+        self.storage.register_post_commit_callback(callback)
+
     async def recur(self, **kwargs: Any) -> None:
         """
         Restart the workflow with fresh history (Erlang-style tail recursion).

{edda_framework-0.8.0 → edda_framework-0.9.1}/edda/storage/models.py

@@ -136,27 +136,6 @@ WORKFLOW_TIMER_SUBSCRIPTIONS_INDEXES = [
     "CREATE INDEX IF NOT EXISTS idx_timer_subscriptions_instance ON workflow_timer_subscriptions(instance_id);",
 ]
 
-# SQL schema for message subscriptions (for wait_message)
-WORKFLOW_MESSAGE_SUBSCRIPTIONS_TABLE = """
-CREATE TABLE IF NOT EXISTS workflow_message_subscriptions (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    instance_id TEXT NOT NULL,
-    channel TEXT NOT NULL,
-    activity_id TEXT,
-    timeout_at TEXT,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    FOREIGN KEY (instance_id) REFERENCES workflow_instances(instance_id) ON DELETE CASCADE,
-    CONSTRAINT unique_instance_channel UNIQUE (instance_id, channel)
-);
-"""
-
-# Indexes for message subscriptions
-WORKFLOW_MESSAGE_SUBSCRIPTIONS_INDEXES = [
-    "CREATE INDEX IF NOT EXISTS idx_message_subscriptions_channel ON workflow_message_subscriptions(channel);",
-    "CREATE INDEX IF NOT EXISTS idx_message_subscriptions_timeout ON workflow_message_subscriptions(timeout_at);",
-    "CREATE INDEX IF NOT EXISTS idx_message_subscriptions_instance ON workflow_message_subscriptions(instance_id);",
-]
-
 # SQL schema for group memberships (Erlang pg style)
 WORKFLOW_GROUP_MEMBERSHIPS_TABLE = """
 CREATE TABLE IF NOT EXISTS workflow_group_memberships (
@@ -306,7 +285,6 @@ ALL_TABLES = [
     WORKFLOW_HISTORY_ARCHIVE_TABLE,
     WORKFLOW_COMPENSATIONS_TABLE,
     WORKFLOW_TIMER_SUBSCRIPTIONS_TABLE,
-    WORKFLOW_MESSAGE_SUBSCRIPTIONS_TABLE,
     WORKFLOW_GROUP_MEMBERSHIPS_TABLE,
     OUTBOX_EVENTS_TABLE,
     # Channel-based Message Queue System
@@ -324,7 +302,6 @@ ALL_INDEXES = (
     + WORKFLOW_HISTORY_ARCHIVE_INDEXES
     + WORKFLOW_COMPENSATIONS_INDEXES
     + WORKFLOW_TIMER_SUBSCRIPTIONS_INDEXES
-    + WORKFLOW_MESSAGE_SUBSCRIPTIONS_INDEXES
     + WORKFLOW_GROUP_MEMBERSHIPS_INDEXES
     + OUTBOX_EVENTS_INDEXES
     # Channel-based Message Queue System