resilient-circuit 0.4.1__py3-none-any.whl

resilient_circuit/__init__.py

@@ -0,0 +1,16 @@
+from resilient_circuit.backoff import ExponentialDelay, FixedDelay
+from resilient_circuit.circuit_breaker import CircuitProtectorPolicy
+from resilient_circuit.circuit_breaker import CircuitStatus as CircuitState
+from resilient_circuit.failsafe import SafetyNet
+from resilient_circuit.policy import ProtectionPolicy
+from resilient_circuit.retry import RetryWithBackoffPolicy
+
+__all__ = (
+    "ExponentialDelay",
+    "CircuitProtectorPolicy",
+    "CircuitState",
+    "FixedDelay",
+    "SafetyNet",
+    "ProtectionPolicy",
+    "RetryWithBackoffPolicy",
+)

resilient_circuit/backoff.py

@@ -0,0 +1,37 @@
+import random
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class ExponentialDelay:
+    min_delay: timedelta
+    max_delay: timedelta
+    factor: int = 2
+    jitter: Optional[float] = None
+
+    def __post_init__(self) -> None:
+        if self.jitter is not None and (self.jitter < 0 or self.jitter > 1):
+            raise ValueError("`jitter` must be in range [0, 1].")
+
+    def for_attempt(self, attempt: int) -> float:
+        """Compute delay in seconds for a given attempt."""
+
+        if attempt < 1:
+            raise ValueError("`attempt` must be positive.")
+
+        delay = self.min_delay.total_seconds() * pow(self.factor, attempt - 1)
+
+        if self.jitter is not None:
+            offset = delay * self.jitter
+            delay += random.uniform(-offset, offset)
+
+        return min(delay, self.max_delay.total_seconds())
+
+
+class FixedDelay(ExponentialDelay):
+    """Special case of ExponentialDelay when delay between calls is constant."""
+
+    def __init__(self, delay: timedelta) -> None:
+        super().__init__(min_delay=delay, max_delay=delay, factor=1)

resilient_circuit/buffer.py

@@ -0,0 +1,55 @@
+from fractions import Fraction
+from typing import Generic, List, TypeVar
+
+T = TypeVar("T")
+
+
+class GenericCircularBuffer(Generic[T]):
+    """Buffer that keeps last N items."""
+
+    def __init__(self, size: int) -> None:
+        if size < 1:
+            raise ValueError("`size` must be positive.")
+
+        self.size = size
+        self._items: List[T] = []
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def __str__(self) -> str:
+        return str(self._items)
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}(size={self.size}): {self}>"
+
+    def add(self, item: T) -> None:
+        self._items.append(item)
+        self._items = self._items[-self.size :]
+
+    @property
+    def is_full(self) -> bool:
+        return len(self) >= self.size
+
+
+class BinaryCircularBuffer(GenericCircularBuffer[bool]):
+    """GenericCircularBuffer of boolean items.
+
+    Introduces properties to get success/failures and their respective ratios.
+    """
+
+    @property
+    def success_count(self) -> int:
+        return self._items.count(True)
+
+    @property
+    def failure_count(self) -> int:
+        return self._items.count(False)
+
+    @property
+    def success_rate(self) -> Fraction:
+        return Fraction(self.success_count, len(self))
+
+    @property
+    def failure_rate(self) -> Fraction:
+        return Fraction(self.failure_count, len(self))

resilient_circuit/circuit_breaker.py

@@ -0,0 +1,311 @@
+import abc
+import enum
+import logging
+from datetime import datetime, timedelta
+from fractions import Fraction
+from functools import wraps
+from typing import Callable, Optional, TypeVar
+
+from typing_extensions import ParamSpec
+
+from resilient_circuit.buffer import BinaryCircularBuffer
+from resilient_circuit.exceptions import ProtectedCallError
+from resilient_circuit.policy import ProtectionPolicy
+from resilient_circuit.storage import CircuitBreakerStorage, InMemoryStorage, create_storage
+
+R = TypeVar("R")
+P = ParamSpec("P")
+
+logger = logging.getLogger(__name__)
+
+
+class CircuitStatus(enum.Enum):
+    CLOSED = "CLOSED"
+    OPEN = "OPEN"
+    HALF_OPEN = "HALF_OPEN"
+
+
+class CircuitProtectorPolicy(ProtectionPolicy):
+    DEFAULT_THRESHOLD = Fraction(1, 1)
+
+    def __init__(
+        self,
+        *,
+        resource_key: Optional[str] = None,
+        storage: Optional[CircuitBreakerStorage] = None,
+        namespace: Optional[str] = None,
+        cooldown: timedelta = timedelta(0),
+        failure_limit: Fraction = DEFAULT_THRESHOLD,
+        success_limit: Fraction = DEFAULT_THRESHOLD,
+        should_handle: Callable[[Exception], bool] = lambda e: True,
+        on_status_change: Optional[
+            Callable[["CircuitProtectorPolicy", CircuitStatus, CircuitStatus], None]
+        ] = None,
+    ) -> None:
+        # Generate a default resource key if not provided for backward compatibility
+        self.resource_key = resource_key or f"anonymous_{id(self)}"
+        # Create storage with namespace support if not provided
+        self.storage = storage or create_storage(namespace=namespace)
+        self.cooldown = cooldown
+        self.success_limit = success_limit
+        self.failure_limit = failure_limit
+        self.should_consider_failure = should_handle
+        self._on_status_change = on_status_change
+
+        # Load state from storage
+        self._load_state()
+
+    def _load_state(self) -> None:
+        """Load circuit breaker state from storage."""
+        try:
+            state_data = self.storage.get_state(self.resource_key)
+            if state_data:
+                # Restore state from storage
+                state = CircuitStatus(state_data["state"])
+                failure_count = int(state_data.get("failure_count", 0))
+                open_until = float(state_data.get("open_until", 0))
+
+                # Initialize status based on stored state
+                status: CircuitStatusBase
+                if state == CircuitStatus.CLOSED:
+                    status = StatusClosed(policy=self, failure_count=failure_count)
+                elif state == CircuitStatus.OPEN:
+                    # For OPEN state, we need a previous status to pass to the constructor
+                    # We'll use a temporary closed status with same failure count
+                    temp_status = StatusClosed(policy=self, failure_count=failure_count)
+                    status = StatusOpen(policy=self, previous_status=temp_status, open_until=open_until)
+                else:  # HALF_OPEN
+                    status = StatusHalfOpen(policy=self, failure_count=failure_count)
+
+                self._status = status
+                logger.debug(f"Loaded circuit breaker state for {self.resource_key}: {state.value}")
+            else:
+                # No state found, start with CLOSED
+                self._status = StatusClosed(policy=self)
+                logger.debug(f"No stored state found for {self.resource_key}, starting with CLOSED")
+        except Exception as e:
+            logger.error(f"Failed to load state for {self.resource_key}: {e}")
+            # Fallback to default state
+            self._status = StatusClosed(policy=self)
+
+    def _save_state(self) -> None:
+        """Save circuit breaker state to storage."""
+        try:
+            state_value: str = self._status.status_type.value
+            failure_count_val: int = int(getattr(self._status, 'failure_count', 0))
+            # For StatusOpen, use open_until_timestamp; for others, default to 0
+            open_until_val: float = float(
+                getattr(self._status, 'open_until_timestamp', 0)
+                if hasattr(self._status, 'open_until_timestamp') else 0
+            )
+
+            self.storage.set_state(
+                self.resource_key,
+                state_value,
+                failure_count_val,
+                open_until_val
+            )
+            logger.debug(f"Saved circuit breaker state for {self.resource_key}: {state_value}")
+        except Exception as e:
+            logger.error(f"Failed to save state for {self.resource_key}: {e}")
+
+    @property
+    def execution_log(self) -> BinaryCircularBuffer:
+        return self._status.execution_log
+
+    @property
+    def status(self) -> CircuitStatus:
+        return self._status.status_type
+
+    @status.setter
+    def status(self, new_status: CircuitStatus) -> None:
+        old_status = self.status
+        new_status_obj: CircuitStatusBase
+        if new_status is CircuitStatus.CLOSED:
+            # When transitioning to CLOSED, reset failure count
+            new_status_obj = StatusClosed(policy=self, failure_count=0)
+        elif new_status is CircuitStatus.OPEN:
+            # When transitioning to OPEN, keep the failure count from current status
+            current_failure_count = getattr(self._status, 'failure_count', 0)
+            # Calculate the open_until timestamp based on current time and cooldown
+            from datetime import datetime
+            open_until = (datetime.now() + self.cooldown).timestamp()
+            new_status_obj = StatusOpen(policy=self, previous_status=self._status, open_until=open_until)
+        else:  # HALF_OPEN
+            # When transitioning to HALF_OPEN, reset failure count
+            new_status_obj = StatusHalfOpen(policy=self, failure_count=0)
+
+        self._status = new_status_obj
+        self.on_status_change(old_status, new_status)
+        self._save_state()  # Persist state change
+
+    def on_status_change(self, current: CircuitStatus, new: CircuitStatus) -> None:
+        """This method is called whenever protector changes its status."""
+        if self._on_status_change is not None:
+            self._on_status_change(self, current, new)
+
+    def __call__(self, func: Callable[P, R]) -> Callable[P, R]:
+        @wraps(func)
+        def decorated(*args: P.args, **kwargs: P.kwargs) -> R:
+            self._status.validate_execution()
+            try:
+                result = func(*args, **kwargs)
+            except Exception as e:
+                if self.should_consider_failure(e):
+                    self._status.mark_failure()
+                else:
+                    self._status.mark_success()
+                self._save_state()  # Persist state after exception
+                raise
+            else:
+                self._status.mark_success()
+                self._save_state()  # Persist state after success
+                return result
+
+        return decorated
+
+
+class CircuitStatusBase(abc.ABC):
+    """Interface describing common methods of CircuitProtector's status."""
+
+    execution_log: BinaryCircularBuffer
+
+    def __init__(self, policy: CircuitProtectorPolicy):
+        self.policy = policy
+
+    @property
+    @abc.abstractmethod
+    def status_type(self) -> CircuitStatus:
+        """Defines type of the status."""
+
+    @abc.abstractmethod
+    def validate_execution(self) -> None:
+        """Override this method to raise an exception to prevent execution."""
+
+    @abc.abstractmethod
+    def mark_failure(self) -> None:
+        """This method is called whenever execution fails."""
+
+    @abc.abstractmethod
+    def mark_success(self) -> None:
+        """This method is called whenever execution succeeds."""
+
+
+class StatusClosed(CircuitStatusBase):
+    status_type = CircuitStatus.CLOSED
+
+    def __init__(self, policy: CircuitProtectorPolicy, failure_count: int = 0):
+        super().__init__(policy)
+        # Initialize failure_count for StatusClosed
+        self.failure_count = failure_count
+        self.execution_log = BinaryCircularBuffer(size=policy.failure_limit.denominator)
+
+    def validate_execution(self) -> None:
+        # In the CLOSED status, execution is allowed
+        pass
+
+    def mark_failure(self) -> None:
+        self.failure_count += 1  # Increment failure count
+        self.execution_log.add(False)
+        if (
+            self.execution_log.is_full
+            and self.execution_log.failure_rate >= self.policy.failure_limit
+        ):
+            self.policy.status = CircuitStatus.OPEN
+
+    def mark_success(self) -> None:
+        self.failure_count = 0  # Reset failure count on success
+        self.execution_log.add(True)
+
+
+class StatusOpen(CircuitStatusBase):
+    status_type = CircuitStatus.OPEN
+
+    def __init__(self, policy: CircuitProtectorPolicy, previous_status: CircuitStatusBase, open_until: float = 0) -> None:
+        super().__init__(policy)
+        self.execution_log = previous_status.execution_log
+        # Handle setting failure_count from previous_status if it exists
+        if hasattr(previous_status, 'failure_count'):
+            self.failure_count = getattr(previous_status, 'failure_count', 0)
+        else:
+            self.failure_count = 0
+
+        # Store the timestamp when the OPEN state should end (cooldown period)
+        # If open_until is 0, circuit should be blocked for the full cooldown period
+        from datetime import datetime
+        if open_until and open_until > 0:
+            self.open_until_timestamp = open_until  # This is when cooldown ends
+        else:
+            # Calculate when cooldown should end based on current time and policy cooldown
+            self.open_until_timestamp = (datetime.now() + policy.cooldown).timestamp()
+
+    def validate_execution(self) -> None:
+        from datetime import datetime
+        # Check if cooldown period has expired
+        if datetime.now().timestamp() >= self.open_until_timestamp:
+            # Cooldown expired, transition to HALF_OPEN to allow test requests
+            self.policy.status = CircuitStatus.HALF_OPEN
+            return  # Allow execution in HALF_OPEN state
+
+        # Still in cooldown period, block execution
+        raise ProtectedCallError
+
+    def mark_failure(self) -> None:
+        # In OPEN status, errors are not recorded because execution is blocked
+        pass
+
+    def mark_success(self) -> None:
+        self.policy.status = CircuitStatus.HALF_OPEN
+
+
+class StatusHalfOpen(CircuitStatusBase):
+    status_type = CircuitStatus.HALF_OPEN
+
+    def __init__(self, policy: CircuitProtectorPolicy, failure_count: int = 0):
+        super().__init__(policy)
+        self.failure_count = failure_count
+        self.use_success = policy.success_limit != policy.DEFAULT_THRESHOLD
+        self.execution_log = BinaryCircularBuffer(
+            size=(
+                policy.success_limit.denominator
+                if self.use_success
+                else policy.failure_limit.denominator
+            )
+        )
+
+    def validate_execution(self) -> None:
+        # In HALF_OPEN status, execution is allowed
+        pass
+
+    def mark_failure(self) -> None:
+        self.failure_count += 1
+        self.execution_log.add(False)
+        self._check_limit()
+
+    def mark_success(self) -> None:
+        self.failure_count = 0  # Reset on success
+        self.execution_log.add(True)
+        self._check_limit()
+
+    def _check_limit(self) -> None:
+        """Determine whether a limit has been met and the circuit should be opened or closed.
+
+        The circuit changes status only after the expected number of executions take place.
+        If configured, success ratio has precedence over failure ratio.
+        """
+
+        if not self.execution_log.is_full:
+            return
+
+        if self.use_success:
+            self.policy.status = (
+                CircuitStatus.CLOSED
+                if self.execution_log.success_rate >= self.policy.success_limit
+                else CircuitStatus.OPEN
+            )
+        else:
+            self.policy.status = (
+                CircuitStatus.OPEN
+                if self.execution_log.failure_rate >= self.policy.failure_limit
+                else CircuitStatus.CLOSED
+            )

resilient_circuit/cli.py

@@ -0,0 +1,261 @@
+"""
+CLI module for Highway Circuit Breaker
+"""
+
+import argparse
+import os
+import sys
+from typing import Optional
+
+try:
+    import psycopg
+except ImportError:
+    psycopg = None
+
+try:
+    from dotenv import load_dotenv
+except ImportError:
+    load_dotenv = None
+
+
+def load_env_vars():
+    """Load environment variables from .env file if available."""
+    if load_dotenv:
+        load_dotenv()
+    else:
+        print("Warning: python-dotenv not found, skipping .env file loading")
+
+
+def get_db_config_from_env() -> dict:
+    """Get database configuration from environment variables."""
+    return {
+        'host': os.getenv('RC_DB_HOST', 'localhost'),
+        'port': int(os.getenv('RC_DB_PORT', '5432')),
+        'dbname': os.getenv('RC_DB_NAME', 'resilient_circuit_db'),
+        'user': os.getenv('RC_DB_USER', 'postgres'),
+        'password': os.getenv('RC_DB_PASSWORD', 'postgres')
+    }
+
+
+def create_postgres_table(config: dict) -> bool:
+    """Create the circuit breaker table in PostgreSQL database."""
+    if not psycopg:
+        print("Error: psycopg is required for PostgreSQL setup. Install with: pip install resilient_circuit[postgres]")
+        return False
+
+    try:
+        # Connect to the database
+        conn = psycopg.connect(
+            host=config['host'],
+            port=config['port'],
+            dbname=config['dbname'],
+            user=config['user'],
+            password=config['password']
+        )
+
+        with conn:
+            with conn.cursor() as cur:
+                # Check if table already exists
+                cur.execute("""
+                    SELECT EXISTS (
+                        SELECT FROM information_schema.tables
+                        WHERE table_schema = 'public'
+                        AND table_name = 'rc_circuit_breakers'
+                    );
+                """)
+
+                table_exists = cur.fetchone()[0]
+                if table_exists:
+                    print(f"ℹ️  Table 'rc_circuit_breakers' already exists, checking for updates...")
+
+                # Create the circuit breaker table
+                cur.execute("""
+                    CREATE TABLE IF NOT EXISTS rc_circuit_breakers (
+                        resource_key VARCHAR(255) NOT NULL,
+                        state VARCHAR(20) NOT NULL CHECK (state IN ('CLOSED', 'OPEN', 'HALF_OPEN')),
+                        failure_count INTEGER NOT NULL DEFAULT 0 CHECK (failure_count >= 0 AND failure_count <= 2147483647),
+                        open_until TIMESTAMPTZ,
+                        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                        PRIMARY KEY (resource_key)
+                    );
+                """)
+
+                # Create optimized indexes
+                cur.execute("""
+                    CREATE INDEX IF NOT EXISTS idx_rc_circuit_breakers_state
+                    ON rc_circuit_breakers (state);
+                """)
+
+                cur.execute("""
+                    CREATE INDEX IF NOT EXISTS idx_rc_circuit_breakers_open_until
+                    ON rc_circuit_breakers (open_until)
+                    WHERE open_until IS NOT NULL;
+                """)
+
+                cur.execute("""
+                    CREATE INDEX IF NOT EXISTS idx_rc_circuit_breakers_key_state
+                    ON rc_circuit_breakers (resource_key, state);
+                """)
+
+                cur.execute("""
+                    CREATE INDEX IF NOT EXISTS idx_rc_circuit_breakers_state_updated
+                    ON rc_circuit_breakers (state, updated_at DESC);
+                """)
+
+                # Create trigger function
+                cur.execute("""
+                    CREATE OR REPLACE FUNCTION update_rc_circuit_breakers_updated_at_column()
+                    RETURNS TRIGGER AS $$
+                    BEGIN
+                        NEW.updated_at = NOW();
+                        RETURN NEW;
+                    END;
+                    $$ language 'plpgsql' SET search_path = public;
+                """)
+
+                # Create trigger
+                cur.execute("""
+                    DROP TRIGGER IF EXISTS update_rc_circuit_breakers_updated_at
+                    ON rc_circuit_breakers;
+                """)
+
+                cur.execute("""
+                    CREATE TRIGGER update_rc_circuit_breakers_updated_at
+                        BEFORE UPDATE ON rc_circuit_breakers
+                        FOR EACH ROW
+                        WHEN (OLD IS DISTINCT FROM NEW)
+                        EXECUTE FUNCTION update_rc_circuit_breakers_updated_at_column();
+                """)
+
+                # Add table comments
+                cur.execute("""
+                    COMMENT ON TABLE rc_circuit_breakers IS
+                    'Circuit breaker state storage with performance optimizations';
+                """)
+
+                cur.execute("""
+                    COMMENT ON COLUMN rc_circuit_breakers.state IS
+                    'Current state of the circuit breaker: CLOSED, OPEN, or HALF_OPEN';
+                """)
+
+                cur.execute("""
+                    COMMENT ON COLUMN rc_circuit_breakers.open_until IS
+                    'Timestamp when the circuit breaker should transition from OPEN to HALF_OPEN';
+                """)
+
+                cur.execute("""
+                    COMMENT ON COLUMN rc_circuit_breakers.failure_count IS
+                    'Number of consecutive failures since last reset';
+                """)
+
+                conn.commit()
+
+                if table_exists:
+                    print(f"✅ Successfully updated table in database: {config['dbname']}")
+                else:
+                    print(f"✅ Successfully created table in database: {config['dbname']}")
+                return True
+
+    except psycopg.OperationalError as e:
+        if "database" in str(e) and "does not exist" in str(e):
+            print(f"❌ Error: Database '{config['dbname']}' does not exist.")
+            print("💡 Please create the database first or update your RC_DB_NAME in the .env file.")
+            print(f"   You can create it with: createdb -h {config['host']} -p {config['port']} -U {config['user']} {config['dbname']}")
+        else:
+            print(f"❌ Database connection error: {e}")
+        return False
+    except Exception as e:
+        print(f"❌ Error creating table: {e}")
+        return False
+
+
+def run_pg_setup(args: argparse.Namespace) -> int:
+    """Run the PostgreSQL setup command."""
+    print("🚀 Highway Circuit Breaker PostgreSQL Setup")
+    print()
+
+    load_env_vars()
+
+    # Get config from environment
+    config = get_db_config_from_env()
+
+    print(f"🔧 Using database configuration from environment:")
+    print(f"   Host: {config['host']}")
+    print(f"   Port: {config['port']}")
+    print(f"   Database: {config['dbname']}")
+    print(f"   User: {config['user']}")
+
+    if config['dbname'] == 'resilient_circuit_db':
+        print(f"\n⚠️  Note: Using default database name '{config['dbname']}'.")
+        print("   You can customize this by setting RC_DB_NAME in your .env file.")
+
+    if args.dry_run:
+        print("\n📝 DRY RUN MODE - No changes will be made to the database")
+        print("This command would create the required tables and indexes in your PostgreSQL database.")
+        return 0
+
+    # Confirm before proceeding
+    if not args.yes:
+        response = input(f"\n⚠️  This will create/update the circuit breaker table in '{config['dbname']}'. Continue? [y/N]: ")
+        if response.lower() not in ['y', 'yes']:
+            print("❌ Setup cancelled by user.")
+            return 1
+
+    print("\n📦 Creating PostgreSQL table and indexes...")
+    success = create_postgres_table(config)
+
+    if success:
+        print("\n✅ PostgreSQL setup completed successfully!")
+        print("\n📋 The following have been created/updated:")
+        print("   - Table: rc_circuit_breakers")
+        print("   - Primary key index: rc_circuit_breakers_pkey")
+        print("   - Index: idx_rc_circuit_breakers_state")
+        print("   - Index: idx_rc_circuit_breakers_open_until")
+        print("   - Index: idx_rc_circuit_breakers_key_state")
+        print("   - Index: idx_rc_circuit_breakers_state_updated")
+        print("   - Trigger: update_rc_circuit_breakers_updated_at")
+        print("   - Function: update_rc_circuit_breakers_updated_at_column")
+
+        print(f"\n💡 The database '{config['dbname']}' is now ready for use with Highway Circuit Breaker!")
+        return 0
+    else:
+        print("\n❌ PostgreSQL setup failed!")
+        return 1
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog='highway-circutbreaker-cli',
+        description='Highway Circuit Breaker CLI tools'
+    )
+
+    subparsers = parser.add_subparsers(dest='command', help='Available commands')
+
+    # PostgreSQL setup command
+    pg_setup_parser = subparsers.add_parser(
+        'pg-setup',
+        help='Setup PostgreSQL table for circuit breaker state storage'
+    )
+    pg_setup_parser.add_argument(
+        '--yes',
+        action='store_true',
+        help='Skip confirmation prompt'
+    )
+    pg_setup_parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Show what would be done without making changes'
+    )
+
+    args = parser.parse_args()
+
+    if args.command == 'pg-setup':
+        return run_pg_setup(args)
+    else:
+        parser.print_help()
+        return 1
+
+if __name__ == '__main__':
+    sys.exit(main())

resilient_circuit/exceptions.py

@@ -0,0 +1,10 @@
+class ProtectionException(Exception):
+    pass
+
+
+class RetryLimitReached(ProtectionException):
+    pass
+
+
+class ProtectedCallError(ProtectionException):
+    pass