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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.8.0
+Version: 0.9.0
 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.0}/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.0}/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.0}/docs/core-features/messages.md

@@ -496,6 +496,80 @@ 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.0}/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.0}/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.0}/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
 
@@ -451,6 +451,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.0}/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

{edda_framework-0.8.0 → edda_framework-0.9.0}/edda/storage/protocol.py

@@ -5,6 +5,7 @@ This module defines the StorageProtocol using Python's structural typing (Protoc
 Any storage implementation that conforms to this protocol can be used with Edda.
 """
 
+from collections.abc import Awaitable, Callable
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
@@ -104,6 +105,21 @@ class StorageProtocol(Protocol):
         """
         ...
 
+    def register_post_commit_callback(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.
+
+        Args:
+            callback: An async function to call after commit.
+
+        Raises:
+            RuntimeError: If not in a transaction.
+        """
+        ...
+
     # -------------------------------------------------------------------------
     # Workflow Definition Methods
     # -------------------------------------------------------------------------
@@ -713,39 +729,6 @@ class StorageProtocol(Protocol):
     # Message Subscription Methods (for wait_message)
     # -------------------------------------------------------------------------
 
-    async def register_message_subscription_and_release_lock(
-        self,
-        instance_id: str,
-        worker_id: str,
-        channel: str,
-        timeout_at: datetime | None = None,
-        activity_id: str | None = None,
-    ) -> None:
-        """
-        Atomically register message subscription and release workflow lock.
-
-        This method performs the following operations in a SINGLE database transaction:
-        1. Register message subscription (INSERT into workflow_message_subscriptions)
-        2. Update current activity (UPDATE workflow_instances.current_activity_id)
-        3. Update status to 'waiting_for_event'
-        4. Release lock (UPDATE workflow_instances set locked_by=NULL)
-
-        This ensures that when a workflow calls wait_message(), the subscription is
-        registered and the lock is released atomically, preventing race conditions
-        in distributed environments (distributed coroutines pattern).
-
-        Args:
-            instance_id: Workflow instance ID
-            worker_id: Worker ID that currently holds the lock
-            channel: Channel name to wait on
-            timeout_at: Optional timeout timestamp
-            activity_id: Current activity ID to record
-
-        Raises:
-            RuntimeError: If the worker doesn't hold the lock (sanity check)
-        """
-        ...
-
     async def find_waiting_instances_by_channel(
         self,
         channel: str,
@@ -911,9 +894,8 @@ class StorageProtocol(Protocol):
 
         Removes entries from:
         - workflow_timer_subscriptions
-        - workflow_message_subscriptions
-        - channel_subscriptions (new)
-        - channel_message_claims (new)
+        - channel_subscriptions
+        - channel_message_claims
 
         Args:
             instance_id: Workflow instance ID to clean up