rollgate 1.0.0__py3-none-any.whl

rollgate/__init__.py

@@ -0,0 +1,135 @@
+"""
+Rollgate Python SDK - Feature flags made simple.
+
+Usage:
+    from rollgate import RollgateClient
+
+    client = RollgateClient(api_key="your-api-key")
+    await client.init()
+
+    if client.is_enabled("my-feature"):
+        # Feature is enabled
+        pass
+"""
+
+from rollgate.client import RollgateClient, RollgateConfig, UserContext
+from rollgate.circuit_breaker import (
+    CircuitBreaker,
+    CircuitBreakerConfig,
+    CircuitOpenError,
+    CircuitState,
+)
+from rollgate.retry import RetryConfig, calculate_backoff, is_retryable_error
+from rollgate.cache import CacheConfig, CacheStats, FlagCache
+from rollgate.errors import (
+    RollgateError,
+    AuthenticationError,
+    NetworkError,
+    RateLimitError,
+    ValidationError,
+    InternalError,
+    ErrorCategory,
+)
+from rollgate.dedup import RequestDeduplicator, DedupConfig
+from rollgate.metrics import (
+    SDKMetrics,
+    MetricsSnapshot,
+    RequestMetrics,
+    FlagStats,
+    get_metrics,
+    create_metrics,
+)
+from rollgate.tracing import (
+    TraceContext,
+    RequestTrace,
+    TracingManager,
+    get_tracer,
+    create_tracer,
+)
+from rollgate.evaluate import (
+    Condition,
+    TargetingRule,
+    FlagRule,
+    RulesPayload,
+    EvaluationResult,
+    LocalEvaluator,
+    evaluate_flag,
+    evaluate_all_flags,
+)
+from rollgate.reasons import (
+    EvaluationReason,
+    EvaluationDetail,
+    EvaluationReasonKind,
+    EvaluationErrorKind,
+    off_reason,
+    target_match_reason,
+    rule_match_reason,
+    fallthrough_reason,
+    error_reason,
+    unknown_reason,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    # Client
+    "RollgateClient",
+    "RollgateConfig",
+    "UserContext",
+    # Circuit Breaker
+    "CircuitBreaker",
+    "CircuitBreakerConfig",
+    "CircuitOpenError",
+    "CircuitState",
+    # Retry
+    "RetryConfig",
+    "calculate_backoff",
+    "is_retryable_error",
+    # Cache
+    "CacheConfig",
+    "CacheStats",
+    "FlagCache",
+    # Errors
+    "RollgateError",
+    "AuthenticationError",
+    "NetworkError",
+    "RateLimitError",
+    "ValidationError",
+    "InternalError",
+    "ErrorCategory",
+    # Dedup
+    "RequestDeduplicator",
+    "DedupConfig",
+    # Metrics
+    "SDKMetrics",
+    "MetricsSnapshot",
+    "RequestMetrics",
+    "FlagStats",
+    "get_metrics",
+    "create_metrics",
+    # Tracing
+    "TraceContext",
+    "RequestTrace",
+    "TracingManager",
+    "get_tracer",
+    "create_tracer",
+    # Evaluation
+    "Condition",
+    "TargetingRule",
+    "FlagRule",
+    "RulesPayload",
+    "EvaluationResult",
+    "LocalEvaluator",
+    "evaluate_flag",
+    "evaluate_all_flags",
+    # Reasons
+    "EvaluationReason",
+    "EvaluationDetail",
+    "EvaluationReasonKind",
+    "EvaluationErrorKind",
+    "off_reason",
+    "target_match_reason",
+    "rule_match_reason",
+    "fallthrough_reason",
+    "error_reason",
+    "unknown_reason",
+]

rollgate/cache.py

@@ -0,0 +1,260 @@
+"""
+Flag cache with stale-while-revalidate support.
+"""
+
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional, Callable, Dict, Any
+
+
+@dataclass
+class CacheConfig:
+    """Configuration for cache behavior."""
+
+    ttl_ms: int = 300000
+    """Time-to-live for fresh cache entries (default: 5 minutes)."""
+
+    stale_ttl_ms: int = 3600000
+    """Time-to-live for stale cache entries (default: 1 hour)."""
+
+    persist_path: Optional[str] = None
+    """File path for persistent cache."""
+
+
+@dataclass
+class CacheStats:
+    """Cache statistics."""
+
+    hits: int = 0
+    misses: int = 0
+    stale_hits: int = 0
+    size: int = 0
+
+
+@dataclass
+class CacheEntry:
+    """Cache entry with metadata."""
+
+    value: Dict[str, bool]
+    timestamp: float
+    stale: bool = False
+
+
+@dataclass
+class CacheResult:
+    """Result of a cache lookup."""
+
+    flags: Dict[str, bool]
+    stale: bool
+
+
+DEFAULT_CACHE_CONFIG = CacheConfig()
+
+
+class FlagCache:
+    """
+    Flag cache with stale fallback support.
+
+    Features:
+    - In-memory caching with configurable TTL
+    - Stale-while-revalidate pattern
+    - File persistence
+    - Event callbacks for cache state changes
+    """
+
+    def __init__(self, config: Optional[CacheConfig] = None):
+        self._config = config or DEFAULT_CACHE_CONFIG
+        self._cache: Dict[str, CacheEntry] = {}
+        self._stats = CacheStats()
+        self._callbacks: Dict[str, list[Callable]] = {
+            "cache_hit": [],
+            "cache_miss": [],
+            "cache_set": [],
+            "cache_expired": [],
+            "cache_stale": [],
+        }
+
+    def on(self, event: str, callback: Callable) -> None:
+        """Register an event callback."""
+        if event in self._callbacks:
+            self._callbacks[event].append(callback)
+
+    def off(self, event: str, callback: Callable) -> None:
+        """Remove an event callback."""
+        if event in self._callbacks and callback in self._callbacks[event]:
+            self._callbacks[event].remove(callback)
+
+    def _emit(self, event: str, *args) -> None:
+        """Emit an event to all registered callbacks."""
+        for callback in self._callbacks.get(event, []):
+            try:
+                callback(*args)
+            except Exception:
+                pass
+
+    def get(self, key: str = "flags") -> Optional[CacheResult]:
+        """
+        Get cached flags.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            CacheResult with flags and stale indicator, or None if not found
+        """
+        entry = self._cache.get(key)
+
+        if entry is None:
+            self._stats.misses += 1
+            self._emit("cache_miss", key)
+            return None
+
+        age_ms = (time.time() - entry.timestamp) * 1000
+
+        # Fresh cache
+        if age_ms < self._config.ttl_ms:
+            self._stats.hits += 1
+            self._emit("cache_hit", key, False, age_ms)
+            return CacheResult(flags=entry.value, stale=False)
+
+        # Stale but usable
+        if age_ms < self._config.stale_ttl_ms:
+            self._stats.stale_hits += 1
+            self._emit("cache_hit", key, True, age_ms)
+            self._emit("cache_stale", key, age_ms)
+            return CacheResult(flags=entry.value, stale=True)
+
+        # Expired - remove from cache
+        del self._cache[key]
+        self._stats.size = len(self._cache)
+        self._stats.misses += 1
+        self._emit("cache_expired", key, age_ms)
+        return None
+
+    def set(self, key: str, flags: Dict[str, bool]) -> None:
+        """
+        Store flags in cache.
+
+        Args:
+            key: Cache key
+            flags: Flags dictionary
+        """
+        entry = CacheEntry(
+            value=flags,
+            timestamp=time.time(),
+            stale=False,
+        )
+
+        self._cache[key] = entry
+        self._stats.size = len(self._cache)
+        self._emit("cache_set", key, len(flags))
+
+        # Persist if configured
+        self._persist()
+
+    def has_fresh(self, key: str = "flags") -> bool:
+        """Check if cache has fresh data."""
+        entry = self._cache.get(key)
+        if entry is None:
+            return False
+        age_ms = (time.time() - entry.timestamp) * 1000
+        return age_ms < self._config.ttl_ms
+
+    def has_any(self, key: str = "flags") -> bool:
+        """Check if cache has any data (fresh or stale)."""
+        entry = self._cache.get(key)
+        if entry is None:
+            return False
+        age_ms = (time.time() - entry.timestamp) * 1000
+        return age_ms < self._config.stale_ttl_ms
+
+    def clear(self) -> None:
+        """Clear all cached data."""
+        self._cache.clear()
+        self._stats.size = 0
+
+    def get_stats(self) -> CacheStats:
+        """Get cache statistics."""
+        return CacheStats(
+            hits=self._stats.hits,
+            misses=self._stats.misses,
+            stale_hits=self._stats.stale_hits,
+            size=self._stats.size,
+        )
+
+    def get_hit_rate(self) -> float:
+        """Get hit rate (hits / (hits + misses))."""
+        total = self._stats.hits + self._stats.stale_hits + self._stats.misses
+        if total == 0:
+            return 0.0
+        return (self._stats.hits + self._stats.stale_hits) / total
+
+    def load(self) -> bool:
+        """
+        Load cache from persistent storage.
+
+        Returns:
+            True if cache was loaded successfully
+        """
+        if not self._config.persist_path:
+            return False
+
+        try:
+            path = Path(self._config.persist_path)
+            if not path.exists():
+                return False
+
+            data = json.loads(path.read_text())
+            entries = data.get("entries", [])
+
+            for key, entry_data in entries:
+                timestamp = entry_data.get("timestamp", 0)
+                age_ms = (time.time() - timestamp) * 1000
+
+                # Only restore if within stale TTL
+                if age_ms < self._config.stale_ttl_ms:
+                    self._cache[key] = CacheEntry(
+                        value=entry_data.get("value", {}),
+                        timestamp=timestamp,
+                        stale=age_ms >= self._config.ttl_ms,
+                    )
+
+            self._stats.size = len(self._cache)
+            return True
+        except Exception:
+            return False
+
+    def _persist(self) -> bool:
+        """
+        Persist cache to storage.
+
+        Returns:
+            True if cache was persisted successfully
+        """
+        if not self._config.persist_path:
+            return False
+
+        try:
+            data = {
+                "version": 1,
+                "entries": [
+                    [key, {"value": entry.value, "timestamp": entry.timestamp}]
+                    for key, entry in self._cache.items()
+                ],
+            }
+            path = Path(self._config.persist_path)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(json.dumps(data))
+            return True
+        except Exception:
+            return False
+
+    def close(self) -> None:
+        """Cleanup resources and final persist."""
+        if self._config.persist_path:
+            self._persist()
+        # Clear all callbacks to prevent memory leaks
+        for event in self._callbacks:
+            self._callbacks[event].clear()

rollgate/circuit_breaker.py

@@ -0,0 +1,240 @@
+"""
+Circuit Breaker implementation.
+
+Prevents cascading failures by failing fast when a service is down.
+"""
+
+import time
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable, TypeVar, Optional, Awaitable, List
+
+T = TypeVar("T")
+
+
+class CircuitState(str, Enum):
+    """Circuit breaker states."""
+
+    CLOSED = "closed"
+    """Normal operation, requests pass through."""
+
+    OPEN = "open"
+    """Circuit is open, requests fail fast."""
+
+    HALF_OPEN = "half_open"
+    """Testing if service has recovered."""
+
+
+@dataclass
+class CircuitBreakerConfig:
+    """Configuration for circuit breaker behavior."""
+
+    failure_threshold: int = 5
+    """Number of failures before opening circuit."""
+
+    recovery_timeout_ms: int = 30000
+    """Time to wait before attempting recovery."""
+
+    monitoring_window_ms: int = 60000
+    """Window for counting failures."""
+
+    success_threshold: int = 3
+    """Number of successful requests in half-open to close circuit."""
+
+
+@dataclass
+class CircuitBreakerStats:
+    """Statistics about circuit breaker state."""
+
+    state: CircuitState
+    failures: int
+    last_failure_time: Optional[float]
+    half_open_successes: int
+
+
+class CircuitOpenError(Exception):
+    """Raised when circuit breaker is open."""
+
+    def __init__(self, message: str = "Circuit breaker is open", retry_after_ms: int = 0):
+        super().__init__(message)
+        self.retry_after_ms = retry_after_ms
+
+
+DEFAULT_CIRCUIT_BREAKER_CONFIG = CircuitBreakerConfig()
+
+
+class CircuitBreaker:
+    """
+    Circuit Breaker implementation.
+
+    States:
+    - CLOSED: Normal operation, all requests pass through
+    - OPEN: Service is down, all requests fail immediately
+    - HALF_OPEN: Testing recovery, limited requests allowed
+    """
+
+    def __init__(self, config: Optional[CircuitBreakerConfig] = None):
+        self._config = config or DEFAULT_CIRCUIT_BREAKER_CONFIG
+        self._state = CircuitState.CLOSED
+        self._failures: List[float] = []
+        self._last_failure_time: float = 0
+        self._half_open_successes: int = 0
+        self._callbacks: dict[str, list[Callable]] = {
+            "state_change": [],
+            "circuit_open": [],
+            "circuit_closed": [],
+            "circuit_half_open": [],
+        }
+
+    def on(self, event: str, callback: Callable) -> None:
+        """Register an event callback."""
+        if event in self._callbacks:
+            self._callbacks[event].append(callback)
+
+    def off(self, event: str, callback: Callable) -> None:
+        """Remove an event callback."""
+        if event in self._callbacks and callback in self._callbacks[event]:
+            self._callbacks[event].remove(callback)
+
+    def clear_callbacks(self) -> None:
+        """Clear all callbacks (for cleanup)."""
+        for event in self._callbacks:
+            self._callbacks[event].clear()
+
+    def _emit(self, event: str, *args) -> None:
+        """Emit an event to all registered callbacks."""
+        for callback in self._callbacks.get(event, []):
+            try:
+                callback(*args)
+            except Exception:
+                pass  # Don't let callback errors affect circuit breaker
+
+    async def execute(self, fn: Callable[[], Awaitable[T]]) -> T:
+        """
+        Execute a function through the circuit breaker.
+
+        Args:
+            fn: Async function to execute
+
+        Returns:
+            Result of the function
+
+        Raises:
+            CircuitOpenError: If circuit is open
+            Exception: Any exception from the function
+        """
+        # Check if circuit should transition from OPEN to HALF_OPEN
+        if self._state == CircuitState.OPEN:
+            if self._should_attempt_reset():
+                self._transition_to(CircuitState.HALF_OPEN)
+            else:
+                retry_after = self._get_time_until_retry()
+                raise CircuitOpenError(
+                    f"Circuit breaker is open. Will retry after {retry_after}ms",
+                    retry_after_ms=retry_after,
+                )
+
+        try:
+            result = await fn()
+            self._on_success()
+            return result
+        except Exception as error:
+            self._on_failure()
+            raise
+
+    def _on_success(self) -> None:
+        """Handle successful request."""
+        if self._state == CircuitState.HALF_OPEN:
+            self._half_open_successes += 1
+
+            if self._half_open_successes >= self._config.success_threshold:
+                self._reset()
+
+        # Clean up old failures outside monitoring window
+        self._cleanup_old_failures()
+
+    def _on_failure(self) -> None:
+        """Handle failed request."""
+        now = time.time() * 1000  # Convert to ms
+        self._failures.append(now)
+        self._last_failure_time = now
+
+        # If in HALF_OPEN, immediately open the circuit
+        if self._state == CircuitState.HALF_OPEN:
+            self._transition_to(CircuitState.OPEN)
+            self._half_open_successes = 0
+            return
+
+        # Clean up old failures and check threshold
+        self._cleanup_old_failures()
+
+        if len(self._failures) >= self._config.failure_threshold:
+            self._transition_to(CircuitState.OPEN)
+
+    def _cleanup_old_failures(self) -> None:
+        """Remove failures outside the monitoring window."""
+        cutoff = time.time() * 1000 - self._config.monitoring_window_ms
+        self._failures = [t for t in self._failures if t > cutoff]
+
+    def _should_attempt_reset(self) -> bool:
+        """Check if enough time has passed to attempt reset."""
+        elapsed = time.time() * 1000 - self._last_failure_time
+        return elapsed >= self._config.recovery_timeout_ms
+
+    def _get_time_until_retry(self) -> int:
+        """Get time until next retry attempt is allowed."""
+        elapsed = time.time() * 1000 - self._last_failure_time
+        return max(0, int(self._config.recovery_timeout_ms - elapsed))
+
+    def _transition_to(self, new_state: CircuitState) -> None:
+        """Transition to a new state."""
+        old_state = self._state
+        self._state = new_state
+
+        self._emit("state_change", old_state, new_state)
+
+        if new_state == CircuitState.OPEN:
+            self._emit("circuit_open", len(self._failures), self._last_failure_time)
+        elif new_state == CircuitState.CLOSED:
+            self._emit("circuit_closed")
+        elif new_state == CircuitState.HALF_OPEN:
+            self._emit("circuit_half_open")
+
+    def _reset(self) -> None:
+        """Reset the circuit breaker to closed state."""
+        self._failures = []
+        self._half_open_successes = 0
+        self._transition_to(CircuitState.CLOSED)
+
+    def force_reset(self) -> None:
+        """Force reset the circuit breaker (for testing/manual recovery)."""
+        self._reset()
+
+    def force_open(self) -> None:
+        """Force open the circuit breaker (for testing/manual circuit trip)."""
+        self._last_failure_time = time.time() * 1000
+        self._transition_to(CircuitState.OPEN)
+
+    @property
+    def state(self) -> CircuitState:
+        """Get current circuit state."""
+        return self._state
+
+    def get_stats(self) -> CircuitBreakerStats:
+        """Get circuit breaker statistics."""
+        return CircuitBreakerStats(
+            state=self._state,
+            failures=len(self._failures),
+            last_failure_time=self._last_failure_time if self._last_failure_time else None,
+            half_open_successes=self._half_open_successes,
+        )
+
+    def is_allowing_requests(self) -> bool:
+        """Check if circuit is allowing requests."""
+        if self._state == CircuitState.CLOSED:
+            return True
+        if self._state == CircuitState.HALF_OPEN:
+            return True
+        if self._state == CircuitState.OPEN and self._should_attempt_reset():
+            return True
+        return False