cachekit 0.15.0__tar.gz → 0.16.0__tar.gz

{cachekit-0.15.0 → cachekit-0.16.0}/Cargo.lock

@@ -271,7 +271,7 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.15.0"
+version = "0.16.0"
 dependencies = [
  "cachekit-core",
  "criterion",

{cachekit-0.15.0 → cachekit-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.15.0
+Version: 0.16.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{cachekit-0.15.0 → cachekit-0.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cachekit"
-version = "0.15.0"
+version = "0.16.0"
 description = "Production-ready Redis caching for Python with intelligent reliability features and Rust-powered performance"
 readme = "README.md"
 license = {text = "MIT"}

{cachekit-0.15.0 → cachekit-0.16.0}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cachekit-rs"
-version = "0.15.0"
+version = "0.16.0"
 edition = "2021"
 authors = ["cachekit Contributors"]
 description = "High-performance storage engine for caching with compression and encryption"

{cachekit-0.15.0 → cachekit-0.16.0}/src/cachekit/__init__.py

@@ -67,7 +67,7 @@ Example Usage:
     ```
 """
 
-__version__ = "0.15.0"
+__version__ = "0.16.0"
 
 from collections.abc import Callable
 from typing import Any, TypeVar

{cachekit-0.15.0 → cachekit-0.16.0}/src/cachekit/config/decorator.py

@@ -337,7 +337,6 @@ class DecoratorConfig:
             l1=L1CacheConfig(
                 enabled=True,
                 swr_enabled=False,
-                invalidation_enabled=False,
                 namespace_index=False,
             ),
             circuit_breaker=CircuitBreakerConfig(enabled=False),
@@ -378,7 +377,6 @@ class DecoratorConfig:
             l1=L1CacheConfig(
                 enabled=True,
                 swr_enabled=True,
-                invalidation_enabled=True,
                 namespace_index=True,
             ),
             circuit_breaker=CircuitBreakerConfig(enabled=True),
@@ -444,7 +442,6 @@ class DecoratorConfig:
             l1=L1CacheConfig(
                 enabled=True,  # L1 stores encrypted bytes. Enabled: ~50ns hits vs 2-7ms Redis
                 swr_enabled=True,
-                invalidation_enabled=True,
                 namespace_index=True,
             ),
             encryption=EncryptionConfig(
@@ -493,7 +490,6 @@ class DecoratorConfig:
             l1=L1CacheConfig(
                 enabled=True,
                 swr_enabled=True,
-                invalidation_enabled=False,
                 namespace_index=False,
             ),
             circuit_breaker=CircuitBreakerConfig(enabled=True),
@@ -534,7 +530,6 @@ class DecoratorConfig:
             l1=L1CacheConfig(
                 enabled=True,
                 swr_enabled=False,
-                invalidation_enabled=False,
                 namespace_index=False,
             ),
             circuit_breaker=CircuitBreakerConfig(enabled=False),
@@ -608,7 +603,6 @@ class DecoratorConfig:
             l1=L1CacheConfig(
                 enabled=True,
                 swr_enabled=True,
-                invalidation_enabled=True,
                 namespace_index=True,
             ),
             circuit_breaker=CircuitBreakerConfig(enabled=True),

{cachekit-0.15.0 → cachekit-0.16.0}/src/cachekit/config/nested.py

@@ -30,7 +30,6 @@ class L1CacheConfig:
             task and sync functions via a daemon thread.
         swr_threshold_ratio: Fraction of TTL after which a hit triggers a background
             refresh, in (0.0, 1.0] (default: 0.5)
-        invalidation_enabled: Enable invalidation event broadcasts (default: True)
         namespace_index: Enable fast namespace-based invalidation (default: True)
 
     Examples:
@@ -59,7 +58,6 @@ class L1CacheConfig:
     max_size_mb: int | None = None
     swr_enabled: bool = True
     swr_threshold_ratio: float = 0.5
-    invalidation_enabled: bool = True
     namespace_index: bool = True
 
     def validate(self) -> None:

{cachekit-0.15.0 → cachekit-0.16.0}/src/cachekit/serializers/encryption_wrapper.py

@@ -286,7 +286,11 @@ class EncryptionWrapper:
         Raises:
             ValueError: If cache_key is empty when data is encrypted
             TypeError: If cache_key is not a string
-            EncryptionError: If decryption fails (including cache_key mismatch)
+            DecryptionAuthenticationError: If the entry claims plaintext
+                (``metadata.encrypted=False`` — this wrapper never returns
+                unauthenticated bytes), the tenant mismatches, or AES-GCM
+                authentication fails
+            EncryptionError: If deserialization fails after authenticated decryption
 
         Examples:
             Successful roundtrip with matching cache_key:
@@ -311,11 +315,35 @@ class EncryptionWrapper:
             Traceback (most recent call last):
                 ...
             DecryptionAuthenticationError: Tenant mismatch: data encrypted for 'tenant-1', but current tenant is 'tenant-2'
+
+            An entry claiming plaintext is refused outright — the wrapper is
+            encryption-mandatory and fails closed on its own (LAB-271,
+            defense-in-depth behind the handler-level LAB-241 guard):
+
+            >>> from cachekit.serializers.base import SerializationFormat
+            >>> plain_meta = SerializationMetadata(serialization_format=SerializationFormat.MSGPACK)
+            >>> plain_meta.encrypted
+            False
+            >>> wrapper.deserialize(b"attacker-controlled bytes", plain_meta, cache_key="cart:user:42")  # doctest: +IGNORE_EXCEPTION_DETAIL
+            Traceback (most recent call last):
+                ...
+            DecryptionAuthenticationError: EncryptionWrapper.deserialize received an entry claiming plaintext ...
         """
-        # Handle unencrypted data (fallback case)
-        # Check encrypted flag (orthogonal to format - encryption is a wrapper, not a format)
+        # SECURITY (LAB-271, defense-in-depth behind the LAB-241 handler guard):
+        # this wrapper is encryption-mandatory, so an entry claiming plaintext can
+        # never be legitimate input here. The frame header carrying this flag is
+        # NOT covered by the AES-GCM tag and may be forged; benign migration reads
+        # are converted to miss+evict by CacheSerializationHandler.deserialize_data
+        # before this wrapper is ever invoked. Reaching this branch means a caller
+        # bypassed that guard — fail closed rather than return unauthenticated bytes.
         if not metadata.encrypted:
-            return self.serializer.deserialize(data, metadata)
+            raise DecryptionAuthenticationError(
+                "EncryptionWrapper.deserialize received an entry claiming plaintext "
+                "(metadata.encrypted=False). This wrapper is encryption-mandatory and "
+                "never returns unauthenticated bytes: the plaintext flag lives in the "
+                "unauthenticated frame header and may be forged. Route legitimate "
+                "plaintext reads through CacheSerializationHandler, not this wrapper."
+            )
 
         # SECURITY: Validate cache_key type and value for encrypted data
         if not isinstance(cache_key, str):

cachekit-0.15.0/src/cachekit/invalidation/__init__.py

@@ -1,31 +0,0 @@
-"""L1 cache invalidation system.
-
-This package provides cross-pod invalidation for L1 caches via messaging
-channels. The system is optional and degrades gracefully - L1 caches work
-without invalidation, relying on TTL expiry.
-
-Exports:
-    InvalidationChannel: Protocol for invalidation broadcast
-    InvalidationEvent: Immutable message for invalidation broadcast
-    InvalidationLevel: Enum for invalidation scope
-    InvalidationCallback: Type alias for event callback
-    RedisInvalidationChannel: Redis Pub/Sub implementation of InvalidationChannel
-"""
-
-from cachekit.invalidation.channel import (
-    InvalidationCallback,
-    InvalidationChannel,
-)
-from cachekit.invalidation.event import (
-    InvalidationEvent,
-    InvalidationLevel,
-)
-from cachekit.invalidation.redis_channel import RedisInvalidationChannel
-
-__all__ = [
-    "InvalidationChannel",
-    "InvalidationEvent",
-    "InvalidationLevel",
-    "InvalidationCallback",
-    "RedisInvalidationChannel",
-]

cachekit-0.15.0/src/cachekit/invalidation/channel.py

@@ -1,125 +0,0 @@
-"""InvalidationChannel protocol for cross-pod cache invalidation.
-
-This module defines the protocol for broadcasting invalidation events across
-multiple L1 cache instances. Implementations may use Redis Pub/Sub, HTTP SSE,
-WebSockets, or other messaging systems.
-
-Protocol uses structural subtyping (PEP 544) - any class implementing these
-methods is considered a valid InvalidationChannel.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import TYPE_CHECKING, Any, Protocol
-
-if TYPE_CHECKING:
-    pass
-
-# Type aliases for invalidation system
-InvalidationCallback = Callable[[Any], None]
-"""Callback invoked when invalidation event is received.
-
-Args:
-    event: The InvalidationEvent containing invalidation details
-
-Note:
-    Callback must not raise exceptions. Exceptions are logged and suppressed
-    to prevent breaking the invalidation listener.
-"""
-
-
-class InvalidationChannel(Protocol):
-    """Protocol for broadcasting cache invalidation events.
-
-    This protocol defines the contract for invalidation channels that enable
-    cross-pod L1 cache invalidation. All methods must be thread-safe.
-
-    Design principles:
-    - Fire-and-forget publishing (never raises, never blocks)
-    - Multiple subscribers supported (fan-out)
-    - Graceful degradation (cache works even if channel unavailable)
-    - Idempotent lifecycle (start/stop can be called multiple times)
-
-    Example:
-        >>> from cachekit.invalidation import RedisInvalidationChannel
-        >>> channel = RedisInvalidationChannel(redis_client)  # doctest: +SKIP
-        >>> channel.subscribe(lambda event: cache.handle_invalidation(event))  # doctest: +SKIP
-        >>> channel.start()  # doctest: +SKIP
-        >>> channel.stop()  # doctest: +SKIP
-    """
-
-    def publish(self, event: Any) -> None:
-        """Publish invalidation event to all subscribers.
-
-        This is a fire-and-forget operation that never raises exceptions
-        and never blocks. Failures are logged but do not propagate.
-
-        Args:
-            event: The InvalidationEvent to broadcast
-
-        Note:
-            If channel is unavailable, event is dropped and logged. This is
-            acceptable because L1 cache entries eventually expire via TTL.
-            Cross-pod invalidation is a best-effort optimization.
-        """
-        ...
-
-    def subscribe(self, callback: InvalidationCallback) -> None:
-        """Register callback to receive invalidation events.
-
-        Multiple callbacks may be registered. All callbacks are invoked
-        when an event is received. Callbacks are invoked synchronously
-        in the listener thread.
-
-        Args:
-            callback: Function to invoke when event is received
-
-        Note:
-            Callback exceptions are caught, logged, and suppressed to prevent
-            breaking the listener. Callback should complete quickly (<10ms)
-            to avoid blocking other subscribers.
-        """
-        ...
-
-    def start(self) -> None:
-        """Start the invalidation channel listener.
-
-        This is idempotent - calling multiple times has no effect if already
-        started. The listener runs in a background thread and automatically
-        reconnects if connection is lost.
-
-        Raises:
-            RuntimeError: If channel fails to start (e.g., connection error)
-
-        Note:
-            Implementations should start a daemon thread so process can exit
-            cleanly even if listener is running.
-        """
-        ...
-
-    def stop(self) -> None:
-        """Stop the invalidation channel listener.
-
-        Blocks until listener thread terminates (max 5 seconds). This is
-        idempotent - calling multiple times has no effect if already stopped.
-
-        Note:
-            After stop(), channel can be restarted via start(). Pending
-            callbacks may still execute during shutdown.
-        """
-        ...
-
-    def is_available(self) -> bool:
-        """Check if channel is operational.
-
-        Returns:
-            True if channel is connected and ready to publish/receive events
-            False if channel is disconnected or unavailable
-
-        Note:
-            This is a snapshot check. Channel may become unavailable
-            immediately after returning True. Use for health checks and
-            metrics, not for critical logic.
-        """
-        ...

cachekit-0.15.0/src/cachekit/invalidation/event.py

@@ -1,232 +0,0 @@
-"""InvalidationEvent dataclass for cross-pod cache invalidation messages.
-
-This module defines the immutable message format for broadcasting L1 cache
-invalidation events. Events are serialized to MessagePack for wire transport
-with strict security limits to prevent abuse.
-
-Security:
-    - Max message size: 10KB (prevents memory exhaustion)
-    - Max string length: 1024 characters
-    - Max array/map size: 100 elements
-    - Namespace/params_hash format validation via regex
-"""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-from enum import Enum
-from typing import Any
-
-import msgpack
-
-# Security limits (non-negotiable)
-MAX_MESSAGE_SIZE = 10 * 1024  # 10KB max payload
-NAMESPACE_PATTERN = re.compile(r"^[a-zA-Z0-9_-]{1,128}$")
-PARAMS_HASH_PATTERN = re.compile(r"^[a-f0-9]{64}$")
-
-
-class InvalidationLevel(Enum):
-    """Invalidation scope level.
-
-    - GLOBAL: Invalidate entire L1 cache across all pods
-    - NAMESPACE: Invalidate all entries within a namespace
-    - PARAMS: Invalidate specific cache key by params_hash
-    """
-
-    GLOBAL = "global"
-    NAMESPACE = "namespace"
-    PARAMS = "params"
-
-
-@dataclass(frozen=True)
-class InvalidationEvent:
-    """Immutable invalidation event for cross-pod broadcast.
-
-    This dataclass represents a single invalidation message that gets
-    serialized to MessagePack and sent via InvalidationChannel (Redis Pub/Sub,
-    HTTP SSE, etc.).
-
-    Attributes:
-        level: Invalidation scope (global, namespace, or params)
-        namespace: Cache namespace (required for NAMESPACE level)
-        params_hash: 64-char hex params hash (required for PARAMS level)
-
-    Validation Rules:
-        - NAMESPACE level: namespace must be provided and match NAMESPACE_PATTERN
-        - PARAMS level: params_hash must be provided and match PARAMS_HASH_PATTERN (64-char hex)
-        - GLOBAL level: namespace and params_hash must be None
-
-    Serialization Format:
-        MessagePack with compact keys to minimize wire size:
-        - "l" -> level (str: "global", "namespace", "params")
-        - "ns" -> namespace (str or None)
-        - "ph" -> params_hash (str or None)
-
-    Security:
-        - from_bytes() enforces strict msgpack limits (max_bin_len, max_str_len, etc.)
-        - Rejects payloads >10KB
-        - Validates namespace/params_hash format via regex
-
-    Examples:
-        >>> # Global invalidation (clear all caches)
-        >>> event = InvalidationEvent(level=InvalidationLevel.GLOBAL, namespace=None, params_hash=None)
-        >>> data = event.to_bytes()
-        >>> restored = InvalidationEvent.from_bytes(data)
-        >>> restored == event
-        True
-
-        >>> # Namespace invalidation
-        >>> event = InvalidationEvent(level=InvalidationLevel.NAMESPACE, namespace="user_cache", params_hash=None)
-        >>> data = event.to_bytes()
-        >>> len(data) < 100  # Compact serialization
-        True
-
-        >>> # Params invalidation
-        >>> params_hash = "a" * 64  # Valid 64-char hex
-        >>> event = InvalidationEvent(level=InvalidationLevel.PARAMS, namespace=None, params_hash=params_hash)
-        >>> restored = InvalidationEvent.from_bytes(event.to_bytes())
-        >>> restored.params_hash == params_hash
-        True
-
-        >>> # Validation errors
-        >>> InvalidationEvent(level=InvalidationLevel.NAMESPACE, namespace=None, params_hash=None)
-        Traceback (most recent call last):
-        ValueError: NAMESPACE level requires namespace
-
-        >>> InvalidationEvent(level=InvalidationLevel.PARAMS, namespace=None, params_hash="invalid")
-        Traceback (most recent call last):
-        ValueError: params_hash must be 64-character lowercase hex string
-
-        >>> InvalidationEvent(level=InvalidationLevel.NAMESPACE, namespace="invalid space", params_hash=None)
-        Traceback (most recent call last):
-        ValueError: namespace must match pattern...
-    """
-
-    level: InvalidationLevel
-    namespace: str | None
-    params_hash: str | None
-
-    def __post_init__(self) -> None:
-        """Validate invalidation event after initialization.
-
-        Raises:
-            ValueError: If validation fails (missing required fields, invalid formats)
-        """
-        # NAMESPACE level requires namespace
-        if self.level == InvalidationLevel.NAMESPACE:
-            if self.namespace is None:
-                raise ValueError("NAMESPACE level requires namespace")
-            if not NAMESPACE_PATTERN.match(self.namespace):
-                raise ValueError(
-                    f"namespace must match pattern {NAMESPACE_PATTERN.pattern} (alphanumeric, underscore, hyphen, 1-128 chars)"
-                )
-
-        # PARAMS level requires params_hash
-        if self.level == InvalidationLevel.PARAMS:
-            if self.params_hash is None:
-                raise ValueError("PARAMS level requires params_hash")
-            if not PARAMS_HASH_PATTERN.match(self.params_hash):
-                raise ValueError("params_hash must be 64-character lowercase hex string")
-
-        # GLOBAL level must have both fields as None
-        if self.level == InvalidationLevel.GLOBAL:
-            if self.namespace is not None or self.params_hash is not None:
-                raise ValueError("GLOBAL level must have namespace=None and params_hash=None")
-
-    def to_bytes(self) -> bytes:
-        """Serialize event to MessagePack bytes.
-
-        Uses compact keys to minimize wire size:
-        - "l" -> level
-        - "ns" -> namespace
-        - "ph" -> params_hash
-
-        Returns:
-            MessagePack-encoded bytes (typically <100 bytes)
-
-        Examples:
-            >>> event = InvalidationEvent(level=InvalidationLevel.GLOBAL, namespace=None, params_hash=None)
-            >>> data = event.to_bytes()
-            >>> len(data) < 50  # Very compact
-            True
-        """
-        payload: dict[str, Any] = {
-            "l": self.level.value,  # "global", "namespace", or "params"
-        }
-
-        if self.namespace is not None:
-            payload["ns"] = self.namespace
-
-        if self.params_hash is not None:
-            payload["ph"] = self.params_hash
-
-        return msgpack.packb(payload, use_bin_type=True)  # type: ignore[return-value]
-
-    @classmethod
-    def from_bytes(cls, data: bytes) -> InvalidationEvent:
-        """Deserialize InvalidationEvent from MessagePack bytes.
-
-        Enforces strict security limits:
-        - max_bin_len: 10KB (MAX_MESSAGE_SIZE)
-        - max_str_len: 1024 characters
-        - max_array_len: 100 elements
-        - max_map_len: 100 keys
-
-        Args:
-            data: MessagePack-encoded bytes from to_bytes()
-
-        Returns:
-            Deserialized InvalidationEvent
-
-        Raises:
-            ValueError: If data is malformed, oversized, or fails validation
-
-        Examples:
-            >>> event = InvalidationEvent(level=InvalidationLevel.GLOBAL, namespace=None, params_hash=None)
-            >>> data = event.to_bytes()
-            >>> restored = InvalidationEvent.from_bytes(data)
-            >>> restored == event
-            True
-
-            >>> # Security: reject oversized payload
-            >>> huge_payload = msgpack.packb({"l": "global", "data": "x" * 20000})
-            >>> InvalidationEvent.from_bytes(huge_payload)  # doctest: +SKIP
-            Traceback (most recent call last):
-            ValueError: ...
-        """
-        try:
-            # Enforce strict security limits
-            payload = msgpack.unpackb(
-                data,
-                max_bin_len=MAX_MESSAGE_SIZE,
-                max_str_len=1024,
-                max_array_len=100,
-                max_map_len=100,
-                raw=False,
-                use_list=True,
-            )
-        except (msgpack.exceptions.UnpackException, ValueError) as e:
-            raise ValueError(f"Failed to deserialize InvalidationEvent: {e}") from e
-
-        # Validate payload is a dict
-        if not isinstance(payload, dict):
-            raise ValueError(f"Invalid payload: expected dict, got {type(payload).__name__}")
-
-        # Extract level (required)
-        level_str = payload.get("l")
-        if level_str is None:
-            raise ValueError("Missing required field 'l' (level)")
-
-        # Convert level string to enum
-        try:
-            level = InvalidationLevel(level_str)
-        except ValueError as e:
-            raise ValueError(f"Invalid level value '{level_str}': {e}") from e
-
-        # Extract optional fields
-        namespace = payload.get("ns")
-        params_hash = payload.get("ph")
-
-        # Construct and validate event (validation happens in __post_init__)
-        return cls(level=level, namespace=namespace, params_hash=params_hash)

cachekit-0.15.0/src/cachekit/invalidation/redis_channel.py

@@ -1,403 +0,0 @@
-"""Redis Pub/Sub implementation of InvalidationChannel protocol.
-
-This module provides production-ready cross-pod L1 cache invalidation using
-Redis Pub/Sub messaging. Supports multiple subscribers with automatic
-reconnection and exponential backoff.
-
-IMPORTANT: Redis Pub/Sub is at-most-once delivery (fire-and-forget). Messages
-published while a subscriber is disconnected are lost. This is acceptable for
-cache invalidation because L1 entries eventually expire via TTL. Cross-pod
-invalidation is a best-effort optimization for reducing stale cache window.
-
-Architecture:
-- Dedicated PubSub connection (separate from main Redis client)
-- Daemon listener thread (name="cachekit-invalidation-listener")
-- threading.RLock for state protection
-- Exponential backoff reconnection (1.0s -> 2.0s -> 4.0s -> ... -> 30.0s max)
-- Optional metrics hooks via self._metrics attribute
-"""
-
-from __future__ import annotations
-
-import logging
-import threading
-import time
-from typing import TYPE_CHECKING, Any, Optional
-
-import redis
-
-from cachekit.invalidation.event import InvalidationEvent
-
-if TYPE_CHECKING:
-    from cachekit.invalidation.channel import InvalidationCallback
-
-logger = logging.getLogger(__name__)
-
-# Redis Pub/Sub channel name for invalidation events
-INVALIDATION_CHANNEL = "cachekit:invalidation"
-
-# Reconnection backoff parameters
-INITIAL_BACKOFF = 1.0  # Start with 1 second
-MAX_BACKOFF = 30.0  # Cap at 30 seconds
-BACKOFF_MULTIPLIER = 2.0  # Exponential backoff
-
-
-class RedisInvalidationChannel:
-    """Redis Pub/Sub implementation of InvalidationChannel protocol.
-
-    Provides cross-pod cache invalidation using Redis Pub/Sub messaging.
-    Implements the InvalidationChannel protocol with automatic reconnection
-    and exponential backoff.
-
-    IMPORTANT: This implementation provides at-most-once delivery semantics.
-    Messages may be lost during network partitions or subscriber restarts.
-    This is acceptable for cache invalidation - entries expire via TTL anyway.
-
-    Thread Safety:
-        All public methods are thread-safe via threading.RLock.
-
-    Examples:
-        >>> from cachekit.invalidation import RedisInvalidationChannel, InvalidationEvent, InvalidationLevel
-        >>> import redis
-        >>> client = redis.Redis.from_url("redis://localhost:6379")  # doctest: +SKIP
-        >>> channel = RedisInvalidationChannel(client)  # doctest: +SKIP
-        >>> channel.subscribe(lambda event: print(f"Received: {event}"))  # doctest: +SKIP
-        >>> channel.start()  # doctest: +SKIP
-        >>> event = InvalidationEvent(level=InvalidationLevel.GLOBAL, namespace=None, params_hash=None)  # doctest: +SKIP
-        >>> channel.publish(event)  # doctest: +SKIP
-        >>> channel.stop()  # doctest: +SKIP
-    """
-
-    def __init__(
-        self,
-        redis_client: redis.Redis,
-        channel_name: str = INVALIDATION_CHANNEL,
-        metrics: Optional[Any] = None,
-    ):
-        """Initialize RedisInvalidationChannel.
-
-        Args:
-            redis_client: Redis client instance (used to create dedicated PubSub connection)
-            channel_name: Redis channel name for invalidation messages (default: "cachekit:invalidation")
-            metrics: Optional metrics collector (must have inc() method)
-
-        Note:
-            Creates a dedicated PubSub connection separate from the main Redis client
-            to avoid blocking cache operations.
-        """
-        self._redis_client = redis_client
-        self._channel_name = channel_name
-        self._metrics = metrics
-
-        # State protected by RLock
-        self._lock = threading.RLock()
-        self._callbacks: list[InvalidationCallback] = []
-        self._listener_thread: Optional[threading.Thread] = None
-        self._running = False
-        self._pubsub: Any = None  # redis.client.PubSub type not exported
-        self._backoff = INITIAL_BACKOFF
-
-    def publish(self, event: Any) -> None:
-        """Publish invalidation event to all subscribers.
-
-        This is a fire-and-forget operation that never raises exceptions
-        and never blocks. Failures are logged but do not propagate.
-
-        Args:
-            event: InvalidationEvent to broadcast
-
-        Note:
-            If Redis is unavailable, event is dropped and logged at CRITICAL level.
-            This is acceptable because L1 cache entries eventually expire via TTL.
-
-        Examples:
-            >>> from cachekit.invalidation import InvalidationEvent, InvalidationLevel
-            >>> channel = RedisInvalidationChannel(redis_client)  # doctest: +SKIP
-            >>> event = InvalidationEvent(level=InvalidationLevel.GLOBAL, namespace=None, params_hash=None)  # doctest: +SKIP
-            >>> channel.publish(event)  # Never raises, never blocks  # doctest: +SKIP
-        """
-        try:
-            # Serialize event to bytes
-            data = event.to_bytes()
-
-            # Publish to Redis (returns subscriber_count)
-            subscriber_count = self._redis_client.publish(self._channel_name, data)
-
-            # Warn if no subscribers (message was lost)
-            if subscriber_count == 0:
-                logger.warning(
-                    "Published invalidation but no subscribers listening (message lost)",
-                    extra={"level": event.level.value, "namespace": event.namespace},
-                )
-                if self._metrics:
-                    self._metrics.inc("invalidation_no_subscribers_total")
-
-            # Success metric
-            if self._metrics:
-                self._metrics.inc("invalidation_published_total")
-
-        except Exception as e:
-            # CRITICAL: Other pods will serve stale data until TTL expires
-            logger.error(
-                "CRITICAL: Failed to publish invalidation: %s (other pods will serve stale until TTL)",
-                e,
-                extra={"level": event.level.value, "namespace": event.namespace},
-            )
-            if self._metrics:
-                self._metrics.inc("invalidation_publish_failed_total")
-
-    def subscribe(self, callback: InvalidationCallback) -> None:
-        """Register callback to receive invalidation events.
-
-        Multiple callbacks may be registered. All callbacks are invoked
-        when an event is received. Callbacks are invoked synchronously
-        in the listener thread.
-
-        Args:
-            callback: Function to invoke when event is received
-
-        Note:
-            Callback exceptions are caught, logged, and suppressed to prevent
-            breaking the listener. Callback should complete quickly (<10ms)
-            to avoid blocking other subscribers.
-
-        Examples:
-            >>> def handle_invalidation(event):  # doctest: +SKIP
-            ...     print(f"Cache invalidated: {event}")
-            >>> channel.subscribe(handle_invalidation)  # doctest: +SKIP
-        """
-        with self._lock:
-            self._callbacks.append(callback)
-
-    def start(self) -> None:
-        """Start the invalidation channel listener.
-
-        This is idempotent - calling multiple times has no effect if already
-        started. The listener runs in a background thread and automatically
-        reconnects if connection is lost.
-
-        Raises:
-            RuntimeError: If channel fails to start (e.g., connection error)
-
-        Note:
-            Starts a daemon thread so process can exit cleanly even if
-            listener is running.
-
-        Examples:
-            >>> channel = RedisInvalidationChannel(redis_client)  # doctest: +SKIP
-            >>> channel.start()  # Idempotent  # doctest: +SKIP
-            >>> channel.start()  # No-op if already started  # doctest: +SKIP
-        """
-        with self._lock:
-            # Idempotent - no-op if already started
-            if self._running:
-                return
-
-            try:
-                # Create dedicated PubSub connection
-                self._pubsub = self._redis_client.pubsub(ignore_subscribe_messages=True)
-                self._pubsub.subscribe(self._channel_name)
-
-                # Start daemon listener thread
-                self._running = True
-                self._listener_thread = threading.Thread(
-                    target=self._listen_loop,
-                    name="cachekit-invalidation-listener",
-                    daemon=True,
-                )
-                self._listener_thread.start()
-
-                logger.info("Started invalidation channel listener on %s", self._channel_name)
-
-            except Exception as e:
-                # Cleanup on failure
-                self._running = False
-                if self._pubsub:
-                    try:
-                        self._pubsub.close()
-                    except Exception as close_err:
-                        logger.debug("Error closing PubSub during start failure cleanup: %s", close_err)
-                    self._pubsub = None
-
-                raise RuntimeError(f"Failed to start invalidation channel: {e}") from e
-
-    def stop(self) -> None:
-        """Stop the invalidation channel listener.
-
-        Blocks until listener thread terminates (max 5 seconds). This is
-        idempotent - calling multiple times has no effect if already stopped.
-
-        Note:
-            After stop(), channel can be restarted via start(). Pending
-            callbacks may still execute during shutdown.
-
-        Examples:
-            >>> channel.stop()  # Blocks until listener exits  # doctest: +SKIP
-            >>> channel.stop()  # No-op if already stopped  # doctest: +SKIP
-        """
-        with self._lock:
-            # Idempotent - no-op if already stopped
-            if not self._running:
-                return
-
-            # Signal thread to stop
-            self._running = False
-
-        # Wait for thread to exit (max 5 seconds, without holding lock)
-        if self._listener_thread and self._listener_thread.is_alive():
-            self._listener_thread.join(timeout=5.0)
-
-        # Cleanup PubSub connection
-        with self._lock:
-            if self._pubsub:
-                try:
-                    self._pubsub.unsubscribe(self._channel_name)
-                    self._pubsub.close()
-                except Exception as e:
-                    logger.debug("Error closing PubSub connection during shutdown: %s", e)
-                finally:
-                    self._pubsub = None
-
-            self._listener_thread = None
-            self._backoff = INITIAL_BACKOFF  # Reset backoff for next start
-
-        logger.info("Stopped invalidation channel listener")
-
-    def is_available(self) -> bool:
-        """Check if channel is operational.
-
-        Returns:
-            True if channel is connected and ready to publish/receive events
-            False if channel is disconnected or unavailable
-
-        Note:
-            This is a snapshot check. Channel may become unavailable
-            immediately after returning True. Use for health checks and
-            metrics, not for critical logic.
-
-        Examples:
-            >>> channel.start()  # doctest: +SKIP
-            >>> channel.is_available()  # doctest: +SKIP
-            True
-            >>> channel.stop()  # doctest: +SKIP
-            >>> channel.is_available()  # doctest: +SKIP
-            False
-        """
-        with self._lock:
-            return self._running and self._pubsub is not None
-
-    def _listen_loop(self) -> None:
-        """Background listener thread that receives and dispatches events.
-
-        Runs until self._running is set to False. Implements exponential
-        backoff reconnection on failure (1s -> 2s -> 4s -> ... -> 30s max).
-
-        Note:
-            This method runs in a daemon thread and should never raise exceptions.
-            All errors are caught, logged, and trigger reconnection.
-        """
-        while self._running:
-            try:
-                # Get message from PubSub (blocking call)
-                with self._lock:
-                    pubsub = self._pubsub
-
-                if pubsub is None:
-                    # Shutting down, exit gracefully
-                    break
-
-                # Listen for messages (timeout=1.0 allows checking self._running periodically)
-                message = pubsub.get_message(timeout=1.0)
-
-                if message is None:
-                    # Timeout, continue loop
-                    continue
-
-                # Only process data messages (ignore subscribe/unsubscribe confirmations)
-                if message["type"] != "message":
-                    continue
-
-                # Deserialize and dispatch event
-                try:
-                    data = message["data"]
-
-                    # Handle both str and bytes (Redis may decode based on decode_responses)
-                    if isinstance(data, str):
-                        data = data.encode("utf-8")
-
-                    event = InvalidationEvent.from_bytes(data)
-
-                    # Dispatch to all callbacks (suppress exceptions)
-                    with self._lock:
-                        callbacks = self._callbacks.copy()
-
-                    for callback in callbacks:
-                        try:
-                            callback(event)
-                        except Exception as e:
-                            logger.error("Callback raised exception during invalidation: %s", e, exc_info=True)
-                            if self._metrics:
-                                self._metrics.inc("invalidation_callback_error_total")
-
-                    # Success - reset backoff
-                    with self._lock:
-                        self._backoff = INITIAL_BACKOFF
-
-                    if self._metrics:
-                        self._metrics.inc("invalidation_received_total")
-
-                except ValueError as e:
-                    # Malformed message - log and skip
-                    logger.warning("Received malformed invalidation message: %s", e)
-                    if self._metrics:
-                        self._metrics.inc("invalidation_malformed_total")
-
-            except Exception as e:
-                # Connection error or other failure - reconnect with backoff
-                logger.error("Invalidation listener error: %s (will reconnect after %s seconds)", e, self._backoff)
-
-                if self._metrics:
-                    self._metrics.inc("invalidation_listener_error_total")
-
-                # Sleep before reconnection attempt (without holding lock)
-                time.sleep(self._backoff)
-
-                # Exponential backoff
-                with self._lock:
-                    self._backoff = min(self._backoff * BACKOFF_MULTIPLIER, MAX_BACKOFF)
-
-                # Attempt reconnection
-                self._reconnect()
-
-    def _reconnect(self) -> None:
-        """Reconnect PubSub connection after failure.
-
-        Closes existing connection and creates a new one. Used by listener
-        thread during reconnection backoff loop.
-
-        Note:
-            This method is called from the listener thread and should never
-            raise exceptions. All errors are logged and suppressed.
-        """
-        with self._lock:
-            # Only reconnect if still running
-            if not self._running:
-                return
-
-            # Close existing connection
-            if self._pubsub:
-                try:
-                    self._pubsub.close()
-                except Exception as e:
-                    logger.debug("Error closing PubSub during reconnection: %s", e)
-                finally:
-                    self._pubsub = None
-
-            # Create new connection
-            try:
-                self._pubsub = self._redis_client.pubsub(ignore_subscribe_messages=True)
-                self._pubsub.subscribe(self._channel_name)
-                logger.info("Reconnected to invalidation channel")
-            except Exception as e:
-                logger.error("Failed to reconnect to invalidation channel: %s", e)
-                # Leave _pubsub as None, will retry on next loop iteration