cachekit 0.3.0__cp39-cp39-win_amd64.whl

cachekit/__init__.py

@@ -0,0 +1,114 @@
+r"""cachekit - Caching decorator for Python applications.
+
+A robust, production-ready Python library that provides intelligent Redis caching
+capabilities with advanced features like chunked data handling, multi-serialization
+support, distributed locking, and automatic corruption detection.
+
+Key Features:
+- **Intelligent @cache decorator** with auto-detection and intent-based optimization
+- **Circuit breaker protection** against cascading failures
+- **Adaptive timeout adjustment** based on historical Redis latency patterns
+- **Backpressure control** to prevent Redis overload
+- **Connection pooling** for optimized performance
+- **Health check methods** for comprehensive monitoring
+- **Structured logging** with correlation IDs and distributed tracing
+- **Statistics collection** for Prometheus metrics integration
+
+Architecture Overview:
+cachekit v0.1.0 provides a modular decorator architecture with intelligent
+auto-detection and intent-based optimization. The v0.1 architecture includes:
+
+- FeatureOrchestrator: Manages enterprise-grade reliability and monitoring features
+- Flexible configuration interface with intelligent auto-detection
+- Enhanced error handling with comprehensive safety checks
+- Streamlined connection management with optimized components
+
+Born from production debugging of Redis caching failures:
+- UTF-8 corruption prevention with intelligent binary data handling
+- Binary data magic byte detection and validation
+- Chunked storage for large objects with atomic operations
+- Comprehensive checksum validation and recovery
+
+Example Usage:
+    ```python
+    from cachekit import cache
+
+    # Intelligent cache with zero configuration (90% of use cases)
+    @cache
+    def expensive_function():
+        return compute_result()
+
+    # Intent-based optimization (9% of use cases)
+    @cache.minimal      # Speed-critical functions
+    def get_price(symbol: str):
+        return fetch_price(symbol)
+
+    @cache.production      # Reliability-critical functions
+    def process_payment(amount: Decimal):
+        return payment_gateway.charge(amount)
+
+    @cache.secure    # Security-critical functions
+    def get_user_data(user_id: int) -> UserProfile:
+        return db.fetch_user(user_id)
+
+    # Manual configuration when needed (1% of use cases)
+    @cache(ttl=3600, namespace="custom", circuit_breaker=True)
+    def custom_function():
+        return special_computation()
+
+    # Health monitoring
+    health = custom_function.get_health_status()
+    full_health = custom_function.check_health()
+    ```
+"""
+
+__version__ = "0.3.0"
+
+from typing import Any, Callable, TypeVar
+
+# Configure hiredis compatibility BEFORE any Redis imports
+# This prevents GIL warnings in Python 3.13+ free-threading mode
+try:
+    from . import hiredis_compat
+except ImportError:
+    pass
+
+# Import the configuration classes
+# Redis client is automatically fast - no special import needed
+from .config import DecoratorConfig
+
+# Import the intelligent cache decorator and CacheInfo
+from .decorators import cache
+from .decorators.wrapper import CacheInfo
+
+# Import health check functionality
+from .health import (
+    HealthCheckResult,
+    HealthLevel,
+    HealthStatus,
+    async_health_check_handler,
+    get_health_checker,
+    health_check_handler,
+)
+
+# L1/L2 architecture integrated into standard cache interface
+# No separate imports needed - cache.minimal/.production/.secure handle L1+L2 transparently
+# Import reliability configuration
+from .reliability import CircuitBreakerConfig
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+__all__ = [
+    "__version__",
+    "async_health_check_handler",
+    "cache",
+    "CacheInfo",
+    "CircuitBreakerConfig",
+    "DecoratorConfig",
+    "get_health_checker",
+    "health_check_handler",
+    "HealthCheckResult",
+    "HealthLevel",
+    "HealthStatus",
+]

cachekit/backends/__init__.py

@@ -0,0 +1,94 @@
+"""Backend storage abstraction for cachekit.
+
+This module provides protocol-based abstraction for L2 backend storage with
+dependency injection pattern. Backends can be Redis, HTTP, DynamoDB, or any
+key-value store.
+
+Public API:
+    - BaseBackend: Core protocol (5 methods: get, set, delete, exists, health_check)
+    - TTLInspectableBackend: Optional protocol for TTL inspection/refresh
+    - LockableBackend: Optional protocol for distributed locking
+    - TimeoutConfigurableBackend: Optional protocol for per-operation timeouts
+    - BackendProvider: Dependency injection protocol
+    - BackendError: Exception raised by backend operations
+    - BackendErrorType: Error classification enum
+    - CapabilityNotAvailableError: Exception for missing optional capabilities
+    - RedisBackend: Redis implementation (default)
+
+Usage:
+    >>> from cachekit.backends import BaseBackend, RedisBackend, BackendError
+    >>> # RedisBackend usage requires Redis connection
+    >>> # See RedisBackend documentation for connection details
+
+Dependency injection pattern:
+    >>> from cachekit.backends import BackendProvider
+    >>> # Implement BackendProvider protocol in your application
+    >>> # See BackendProvider documentation for implementation examples
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from cachekit.backends.base import (
+    BaseBackend,
+    LockableBackend,
+    TimeoutConfigurableBackend,
+    TTLInspectableBackend,
+)
+from cachekit.backends.errors import (
+    BackendError,
+    BackendErrorType,
+    CapabilityNotAvailableError,
+)
+from cachekit.backends.redis import RedisBackend
+
+__all__ = [
+    "BaseBackend",
+    "TTLInspectableBackend",
+    "LockableBackend",
+    "TimeoutConfigurableBackend",
+    "BackendProvider",
+    "BackendError",
+    "BackendErrorType",
+    "CapabilityNotAvailableError",
+    "RedisBackend",
+]
+
+
+class BackendProvider(Protocol):
+    """Protocol for dependency injection of backend instances.
+
+    Enables testability and pluggable backends without hardcoding concrete
+    implementations. The provider manages backend lifecycle (singleton,
+    pooling, per-request creation, etc.).
+
+    Example:
+        >>> from cachekit.backends import BackendProvider, BaseBackend
+        >>> # Implement BackendProvider protocol:
+        >>> # class MyProvider:
+        >>> #     def get_backend(self) -> BaseBackend:
+        >>> #         return RedisBackend()
+        >>> # provider = MyProvider()
+        >>> # backend = provider.get_backend()
+
+    Note:
+        This is a structural protocol (PEP 544) - any class with a get_backend()
+        method satisfies this protocol without explicit inheritance.
+    """
+
+    def get_backend(self) -> BaseBackend:
+        """Return a BaseBackend instance.
+
+        Implementation can manage singleton, pooling, or per-request creation
+        depending on backend requirements.
+
+        Returns:
+            BaseBackend instance ready for cache operations
+
+        Example:
+            >>> provider = RedisBackendProvider()  # doctest: +SKIP
+            >>> backend = provider.get_backend()  # doctest: +SKIP
+            >>> backend.set("key", b"value", ttl=60)  # doctest: +SKIP
+        """
+        ...

cachekit/backends/base.py

@@ -0,0 +1,276 @@
+"""Base backend protocol definitions.
+
+This module defines the storage backend contract using PEP 544 protocol-based abstraction.
+All L2 backends (Redis, HTTP, etc.) must implement BaseBackend protocol.
+
+Optional capability protocols (TTLInspectableBackend, LockableBackend,
+TimeoutConfigurableBackend) enable advanced features with graceful degradation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any, Optional, Protocol, runtime_checkable
+
+# Re-export BackendError for convenience (public API)
+from cachekit.backends.errors import BackendError  # noqa: F401
+
+
+@runtime_checkable
+class BaseBackend(Protocol):
+    """Protocol defining the L2 backend storage contract.
+
+    All backend implementations must support these four operations on bytes.
+    This protocol uses structural subtyping (PEP 544) - any class implementing
+    these methods is considered a valid backend.
+
+    Design principles:
+    - Stateless operations (no connection management in protocol)
+    - Bytes-only interface (language-agnostic, no Python-specific types)
+    - No Redis-specific concepts (works for any backend: Redis, HTTP, DynamoDB, etc.)
+    - Simple and focused (KISS principle)
+
+    Example:
+        >>> from cachekit.backends import BaseBackend, RedisBackend
+        >>> backend = RedisBackend()
+        >>> isinstance(backend, BaseBackend)  # Runtime checkable protocol
+        True
+        >>> backend.set("key", b"value", ttl=60)  # doctest: +SKIP
+        >>> data = backend.get("key")  # doctest: +SKIP
+    """
+
+    def get(self, key: str) -> Optional[bytes]:
+        """Retrieve value from backend storage.
+
+        Args:
+            key: Cache key to retrieve
+
+        Returns:
+            Bytes value if found, None if key doesn't exist
+
+        Raises:
+            BackendError: If backend operation fails (network, timeout, etc.)
+        """
+        ...
+
+    def set(self, key: str, value: bytes, ttl: Optional[int] = None) -> None:
+        """Store value in backend storage.
+
+        Args:
+            key: Cache key to store
+            value: Bytes value to store (encrypted or plaintext msgpack)
+            ttl: Time-to-live in seconds (None = no expiry)
+
+        Raises:
+            BackendError: If backend operation fails (network, timeout, etc.)
+        """
+        ...
+
+    def delete(self, key: str) -> bool:
+        """Delete key from backend storage.
+
+        Args:
+            key: Cache key to delete
+
+        Returns:
+            True if key was deleted, False if key didn't exist
+
+        Raises:
+            BackendError: If backend operation fails (network, timeout, etc.)
+        """
+        ...
+
+    def exists(self, key: str) -> bool:
+        """Check if key exists in backend storage.
+
+        Args:
+            key: Cache key to check
+
+        Returns:
+            True if key exists, False otherwise
+
+        Raises:
+            BackendError: If backend operation fails (network, timeout, etc.)
+        """
+        ...
+
+    def health_check(self) -> tuple[bool, dict[str, Any]]:
+        """Check backend health status.
+
+        Returns:
+            Tuple of (is_healthy, details_dict)
+            Details must include 'latency_ms' and 'backend_type'
+
+        Example:
+            >>> backend = RedisBackend()  # doctest: +SKIP
+            >>> is_healthy, details = backend.health_check()  # doctest: +SKIP
+            >>> assert 'latency_ms' in details  # doctest: +SKIP
+            >>> assert 'backend_type' in details  # doctest: +SKIP
+        """
+        ...
+
+
+@runtime_checkable
+class TTLInspectableBackend(Protocol):
+    """Optional protocol for backends that support TTL inspection and refresh.
+
+    Backends implementing this protocol can report remaining TTL on keys
+    and refresh TTLs on existing keys. This enables features like automatic
+    TTL refresh for frequently-accessed keys.
+
+    Not all backends support this capability:
+    - Supported: Redis, PostgreSQL, DynamoDB, SQLite, FileSystem
+    - Not supported: HTTP (stateless), Memcached (limited), S3 (limited)
+
+    Example:
+        >>> # TTL inspection pattern (async context):
+        >>> # if hasattr(backend, 'get_ttl'):
+        >>> #     ttl = await backend.get_ttl("user:123")
+        >>> #     if ttl and ttl < 60:
+        >>> #         await backend.refresh_ttl("user:123", 3600)
+    """
+
+    async def get_ttl(self, key: str) -> Optional[int]:
+        """Get remaining TTL on key (in seconds).
+
+        Args:
+            key: Cache key to inspect
+
+        Returns:
+            Remaining TTL in seconds, or None if:
+            - Key doesn't exist
+            - Key has no expiration (permanent)
+
+        Raises:
+            BackendError: If backend operation fails
+
+        Example:
+            >>> ttl = await backend.get_ttl("user:123")  # doctest: +SKIP
+            >>> if ttl and ttl < 60:  # doctest: +SKIP
+            ...     # Key expiring soon
+            ...     pass  # doctest: +SKIP
+        """
+        ...
+
+    async def refresh_ttl(self, key: str, ttl: int) -> bool:
+        """Refresh (update) TTL on existing key.
+
+        Args:
+            key: Cache key to refresh
+            ttl: New TTL in seconds
+
+        Returns:
+            True if key existed and TTL was refreshed
+            False if key doesn't exist (no-op)
+
+        Raises:
+            BackendError: If backend operation fails
+
+        Example:
+            >>> refreshed = await backend.refresh_ttl("user:123", 3600)  # doctest: +SKIP
+            >>> if refreshed:  # doctest: +SKIP
+            ...     # TTL successfully updated
+            ...     pass  # doctest: +SKIP
+        """
+        ...
+
+
+@runtime_checkable
+class LockableBackend(Protocol):
+    """Optional protocol for backends supporting distributed locking.
+
+    Backends implementing this protocol can provide distributed lock semantics
+    for coordinating access across multiple processes/servers. This enables
+    features like cache stampede prevention and critical sections.
+
+    Not all backends support this capability:
+    - Supported: Redis, PostgreSQL, DynamoDB
+    - Local-only: SQLite, FileSystem (single-process locking)
+    - Not supported: HTTP (stateless), Memcached, S3
+
+    Example:
+        >>> # Distributed locking pattern (async context):
+        >>> # if hasattr(backend, 'acquire_lock'):
+        >>> #     async with backend.acquire_lock("lock:compute", timeout=30) as acquired:
+        >>> #         if acquired:
+        >>> #             result = expensive_computation()
+    """
+
+    async def acquire_lock(
+        self,
+        key: str,
+        timeout: float,
+        blocking_timeout: Optional[float] = None,
+    ) -> AsyncIterator[bool]:
+        """Acquire a distributed lock on key.
+
+        Args:
+            key: Lock key (e.g., "lock:user:123")
+            timeout: How long to hold the lock (seconds) before auto-release
+            blocking_timeout: Max time to wait for lock acquisition (None = non-blocking)
+
+        Yields:
+            True if lock was acquired
+            False if timeout occurred waiting for lock
+
+        Raises:
+            BackendError: If backend operation fails
+
+        Example:
+            >>> async with backend.acquire_lock("lock:key", timeout=30, blocking_timeout=5) as acquired:  # doctest: +SKIP
+            ...     if acquired:  # doctest: +SKIP
+            ...         # Lock held, safe to proceed
+            ...         pass  # doctest: +SKIP
+            ...     else:  # doctest: +SKIP
+            ...         # Timeout waiting for lock
+            ...         pass  # doctest: +SKIP
+
+        Note:
+            Lock is automatically released on context exit, even if exception occurs.
+        """
+        ...
+
+
+@runtime_checkable
+class TimeoutConfigurableBackend(Protocol):
+    """Optional protocol for per-operation timeout configuration.
+
+    Backends implementing this protocol allow fine-grained timeout control
+    per operation. This enables features like adaptive timeouts that adjust
+    based on operation latency.
+
+    All backends support some timeout mechanism, but granularity varies:
+    - Per-operation: HTTP, DynamoDB, PostgreSQL
+    - Per-socket/transaction: Redis, Memcached, SQLite
+    - Global: KV, S3
+
+    Example:
+        >>> # Per-operation timeout pattern (async context):
+        >>> # if hasattr(backend, 'with_timeout'):
+        >>> #     async with backend.with_timeout("get", 100):
+        >>> #         value = await backend.get("key")
+    """
+
+    async def with_timeout(
+        self,
+        operation: str,
+        timeout_ms: int,
+    ) -> AsyncIterator[None]:
+        """Set timeout for operations within context.
+
+        Args:
+            operation: Operation name (e.g., "get", "set", "delete")
+            timeout_ms: Timeout in milliseconds
+
+        Raises:
+            BackendError: With error_type=TIMEOUT if timeout exceeded
+
+        Example:
+            >>> async with backend.with_timeout("get", 100):  # doctest: +SKIP
+            ...     value = await backend.get("key")  # doctest: +SKIP
+
+        Note:
+            Backends without per-operation timeout may apply timeout at
+            socket or global level (coarser-grained fallback).
+        """
+        ...

cachekit/backends/errors.py

@@ -0,0 +1,181 @@
+"""Backend error types and classification.
+
+This module defines error hierarchies for backend operations, enabling
+circuit breaker and retry logic to make correct decisions without
+Redis-specific exception handling.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+
+class BackendErrorType(str, Enum):
+    """Error classification for circuit breaker and retry decisions.
+
+    Inherits from str for JSON serialization and string comparisons.
+    Each error type dictates a different retry/recovery strategy:
+
+    - TRANSIENT: Temporary failure, retry with exponential backoff + jitter
+    - PERMANENT: Unfixable error, fail fast without retry
+    - TIMEOUT: Operation exceeded time limit, configurable retry strategy
+    - AUTHENTICATION: Credential/auth issue, alert operations team
+    - UNKNOWN: Unclassified error, assume transient and log for investigation
+
+    Example:
+        >>> error = BackendError("Connection lost", error_type=BackendErrorType.TRANSIENT)
+        >>> if error.is_transient:
+        ...     # Retry with exponential backoff
+        ...     pass
+    """
+
+    TRANSIENT = "transient"
+    PERMANENT = "permanent"
+    TIMEOUT = "timeout"
+    AUTHENTICATION = "authentication"
+    UNKNOWN = "unknown"
+
+
+class BackendError(Exception):
+    """Base exception for all backend operations.
+
+    The error_type field enables circuit breaker and retry logic to make
+    correct decisions without inspecting exception types. This approach
+    works with any backend (Redis, HTTP, DynamoDB, etc.).
+
+    Designed for serializability across network boundaries. Contains only
+    simple types (str, enum) and operation context for debugging.
+
+    Attributes:
+        message: Human-readable error message
+        error_type: Error classification (see BackendErrorType)
+        original_exception: The original exception that caused this error (if any)
+        operation: The operation that failed (get, set, delete, exists)
+        key: The cache key involved in the operation (optional, for debugging)
+
+    Example:
+        >>> from redis import ConnectionError as RedisConnectionError
+        >>> try:
+        ...     # Some Redis operation
+        ...     pass
+        ... except RedisConnectionError as exc:
+        ...     raise BackendError(
+        ...         "Redis connection failed",
+        ...         error_type=BackendErrorType.TRANSIENT,
+        ...         original_exception=exc,
+        ...         operation="get",
+        ...         key="user:123"
+        ...     )
+    """
+
+    def __init__(
+        self,
+        message: str,
+        error_type: BackendErrorType = BackendErrorType.UNKNOWN,
+        original_exception: Optional[Exception] = None,
+        operation: str | None = None,
+        key: str | None = None,
+    ):
+        """Initialize BackendError with error classification and context.
+
+        Args:
+            message: Human-readable error message
+            error_type: Error classification for retry/recovery logic
+            original_exception: The original exception that caused this error
+            operation: The operation that failed (get, set, delete, exists)
+            key: The cache key involved in the operation
+        """
+        self.message = message
+        self.error_type = error_type
+        self.original_exception = original_exception
+        self.operation = operation
+        self.key = key
+        super().__init__(self._format_message())
+
+    def _format_message(self) -> str:
+        """Format error message with operation context."""
+        parts = [self.message]
+        if self.operation:
+            parts.append(f"operation={self.operation}")
+        if self.key:
+            # Truncate key for security/readability
+            key_display = self.key[:50] + "..." if len(self.key) > 50 else self.key
+            parts.append(f"key={key_display}")
+        if self.error_type:
+            parts.append(f"type={self.error_type.value}")
+        return " | ".join(parts)
+
+    @property
+    def is_transient(self) -> bool:
+        """Should trigger exponential backoff retry.
+
+        Example:
+            >>> error = BackendError("Temp failure", error_type=BackendErrorType.TRANSIENT)
+            >>> if error.is_transient:
+            ...     # Retry with backoff
+            ...     pass
+        """
+        return self.error_type == BackendErrorType.TRANSIENT
+
+    @property
+    def is_permanent(self) -> bool:
+        """Should fail fast, no retry.
+
+        Example:
+            >>> error = BackendError("Invalid key", error_type=BackendErrorType.PERMANENT)
+            >>> if error.is_permanent:
+            ...     # Don't retry, log and alert
+            ...     pass
+        """
+        return self.error_type == BackendErrorType.PERMANENT
+
+    @property
+    def is_timeout(self) -> bool:
+        """Configurable retry strategy.
+
+        Example:
+            >>> error = BackendError("Operation timeout", error_type=BackendErrorType.TIMEOUT)
+            >>> if error.is_timeout:
+            ...     # Retry with increased timeout
+            ...     pass
+        """
+        return self.error_type == BackendErrorType.TIMEOUT
+
+    @property
+    def is_authentication(self) -> bool:
+        """Should alert operations team.
+
+        Example:
+            >>> error = BackendError("Invalid creds", error_type=BackendErrorType.AUTHENTICATION)
+            >>> if error.is_authentication:
+            ...     # Alert ops, don't retry
+            ...     pass
+        """
+        return self.error_type == BackendErrorType.AUTHENTICATION
+
+    def __repr__(self) -> str:
+        """Developer-friendly representation."""
+        return f"BackendError({self.message!r}, error_type={self.error_type.value!r})"
+
+
+class CapabilityNotAvailableError(BackendError):
+    """Raised when code requires an optional protocol that backend doesn't implement.
+
+    Used for hard requirements that can't be gracefully degraded. For example,
+    if code requires distributed locking but the backend doesn't support it.
+
+    Example:
+        >>> from cachekit.backends.errors import CapabilityNotAvailableError
+        >>> # Usage pattern:
+        >>> # if not hasattr(backend, 'acquire_lock'):
+        >>> #     raise CapabilityNotAvailableError("Backend doesn't support locking")
+    """
+
+    def __init__(self, message: str):
+        """Initialize with permanent error classification.
+
+        Args:
+            message: Human-readable error message explaining missing capability
+        """
+        super().__init__(message, error_type=BackendErrorType.PERMANENT)

cachekit/backends/file/__init__.py

@@ -0,0 +1,30 @@
+"""File-based backend for local disk caching.
+
+This module provides a production-ready filesystem-based cache backend with:
+- Thread-safe operations using reentrant locks and file-level locking
+- Atomic writes via write-then-rename pattern
+- LRU eviction based on disk usage thresholds
+- TTL-based expiration with secure header format
+- Security features (O_NOFOLLOW, symlink prevention)
+
+Public API:
+    - FileBackend: Main backend implementation
+    - FileBackendConfig: Configuration class
+
+Example:
+    >>> from cachekit.backends.file import FileBackend, FileBackendConfig
+    >>> config = FileBackendConfig(cache_dir="/tmp/cachekit")
+    >>> backend = FileBackend(config)
+    >>> backend.set("key", b"value", ttl=60)
+    >>> data = backend.get("key")
+"""
+
+from __future__ import annotations
+
+from cachekit.backends.file.backend import FileBackend
+from cachekit.backends.file.config import FileBackendConfig
+
+__all__ = [
+    "FileBackend",
+    "FileBackendConfig",
+]