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

{edda_framework-0.11.0 → edda_framework-0.12.0}/.github/workflows/ci.yml

@@ -45,7 +45,9 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          submodules: true
 
       - name: Set up uv
         uses: astral-sh/setup-uv@v3

{edda_framework-0.11.0 → edda_framework-0.12.0}/.github/workflows/docs.yml

@@ -16,7 +16,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          submodules: true
 
       - name: Set up Python
         uses: actions/setup-python@v5

{edda_framework-0.11.0 → edda_framework-0.12.0}/.github/workflows/release.yml

@@ -17,7 +17,9 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          submodules: true
 
       - name: Set up uv
         uses: astral-sh/setup-uv@v3
@@ -29,7 +31,9 @@ jobs:
         run: uv sync
 
       - name: Build package
-        run: uv build
+        run: |
+          uv build --sdist
+          uv build --wheel
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1

edda_framework-0.12.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "schema"]
+	path = schema
+	url = https://github.com/durax-io/schema.git

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.11.0
+Version: 0.12.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -286,6 +286,46 @@ pip install "git+https://github.com/i2y/edda.git[postgresql,viewer]"
 
 > **Tip**: For PostgreSQL, install the `postgres-notify` extra for near-instant event delivery using LISTEN/NOTIFY instead of polling.
 
+### Database Schema Migration
+
+**Automatic Migration (Default)**
+
+Edda automatically applies database migrations at startup. No manual commands needed:
+
+```python
+from edda import EddaApp
+
+# Migrations are applied automatically
+app = EddaApp(db_url="postgresql://user:pass@localhost/dbname")
+```
+
+This is safe in multi-worker environments - Edda handles concurrent startup gracefully.
+
+**Manual Migration with dbmate (Optional)**
+
+For explicit schema control, you can disable auto-migration and use [dbmate](https://github.com/amacneil/dbmate):
+
+```python
+# Disable auto-migration
+app = EddaApp(
+    db_url="postgresql://...",
+    auto_migrate=False  # Use dbmate-managed schema
+)
+```
+
+```bash
+# Install dbmate
+brew install dbmate  # macOS
+
+# Add schema submodule
+git submodule add https://github.com/durax-io/schema.git schema
+
+# Run migration manually
+DATABASE_URL="postgresql://user:pass@localhost/dbname" dbmate -d ./schema/db/migrations/postgresql up
+```
+
+> **Note**: Edda's auto-migration uses the same SQL files as dbmate, maintaining full compatibility.
+
 ### Development Installation
 
 If you want to contribute to Edda or modify the framework itself:
@@ -293,7 +333,7 @@ If you want to contribute to Edda or modify the framework itself:
 ```bash
 # Clone repository
 git clone https://github.com/i2y/edda.git
-cd kairo
+cd edda
 uv sync --all-extras
 ```
 
@@ -333,7 +373,7 @@ async def user_signup(ctx: WorkflowContext, email: str):
     return {"status": "completed"}
 ```
 
-**Activity IDs**: Activities are automatically identified with IDs like `"send_email:1"` for deterministic replay. Manual IDs are only needed for concurrent execution (e.g., `asyncio.gather`). See [MIGRATION_GUIDE_ACTIVITY_ID.md](MIGRATION_GUIDE_ACTIVITY_ID.md) for details.
+**Activity IDs**: Activities are automatically identified with IDs like `"send_email:1"` for deterministic replay. Manual IDs are only needed for concurrent execution (e.g., `asyncio.gather`).
 
 ### Durable Execution
 

{edda_framework-0.11.0 → edda_framework-0.12.0}/README.md

@@ -221,6 +221,46 @@ pip install "git+https://github.com/i2y/edda.git[postgresql,viewer]"
 
 > **Tip**: For PostgreSQL, install the `postgres-notify` extra for near-instant event delivery using LISTEN/NOTIFY instead of polling.
 
+### Database Schema Migration
+
+**Automatic Migration (Default)**
+
+Edda automatically applies database migrations at startup. No manual commands needed:
+
+```python
+from edda import EddaApp
+
+# Migrations are applied automatically
+app = EddaApp(db_url="postgresql://user:pass@localhost/dbname")
+```
+
+This is safe in multi-worker environments - Edda handles concurrent startup gracefully.
+
+**Manual Migration with dbmate (Optional)**
+
+For explicit schema control, you can disable auto-migration and use [dbmate](https://github.com/amacneil/dbmate):
+
+```python
+# Disable auto-migration
+app = EddaApp(
+    db_url="postgresql://...",
+    auto_migrate=False  # Use dbmate-managed schema
+)
+```
+
+```bash
+# Install dbmate
+brew install dbmate  # macOS
+
+# Add schema submodule
+git submodule add https://github.com/durax-io/schema.git schema
+
+# Run migration manually
+DATABASE_URL="postgresql://user:pass@localhost/dbname" dbmate -d ./schema/db/migrations/postgresql up
+```
+
+> **Note**: Edda's auto-migration uses the same SQL files as dbmate, maintaining full compatibility.
+
 ### Development Installation
 
 If you want to contribute to Edda or modify the framework itself:
@@ -228,7 +268,7 @@ If you want to contribute to Edda or modify the framework itself:
 ```bash
 # Clone repository
 git clone https://github.com/i2y/edda.git
-cd kairo
+cd edda
 uv sync --all-extras
 ```
 
@@ -268,7 +308,7 @@ async def user_signup(ctx: WorkflowContext, email: str):
     return {"status": "completed"}
 ```
 
-**Activity IDs**: Activities are automatically identified with IDs like `"send_email:1"` for deterministic replay. Manual IDs are only needed for concurrent execution (e.g., `asyncio.gather`). See [MIGRATION_GUIDE_ACTIVITY_ID.md](MIGRATION_GUIDE_ACTIVITY_ID.md) for details.
+**Activity IDs**: Activities are automatically identified with IDs like `"send_email:1"` for deterministic replay. Manual IDs are only needed for concurrent execution (e.g., `asyncio.gather`).
 
 ### Durable Execution
 

{edda_framework-0.11.0 → edda_framework-0.12.0}/docs/core-features/durable-execution/replay.md

@@ -349,7 +349,7 @@ async def resume_workflow_endpoint(instance_id: str):
 
 Edda automatically recovers from crashes in two stages:
 
-#### 3-1. Stale Lock Cleanup (Implemented)
+#### 3-1. Stale Lock Cleanup
 
 When a worker process crashes, its locks become "stale." Edda automatically cleans these up:
 
@@ -394,7 +394,7 @@ This background task starts automatically when `EddaApp` launches.
 
 The `status` field indicates whether the workflow was running normally (`"running"`) or executing compensations (`"compensating"`) when it crashed.
 
-#### 3-2. Automatic Workflow Resume (Implemented)
+#### 3-2. Automatic Workflow Resume
 
 After cleaning stale locks, Edda automatically resumes workflows with `status="running"` or `status="compensating"`:
 
@@ -586,6 +586,7 @@ async with workflow_lock(storage, instance_id, worker_id, timeout_seconds=300):
 ```
 
 Features:
+
 - **5-minute timeout** by default (prevents indefinite locks)
 - **Worker ID tracking** (know which worker holds the lock)
 - **Stale lock cleanup** (automatic recovery after crashes)

{edda_framework-0.11.0 → edda_framework-0.12.0}/docs/core-features/messages.md

@@ -47,6 +47,40 @@ async def notification_service(ctx: WorkflowContext, service_id: str):
 
 - `"broadcast"` (default): All subscribers receive all messages. Use for fan-out patterns like notifications.
 - `"competing"`: Each message is processed by only one subscriber. Use for job queues and task distribution.
+- `"direct"`: Receive messages sent via `send_to()` to this specific instance. Syntactic sugar for point-to-point messaging.
+
+**Using `mode="direct"`**:
+
+The `"direct"` mode simplifies receiving messages sent via `send_to()`:
+
+```python
+@workflow
+async def direct_receiver(ctx: WorkflowContext, id: str):
+    # Subscribe to receive direct messages
+    await subscribe(ctx, "notifications", mode="direct")
+
+    # Wait for a message sent via send_to()
+    msg = await receive(ctx, "notifications")
+    return msg.data
+
+@workflow
+async def sender(ctx: WorkflowContext, receiver_id: str):
+    # Send directly to the receiver instance
+    await send_to(ctx, instance_id=receiver_id, data={"hello": "world"}, channel="notifications")
+```
+
+This is equivalent to manually constructing the channel name:
+
+```python
+# Without mode="direct" (manual approach)
+direct_channel = f"notifications:{ctx.instance_id}"
+await subscribe(ctx, direct_channel, mode="broadcast")
+msg = await receive(ctx, direct_channel)
+
+# With mode="direct" (simplified)
+await subscribe(ctx, "notifications", mode="direct")
+msg = await receive(ctx, "notifications")
+```
 
 #### `unsubscribe()`
 
@@ -202,7 +236,7 @@ async def subscribe(
 
 - `ctx`: Workflow context
 - `channel`: Channel name to subscribe to
-- `mode`: `"broadcast"` (all subscribers receive) or `"competing"` (one subscriber per message)
+- `mode`: `"broadcast"` (all subscribers receive), `"competing"` (one subscriber per message), or `"direct"` (receive messages from `send_to()`)
 
 ### receive()
 

{edda_framework-0.11.0 → edda_framework-0.12.0}/docs/getting-started/installation.md

@@ -310,6 +310,88 @@ app = EddaApp(
 )
 ```
 
+### Schema Migration
+
+#### Automatic Migration (Default)
+
+Edda automatically applies database migrations at startup. No manual commands needed:
+
+```python
+from edda import EddaApp
+
+# Migrations are applied automatically at startup
+app = EddaApp(
+    service_name="demo-service",
+    db_url="postgresql://user:pass@localhost/dbname"
+)
+```
+
+**Key features:**
+
+- **Zero configuration**: Works out of the box
+- **Multi-worker safe**: Handles concurrent startup gracefully (race condition protected)
+- **dbmate compatible**: Uses the same SQL files and `schema_migrations` table
+- **Incremental**: Only applies pending migrations
+
+#### Manual Migration with dbmate (Optional)
+
+For explicit schema control, you can disable auto-migration and use [dbmate](https://github.com/amacneil/dbmate):
+
+```python
+# Disable auto-migration
+app = EddaApp(
+    service_name="demo-service",
+    db_url="postgresql://...",
+    auto_migrate=False  # Use dbmate-managed schema
+)
+```
+
+```bash
+# Install dbmate
+brew install dbmate  # macOS
+# Linux: curl -fsSL https://github.com/amacneil/dbmate/releases/latest/download/dbmate-linux-amd64 -o /usr/local/bin/dbmate && chmod +x /usr/local/bin/dbmate
+
+# Add schema submodule to your project
+git submodule add https://github.com/durax-io/schema.git schema
+
+# Run migration manually
+DATABASE_URL="postgresql://user:pass@localhost/dbname" dbmate -d ./schema/db/migrations/postgresql up
+
+# Check status
+dbmate -d ./schema/db/migrations/postgresql status
+```
+
+> **Note**: Edda's auto-migration uses the same SQL files as dbmate, so you can switch between modes freely.
+
+### Multi-Worker Configuration
+
+When running multiple Edda workers (e.g., in Kubernetes or with multiple processes), Edda automatically coordinates background tasks using **leader election**. Only one worker runs maintenance tasks (timers, message cleanup, etc.) while others focus on workflow execution.
+
+```python
+from edda import EddaApp
+
+app = EddaApp(
+    service_name="demo-service",
+    db_url="postgresql://...",
+    # Leader election settings (optional - defaults work well for most cases)
+    leader_heartbeat_interval=15,  # How often workers check/renew leadership
+    leader_lease_duration=45,      # How long before a failed leader is replaced
+)
+```
+
+**Configuration options:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `leader_heartbeat_interval` | `int` | `15` | Interval in seconds for leader heartbeat |
+| `leader_lease_duration` | `int` | `45` | Duration in seconds before leadership expires |
+
+**Notes:**
+
+- Default values work well for most deployments
+- Reduce `leader_lease_duration` for faster failover (minimum: 3x heartbeat interval)
+- Leader election uses the database for coordination (no external dependencies)
+
 ## Next Steps
 
 - **[Quick Start](quick-start.md)**: Build your first workflow in 5 minutes

{edda_framework-0.11.0 → edda_framework-0.12.0}/docs/integrations/pydantic-rpc.md

@@ -189,5 +189,5 @@ These models work seamlessly with Edda's Pydantic integration for:
 - [Workflows and Activities](../core-features/workflows-activities.md)
 - [Pydantic Integration](../core-features/workflows-activities.md#pydantic-integration)
 - [Example Code](https://github.com/i2y/edda/blob/main/examples/pydantic_rpc_integration.py)
-- [pydantic-rpc](https://github.com/pydantic/pydantic-rpc)
+- [pydantic-rpc](https://github.com/i2y/pydantic-rpc)
 - [connect-python](https://github.com/connectrpc/connect-python)

{edda_framework-0.11.0 → edda_framework-0.12.0}/edda/app.py

@@ -63,6 +63,9 @@ class EddaApp:
         notify_fallback_interval: int = 30,
         # Batch processing settings
         max_workflows_per_batch: int | Literal["auto", "auto:cpu"] = 10,
+        # Leader election settings (for coordinating background tasks across workers)
+        leader_heartbeat_interval: int = 15,
+        leader_lease_duration: int = 45,
     ):
         """
         Initialize Edda application.
@@ -100,6 +103,10 @@ class EddaApp:
                                     - int: Fixed batch size (default: 10)
                                     - "auto": Scale 10-100 based on queue depth
                                     - "auto:cpu": Scale 10-100 based on CPU utilization (requires psutil)
+            leader_heartbeat_interval: Interval in seconds for leader heartbeat (default: 15).
+                                      Controls how often workers attempt to become/maintain leadership.
+            leader_lease_duration: Duration in seconds for leader lease (default: 45).
+                                  If leader fails to heartbeat within this time, another worker takes over.
         """
         self.db_url = db_url
         self.service_name = service_name
@@ -168,6 +175,12 @@ class EddaApp:
                 "Must be int, 'auto', or 'auto:cpu'."
             )
 
+        # Leader election settings (for coordinating background tasks)
+        self._leader_heartbeat_interval = leader_heartbeat_interval
+        self._leader_lease_duration = leader_lease_duration
+        self._is_leader = False
+        self._leader_tasks: list[asyncio.Task[Any]] = []
+
     def _create_storage(self, db_url: str) -> SQLAlchemyStorage:
         """
         Create storage backend from database URL.
@@ -309,19 +322,19 @@ class EddaApp:
 
         # Subscribe to workflow resumable notifications
         await self._notify_listener.subscribe(
-            "edda_workflow_resumable",
+            "workflow_resumable",
             self._on_workflow_resumable_notify,
         )
 
         # Subscribe to outbox notifications
         await self._notify_listener.subscribe(
-            "edda_outbox_pending",
+            "workflow_outbox_pending",
             self._on_outbox_pending_notify,
         )
 
         # Subscribe to timer expired notifications
         await self._notify_listener.subscribe(
-            "edda_timer_expired",
+            "workflow_timer_expired",
             self._on_timer_expired_notify,
         )
 
@@ -462,47 +475,202 @@ class EddaApp:
         self._initialized = False
 
     def _start_background_tasks(self) -> None:
-        """Start background maintenance tasks."""
-        # Task to cleanup stale locks and auto-resume workflows
-        auto_resume_task = asyncio.create_task(
-            auto_resume_stale_workflows_periodically(
-                self.storage,
-                self.replay_engine,
-                self.worker_id,
-                interval=60,  # Check every 60 seconds
-            )
-        )
-        self._background_tasks.append(auto_resume_task)
+        """Start background maintenance tasks.
 
-        # Task to check expired timers and resume workflows
-        timer_check_task = asyncio.create_task(
-            self._check_expired_timers_periodically(interval=10)  # Check every 10 seconds
-        )
-        self._background_tasks.append(timer_check_task)
-
-        # Task to check expired message subscriptions and fail workflows
-        # Note: CloudEvents timeouts are also handled here since wait_event() uses wait_message()
-        message_timeout_task = asyncio.create_task(
-            self._check_expired_message_subscriptions_periodically(
-                interval=10
-            )  # Check every 10 seconds
-        )
-        self._background_tasks.append(message_timeout_task)
+        Background tasks are divided into two categories:
+        1. All-worker tasks: Run on every worker (leader election, workflow resumption)
+        2. Leader-only tasks: Run only on the elected leader (timers, timeouts, cleanup)
+
+        This design reduces database polling load significantly in multi-worker deployments.
+        """
+        # Leader election loop (all workers participate)
+        leader_election_task = asyncio.create_task(self._leader_election_loop())
+        self._background_tasks.append(leader_election_task)
 
-        # Task to resume workflows after message delivery (fast resumption)
+        # Task to resume workflows after message delivery (all workers - competitive lock)
         message_resume_task = asyncio.create_task(
             self._resume_running_workflows_periodically(interval=1)  # Check every 1 second
         )
         self._background_tasks.append(message_resume_task)
 
-        # Task to cleanup old channel messages (orphaned messages)
-        message_cleanup_task = asyncio.create_task(
-            self._cleanup_old_messages_periodically(
-                interval=3600,  # Check every 1 hour
-                retention_days=self._message_retention_days,
+        # Note: Leader-only tasks (timer checks, message timeouts, stale workflow cleanup,
+        # old message cleanup) are started dynamically in _leader_election_loop() when
+        # this worker becomes the leader.
+
+    async def _leader_election_loop(self) -> None:
+        """
+        Leader election loop that runs on all workers.
+
+        Uses system lock to elect a single leader among all workers.
+        The leader runs maintenance tasks (timer checks, message timeouts, etc.).
+        Non-leaders only participate in workflow resumption.
+
+        If a leader task crashes, it will be automatically restarted.
+        """
+        while True:
+            try:
+                was_leader = self._is_leader
+
+                # Try to acquire/renew leadership
+                self._is_leader = await self.storage.try_acquire_system_lock(
+                    lock_name="edda_leader",
+                    worker_id=self.worker_id,
+                    timeout_seconds=self._leader_lease_duration,
+                )
+
+                if self._is_leader and not was_leader:
+                    # Became leader - start leader-only tasks
+                    logger.info(f"Worker {self.worker_id} became leader")
+                    self._leader_tasks = self._create_leader_only_tasks()
+
+                elif not self._is_leader and was_leader:
+                    # Lost leadership - cancel leader-only tasks
+                    logger.info(f"Worker {self.worker_id} lost leadership")
+                    await self._cancel_tasks(self._leader_tasks)
+                    self._leader_tasks = []
+
+                elif self._is_leader:
+                    # Still leader - check if any leader tasks have crashed and restart
+                    await self._monitor_and_restart_leader_tasks()
+
+                # Wait before next heartbeat
+                await asyncio.sleep(self._leader_heartbeat_interval)
+
+            except asyncio.CancelledError:
+                # Shutdown - cancel leader tasks and exit
+                await self._cancel_tasks(self._leader_tasks)
+                self._leader_tasks = []
+                raise
+            except Exception as e:
+                logger.error(f"Leader election error: {e}", exc_info=True)
+                self._is_leader = False
+                await self._cancel_tasks(self._leader_tasks)
+                self._leader_tasks = []
+                # Wait before retry
+                await asyncio.sleep(self._leader_heartbeat_interval)
+
+    def _create_leader_only_tasks(self) -> list[asyncio.Task[Any]]:
+        """
+        Create tasks that should only run on the leader worker.
+
+        These tasks are responsible for:
+        - Timer expiration checks
+        - Message subscription timeout checks
+        - Stale workflow auto-resume
+        - Old message cleanup
+        """
+        tasks = []
+
+        # Timer expiration check
+        tasks.append(
+            asyncio.create_task(
+                self._check_expired_timers_periodically(interval=10),
+                name="leader_timer_check",
             )
         )
-        self._background_tasks.append(message_cleanup_task)
+
+        # Message subscription timeout check
+        tasks.append(
+            asyncio.create_task(
+                self._check_expired_message_subscriptions_periodically(interval=10),
+                name="leader_message_timeout_check",
+            )
+        )
+
+        # Stale workflow auto-resume
+        tasks.append(
+            asyncio.create_task(
+                auto_resume_stale_workflows_periodically(
+                    self.storage,
+                    self.replay_engine,
+                    self.worker_id,
+                    interval=60,
+                ),
+                name="leader_stale_workflow_resume",
+            )
+        )
+
+        # Old message cleanup
+        tasks.append(
+            asyncio.create_task(
+                self._cleanup_old_messages_periodically(
+                    interval=3600,
+                    retention_days=self._message_retention_days,
+                ),
+                name="leader_message_cleanup",
+            )
+        )
+
+        return tasks
+
+    async def _cancel_tasks(self, tasks: list[asyncio.Task[Any]]) -> None:
+        """Cancel a list of tasks and wait for them to finish."""
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+    async def _monitor_and_restart_leader_tasks(self) -> None:
+        """
+        Monitor leader tasks and restart any that have crashed.
+
+        This ensures leader-only tasks keep running even if they encounter errors.
+        """
+        task_creators = {
+            "leader_timer_check": lambda: asyncio.create_task(
+                self._check_expired_timers_periodically(interval=10),
+                name="leader_timer_check",
+            ),
+            "leader_message_timeout_check": lambda: asyncio.create_task(
+                self._check_expired_message_subscriptions_periodically(interval=10),
+                name="leader_message_timeout_check",
+            ),
+            "leader_stale_workflow_resume": lambda: asyncio.create_task(
+                auto_resume_stale_workflows_periodically(
+                    self.storage,
+                    self.replay_engine,
+                    self.worker_id,
+                    interval=60,
+                ),
+                name="leader_stale_workflow_resume",
+            ),
+            "leader_message_cleanup": lambda: asyncio.create_task(
+                self._cleanup_old_messages_periodically(
+                    interval=3600,
+                    retention_days=self._message_retention_days,
+                ),
+                name="leader_message_cleanup",
+            ),
+        }
+
+        # Check each task and restart if done (crashed)
+        new_tasks = []
+        for task in self._leader_tasks:
+            if task.done():
+                # Task has finished (possibly due to error)
+                task_name = task.get_name()
+                try:
+                    # Check if it raised an exception
+                    exc = task.exception()
+                    if exc is not None:
+                        logger.warning(
+                            f"Leader task {task_name} crashed with {type(exc).__name__}: {exc}, "
+                            "restarting..."
+                        )
+                except asyncio.CancelledError:
+                    # Task was cancelled, don't restart
+                    logger.debug(f"Leader task {task_name} was cancelled")
+                    continue
+
+                # Restart the task
+                if task_name in task_creators:
+                    new_task = task_creators[task_name]()
+                    new_tasks.append(new_task)
+                    logger.info(f"Restarted leader task: {task_name}")
+            else:
+                # Task is still running
+                new_tasks.append(task)
+
+        self._leader_tasks = new_tasks
 
     def _auto_register_workflows(self) -> None:
         """