edda-framework 0.1.0__py3-none-any.whl

edda/__init__.py

@@ -0,0 +1,56 @@
+"""
+Edda Framework - CloudEvents-native Durable Execution framework.
+
+Example:
+    >>> import asyncio
+    >>> import sys
+    >>> import uvloop
+    >>> from edda import EddaApp, workflow, activity, wait_event, wait_timer
+    >>>
+    >>> # Python 3.12+ uses asyncio.set_event_loop_policy()
+    >>> if sys.version_info >= (3, 12):
+    ...     asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
+    ... else:
+    ...     uvloop.install()
+    >>>
+    >>> app = EddaApp(
+    ...     service_name="order-service",
+    ...     db_url="sqlite:///workflow.db",
+    ...     outbox_enabled=True
+    ... )
+"""
+
+from edda.activity import activity
+from edda.app import EddaApp
+from edda.compensation import compensation, on_failure, register_compensation
+from edda.context import WorkflowContext
+from edda.events import ReceivedEvent, send_event, wait_event, wait_timer, wait_until
+from edda.exceptions import RetryExhaustedError, TerminalError
+from edda.hooks import HooksBase, WorkflowHooks
+from edda.outbox import OutboxRelayer, send_event_transactional
+from edda.retry import RetryPolicy
+from edda.workflow import workflow
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "EddaApp",
+    "workflow",
+    "activity",
+    "WorkflowContext",
+    "ReceivedEvent",
+    "wait_event",
+    "wait_timer",
+    "wait_until",
+    "send_event",
+    "compensation",
+    "register_compensation",
+    "on_failure",  # Already exported, just confirming it's in __all__
+    "OutboxRelayer",
+    "send_event_transactional",
+    "WorkflowHooks",
+    "HooksBase",
+    "RetryPolicy",
+    "RetryExhaustedError",
+    "TerminalError",
+]

edda/activity.py

@@ -0,0 +1,505 @@
+"""
+Activity module for Edda framework.
+
+This module provides the @activity decorator for defining atomic units of work
+within workflows. Activities are the building blocks of Sagas and support
+deterministic replay through result caching.
+"""
+
+import asyncio
+import functools
+import inspect
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar, cast
+
+from edda.context import WorkflowContext
+from edda.exceptions import RetryExhaustedError, TerminalError, WorkflowCancelledException
+from edda.pydantic_utils import (
+    enum_value_to_enum,
+    extract_enum_from_annotation,
+    extract_pydantic_model_from_annotation,
+    from_json_dict,
+    to_json_dict,
+)
+from edda.retry import RetryMetadata, RetryPolicy
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class Activity:
+    """
+    Wrapper class for activity functions.
+
+    Handles execution, result caching during replay, and history recording.
+    Supports automatic retry with exponential backoff.
+    """
+
+    def __init__(self, func: Callable[..., Any], retry_policy: "RetryPolicy | None" = None):
+        """
+        Initialize activity wrapper.
+
+        Args:
+            func: The async function to wrap
+            retry_policy: Optional retry policy for this activity.
+                         If None, uses the default policy from EddaApp.
+        """
+        self.func = func
+        self.name = func.__name__
+        self.retry_policy = retry_policy
+        functools.update_wrapper(self, func)
+
+    async def __call__(self, ctx: WorkflowContext, *args: Any, **kwargs: Any) -> Any:
+        """
+        Execute the activity with automatic retry.
+
+        During replay, returns cached result. During normal execution,
+        executes the function with retry logic and records the result.
+
+        Args:
+            ctx: Workflow context
+            *args: Positional arguments for the activity
+            **kwargs: Keyword arguments for the activity
+                     Optional: activity_id (str) - Explicit activity ID
+                     - Auto-generated by default (format: "{function_name}:{counter}")
+                     - Manual specification required ONLY for concurrent execution
+                       (asyncio.gather, async for, etc.)
+                     - For sequential execution, rely on auto-generation
+
+        Returns:
+            Activity result
+
+        Raises:
+            RetryExhaustedError: When all retry attempts are exhausted
+            TerminalError: For non-retryable errors
+            WorkflowCancelledException: When workflow is cancelled
+            Any exception raised by the activity function (if retry policy allows)
+
+        Example:
+            Sequential execution (auto-generated IDs - recommended)::
+
+                result1 = await my_activity(ctx, arg1)  # Auto: "my_activity:1"
+                result2 = await my_activity(ctx, arg2)  # Auto: "my_activity:2"
+
+            Concurrent execution (manual IDs - required)::
+
+                results = await asyncio.gather(
+                    my_activity(ctx, arg1, activity_id="my_activity:1"),
+                    my_activity(ctx, arg2, activity_id="my_activity:2"),
+                )
+        """
+        # Resolve activity ID (explicit or auto-generated)
+        activity_id = self._resolve_id(ctx, kwargs.pop("activity_id", None))
+
+        # Record activity ID execution
+        ctx._record_activity_id(activity_id)
+
+        # Call hook: activity start
+        if ctx.hooks and hasattr(ctx.hooks, "on_activity_start"):
+            await ctx.hooks.on_activity_start(
+                ctx.instance_id, activity_id, self.name, ctx.is_replaying
+            )
+
+        # Check if workflow has been cancelled
+        instance = await ctx._get_instance()
+        if instance and instance.get("status") == "cancelled":
+            raise WorkflowCancelledException(f"Workflow {ctx.instance_id} has been cancelled")
+
+        # Check if we're replaying and have a cached result
+        if ctx.is_replaying:
+            found, cached_result = ctx._get_cached_result(activity_id)
+            if found:
+                # Check if this was an error
+                if isinstance(cached_result, dict) and cached_result.get("_error"):
+                    # Reconstruct and raise the error
+                    error_type = cached_result.get("error_type", "Exception")
+                    error_message = cached_result.get("error_message", "Unknown error")
+
+                    # Call hook: activity failed (from cache)
+                    error_obj = Exception(f"{error_type}: {error_message}")
+                    if ctx.hooks and hasattr(ctx.hooks, "on_activity_failed"):
+                        await ctx.hooks.on_activity_failed(
+                            ctx.instance_id, activity_id, self.name, error_obj
+                        )
+
+                    raise error_obj
+
+                # Restore Pydantic model or Enum from cached result based on return type
+                sig = inspect.signature(self.func)
+                restored_result = cached_result
+
+                # Check if return type is Pydantic model
+                model = extract_pydantic_model_from_annotation(sig.return_annotation)
+                if model is not None and isinstance(cached_result, dict):
+                    restored_result = from_json_dict(cached_result, model)
+                # Check if return type is Enum
+                elif (
+                    enum_class := extract_enum_from_annotation(sig.return_annotation)
+                ) is not None:
+                    from enum import Enum
+
+                    if not isinstance(cached_result, Enum):
+                        restored_result = enum_value_to_enum(cached_result, enum_class)
+
+                # Call hook: activity complete (cache hit)
+                if ctx.hooks and hasattr(ctx.hooks, "on_activity_complete"):
+                    await ctx.hooks.on_activity_complete(
+                        ctx.instance_id, activity_id, self.name, restored_result, cache_hit=True
+                    )
+
+                # Return cached successful result
+                return restored_result
+
+        # Resolve retry policy (activity-level > app-level > default)
+        retry_policy = self._resolve_retry_policy(ctx)
+
+        # Retry loop (OUTSIDE transaction - each attempt is independent)
+        attempt = 0
+        start_time = time.time()
+        retry_metadata = RetryMetadata()
+        last_error: Exception | None = None
+
+        while True:
+            attempt += 1
+
+            try:
+                # Execute activity in transaction (one attempt)
+                async with ctx.transaction():
+                    # Calculate retry metadata if there were retries
+                    retry_meta = None
+                    if attempt > 1:
+                        retry_metadata.total_duration_ms = int((time.time() - start_time) * 1000)
+                        retry_metadata.total_attempts = attempt  # Update attempt count on success
+                        retry_meta = retry_metadata
+
+                    result = await self._execute_and_record(
+                        ctx, activity_id, args, kwargs, retry_meta
+                    )
+                    return result
+
+            except WorkflowCancelledException:
+                # Never retry cancellation
+                raise
+
+            except TerminalError as error:
+                # Never retry terminal errors, but record the failure
+                input_data = {
+                    "args": [to_json_dict(arg) for arg in args],
+                    "kwargs": {k: to_json_dict(v) for k, v in kwargs.items()},
+                }
+                # Record failure (no retry metadata for terminal errors)
+                await ctx._record_activity_failed(
+                    activity_id, self.name, error, input_data, retry_metadata=None
+                )
+
+                # Call hook: activity failed
+                if ctx.hooks and hasattr(ctx.hooks, "on_activity_failed"):
+                    await ctx.hooks.on_activity_failed(
+                        ctx.instance_id, activity_id, self.name, error
+                    )
+
+                # Re-raise immediately (no retry)
+                raise
+
+            except Exception as error:
+                last_error = error
+
+                # Record this attempt in metadata
+                retry_metadata.add_attempt(attempt, error)
+
+                # Check if should retry
+                should_retry, reason = self._should_retry(retry_policy, error, attempt, start_time)
+
+                if not should_retry:
+                    # Exhausted retries - mark metadata as exhausted
+                    retry_metadata.exhausted = True
+                    retry_metadata.total_duration_ms = int((time.time() - start_time) * 1000)
+
+                    # Record failure with retry metadata outside transaction
+                    input_data = {
+                        "args": [to_json_dict(arg) for arg in args],
+                        "kwargs": {k: to_json_dict(v) for k, v in kwargs.items()},
+                    }
+                    # Include retry metadata in the failure record
+                    await ctx._record_activity_failed(
+                        activity_id, self.name, error, input_data, retry_metadata
+                    )
+
+                    # Call hook: activity failed
+                    if ctx.hooks and hasattr(ctx.hooks, "on_activity_failed"):
+                        await ctx.hooks.on_activity_failed(
+                            ctx.instance_id, activity_id, self.name, error
+                        )
+
+                    # Raise RetryExhaustedError with original exception as cause
+                    raise RetryExhaustedError(
+                        f"Activity {self.name} failed after {attempt} attempts: {reason}"
+                    ) from last_error
+
+                # Calculate backoff delay
+                delay = retry_policy.calculate_delay(attempt)
+
+                # Call hook: activity retry
+                if ctx.hooks and hasattr(ctx.hooks, "on_activity_retry"):
+                    await ctx.hooks.on_activity_retry(
+                        ctx.instance_id, activity_id, self.name, error, attempt, delay
+                    )
+
+                # Wait before next retry
+                await asyncio.sleep(delay)
+
+    async def _execute_and_record(
+        self,
+        ctx: WorkflowContext,
+        activity_id: str,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        retry_metadata: Any = None,
+    ) -> Any:
+        """
+        Execute activity function and record the result.
+
+        This helper method contains the core execution logic and is called
+        within a transaction. If the activity fails, the exception is propagated
+        and the transaction will be rolled back by the caller.
+
+        Args:
+            ctx: Workflow context
+            activity_id: Activity ID
+            args: Positional arguments for the activity
+            kwargs: Keyword arguments for the activity
+            retry_metadata: Optional retry metadata (RetryMetadata instance)
+
+        Returns:
+            Activity result
+
+        Raises:
+            Any exception raised by the activity function
+        """
+        # Capture input parameters for recording
+        # Convert Pydantic models to JSON dicts for storage
+        # args and kwargs contain the actual activity arguments (ctx is already passed separately)
+        input_data = {
+            "args": [to_json_dict(arg) for arg in args],
+            "kwargs": {k: to_json_dict(v) for k, v in kwargs.items()},
+        }
+
+        # Execute the activity function
+        result = await self.func(ctx, *args, **kwargs)
+
+        # Convert Pydantic model result to JSON dict for storage
+        result_for_storage = to_json_dict(result)
+
+        # Record successful completion with input data
+        # Always record when we actually execute, even during replay
+        # (if we're here, it means there was no cached result)
+        await ctx._record_activity_completed(
+            activity_id, self.name, result_for_storage, input_data, retry_metadata
+        )
+
+        # Auto-register compensation if @on_failure decorator is present
+        if hasattr(self.func, "_compensation_func") and hasattr(self.func, "_has_compensation"):
+            compensation_func = self.func._compensation_func
+
+            # Merge activity result and input kwargs for compensation parameters
+            # Convention: compensation function receives both input params and result values
+            comp_kwargs = {**kwargs}  # Start with input kwargs
+
+            # Add result values if result is a dict
+            if isinstance(result, dict):
+                comp_kwargs.update(result)
+
+            # Register the compensation
+            from edda.compensation import register_compensation
+
+            await register_compensation(
+                ctx, compensation_func, activity_id=activity_id, **comp_kwargs
+            )
+
+            print(f"[Activity] Auto-registered compensation: {compensation_func.__name__}")
+
+        # Check if workflow was cancelled during activity execution
+        instance = await ctx._get_instance()
+        if instance and instance.get("status") == "cancelled":
+            from edda.exceptions import WorkflowCancelledException
+
+            raise WorkflowCancelledException(
+                f"Workflow {ctx.instance_id} was cancelled during {self.name} execution"
+            )
+
+        # Call hook: activity complete (cache miss)
+        if ctx.hooks and hasattr(ctx.hooks, "on_activity_complete"):
+            await ctx.hooks.on_activity_complete(
+                ctx.instance_id, activity_id, self.name, result, cache_hit=False
+            )
+
+        return result
+
+    def _resolve_id(self, ctx: WorkflowContext, explicit_id: str | None) -> str:
+        """
+        Resolve activity ID (explicit or auto-generated).
+
+        Args:
+            ctx: Workflow context
+            explicit_id: Explicitly provided activity ID (from kwargs)
+
+        Returns:
+            Resolved activity ID
+        """
+        if explicit_id is not None:
+            return explicit_id
+
+        # Auto-generate ID using context's generator
+        return ctx._generate_activity_id(self.name)
+
+    def _resolve_retry_policy(self, ctx: WorkflowContext) -> "RetryPolicy":
+        """
+        Resolve retry policy with priority: activity-level > app-level > default.
+
+        Args:
+            ctx: Workflow context
+
+        Returns:
+            Resolved retry policy
+        """
+        from edda.retry import DEFAULT_RETRY_POLICY
+
+        # Priority 1: Activity-level policy (specified in @activity decorator)
+        if self.retry_policy is not None:
+            return self.retry_policy
+
+        # Priority 2: App-level policy (EddaApp default_retry_policy)
+        # Note: This will be implemented in Phase 5 (edda/app.py)
+        if hasattr(ctx, "_app_retry_policy") and ctx._app_retry_policy is not None:
+            return cast(RetryPolicy, ctx._app_retry_policy)
+
+        # Priority 3: Framework default
+        return DEFAULT_RETRY_POLICY
+
+    def _should_retry(
+        self,
+        retry_policy: "RetryPolicy",
+        error: Exception,
+        attempt: int,
+        start_time: float,
+    ) -> tuple[bool, str]:
+        """
+        Determine if the activity should be retried.
+
+        Args:
+            retry_policy: Retry policy configuration
+            error: Exception that caused the failure
+            attempt: Current attempt number (1-indexed)
+            start_time: Start time of the first attempt (Unix timestamp)
+
+        Returns:
+            Tuple of (should_retry: bool, reason: str)
+            - should_retry: True if retry should be attempted, False otherwise
+            - reason: Human-readable reason for the decision
+        """
+        import time
+
+        # Check if error is retryable according to policy
+        if not retry_policy.is_retryable(error):
+            return False, f"Error type {type(error).__name__} is not retryable"
+
+        # Check max_attempts limit
+        if retry_policy.max_attempts is not None and attempt >= retry_policy.max_attempts:
+            return False, f"Max attempts ({retry_policy.max_attempts}) reached"
+
+        # Check max_duration limit
+        if retry_policy.max_duration is not None:
+            elapsed = time.time() - start_time
+            if elapsed >= retry_policy.max_duration:
+                return (
+                    False,
+                    f"Max duration ({retry_policy.max_duration}s) exceeded (elapsed: {elapsed:.1f}s)",
+                )
+
+        # Should retry
+        return True, f"Will retry (attempt {attempt + 1})"
+
+
+def activity(
+    func: F | None = None, *, retry_policy: "RetryPolicy | None" = None
+) -> F | Callable[[F], F]:
+    """
+    Decorator for defining activities (atomic units of work) with automatic retry.
+
+    Activities are async functions that take a WorkflowContext as the first
+    parameter, followed by any other parameters.
+
+    Activities are automatically wrapped in a transaction, ensuring that
+    activity execution, history recording, and event sending are atomic.
+    Each retry attempt is executed in an independent transaction.
+
+    When using ctx.session to access the Edda-managed session, all operations
+    (activity execution, history recording, event sending) use that shared session,
+    ensuring atomicity within a single transaction.
+
+    For non-idempotent operations (e.g., external API calls), place them in
+    Activities to leverage result caching during replay. For operations that
+    can be safely re-executed during replay, place them directly in the
+    Workflow function.
+
+    Example:
+        >>> @activity  # Uses default retry policy (5 attempts, exponential backoff)
+        ... async def reserve_inventory(ctx: WorkflowContext, order_id: str) -> dict:
+        ...     # Your business logic here
+        ...     return {"reservation_id": "123"}
+
+        >>> from edda.retry import RetryPolicy, AGGRESSIVE_RETRY
+        >>> @activity(retry_policy=AGGRESSIVE_RETRY)  # Custom retry policy
+        ... async def process_payment(ctx: WorkflowContext, amount: float) -> dict:
+        ...     # Fast retries for low-latency services
+        ...     return {"status": "completed"}
+
+        >>> @activity  # Non-idempotent operations cached during replay
+        ... async def charge_credit_card(ctx: WorkflowContext, amount: float) -> dict:
+        ...     # External API call - result is cached, won't be called again on replay
+        ...     # If this fails, automatic retry with exponential backoff
+        ...     return {"transaction_id": "txn_123"}
+
+        >>> from edda.exceptions import TerminalError
+        >>> @activity
+        ... async def validate_user(ctx: WorkflowContext, user_id: str) -> dict:
+        ...     user = await fetch_user(user_id)
+        ...     if not user:
+        ...         # Don't retry - user doesn't exist
+        ...         raise TerminalError(f"User {user_id} not found")
+        ...     return {"user_id": user_id, "name": user.name}
+
+    Args:
+        func: Async function to wrap as an activity
+        retry_policy: Optional retry policy for this activity.
+                     If None, uses the default policy from EddaApp.
+
+    Returns:
+        Decorated function that can be called within a workflow
+
+    Raises:
+        RetryExhaustedError: When all retry attempts are exhausted
+        TerminalError: For non-retryable errors (no retry attempted)
+    """
+
+    def decorator(f: F) -> F:
+        # Verify the function is async
+        if not inspect.iscoroutinefunction(f):
+            raise TypeError(f"Activity {f.__name__} must be an async function")
+
+        # Create the Activity wrapper with retry policy
+        activity_wrapper = Activity(f, retry_policy=retry_policy)
+
+        # Mark as activity for introspection
+        activity_wrapper._is_activity = True  # type: ignore[attr-defined]
+
+        # Return the wrapper cast to the original type
+        return cast(F, activity_wrapper)
+
+    # Support both @activity and @activity(retry_policy=...)
+    if func is None:
+        # Called with arguments: @activity(retry_policy=...)
+        return decorator
+    else:
+        # Called without arguments: @activity
+        return decorator(func)