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

{edda_framework-0.7.0 → edda_framework-0.9.0}/Justfile

@@ -31,18 +31,22 @@ test-file FILE:
 
 # Format code with black
 format:
+    @uv sync --extra dev --quiet
     uv run black edda tests
 
 # Check code formatting
 format-check:
+    @uv sync --extra dev --quiet
     uv run black --check edda tests
 
 # Lint code with ruff
 lint:
+    @uv sync --extra dev --quiet
     uv run ruff check edda tests
 
 # Type check with mypy
 type-check:
+    @uv sync --extra dev --quiet
     uv run mypy edda
 
 # Run all checks (format, lint, type-check, test)
@@ -50,6 +54,7 @@ check: format-check lint type-check test
 
 # Auto-fix issues (format + lint with auto-fix)
 fix:
+    @uv sync --extra dev --quiet
     uv run black edda tests
     uv run ruff check --fix edda tests
 
@@ -116,6 +121,18 @@ viewer-demo DB='demo.db' PORT='8080':
     just viewer {{DB}} {{PORT}} "--import-module demo_app"
 
 
+# Build documentation (clears cache for fresh API reference)
+docs:
+    rm -rf .cache site
+    uv run zensical build
+
+# Serve documentation locally (clears cache for fresh API reference)
+docs-serve:
+    @lsof -ti :8000 | xargs kill -15 2>/dev/null || true
+    @sleep 1
+    rm -rf .cache site
+    uv run zensical serve
+
 # Clean build artifacts and caches
 clean:
     rm -rf .pytest_cache
@@ -123,9 +140,102 @@ clean:
     rm -rf .coverage
     rm -rf .mypy_cache
     rm -rf .ruff_cache
+    rm -rf .cache
+    rm -rf site
     rm -rf dist
     rm -rf build
     rm -rf *.egg-info
     find . -type d -name __pycache__ -exec rm -rf {} +
     find . -type f -name "*.pyc" -delete
     rm -f demo.db
+
+# Helper recipe for point-to-point test (uses bash for command substitution)
+_test-point-to-point LOG_FILE:
+    #!/usr/bin/env bash
+    set -e
+    echo "=== Test 3: Point-to-Point Mode (Direct Message) ==="
+    echo "Starting receiver..."
+    curl -s -X POST http://localhost:8001/ \
+        -H "Content-Type: application/cloudevents+json" \
+        -d '{"specversion":"1.0","type":"direct_message_receiver_workflow","source":"test","id":"receiver-1","data":{"receiver_id":"receiver-1"}}' > /dev/null
+    sleep 2
+    # Parse instance_id from server log (format: [RECEIVER] Instance ID: workflow-uuid)
+    # Strip ANSI color codes before grepping
+    INSTANCE_ID=$(sed 's/\x1b\[[0-9;]*m//g' "{{LOG_FILE}}" | grep -o '\[RECEIVER\] Instance ID: [^ ]*' | tail -1 | cut -d' ' -f4)
+    echo "Receiver instance_id: $INSTANCE_ID"
+    if [ -z "$INSTANCE_ID" ]; then
+        echo "ERROR: Could not extract instance_id from server log"
+        echo "Log content (stripped):"
+        sed 's/\x1b\[[0-9;]*m//g' "{{LOG_FILE}}" | grep -i receiver || echo "(no receiver logs found)"
+        exit 1
+    fi
+    echo "Sending direct message to receiver..."
+    curl -s -X POST http://localhost:8001/ \
+        -H "Content-Type: application/cloudevents+json" \
+        -d "{\"specversion\":\"1.0\",\"type\":\"direct_message_sender_workflow\",\"source\":\"test\",\"id\":\"sender-1\",\"data\":{\"target_instance_id\":\"$INSTANCE_ID\",\"message\":\"Hello from sender!\"}}"
+    echo ""
+    sleep 5
+    # Verify receiver got the message (strip ANSI codes)
+    if sed 's/\x1b\[[0-9;]*m//g' "{{LOG_FILE}}" | grep -q "\[RECEIVER\] Received message:"; then
+        echo "✓ Point-to-Point message delivered successfully!"
+    else
+        echo "✗ Point-to-Point message delivery failed"
+    fi
+
+# Test message passing (competing, broadcast, and point-to-point modes)
+test-messages:
+    #!/usr/bin/env bash
+    set -e
+    LOG_FILE=$(mktemp)
+    echo "=== Message Passing Test ==="
+    echo "Server log: $LOG_FILE"
+    echo "Starting demo app in background..."
+    rm -f demo.db
+    uv sync --extra server --quiet
+    PYTHONUNBUFFERED=1 uv run tsuno demo_app:application --bind 127.0.0.1:8001 --workers 1 > "$LOG_FILE" 2>&1 &
+    SERVER_PID=$!
+    sleep 2
+
+    echo ""
+    echo "=== Test 1: Competing Mode (Job Worker) ==="
+    echo "Starting worker..."
+    curl -s -X POST http://localhost:8001/ \
+        -H "Content-Type: application/cloudevents+json" \
+        -d '{"specversion":"1.0","type":"job_worker_workflow","source":"test","id":"worker-1","data":{"worker_id":"worker-1"}}'
+    echo ""
+    sleep 1
+    echo "Publishing job..."
+    curl -s -X POST http://localhost:8001/ \
+        -H "Content-Type: application/cloudevents+json" \
+        -d '{"specversion":"1.0","type":"job_publisher_workflow","source":"test","id":"job-1","data":{"task":"test-task"}}'
+    echo ""
+    sleep 2
+
+    echo ""
+    echo "=== Test 2: Broadcast Mode (Notification) ==="
+    echo "Starting notification service..."
+    curl -s -X POST http://localhost:8001/ \
+        -H "Content-Type: application/cloudevents+json" \
+        -d '{"specversion":"1.0","type":"notification_service_workflow","source":"test","id":"service-1","data":{"service_id":"service-1"}}'
+    echo ""
+    sleep 1
+    echo "Publishing notification..."
+    curl -s -X POST http://localhost:8001/ \
+        -H "Content-Type: application/cloudevents+json" \
+        -d '{"specversion":"1.0","type":"notification_publisher_workflow","source":"test","id":"notification-1","data":{"message":"Test notification"}}'
+    echo ""
+    sleep 2
+
+    just _test-point-to-point "$LOG_FILE"
+
+    echo ""
+    echo "=== Stopping demo app ==="
+    kill -15 $SERVER_PID 2>/dev/null || true
+    sleep 1
+
+    echo ""
+    echo "=== Server Log ==="
+    cat "$LOG_FILE"
+    rm -f "$LOG_FILE"
+    echo ""
+    echo "Done!"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.7.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
 
@@ -85,6 +86,7 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - 📦 **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
+- 📬 **Channel-based Messaging**: Actor-model style communication with competing (job queue) and broadcast (fan-out) modes
 - 🤖 **MCP Integration**: Expose durable workflows as AI tools via Model Context Protocol
 - 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
@@ -107,14 +109,14 @@ Edda's waiting functions make it ideal for time-based and event-driven business
 - **📦 Scheduled Notifications**: Shipping updates, subscription renewals, appointment reminders
 
 **Waiting functions**:
-- `wait_timer(duration_seconds)`: Wait for a relative duration
-- `wait_until(until_time)`: Wait until an absolute datetime (e.g., campaign end date)
+- `sleep(seconds)`: Wait for a relative duration
+- `sleep_until(target_time)`: Wait until an absolute datetime (e.g., campaign end date)
 - `wait_event(event_type)`: Wait for external events (near real-time response)
 
 ```python
 @workflow
 async def onboarding_reminder(ctx: WorkflowContext, user_id: str):
-    await wait_timer(ctx, duration_seconds=3*24*60*60)  # Wait 3 days
+    await sleep(ctx, seconds=3*24*60*60)  # Wait 3 days
     if not await check_completed(ctx, user_id):
         await send_reminder(ctx, user_id)
 ```
@@ -166,7 +168,7 @@ graph TB
 
 - Multiple workers can run simultaneously across different pods/servers
 - Each workflow instance runs on only one worker at a time (automatic coordination)
-- `wait_event()` and `wait_timer()` free up worker resources while waiting, resume on any worker when event arrives or timer expires
+- `wait_event()` and `sleep()` free up worker resources while waiting, resume on any worker when event arrives or timer expires
 - Automatic crash recovery with stale lock cleanup and workflow auto-resume
 
 ## Quick Start
@@ -486,7 +488,10 @@ Multiple workers can safely process workflows using database-based exclusive con
 
 app = EddaApp(
     db_url="postgresql://localhost/workflows",  # Shared database for coordination
-    service_name="order-service"
+    service_name="order-service",
+    # Connection pool settings (optional)
+    pool_size=5,        # Concurrent connections
+    max_overflow=10,    # Additional burst capacity
 )
 ```
 
@@ -614,10 +619,32 @@ async def payment_workflow(ctx: WorkflowContext, order_id: str):
     return payment_event.data
 ```
 
-**wait_timer() for time-based waiting**:
+**ReceivedEvent attributes**: The `wait_event()` function returns a `ReceivedEvent` object:
+
+```python
+event = await wait_event(ctx, "payment.completed")
+amount = event.data["amount"]           # Event payload (dict or bytes)
+source = event.metadata.source          # CloudEvents source
+event_type = event.metadata.type        # CloudEvents type
+extensions = event.extensions           # CloudEvents extensions
+```
+
+**Timeout handling with EventTimeoutError**:
+
+```python
+from edda import wait_event, EventTimeoutError
+
+try:
+    event = await wait_event(ctx, "payment.completed", timeout_seconds=60)
+except EventTimeoutError:
+    # Handle timeout (e.g., cancel order, send reminder)
+    await cancel_order(ctx, order_id)
+```
+
+**sleep() for time-based waiting**:
 
 ```python
-from edda import wait_timer
+from edda import sleep
 
 @workflow
 async def order_with_timeout(ctx: WorkflowContext, order_id: str):
@@ -625,7 +652,7 @@ async def order_with_timeout(ctx: WorkflowContext, order_id: str):
     await create_order(ctx, order_id)
 
     # Wait 60 seconds for payment
-    await wait_timer(ctx, duration_seconds=60)
+    await sleep(ctx, seconds=60)
 
     # Check payment status
     return await check_payment(ctx, order_id)
@@ -639,6 +666,79 @@ async def order_with_timeout(ctx: WorkflowContext, order_id: str):
 
 **For technical details**, see [Multi-Worker Continuations](local-docs/distributed-coroutines.md).
 
+### Channel-based Messaging
+
+Edda provides channel-based messaging for workflow-to-workflow communication with two delivery modes:
+
+```python
+from edda import workflow, subscribe, receive, publish, send_to, WorkflowContext
+
+# Job Worker - processes jobs exclusively (competing mode)
+@workflow
+async def job_worker(ctx: WorkflowContext, worker_id: str):
+    # Subscribe with competing mode - each job goes to ONE worker only
+    await subscribe(ctx, channel="jobs", mode="competing")
+
+    while True:
+        job = await receive(ctx, channel="jobs")  # Get next job
+        await process_job(ctx, job.data)
+        await ctx.recur(worker_id)  # Continue processing
+
+# Notification Handler - receives ALL messages (broadcast mode)
+@workflow
+async def notification_handler(ctx: WorkflowContext, handler_id: str):
+    # Subscribe with broadcast mode - ALL handlers receive each message
+    await subscribe(ctx, channel="notifications", mode="broadcast")
+
+    while True:
+        msg = await receive(ctx, channel="notifications")
+        await send_notification(ctx, msg.data)
+        await ctx.recur(handler_id)
+
+# 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**:
+- **`competing`**: Each message goes to exactly ONE subscriber (job queue/task distribution)
+- **`broadcast`**: Each message goes to ALL subscribers (notifications/fan-out)
+
+**Key features**:
+- **Channel-based messaging**: Messages are delivered to workflows waiting on specific channels
+- **Competing vs Broadcast**: Choose semantics per subscription
+- **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
+
+### Workflow Recurrence
+
+Long-running workflows can use `ctx.recur()` to restart with fresh history while maintaining the same instance ID. This is essential for workflows that run indefinitely (job workers, notification handlers, etc.):
+
+```python
+from edda import workflow, subscribe, receive, WorkflowContext
+
+@workflow
+async def job_worker(ctx: WorkflowContext, worker_id: str):
+    await subscribe(ctx, channel="jobs", mode="competing")
+
+    # Process one job
+    job = await receive(ctx, channel="jobs")
+    await process_job(ctx, job.data)
+
+    # Archive history and restart with same instance_id
+    # Prevents unbounded history growth
+    await ctx.recur(worker_id)
+```
+
+**Key benefits**:
+- **Prevents history growth**: Archives old history, starts fresh
+- **Maintains instance ID**: Same workflow continues logically
+- **Preserves subscriptions**: Channel subscriptions survive recurrence
+- **Enables infinite loops**: Essential for long-running workers
+
 ### ASGI Integration
 
 Edda runs as an ASGI application:

{edda_framework-0.7.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
 
@@ -27,6 +28,7 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - 📦 **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
+- 📬 **Channel-based Messaging**: Actor-model style communication with competing (job queue) and broadcast (fan-out) modes
 - 🤖 **MCP Integration**: Expose durable workflows as AI tools via Model Context Protocol
 - 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
@@ -49,14 +51,14 @@ Edda's waiting functions make it ideal for time-based and event-driven business
 - **📦 Scheduled Notifications**: Shipping updates, subscription renewals, appointment reminders
 
 **Waiting functions**:
-- `wait_timer(duration_seconds)`: Wait for a relative duration
-- `wait_until(until_time)`: Wait until an absolute datetime (e.g., campaign end date)
+- `sleep(seconds)`: Wait for a relative duration
+- `sleep_until(target_time)`: Wait until an absolute datetime (e.g., campaign end date)
 - `wait_event(event_type)`: Wait for external events (near real-time response)
 
 ```python
 @workflow
 async def onboarding_reminder(ctx: WorkflowContext, user_id: str):
-    await wait_timer(ctx, duration_seconds=3*24*60*60)  # Wait 3 days
+    await sleep(ctx, seconds=3*24*60*60)  # Wait 3 days
     if not await check_completed(ctx, user_id):
         await send_reminder(ctx, user_id)
 ```
@@ -108,7 +110,7 @@ graph TB
 
 - Multiple workers can run simultaneously across different pods/servers
 - Each workflow instance runs on only one worker at a time (automatic coordination)
-- `wait_event()` and `wait_timer()` free up worker resources while waiting, resume on any worker when event arrives or timer expires
+- `wait_event()` and `sleep()` free up worker resources while waiting, resume on any worker when event arrives or timer expires
 - Automatic crash recovery with stale lock cleanup and workflow auto-resume
 
 ## Quick Start
@@ -428,7 +430,10 @@ Multiple workers can safely process workflows using database-based exclusive con
 
 app = EddaApp(
     db_url="postgresql://localhost/workflows",  # Shared database for coordination
-    service_name="order-service"
+    service_name="order-service",
+    # Connection pool settings (optional)
+    pool_size=5,        # Concurrent connections
+    max_overflow=10,    # Additional burst capacity
 )
 ```
 
@@ -556,10 +561,32 @@ async def payment_workflow(ctx: WorkflowContext, order_id: str):
     return payment_event.data
 ```
 
-**wait_timer() for time-based waiting**:
+**ReceivedEvent attributes**: The `wait_event()` function returns a `ReceivedEvent` object:
+
+```python
+event = await wait_event(ctx, "payment.completed")
+amount = event.data["amount"]           # Event payload (dict or bytes)
+source = event.metadata.source          # CloudEvents source
+event_type = event.metadata.type        # CloudEvents type
+extensions = event.extensions           # CloudEvents extensions
+```
+
+**Timeout handling with EventTimeoutError**:
+
+```python
+from edda import wait_event, EventTimeoutError
+
+try:
+    event = await wait_event(ctx, "payment.completed", timeout_seconds=60)
+except EventTimeoutError:
+    # Handle timeout (e.g., cancel order, send reminder)
+    await cancel_order(ctx, order_id)
+```
+
+**sleep() for time-based waiting**:
 
 ```python
-from edda import wait_timer
+from edda import sleep
 
 @workflow
 async def order_with_timeout(ctx: WorkflowContext, order_id: str):
@@ -567,7 +594,7 @@ async def order_with_timeout(ctx: WorkflowContext, order_id: str):
     await create_order(ctx, order_id)
 
     # Wait 60 seconds for payment
-    await wait_timer(ctx, duration_seconds=60)
+    await sleep(ctx, seconds=60)
 
     # Check payment status
     return await check_payment(ctx, order_id)
@@ -581,6 +608,79 @@ async def order_with_timeout(ctx: WorkflowContext, order_id: str):
 
 **For technical details**, see [Multi-Worker Continuations](local-docs/distributed-coroutines.md).
 
+### Channel-based Messaging
+
+Edda provides channel-based messaging for workflow-to-workflow communication with two delivery modes:
+
+```python
+from edda import workflow, subscribe, receive, publish, send_to, WorkflowContext
+
+# Job Worker - processes jobs exclusively (competing mode)
+@workflow
+async def job_worker(ctx: WorkflowContext, worker_id: str):
+    # Subscribe with competing mode - each job goes to ONE worker only
+    await subscribe(ctx, channel="jobs", mode="competing")
+
+    while True:
+        job = await receive(ctx, channel="jobs")  # Get next job
+        await process_job(ctx, job.data)
+        await ctx.recur(worker_id)  # Continue processing
+
+# Notification Handler - receives ALL messages (broadcast mode)
+@workflow
+async def notification_handler(ctx: WorkflowContext, handler_id: str):
+    # Subscribe with broadcast mode - ALL handlers receive each message
+    await subscribe(ctx, channel="notifications", mode="broadcast")
+
+    while True:
+        msg = await receive(ctx, channel="notifications")
+        await send_notification(ctx, msg.data)
+        await ctx.recur(handler_id)
+
+# 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**:
+- **`competing`**: Each message goes to exactly ONE subscriber (job queue/task distribution)
+- **`broadcast`**: Each message goes to ALL subscribers (notifications/fan-out)
+
+**Key features**:
+- **Channel-based messaging**: Messages are delivered to workflows waiting on specific channels
+- **Competing vs Broadcast**: Choose semantics per subscription
+- **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
+
+### Workflow Recurrence
+
+Long-running workflows can use `ctx.recur()` to restart with fresh history while maintaining the same instance ID. This is essential for workflows that run indefinitely (job workers, notification handlers, etc.):
+
+```python
+from edda import workflow, subscribe, receive, WorkflowContext
+
+@workflow
+async def job_worker(ctx: WorkflowContext, worker_id: str):
+    await subscribe(ctx, channel="jobs", mode="competing")
+
+    # Process one job
+    job = await receive(ctx, channel="jobs")
+    await process_job(ctx, job.data)
+
+    # Archive history and restart with same instance_id
+    # Prevents unbounded history growth
+    await ctx.recur(worker_id)
+```
+
+**Key benefits**:
+- **Prevents history growth**: Archives old history, starts fresh
+- **Maintains instance ID**: Same workflow continues logically
+- **Preserves subscriptions**: Channel subscriptions survive recurrence
+- **Enables infinite loops**: Essential for long-running workers
+
 ### ASGI Integration
 
 Edda runs as an ASGI application: