rollgate 1.0.0__py3-none-any.whl

rollgate/dedup.py

@@ -0,0 +1,172 @@
+"""
+Request deduplication to prevent duplicate inflight requests.
+"""
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Dict, Optional, Any, Callable, Awaitable, TypeVar, Generic
+
+T = TypeVar("T")
+
+
+@dataclass
+class DedupConfig:
+    """Configuration for request deduplication."""
+
+    enabled: bool = True
+    """Enable request deduplication."""
+
+    ttl_ms: int = 5000
+    """Time-to-live for inflight request tracking (default: 5s)."""
+
+
+DEFAULT_DEDUP_CONFIG = DedupConfig()
+
+
+@dataclass
+class InflightRequest(Generic[T]):
+    """Represents an inflight request."""
+
+    future: asyncio.Future
+    timestamp: float
+    key: str
+
+
+class RequestDeduplicator:
+    """
+    Deduplicates concurrent identical requests.
+
+    When multiple callers request the same resource simultaneously,
+    only one actual request is made and the result is shared.
+
+    Example:
+        ```python
+        dedup = RequestDeduplicator()
+
+        # These concurrent calls will result in only one actual fetch
+        async with asyncio.TaskGroup() as tg:
+            tg.create_task(dedup.dedupe("flags", fetch_flags))
+            tg.create_task(dedup.dedupe("flags", fetch_flags))
+            tg.create_task(dedup.dedupe("flags", fetch_flags))
+        ```
+    """
+
+    def __init__(self, config: DedupConfig = DEFAULT_DEDUP_CONFIG):
+        """
+        Initialize the deduplicator.
+
+        Args:
+            config: Deduplication configuration
+        """
+        self._config = config
+        self._inflight: Dict[str, InflightRequest] = {}
+        self._lock = asyncio.Lock()
+
+        # Statistics
+        self._total_requests = 0
+        self._deduplicated_requests = 0
+
+    async def dedupe(
+        self,
+        key: str,
+        request_fn: Callable[[], Awaitable[T]],
+    ) -> T:
+        """
+        Execute a request with deduplication.
+
+        If an identical request (by key) is already inflight,
+        wait for its result instead of making a new request.
+
+        Args:
+            key: Unique key for this request type
+            request_fn: Async function to execute if no inflight request exists
+
+        Returns:
+            Result of the request
+        """
+        if not self._config.enabled:
+            return await request_fn()
+
+        async with self._lock:
+            self._total_requests += 1
+
+            # Clean up expired inflight requests
+            self._cleanup_expired()
+
+            # Check for existing inflight request
+            if key in self._inflight:
+                inflight = self._inflight[key]
+                self._deduplicated_requests += 1
+                # Wait for existing request to complete
+                return await inflight.future
+
+            # Create new inflight request
+            loop = asyncio.get_running_loop()
+            future: asyncio.Future = loop.create_future()
+            self._inflight[key] = InflightRequest(
+                future=future,
+                timestamp=time.time(),
+                key=key,
+            )
+
+        # Execute request outside lock
+        try:
+            result = await request_fn()
+            # Set result for all waiters
+            if not future.done():
+                future.set_result(result)
+            return result
+        except Exception as e:
+            # Propagate error to all waiters
+            if not future.done():
+                future.set_exception(e)
+            raise
+        finally:
+            # Remove from inflight
+            async with self._lock:
+                if key in self._inflight and self._inflight[key].future is future:
+                    del self._inflight[key]
+
+    def _cleanup_expired(self) -> None:
+        """Remove expired inflight requests."""
+        now = time.time()
+        ttl_seconds = self._config.ttl_ms / 1000
+        expired_keys = [
+            key
+            for key, req in self._inflight.items()
+            if now - req.timestamp > ttl_seconds
+        ]
+        for key in expired_keys:
+            del self._inflight[key]
+
+    @property
+    def inflight_count(self) -> int:
+        """Get number of currently inflight requests."""
+        return len(self._inflight)
+
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get deduplication statistics.
+
+        Returns:
+            Dictionary with total_requests, deduplicated_requests, dedup_rate
+        """
+        total = self._total_requests
+        deduped = self._deduplicated_requests
+        return {
+            "total_requests": total,
+            "deduplicated_requests": deduped,
+            "dedup_rate": deduped / total if total > 0 else 0,
+            "inflight_count": len(self._inflight),
+        }
+
+    def reset_stats(self) -> None:
+        """Reset statistics counters."""
+        self._total_requests = 0
+        self._deduplicated_requests = 0
+
+    async def clear(self) -> None:
+        """Clear all inflight requests."""
+        async with self._lock:
+            self._inflight.clear()

rollgate/errors.py

@@ -0,0 +1,162 @@
+"""
+Error types for Rollgate SDK.
+
+Provides structured error handling with categories for better error management.
+"""
+
+from enum import Enum
+from typing import Optional
+
+
+class ErrorCategory(str, Enum):
+    """Categories of errors for classification."""
+
+    AUTH = "auth"
+    NETWORK = "network"
+    RATE_LIMIT = "rate_limit"
+    VALIDATION = "validation"
+    NOT_FOUND = "not_found"
+    INTERNAL = "internal"
+    UNKNOWN = "unknown"
+
+
+class RollgateError(Exception):
+    """Base exception for all Rollgate SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        category: ErrorCategory = ErrorCategory.UNKNOWN,
+        status_code: Optional[int] = None,
+        retryable: bool = False,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.category = category
+        self.status_code = status_code
+        self.retryable = retryable
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(message={self.message!r}, category={self.category})"
+
+
+class AuthenticationError(RollgateError):
+    """Raised when authentication fails (401/403)."""
+
+    def __init__(self, message: str = "Authentication failed", status_code: int = 401):
+        super().__init__(
+            message,
+            category=ErrorCategory.AUTH,
+            status_code=status_code,
+            retryable=False,
+        )
+
+
+class NetworkError(RollgateError):
+    """Raised when a network error occurs."""
+
+    def __init__(self, message: str = "Network error"):
+        super().__init__(
+            message,
+            category=ErrorCategory.NETWORK,
+            status_code=None,
+            retryable=True,
+        )
+
+
+class RateLimitError(RollgateError):
+    """Raised when rate limited (429)."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: Optional[int] = None,
+    ):
+        super().__init__(
+            message,
+            category=ErrorCategory.RATE_LIMIT,
+            status_code=429,
+            retryable=True,
+        )
+        self.retry_after = retry_after
+
+
+class ValidationError(RollgateError):
+    """Raised when validation fails (400)."""
+
+    def __init__(self, message: str = "Validation error"):
+        super().__init__(
+            message,
+            category=ErrorCategory.VALIDATION,
+            status_code=400,
+            retryable=False,
+        )
+
+
+class NotFoundError(RollgateError):
+    """Raised when resource not found (404)."""
+
+    def __init__(self, message: str = "Resource not found"):
+        super().__init__(
+            message,
+            category=ErrorCategory.NOT_FOUND,
+            status_code=404,
+            retryable=False,
+        )
+
+
+class InternalError(RollgateError):
+    """Raised when server error occurs (5xx)."""
+
+    def __init__(self, message: str = "Internal server error", status_code: int = 500):
+        super().__init__(
+            message,
+            category=ErrorCategory.INTERNAL,
+            status_code=status_code,
+            retryable=True,
+        )
+
+
+def classify_error(error: Exception, status_code: Optional[int] = None) -> RollgateError:
+    """
+    Classify an exception into a RollgateError.
+
+    Args:
+        error: The original exception
+        status_code: Optional HTTP status code
+
+    Returns:
+        A classified RollgateError
+    """
+    if isinstance(error, RollgateError):
+        return error
+
+    message = str(error)
+
+    # Network errors
+    network_indicators = [
+        "connection",
+        "timeout",
+        "econnrefused",
+        "etimedout",
+        "enotfound",
+        "network",
+        "dns",
+    ]
+    if any(indicator in message.lower() for indicator in network_indicators):
+        return NetworkError(message)
+
+    # HTTP status code based classification
+    if status_code:
+        if status_code == 401 or status_code == 403:
+            return AuthenticationError(message, status_code)
+        if status_code == 404:
+            return NotFoundError(message)
+        if status_code == 429:
+            return RateLimitError(message)
+        if status_code == 400:
+            return ValidationError(message)
+        if 500 <= status_code < 600:
+            return InternalError(message, status_code)
+
+    return RollgateError(message)

rollgate/evaluate.py

@@ -0,0 +1,345 @@
+"""
+Client-side flag evaluation logic.
+Mirrors the server-side evaluation for consistency.
+"""
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any, Union
+
+
+@dataclass
+class Condition:
+    """Represents a targeting condition."""
+    attribute: str
+    operator: str
+    value: str
+
+
+@dataclass
+class TargetingRule:
+    """Represents a targeting rule with conditions."""
+    id: str
+    enabled: bool
+    rollout: int
+    conditions: List[Condition] = field(default_factory=list)
+    name: Optional[str] = None
+
+
+@dataclass
+class FlagRule:
+    """Represents a feature flag with targeting rules."""
+    key: str
+    enabled: bool
+    rollout: int
+    target_users: List[str] = field(default_factory=list)
+    rules: List[TargetingRule] = field(default_factory=list)
+
+
+@dataclass
+class RulesPayload:
+    """Represents the rules response from the API."""
+    version: str
+    flags: Dict[str, FlagRule] = field(default_factory=dict)
+
+
+@dataclass
+class EvaluationResult:
+    """Represents the result of a flag evaluation."""
+    enabled: bool
+    value: Any
+    variation_id: Optional[str] = None
+
+
+@dataclass
+class UserContext:
+    """User context for targeting."""
+    id: str
+    email: Optional[str] = None
+    attributes: Optional[Dict[str, Any]] = None
+
+
+def evaluate_flag(rule: FlagRule, user: Optional[UserContext]) -> bool:
+    """
+    Evaluate a flag for a given user context using client-side rules.
+
+    Evaluation priority:
+    1. If flag is disabled, return false
+    2. If user is in targetUsers list, return true
+    3. If user matches any enabled targeting rule, use rule's rollout
+    4. Otherwise, use flag's default rollout percentage
+    """
+    # 1. If flag is disabled, always return false
+    if not rule.enabled:
+        return False
+
+    # 2. Check if user is in target list
+    if user and user.id and rule.target_users:
+        if user.id in rule.target_users:
+            return True
+
+    # 3. Check targeting rules
+    if user and rule.rules:
+        for targeting_rule in rule.rules:
+            if targeting_rule.enabled and _matches_rule(targeting_rule, user):
+                if targeting_rule.rollout >= 100:
+                    return True
+                if targeting_rule.rollout <= 0:
+                    return False
+                return _is_in_rollout(rule.key, user.id, targeting_rule.rollout)
+
+    # 4. Default rollout percentage
+    if rule.rollout >= 100:
+        return True
+    if rule.rollout <= 0:
+        return False
+
+    # Use consistent hashing for rollout (requires user ID)
+    if not user or not user.id:
+        return False
+    return _is_in_rollout(rule.key, user.id, rule.rollout)
+
+
+def _matches_rule(rule: TargetingRule, user: UserContext) -> bool:
+    """
+    Check if a user matches a targeting rule.
+    All conditions within a rule must match (AND logic).
+    """
+    if not rule.conditions:
+        return False
+
+    for condition in rule.conditions:
+        if not _matches_condition(condition, user):
+            return False
+    return True
+
+
+def _matches_condition(condition: Condition, user: UserContext) -> bool:
+    """Check if a user matches a single condition."""
+    attr_value = _get_attribute_value(condition.attribute, user)
+    exists = attr_value is not None and str(attr_value) != ""
+
+    # Handle is_set / is_not_set operators first
+    if condition.operator == "is_set":
+        return exists
+    if condition.operator == "is_not_set":
+        return not exists
+
+    # For other operators, if attribute doesn't exist, condition fails
+    if not exists:
+        return False
+
+    value = str(attr_value).lower()
+    cond_value = condition.value.lower()
+
+    if condition.operator == "equals":
+        return value == cond_value
+    elif condition.operator == "not_equals":
+        return value != cond_value
+    elif condition.operator == "contains":
+        return cond_value in value
+    elif condition.operator == "not_contains":
+        return cond_value not in value
+    elif condition.operator == "starts_with":
+        return value.startswith(cond_value)
+    elif condition.operator == "ends_with":
+        return value.endswith(cond_value)
+    elif condition.operator == "in":
+        values = [v.strip().lower() for v in condition.value.split(",")]
+        return value in values
+    elif condition.operator == "not_in":
+        values = [v.strip().lower() for v in condition.value.split(",")]
+        return value not in values
+    elif condition.operator == "greater_than":
+        return _compare_numeric(attr_value, condition.value, ">")
+    elif condition.operator == "greater_equal":
+        return _compare_numeric(attr_value, condition.value, ">=")
+    elif condition.operator == "less_than":
+        return _compare_numeric(attr_value, condition.value, "<")
+    elif condition.operator == "less_equal":
+        return _compare_numeric(attr_value, condition.value, "<=")
+    elif condition.operator == "regex":
+        try:
+            return bool(re.match(condition.value, str(attr_value)))
+        except re.error:
+            return False
+    elif condition.operator == "semver_gt":
+        return _compare_semver(str(attr_value), condition.value, ">")
+    elif condition.operator == "semver_lt":
+        return _compare_semver(str(attr_value), condition.value, "<")
+    elif condition.operator == "semver_eq":
+        return _compare_semver(str(attr_value), condition.value, "=")
+    else:
+        return False
+
+
+def _get_attribute_value(attribute: str, user: UserContext) -> Any:
+    """Get an attribute value from user context."""
+    if user is None:
+        return None
+    if attribute == "id":
+        return user.id
+    elif attribute == "email":
+        return user.email
+    elif user.attributes:
+        return user.attributes.get(attribute)
+    return None
+
+
+def _compare_numeric(attr_val: Any, cond_val: str, op: str) -> bool:
+    """Compare two numeric values."""
+    try:
+        a = float(str(attr_val))
+        b = float(cond_val)
+
+        if op == ">":
+            return a > b
+        elif op == ">=":
+            return a >= b
+        elif op == "<":
+            return a < b
+        elif op == "<=":
+            return a <= b
+        else:
+            return False
+    except (ValueError, TypeError):
+        return False
+
+
+def _compare_semver(attr_val: str, cond_val: str, op: str) -> bool:
+    """Compare two semantic versions."""
+    a = _parse_version(attr_val)
+    b = _parse_version(cond_val)
+    if a is None or b is None:
+        return False
+
+    # Pad lists to same length
+    while len(a) < len(b):
+        a.append(0)
+    while len(b) < len(a):
+        b.append(0)
+
+    # Compare each part
+    for i in range(len(a)):
+        if a[i] > b[i]:
+            return op in (">", ">=")
+        if a[i] < b[i]:
+            return op in ("<", "<=")
+
+    # Equal
+    return op in ("=", ">=", "<=")
+
+
+def _parse_version(v: str) -> Optional[List[int]]:
+    """Parse a semantic version string."""
+    clean = v.lstrip("v")
+    parts = clean.split(".")
+    try:
+        return [int(p) for p in parts]
+    except ValueError:
+        return None
+
+
+def _is_in_rollout(flag_key: str, user_id: str, percentage: int) -> bool:
+    """
+    Consistent hashing for rollout percentage.
+    Uses SHA-256 hash of flagKey:userId to ensure:
+    - Same user always gets same result for a given flag
+    - Distribution is statistically uniform
+    """
+    hash_input = f"{flag_key}:{user_id}".encode("utf-8")
+    hash_bytes = hashlib.sha256(hash_input).digest()
+    # Use first 4 bytes as uint32 and mod 100 to get a value 0-99
+    value = int.from_bytes(hash_bytes[:4], byteorder="big") % 100
+    return value < percentage
+
+
+def evaluate_all_flags(
+    rules: Dict[str, FlagRule],
+    user: Optional[UserContext]
+) -> Dict[str, bool]:
+    """Evaluate all flags for a user context."""
+    return {key: evaluate_flag(rule, user) for key, rule in rules.items()}
+
+
+class LocalEvaluator:
+    """
+    Local evaluator for client-side flag evaluation.
+
+    Example:
+        ```python
+        evaluator = LocalEvaluator()
+        evaluator.set_rules(rules_payload)
+
+        user = UserContext(id="user-123", email="user@example.com")
+        enabled = evaluator.evaluate("my-feature", user, default_value=False)
+        ```
+    """
+
+    def __init__(self):
+        """Initialize the local evaluator."""
+        self._rules: Dict[str, FlagRule] = {}
+        self._version: str = ""
+
+    def set_rules(self, payload: RulesPayload) -> None:
+        """Set the rules for local evaluation."""
+        self._rules = payload.flags
+        self._version = payload.version
+
+    def set_rules_from_dict(self, data: Dict[str, Any]) -> None:
+        """Set rules from a dictionary (e.g., from JSON)."""
+        self._version = data.get("version", "")
+        self._rules = {}
+
+        for key, flag_data in data.get("flags", {}).items():
+            rules = []
+            for rule_data in flag_data.get("rules", []):
+                conditions = [
+                    Condition(
+                        attribute=c.get("attribute", ""),
+                        operator=c.get("operator", ""),
+                        value=c.get("value", ""),
+                    )
+                    for c in rule_data.get("conditions", [])
+                ]
+                rules.append(TargetingRule(
+                    id=rule_data.get("id", ""),
+                    name=rule_data.get("name"),
+                    enabled=rule_data.get("enabled", False),
+                    rollout=rule_data.get("rollout", 0),
+                    conditions=conditions,
+                ))
+
+            self._rules[key] = FlagRule(
+                key=key,
+                enabled=flag_data.get("enabled", False),
+                rollout=flag_data.get("rollout", 0),
+                target_users=flag_data.get("targetUsers", []),
+                rules=rules,
+            )
+
+    @property
+    def version(self) -> str:
+        """Get the current rules version."""
+        return self._version
+
+    def evaluate(
+        self,
+        flag_key: str,
+        user: Optional[UserContext],
+        default_value: bool = False
+    ) -> bool:
+        """Evaluate a single flag."""
+        rule = self._rules.get(flag_key)
+        if rule is None:
+            return default_value
+        return evaluate_flag(rule, user)
+
+    def evaluate_all(self, user: Optional[UserContext]) -> Dict[str, bool]:
+        """Evaluate all flags."""
+        return evaluate_all_flags(self._rules, user)
+
+    def has_flag(self, flag_key: str) -> bool:
+        """Check if a flag exists."""
+        return flag_key in self._rules