edda-framework 0.1.0__py3-none-any.whl

edda/retry.py

@@ -0,0 +1,207 @@
+"""
+Retry policy module for Edda framework.
+
+This module provides retry configuration and metadata tracking for activities.
+Inspired by Restate's retry mechanism and Temporal's retry policies.
+"""
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class RetryPolicy:
+    """
+    Retry policy configuration for activities.
+
+    Inspired by Restate's retry mechanism with Edda-specific optimizations.
+
+    Attributes:
+        initial_interval: First retry delay in seconds
+        backoff_coefficient: Exponential backoff multiplier
+        max_interval: Maximum retry delay in seconds (caps exponential growth)
+        max_attempts: Maximum retry attempts (None = infinite, use with caution)
+        max_duration: Maximum total retry duration in seconds (None = infinite)
+        retryable_error_types: Tuple of exception types to retry
+        non_retryable_error_types: Tuple of exception types to never retry
+
+    Example:
+        # Default policy (5 attempts, exponential backoff)
+        policy = RetryPolicy()
+
+        # Custom policy
+        policy = RetryPolicy(
+            initial_interval=0.5,
+            backoff_coefficient=1.5,
+            max_attempts=10,
+            max_duration=120.0,
+        )
+
+        # Infinite retry (Restate-style, use with caution)
+        policy = RetryPolicy(max_attempts=None, max_duration=None)
+    """
+
+    # Backoff parameters
+    initial_interval: float = 1.0  # seconds
+    backoff_coefficient: float = 2.0  # exponential multiplier
+    max_interval: float = 60.0  # seconds (cap exponential growth)
+
+    # Retry limits
+    max_attempts: int | None = 5  # None = infinite (Restate-style)
+    max_duration: float | None = 300.0  # seconds (5 minutes), None = infinite
+
+    # Exception filtering
+    retryable_error_types: tuple[type[Exception], ...] = (Exception,)
+    non_retryable_error_types: tuple[type[Exception], ...] = ()
+
+    def is_retryable(self, error: Exception) -> bool:
+        """
+        Determine if an error is retryable.
+
+        Priority:
+        1. TerminalError -> always non-retryable
+        2. non_retryable_error_types -> non-retryable
+        3. retryable_error_types -> retryable
+        4. Default: non-retryable (safe default)
+
+        Args:
+            error: Exception to check
+
+        Returns:
+            True if error should be retried, False otherwise
+        """
+        # Import here to avoid circular dependency
+        from edda.exceptions import TerminalError
+
+        # TerminalError always stops retry
+        if isinstance(error, TerminalError):
+            return False
+
+        # Check explicit non-retryable types
+        if self.non_retryable_error_types and isinstance(error, self.non_retryable_error_types):
+            return False
+
+        # Check explicit retryable types (default: non-retryable)
+        return bool(self.retryable_error_types and isinstance(error, self.retryable_error_types))
+
+    def calculate_delay(self, attempt: int) -> float:
+        """
+        Calculate backoff delay for given attempt number.
+
+        Formula: delay = initial_interval * (backoff_coefficient ^ (attempt - 1))
+        Capped at max_interval to prevent excessive delays.
+
+        Args:
+            attempt: Current attempt number (1-indexed)
+
+        Returns:
+            Delay in seconds (exponential backoff, capped at max_interval)
+
+        Example:
+            # Default policy: initial=1.0, coefficient=2.0, max=60.0
+            # Attempt 1: 1.0s
+            # Attempt 2: 2.0s
+            # Attempt 3: 4.0s
+            # Attempt 4: 8.0s
+            # Attempt 5: 16.0s
+            # Attempt 6: 32.0s
+            # Attempt 7: 60.0s (capped)
+            # Attempt 8: 60.0s (capped)
+        """
+        delay = self.initial_interval * (self.backoff_coefficient ** (attempt - 1))
+        return min(delay, self.max_interval)
+
+
+@dataclass
+class RetryMetadata:
+    """
+    Track retry attempts for observability.
+
+    This metadata is stored in workflow history for debugging and monitoring.
+
+    Attributes:
+        total_attempts: Total number of attempts made
+        total_duration_ms: Total time spent retrying (milliseconds)
+        exhausted: Whether max retries were reached
+        errors: List of error information for each attempt
+        last_error: Information about the last error encountered
+    """
+
+    total_attempts: int = 0
+    total_duration_ms: int = 0
+    exhausted: bool = False
+    errors: list[dict[str, Any]] = field(default_factory=list)
+    last_error: dict[str, Any] | None = None
+
+    def add_attempt(self, attempt: int, error: Exception) -> None:
+        """
+        Record a failed attempt.
+
+        Args:
+            attempt: Attempt number (1-indexed)
+            error: Exception that caused the failure
+        """
+        self.total_attempts = attempt
+        error_info = {
+            "attempt": attempt,
+            "error_type": type(error).__name__,
+            "message": str(error),
+            "timestamp_ms": int(time.time() * 1000),
+        }
+        self.errors.append(error_info)
+        self.last_error = {
+            "error_type": type(error).__name__,
+            "message": str(error),
+        }
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert to JSON-serializable dict for storage.
+
+        Returns:
+            Dictionary representation of retry metadata
+        """
+        return {
+            "total_attempts": self.total_attempts,
+            "total_duration_ms": self.total_duration_ms,
+            "exhausted": self.exhausted,
+            "errors": self.errors,
+            "last_error": self.last_error,
+        }
+
+
+# Default retry policy
+DEFAULT_RETRY_POLICY = RetryPolicy(
+    initial_interval=1.0,  # Start with 1 second delay
+    backoff_coefficient=2.0,  # Standard exponential backoff
+    max_interval=60.0,  # Cap at 60 seconds
+    max_attempts=5,  # Balance between resilience and fail-fast
+    max_duration=300.0,  # 5 minutes total (prevents runaway retry)
+)
+
+
+# Preset policies for common scenarios
+AGGRESSIVE_RETRY = RetryPolicy(
+    initial_interval=0.1,  # Fast retries for low-latency services
+    backoff_coefficient=1.5,  # Slower exponential growth
+    max_interval=10.0,  # Short max delay
+    max_attempts=10,  # More attempts
+    max_duration=60.0,  # 1 minute total
+)
+
+CONSERVATIVE_RETRY = RetryPolicy(
+    initial_interval=5.0,  # Wait longer between attempts
+    backoff_coefficient=2.0,  # Standard exponential
+    max_interval=300.0,  # Up to 5 minutes between retries
+    max_attempts=3,  # Fewer attempts (fail faster)
+    max_duration=900.0,  # 15 minutes total
+)
+
+INFINITE_RETRY = RetryPolicy(
+    initial_interval=1.0,
+    backoff_coefficient=2.0,
+    max_interval=60.0,
+    max_attempts=None,  # Infinite attempts (Restate-style)
+    max_duration=None,  # Infinite duration (use with caution)
+)

edda/serialization/__init__.py

@@ -0,0 +1,9 @@
+"""Serialization layer for Edda framework."""
+
+from edda.serialization.base import SerializerProtocol
+from edda.serialization.json import JSONSerializer
+
+__all__ = [
+    "SerializerProtocol",
+    "JSONSerializer",
+]

edda/serialization/base.py

@@ -0,0 +1,83 @@
+"""
+Base serialization protocol for Edda framework.
+
+This module defines the SerializerProtocol that all serializers must implement.
+"""
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SerializerProtocol(Protocol):
+    """
+    Protocol for serialization implementations.
+
+    Serializers are used to encode/decode CloudEvent data payloads.
+    Edda supports JSON serialization.
+    """
+
+    @property
+    def content_type(self) -> str:
+        """
+        Get the Content-Type header value for this serializer.
+
+        Returns:
+            Content-Type string (e.g., "application/json")
+        """
+        ...
+
+    def serialize(self, data: Any) -> bytes:
+        """
+        Serialize data to bytes.
+
+        Args:
+            data: Data to serialize (typically a dict for JSON)
+
+        Returns:
+            Serialized bytes
+
+        Raises:
+            ValueError: If data cannot be serialized
+        """
+        ...
+
+    def deserialize(self, data: bytes, message_type: type[Any] | None = None) -> Any:
+        """
+        Deserialize bytes to data.
+
+        Args:
+            data: Serialized bytes
+            message_type: Optional message type (unused for JSON serializer)
+
+        Returns:
+            Deserialized data (typically a dict for JSON)
+
+        Raises:
+            ValueError: If data cannot be deserialized
+        """
+        ...
+
+    def to_dict(self, data: Any) -> dict[str, Any]:
+        """
+        Convert data to dictionary (for storage).
+
+        Args:
+            data: Data to convert
+
+        Returns:
+            Dictionary representation
+        """
+        ...
+
+    def from_dict(self, data: dict[str, Any], message_type: type[Any] | None = None) -> Any:
+        """
+        Convert dictionary to data (from storage).
+
+        Args:
+            data: Dictionary representation
+            message_type: Optional message type (unused for JSON serializer)
+
+        Returns:
+            Reconstructed data
+        """
+        ...

edda/serialization/json.py

@@ -0,0 +1,102 @@
+"""
+JSON serialization implementation for Edda framework.
+
+This is the default serializer, using Python's standard library json module.
+"""
+
+import json
+from typing import Any
+
+
+class JSONSerializer:
+    """
+    JSON serializer implementation.
+
+    Uses Python's standard library json module for serialization.
+    This is the default and recommended serializer for most use cases.
+    """
+
+    @property
+    def content_type(self) -> str:
+        """Get Content-Type header."""
+        return "application/json"
+
+    def serialize(self, data: Any) -> bytes:
+        """
+        Serialize data to JSON bytes.
+
+        Args:
+            data: Data to serialize (must be JSON-serializable)
+
+        Returns:
+            UTF-8 encoded JSON bytes
+
+        Raises:
+            TypeError: If data is not JSON-serializable
+        """
+        try:
+            json_str = json.dumps(data, ensure_ascii=False, sort_keys=True)
+            return json_str.encode("utf-8")
+        except (TypeError, ValueError) as e:
+            raise ValueError(f"Failed to serialize data to JSON: {e}") from e
+
+    def deserialize(self, data: bytes, _message_type: type[Any] | None = None) -> Any:
+        """
+        Deserialize JSON bytes to data.
+
+        Args:
+            data: UTF-8 encoded JSON bytes
+            _message_type: Ignored for JSON serializer
+
+        Returns:
+            Deserialized Python data (dict, list, etc.)
+
+        Raises:
+            ValueError: If data is not valid JSON
+        """
+        try:
+            json_str = data.decode("utf-8")
+            return json.loads(json_str)
+        except (UnicodeDecodeError, json.JSONDecodeError) as e:
+            raise ValueError(f"Failed to deserialize JSON data: {e}") from e
+
+    def to_dict(self, data: Any) -> dict[str, Any]:
+        """
+        Convert data to dictionary.
+
+        For JSON serializer, this is typically a no-op if data is already a dict.
+
+        Args:
+            data: Data to convert
+
+        Returns:
+            Dictionary representation
+        """
+        if isinstance(data, dict):
+            return data
+        elif isinstance(data, str):
+            # Try to parse as JSON
+            try:
+                result = json.loads(data)
+                if isinstance(result, dict):
+                    return result
+            except json.JSONDecodeError:
+                pass
+
+        # Wrap in dict if not already
+        return {"value": data}
+
+    def from_dict(self, data: dict[str, Any], _message_type: type[Any] | None = None) -> Any:
+        """
+        Convert dictionary to data.
+
+        For JSON serializer, this is typically a no-op.
+
+        Args:
+            data: Dictionary representation
+            _message_type: Ignored for JSON serializer
+
+        Returns:
+            Data (usually just returns the dict)
+        """
+        return data

edda/storage/__init__.py

@@ -0,0 +1,9 @@
+"""Storage layer for Edda framework."""
+
+from edda.storage.protocol import StorageProtocol
+from edda.storage.sqlalchemy_storage import SQLAlchemyStorage
+
+__all__ = [
+    "StorageProtocol",
+    "SQLAlchemyStorage",
+]

edda/storage/models.py

@@ -0,0 +1,194 @@
+"""
+SQLite database schema for Edda framework.
+
+This module defines the table schemas for storing workflow instances,
+execution history, compensations, event subscriptions, and outbox events.
+"""
+
+# SQL schema for workflow definitions (source code storage)
+WORKFLOW_DEFINITIONS_TABLE = """
+CREATE TABLE IF NOT EXISTS workflow_definitions (
+    workflow_name TEXT NOT NULL,
+    source_hash TEXT NOT NULL,
+    source_code TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (workflow_name, source_hash)
+);
+"""
+
+# Indexes for workflow definitions
+WORKFLOW_DEFINITIONS_INDEXES = [
+    "CREATE INDEX IF NOT EXISTS idx_definitions_name ON workflow_definitions(workflow_name);",
+    "CREATE INDEX IF NOT EXISTS idx_definitions_hash ON workflow_definitions(source_hash);",
+]
+
+# SQL schema for workflow instances table with distributed locking support
+WORKFLOW_INSTANCES_TABLE = """
+CREATE TABLE IF NOT EXISTS workflow_instances (
+    instance_id TEXT PRIMARY KEY,
+    workflow_name TEXT NOT NULL,
+    source_hash TEXT NOT NULL,
+    owner_service TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'running',
+    current_activity_id TEXT,
+    started_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    input_data TEXT NOT NULL,
+    output_data TEXT,
+    locked_by TEXT,
+    locked_at TEXT,
+    lock_timeout_seconds INTEGER,
+    CONSTRAINT valid_status CHECK (
+        status IN ('running', 'completed', 'failed', 'waiting_for_event', 'waiting_for_timer', 'compensating', 'cancelled')
+    ),
+    FOREIGN KEY (workflow_name, source_hash) REFERENCES workflow_definitions(workflow_name, source_hash)
+);
+"""
+
+# Indexes for workflow instances
+WORKFLOW_INSTANCES_INDEXES = [
+    "CREATE INDEX IF NOT EXISTS idx_instances_status ON workflow_instances(status);",
+    "CREATE INDEX IF NOT EXISTS idx_instances_workflow ON workflow_instances(workflow_name);",
+    "CREATE INDEX IF NOT EXISTS idx_instances_owner ON workflow_instances(owner_service);",
+    "CREATE INDEX IF NOT EXISTS idx_instances_locked ON workflow_instances(locked_by, locked_at);",
+    "CREATE INDEX IF NOT EXISTS idx_instances_updated ON workflow_instances(updated_at);",
+    "CREATE INDEX IF NOT EXISTS idx_instances_hash ON workflow_instances(source_hash);",
+]
+
+# SQL schema for workflow execution history (for deterministic replay)
+WORKFLOW_HISTORY_TABLE = """
+CREATE TABLE IF NOT EXISTS workflow_history (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    instance_id TEXT NOT NULL,
+    activity_id TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    event_data TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (instance_id) REFERENCES workflow_instances(instance_id) ON DELETE CASCADE,
+    CONSTRAINT unique_instance_activity UNIQUE (instance_id, activity_id)
+);
+"""
+
+# Indexes for workflow history
+WORKFLOW_HISTORY_INDEXES = [
+    "CREATE INDEX IF NOT EXISTS idx_history_instance ON workflow_history(instance_id, activity_id);",
+    "CREATE INDEX IF NOT EXISTS idx_history_created ON workflow_history(created_at);",
+]
+
+# SQL schema for compensation transactions (LIFO stack for Saga pattern)
+WORKFLOW_COMPENSATIONS_TABLE = """
+CREATE TABLE IF NOT EXISTS workflow_compensations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    instance_id TEXT NOT NULL,
+    activity_id TEXT NOT NULL,
+    activity_name TEXT NOT NULL,
+    args TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (instance_id) REFERENCES workflow_instances(instance_id) ON DELETE CASCADE
+);
+"""
+
+# Indexes for workflow compensations
+WORKFLOW_COMPENSATIONS_INDEXES = [
+    "CREATE INDEX IF NOT EXISTS idx_compensations_instance ON workflow_compensations(instance_id, created_at DESC);",
+]
+
+# SQL schema for event subscriptions (for wait_event)
+WORKFLOW_EVENT_SUBSCRIPTIONS_TABLE = """
+CREATE TABLE IF NOT EXISTS workflow_event_subscriptions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    instance_id TEXT NOT NULL,
+    event_type 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_event UNIQUE (instance_id, event_type)
+);
+"""
+
+# Indexes for event subscriptions
+WORKFLOW_EVENT_SUBSCRIPTIONS_INDEXES = [
+    "CREATE INDEX IF NOT EXISTS idx_subscriptions_event ON workflow_event_subscriptions(event_type);",
+    "CREATE INDEX IF NOT EXISTS idx_subscriptions_timeout ON workflow_event_subscriptions(timeout_at);",
+    "CREATE INDEX IF NOT EXISTS idx_subscriptions_instance ON workflow_event_subscriptions(instance_id);",
+]
+
+# SQL schema for timer subscriptions (for wait_timer)
+WORKFLOW_TIMER_SUBSCRIPTIONS_TABLE = """
+CREATE TABLE IF NOT EXISTS workflow_timer_subscriptions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    instance_id TEXT NOT NULL,
+    timer_id TEXT NOT NULL,
+    expires_at TEXT NOT NULL,
+    activity_id TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (instance_id) REFERENCES workflow_instances(instance_id) ON DELETE CASCADE,
+    CONSTRAINT unique_instance_timer UNIQUE (instance_id, timer_id)
+);
+"""
+
+# Indexes for timer subscriptions
+WORKFLOW_TIMER_SUBSCRIPTIONS_INDEXES = [
+    "CREATE INDEX IF NOT EXISTS idx_timer_subscriptions_expires ON workflow_timer_subscriptions(expires_at);",
+    "CREATE INDEX IF NOT EXISTS idx_timer_subscriptions_instance ON workflow_timer_subscriptions(instance_id);",
+]
+
+# SQL schema for transactional outbox pattern
+OUTBOX_EVENTS_TABLE = """
+CREATE TABLE IF NOT EXISTS outbox_events (
+    event_id TEXT PRIMARY KEY,
+    event_type TEXT NOT NULL,
+    event_source TEXT NOT NULL,
+    event_data TEXT NOT NULL,
+    content_type TEXT NOT NULL DEFAULT 'application/json',
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    published_at TEXT,
+    status TEXT NOT NULL DEFAULT 'pending',
+    retry_count INTEGER DEFAULT 0,
+    last_error TEXT,
+    CONSTRAINT valid_outbox_status CHECK (status IN ('pending', 'processing', 'published', 'failed', 'invalid', 'expired'))
+);
+"""
+
+# SQL schema for schema version tracking
+SCHEMA_VERSION_TABLE = """
+CREATE TABLE IF NOT EXISTS schema_version (
+    version INTEGER PRIMARY KEY,
+    applied_at TEXT NOT NULL DEFAULT (datetime('now')),
+    description TEXT NOT NULL
+);
+"""
+
+# Indexes for outbox events
+OUTBOX_EVENTS_INDEXES = [
+    "CREATE INDEX IF NOT EXISTS idx_outbox_status ON outbox_events(status, created_at);",
+    "CREATE INDEX IF NOT EXISTS idx_outbox_retry ON outbox_events(status, retry_count);",
+    "CREATE INDEX IF NOT EXISTS idx_outbox_published ON outbox_events(published_at);",
+]
+
+# Current schema version
+CURRENT_SCHEMA_VERSION = 1
+
+# All table creation statements
+ALL_TABLES = [
+    SCHEMA_VERSION_TABLE,
+    WORKFLOW_DEFINITIONS_TABLE,
+    WORKFLOW_INSTANCES_TABLE,
+    WORKFLOW_HISTORY_TABLE,
+    WORKFLOW_COMPENSATIONS_TABLE,
+    WORKFLOW_EVENT_SUBSCRIPTIONS_TABLE,
+    WORKFLOW_TIMER_SUBSCRIPTIONS_TABLE,
+    OUTBOX_EVENTS_TABLE,
+]
+
+# All index creation statements
+ALL_INDEXES = (
+    WORKFLOW_DEFINITIONS_INDEXES
+    + WORKFLOW_INSTANCES_INDEXES
+    + WORKFLOW_HISTORY_INDEXES
+    + WORKFLOW_COMPENSATIONS_INDEXES
+    + WORKFLOW_EVENT_SUBSCRIPTIONS_INDEXES
+    + WORKFLOW_TIMER_SUBSCRIPTIONS_INDEXES
+    + OUTBOX_EVENTS_INDEXES
+)