cachekit 0.6.1__tar.gz → 0.7.0__tar.gz

{cachekit-0.6.1 → cachekit-0.7.0}/Cargo.lock

@@ -231,7 +231,7 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.6.1"
+version = "0.7.0"
 dependencies = [
  "cachekit-core",
  "criterion",

{cachekit-0.6.1 → cachekit-0.7.0}/PKG-INFO

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

{cachekit-0.6.1 → cachekit-0.7.0}/pyproject.toml

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

{cachekit-0.6.1 → cachekit-0.7.0}/rust/Cargo.toml

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

{cachekit-0.6.1 → cachekit-0.7.0}/src/cachekit/__init__.py

@@ -68,7 +68,7 @@ Example Usage:
     ```
 """
 
-__version__ = "0.6.1"
+__version__ = "0.7.0"
 
 from typing import Any, Callable, TypeVar
 

{cachekit-0.6.1 → cachekit-0.7.0}/src/cachekit/backends/cachekitio/backend.py

@@ -2,16 +2,22 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
+import math
+import random
 import time
-from typing import TYPE_CHECKING, Any
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any, Optional
+from urllib.parse import quote
 
 import httpx
 
 from cachekit.backends.cachekitio.client import get_cached_async_http_client, get_sync_http_client
 from cachekit.backends.cachekitio.config import CachekitIOBackendConfig
 from cachekit.backends.cachekitio.error_handler import classify_http_error
-from cachekit.backends.errors import BackendError
+from cachekit.backends.errors import BackendError, BackendErrorType
 from cachekit.decorators.stats_context import get_current_function_stats
 from cachekit.logging import get_structured_logger
 
@@ -544,42 +550,104 @@ class CachekitIOBackend:
 
     # ==================== LockableBackend Protocol ====================
 
-    async def acquire_lock(self, lock_key: str, timeout: int = 5) -> str | None:
-        """Acquire distributed lock.
+    async def _try_acquire_lock(self, lock_key: str, timeout: float) -> str | None:
+        """Single attempt at the SaaS lock endpoint. Returns lock_id, or None if held.
 
-        Args:
-            lock_key: Lock identifier
-            timeout: Lock timeout in seconds
+        Non-finite (NaN / ±inf) or non-positive ``timeout`` is clamped to 1ms — without
+        the guard, ``int(NaN)`` / ``int(inf)`` would raise outside ``BackendError`` and
+        escape the wrapper's degrade-to-no-lock branch.
 
-        Returns:
-            Lock ID if acquired, None if failed
+        Raises:
+            BackendError: For AUTHENTICATION and PERMANENT failures (bad key, bad lock_key
+                format) — polling won't recover and the wrapper degrades to no-lock execution.
+                TRANSIENT/TIMEOUT/UNKNOWN are swallowed as None so the polling loop can retry.
         """
+        # Clamp non-positive / non-finite timeouts before the int conversion.
+        # int(NaN) / int(inf) raise ValueError/OverflowError that aren't BackendError, so
+        # they'd escape the wrapper's degrade-to-no-lock branch and crash the @cache.io call.
+        timeout_ms = max(1, int(timeout * 1000)) if math.isfinite(timeout) else 1
+        encoded_key = quote(lock_key, safe="")
         try:
-            payload = json.dumps({"timeout_ms": timeout * 1000})
             response = await self._request_async(
                 "POST",
-                f"{lock_key}/lock",
-                content=payload.encode(),
+                f"{encoded_key}/lock",
+                content=json.dumps({"timeout_ms": timeout_ms}).encode(),
                 headers={"Content-Type": "application/json"},
             )
+        except BackendError as exc:
+            # Re-raise unrecoverable failures so the wrapper can log + degrade once,
+            # instead of burning the full blocking_timeout on billable retries.
+            if exc.error_type in (BackendErrorType.AUTHENTICATION, BackendErrorType.PERMANENT):
+                raise
+            return None
+
+        try:
             data = response.json()
-            return data.get("lock_id")
-        except BackendError:
+            lock_id = data.get("lock_id")
+        except (ValueError, AttributeError):
+            # Malformed body from the SaaS — treat as held (retry) rather than crashing
+            # the wrapper. Same failure class as the original issue #129 if we re-raised.
             return None
 
-    async def release_lock(self, lock_key: str, lock_id: str) -> bool:
-        """Release distributed lock.
+        return lock_id if isinstance(lock_id, str) else None
+
+    @asynccontextmanager
+    async def acquire_lock(
+        self,
+        key: str,
+        timeout: float,
+        blocking_timeout: Optional[float] = None,
+    ) -> AsyncIterator[bool]:
+        """Acquire distributed lock (LockableBackend protocol).
+
+        The SaaS endpoint returns immediately; client-side polling implements
+        ``blocking_timeout`` with proportional jitter (0.5×–1× the capped delay) to
+        avoid lockstep retries on concurrent waiters. Each retry is a billable SaaS
+        request — keep the cap tight.
 
         Args:
-            lock_key: Lock identifier
-            lock_id: Lock ID from acquire_lock
+            key: Lock key
+            timeout: Server-side hold duration before auto-release (seconds)
+            blocking_timeout: Max client-side wait to acquire (None = single attempt)
 
-        Returns:
-            True if released, False otherwise
+        Yields:
+            True if acquired, False if ``blocking_timeout`` elapsed without acquisition
+        """
+        lock_id: str | None = None
+        try:
+            lock_id = await self._try_acquire_lock(key, timeout)
+
+            if lock_id is None and blocking_timeout is not None:
+                deadline = time.monotonic() + blocking_timeout
+                delay = 0.05
+                while lock_id is None:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        break
+                    # Proportional jitter (not crypto): spread concurrent waiters, 0.5×–1× the capped delay.
+                    jitter = 0.5 + random.random() * 0.5  # noqa: S311 — backoff jitter, not security
+                    await asyncio.sleep(min(delay, remaining) * jitter)
+                    lock_id = await self._try_acquire_lock(key, timeout)
+                    delay = min(delay * 2, 0.5)
+
+            yield lock_id is not None
+        finally:
+            if lock_id is not None:
+                await self._release_lock(key, lock_id)
+
+    async def _release_lock(self, lock_key: str, lock_id: str) -> bool:
+        """Release distributed lock. Internal helper for ``acquire_lock``'s cleanup.
+
+        Best-effort: swallows ``BackendError`` and returns False so a release failure
+        inside ``__aexit__`` cannot mask the user's exception. The server-side ``timeout``
+        on the lock is the safety net if the DELETE never lands.
         """
+        # URL-encode both segments: lock_key is caller-controlled, lock_id is server-issued
+        # but the SaaS contract doesn't pin a charset.
+        encoded_key = quote(lock_key, safe="")
+        encoded_id = quote(lock_id, safe="")
         try:
-            # DELETE /v1/cache/{key}/lock?lock_id=xxx
-            await self._request_async("DELETE", f"{lock_key}/lock?lock_id={lock_id}")
+            await self._request_async("DELETE", f"{encoded_key}/lock?lock_id={encoded_id}")
             return True
         except BackendError:
             return False

{cachekit-0.6.1 → cachekit-0.7.0}/src/cachekit/backends/provider.py

@@ -102,32 +102,50 @@ class DefaultCacheClientProvider(CacheClientProvider):
 
 
 class DefaultBackendProvider(BackendProviderInterface):
-    """Default backend provider using Redis backend.
+    """Default backend provider with env-based auto-detection.
 
-    Creates RedisBackendProvider singleton with connection pooling.
-    Delegates to RedisBackendProvider.get_backend() for per-request wrappers.
+    Priority order (first matching env var wins):
+        1. CACHEKIT_API_KEY  → CachekitIOBackend (SaaS)
+        2. CACHEKIT_REDIS_URL or REDIS_URL → RedisBackend
 
     For single-tenant deployments (default), sets tenant_context to "default".
     For multi-tenant deployments, tenant_context must be set externally.
     """
 
     def __init__(self):
-        self._provider = None
+        self._cachekitio_backend = None
+        self._redis_provider = None
 
     def get_backend(self):
-        """Get per-request backend instance from singleton provider."""
-        if self._provider is None:
+        """Get backend instance, auto-detected from environment on first call.
+
+        CachekitIO backends are stateless singletons (cached).
+        Redis backends are per-request tenant-scoped wrappers (not cached —
+        RedisBackendProvider.get_backend() reads tenant_context ContextVar).
+        """
+        import os
+
+        # Priority 1: CachekitIO SaaS backend (stateless, safe to cache)
+        if os.environ.get("CACHEKIT_API_KEY"):
+            if self._cachekitio_backend is None:
+                from cachekit.backends.cachekitio import CachekitIOBackend
+
+                self._cachekitio_backend = CachekitIOBackend()
+            return self._cachekitio_backend
+
+        # Priority 2: Redis backend (tenant-scoped, call provider each time)
+        if self._redis_provider is None:
             from cachekit.backends.redis.config import RedisBackendConfig
             from cachekit.backends.redis.provider import RedisBackendProvider, tenant_context
 
             redis_config = RedisBackendConfig.from_env()
-            self._provider = RedisBackendProvider(redis_url=redis_config.redis_url)
+            self._redis_provider = RedisBackendProvider(redis_url=redis_config.redis_url)
 
             # Set default tenant for single-tenant mode (if not already set)
             if tenant_context.get() is None:
                 tenant_context.set("default")
 
-        return self._provider.get_backend()
+        return self._redis_provider.get_backend()
 
 
 __all__ = [

{cachekit-0.6.1 → cachekit-0.7.0}/src/cachekit/cache_handler.py

@@ -303,13 +303,25 @@ class CacheSerializationHandler:
             but extraction fails, ValueError propagates to caller (no fallback to shared key).
         """
         self.serializer_name = serializer_name
+        self.enable_integrity_checking = enable_integrity_checking
+        self._deployment_uuid_value: Optional[str] = None
+
+        # Auto-detect encryption from CACHEKIT_MASTER_KEY when not explicitly configured.
+        # This is the single convergence point for ALL backends and presets.
+        if not encryption and master_key is None and tenant_extractor is None:
+            from cachekit.config.singleton import get_settings
+
+            settings = get_settings()
+            if settings.master_key:
+                encryption = True
+                master_key = settings.master_key.get_secret_value()
+                single_tenant_mode = True
+
         self.encryption = encryption
         self.tenant_extractor = tenant_extractor
         self.single_tenant_mode = single_tenant_mode
         self.deployment_uuid = deployment_uuid
         self.master_key = master_key
-        self.enable_integrity_checking = enable_integrity_checking
-        self._deployment_uuid_value: Optional[str] = None
 
         # Extract string name for metadata storage (for protocol instances, use class name)
         if isinstance(serializer_name, str):
@@ -680,8 +692,9 @@ class CacheSerializationHandler:
             else:
                 # Data is not encrypted - use base serializer directly (no cache_key needed)
                 return base_serializer.deserialize(serialized_data, metadata)
-        except ValueError:
-            # cache_key missing for encrypted data - FAIL CLOSED (re-raise)
+        except (ValueError, SerializationError):
+            # ValueError: cache_key missing for encrypted data — FAIL CLOSED
+            # SerializationError/EncryptionError: let the outer handler log and handle
             raise
         except Exception as e:
             get_logger().error(f"Deserialization failed with {self.serializer_name}: {e}")
@@ -806,6 +819,9 @@ class CacheOperationHandler:
                 # Return a tuple (True, value) to distinguish from "no cache entry"
                 return (True, deserialized)
             return None
+        except SerializationError as e:
+            get_logger().warning(f"L2 cache decrypt/integrity failure for {cache_key}: {e}")
+            return None
         except Exception as e:
             get_logger().warning(f"Backend operation failed for get on {cache_key}: {e}")
             return None
@@ -836,6 +852,9 @@ class CacheOperationHandler:
                 # Return a tuple (True, value) to distinguish from "no cache entry"
                 return (True, deserialized)
             return None
+        except SerializationError as e:
+            get_logger().warning(f"L2 cache decrypt/integrity failure for {cache_key}: {e}")
+            return None
         except Exception as e:
             get_logger().warning(f"Backend operation failed for get on {cache_key}: {e}")
             return None

{cachekit-0.6.1 → cachekit-0.7.0}/src/cachekit/config/decorator.py

@@ -285,7 +285,7 @@ class DecoratorConfig:
             "enable_prometheus_metrics": self.monitoring.enable_prometheus_metrics,
             # Encryption (flattened)
             "encryption": self.encryption.enabled,
-            "master_key": self.encryption.master_key,
+            "master_key": "[REDACTED]" if self.encryption.master_key else None,
             "tenant_extractor": self.encryption.tenant_extractor,
         }
 
@@ -382,7 +382,7 @@ class DecoratorConfig:
         Use cases: PII, medical data, financial records, GDPR compliance
         Architecture: Both L1 and L2 store encrypted bytes (encrypt-at-rest everywhere)
 
-        Note: Backend resolved from REDIS_URL env var, set_default_backend(), or explicit backend= kwarg
+        Note: Backend resolved from CACHEKIT_API_KEY, REDIS_URL, set_default_backend(), or explicit backend= kwarg
         Note: integrity_checking is forced to True (non-negotiable for security)
 
         Args:
@@ -539,6 +539,10 @@ class DecoratorConfig:
             CACHEKIT_API_KEY: API key for authentication (required)
             CACHEKIT_API_URL: API endpoint (default: https://api.cachekit.io)
 
+        Encryption: Set CACHEKIT_MASTER_KEY env var to enable automatic client-side
+        AES-256-GCM encryption — no code changes needed. Auto-detection happens in
+        CacheSerializationHandler and applies to ALL presets, not just .io().
+
         Args:
             **kwargs: Overrides (ttl, namespace, etc.)
 
@@ -572,6 +576,7 @@ class DecoratorConfig:
         backend = CachekitIOBackend()
 
         # Use production-grade settings with SaaS backend
+        # Encryption auto-detected from CACHEKIT_MASTER_KEY in CacheSerializationHandler
         return cls(
             backend=backend,
             integrity_checking=True,

{cachekit-0.6.1 → cachekit-0.7.0}/src/cachekit/config/nested.py

@@ -7,7 +7,7 @@ timeout, backpressure, monitoring, encryption).
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Callable
 
 from .validation import ConfigurationError
@@ -285,6 +285,11 @@ class EncryptionConfig:
     NOTE: Per backend abstraction spec, encryption stores encrypted bytes in BOTH L1 and L2.
     L1 can be enabled with encryption (stores encrypted bytes, not plaintext).
 
+    Tenant mode is required: set single_tenant_mode=True for single-tenant or provide
+    a tenant_extractor callable for multi-tenant key isolation. @cache.secure() sets
+    single_tenant_mode automatically; if using EncryptionConfig directly (e.g. with
+    @cache.io), you must set it explicitly.
+
     Attributes:
         enabled: Enable client-side encryption (default: False)
         master_key: Hex-encoded master key for key derivation (required if enabled)
@@ -322,7 +327,7 @@ class EncryptionConfig:
     """
 
     enabled: bool = False
-    master_key: str | None = None
+    master_key: str | None = field(default=None, repr=False)
     tenant_extractor: Callable[..., str] | None = None
     single_tenant_mode: bool = False
     deployment_uuid: str | None = None

{cachekit-0.6.1 → cachekit-0.7.0}/src/cachekit/decorators/wrapper.py

@@ -20,7 +20,9 @@ from ..cache_handler import (
 )
 from ..key_generator import CacheKeyGenerator
 from ..l1_cache import get_l1_cache
+from ..object_cache import ObjectCache
 from ..reliability import CircuitBreakerConfig
+from ..serializers.base import SerializationError
 
 # Config import removed - using direct DecoratorConfig integration
 from .orchestrator import FeatureOrchestrator
@@ -479,6 +481,10 @@ def create_cache_wrapper(
     # FIX: Initialize L1 cache if enabled
     _l1_cache = get_l1_cache(namespace or "default") if l1_enabled else None
 
+    # L1-only mode: use ObjectCache for raw Python object storage (no serialization).
+    # This preserves types (tuples, sets, frozensets) that MessagePack would degrade.
+    _object_cache: ObjectCache | None = ObjectCache(max_entries=256) if _l1_only_mode else None
+
     # Create per-function statistics tracker with lazy session ID generation
     # Session ID format: "{process_uuid}:{module}.{function_name}"
     # Generated lazily on first use or regenerated after cache_clear()
@@ -569,41 +575,22 @@ def create_cache_wrapper(
             reset_current_function_stats(token)
             return func(*args, **kwargs)
 
-        # L1-ONLY MODE: Skip backend initialization entirely
-        # This is the fix for the sentinel problem: when backend=None is explicitly passed,
-        # we should NOT try to get a backend from the provider
-        if _l1_only_mode:
-            # L1-only mode: Check L1 cache, execute function on miss, store in L1
-            if _l1_cache and cache_key:
-                l1_found, l1_bytes = _l1_cache.get(cache_key)
-                if l1_found and l1_bytes:
-                    # L1 cache hit
-                    try:
-                        # Pass cache_key for AAD verification (required for encryption)
-                        l1_value = operation_handler.serialization_handler.deserialize_data(l1_bytes, cache_key=cache_key)
-                        _stats.record_l1_hit()
-                        reset_current_function_stats(token)
-                        return l1_value
-                    except Exception:
-                        # L1 deserialization failed - invalidate and continue
-                        _l1_cache.invalidate(cache_key)
+        # L1-ONLY MODE: Store raw Python objects (no serialization).
+        # Preserves types (tuples, sets, frozensets) that MessagePack would degrade.
+        if _l1_only_mode and _object_cache:
+            found, cached_value = _object_cache.get(cache_key)
+            if found:
+                _stats.record_l1_hit()
+                features.clear_correlation_id()
+                reset_current_function_stats(token)
+                return cached_value
 
-            # L1 cache miss - execute function and store in L1
+            # Cache miss - execute function and store raw result
             _stats.record_miss()
             try:
                 result = func(*args, **kwargs)
-                # Serialize and store in L1
-                try:
-                    # Pass cache_key for AAD binding (required for encryption)
-                    serialized_bytes = operation_handler.serialization_handler.serialize_data(
-                        result, args, kwargs, cache_key=cache_key
-                    )
-                    if _l1_cache and cache_key and serialized_bytes:
-                        _l1_cache.put(cache_key, serialized_bytes, redis_ttl=ttl)
-                        _cached_keys.add(cache_key)
-                except Exception as e:
-                    # Serialization/storage failed but function succeeded - log and return result
-                    logger().debug(f"L1-only mode: serialization/storage failed for {cache_key}: {e}")
+                _object_cache.put(cache_key, result, ttl=ttl if ttl is not None else 31536000)
+                _cached_keys.add(cache_key)
                 return result
             finally:
                 features.clear_correlation_id()
@@ -913,39 +900,20 @@ def create_cache_wrapper(
                 )
                 return await func(*args, **kwargs)
 
-            # L1-ONLY MODE: Skip backend initialization entirely
-            # This is the fix for the sentinel problem: when backend=None is explicitly passed,
-            # we should NOT try to get a backend from the provider
-            if _l1_only_mode:
-                # L1-only mode: Check L1 cache, execute function on miss, store in L1
-                if _l1_cache and cache_key:
-                    l1_found, l1_bytes = _l1_cache.get(cache_key)
-                    if l1_found and l1_bytes:
-                        # L1 cache hit
-                        try:
-                            # Pass cache_key for AAD verification (required for encryption)
-                            l1_value = operation_handler.serialization_handler.deserialize_data(l1_bytes, cache_key=cache_key)
-                            _stats.record_l1_hit()
-                            return l1_value
-                        except Exception:
-                            # L1 deserialization failed - invalidate and continue
-                            _l1_cache.invalidate(cache_key)
-
-                # L1 cache miss - execute function and store in L1
+            # L1-ONLY MODE: Store raw Python objects (no serialization).
+            # Preserves types (tuples, sets, frozensets) that MessagePack would degrade.
+            if _l1_only_mode and _object_cache:
+                found, cached_value = _object_cache.get(cache_key)
+                if found:
+                    _stats.record_l1_hit()
+                    features.clear_correlation_id()
+                    return cached_value
+
+                # Cache miss - execute function and store raw result
                 _stats.record_miss()
                 result = await func(*args, **kwargs)
-                # Serialize and store in L1
-                try:
-                    # Pass cache_key for AAD binding (required for encryption)
-                    serialized_bytes = operation_handler.serialization_handler.serialize_data(
-                        result, args, kwargs, cache_key=cache_key
-                    )
-                    if _l1_cache and cache_key and serialized_bytes:
-                        _l1_cache.put(cache_key, serialized_bytes, redis_ttl=ttl)
-                        _cached_keys.add(cache_key)
-                except Exception as e:
-                    # Serialization/storage failed but function succeeded - log and return result
-                    logger().debug(f"L1-only mode: serialization/storage failed for {cache_key}: {e}")
+                _object_cache.put(cache_key, result, ttl=ttl if ttl is not None else 31536000)
+                _cached_keys.add(cache_key)
                 return result
 
             # L1+L2 MODE: Original behavior with backend initialization
@@ -1066,8 +1034,21 @@ def create_cache_wrapper(
 
                     return result
 
+            except SerializationError as e:
+                # Decrypt/integrity failure on L2 data — warn explicitly (fail-open: recompute)
+                logger().warning(f"L2 cache decrypt/integrity failure for {cache_key}: {e}")
+                get_duration_ms = (time.perf_counter() - start_time) * 1000
+                features.handle_cache_error(
+                    error=e,
+                    operation="cache_get_deserialize",
+                    cache_key=cache_key or "unknown",
+                    namespace=namespace or "default",
+                    duration_ms=get_duration_ms,
+                    correlation_id=correlation_id,
+                )
+
             except Exception as e:
-                # Redis error - record but continue to function execution
+                # Backend/network error - record but continue to function execution
                 get_duration_ms = (time.perf_counter() - start_time) * 1000
                 features.handle_cache_error(
                     error=e,
@@ -1113,6 +1094,8 @@ def create_cache_wrapper(
                                         _cached_keys.add(cache_key)
 
                                     return result
+                            except SerializationError as e:
+                                logger().warning(f"L2 cache decrypt/integrity failure for {cache_key}: {e}")
                             except Exception as e:
                                 # If double-check fails, continue to execute function
                                 _logger.debug("Double-check cache failed after lock acquisition: %s", e)
@@ -1139,6 +1122,8 @@ def create_cache_wrapper(
                                         _cached_keys.add(cache_key)
 
                                     return result
+                            except SerializationError as e:
+                                logger().warning(f"L2 cache decrypt/integrity failure for {cache_key}: {e}")
                             except Exception:
                                 # Cache check failed - fall through to execute function
                                 logger().warning(
@@ -1314,7 +1299,9 @@ def create_cache_wrapper(
             # Snapshot prevents RuntimeError if another thread adds during iteration
             keys_snapshot = set(_cached_keys)
             for key in keys_snapshot:
-                if _l1_cache:
+                if _object_cache:
+                    _object_cache.delete(key)
+                elif _l1_cache:
                     _l1_cache.invalidate(key)
                 if _backend and not _l1_only_mode:
                     invalidator.set_backend(_backend)
@@ -1329,7 +1316,9 @@ def create_cache_wrapper(
         # Single-key invalidation (specific args provided, or zero-param function)
         cache_key = operation_handler.get_cache_key(func, args, kwargs, namespace, integrity_checking)
 
-        if _l1_cache and cache_key:
+        if _object_cache and cache_key:
+            _object_cache.delete(cache_key)
+        elif _l1_cache and cache_key:
             _l1_cache.invalidate(cache_key)
         _cached_keys.discard(cache_key)
 
@@ -1355,7 +1344,9 @@ def create_cache_wrapper(
         if not args and not kwargs and _func_has_params:
             keys_snapshot = set(_cached_keys)
             for key in keys_snapshot:
-                if _l1_cache:
+                if _object_cache:
+                    _object_cache.delete(key)
+                elif _l1_cache:
                     _l1_cache.invalidate(key)
                 if _backend and not _l1_only_mode:
                     invalidator.set_backend(_backend)
@@ -1370,7 +1361,9 @@ def create_cache_wrapper(
         # Single-key invalidation (specific args provided, or zero-param function)
         cache_key = operation_handler.get_cache_key(func, args, kwargs, namespace, integrity_checking)
 
-        if _l1_cache and cache_key:
+        if _object_cache and cache_key:
+            _object_cache.delete(cache_key)
+        elif _l1_cache and cache_key:
             _l1_cache.invalidate(cache_key)
         _cached_keys.discard(cache_key)
 
@@ -1432,9 +1425,12 @@ def create_cache_wrapper(
     def cache_clear() -> None:
         """Clear cache statistics and invalidate all cached entries."""
         _stats.clear()
-        # Also invalidate actual cache entries
-        if inspect.iscoroutinefunction(func):
-            raise TypeError("cache_clear() cannot clear cache for async functions. Use 'await fn.ainvalidate_cache()' instead.")
+        # In L1-only mode, invalidation is synchronous (no backend I/O needed)
+        # so cache_clear() works for both sync and async functions.
+        if inspect.iscoroutinefunction(func) and not _l1_only_mode:
+            raise TypeError(
+                "cache_clear() cannot clear cache for async functions with a backend. Use 'await fn.ainvalidate_cache()' instead."
+            )
         invalidate_cache()
 
     if inspect.iscoroutinefunction(func):

{cachekit-0.6.1 → cachekit-0.7.0}/src/cachekit/key_generator.py

@@ -43,6 +43,12 @@ class CacheKeyGenerator:
         "local": "l",  # Reference caching (no serialization)
     }
 
+    # Regex for chars allowed in the func component of a SaaS cache key.
+    # SaaS validates: /^[a-zA-Z0-9_.]{1,200}$/
+    _FUNC_ALLOWED_RE = __import__("re").compile(r"[^A-Za-z0-9_.]")
+    _DOUBLE_DOT_RE = __import__("re").compile(r"\.{2,}")
+    _FUNC_NAME_MAX = 200
+
     def __init__(self):
         """Initialize the key generator.
 
@@ -83,8 +89,9 @@ class CacheKeyGenerator:
         if namespace:
             key_parts.extend(["ns:", namespace, ":"])
 
-        # Add function identifier (module + name) - single string operation
-        key_parts.extend(["func:", func.__module__, ".", func.__qualname__, ":"])
+        # Add function identifier (module + name) — sanitized for SaaS key format
+        func_name = self._sanitize_func_name(func.__module__, func.__qualname__)
+        key_parts.extend(["func:", func_name, ":"])
 
         # Generate args hash using Blake2b-256
         args_hash = self._blake2b_hash(args, kwargs)
@@ -347,3 +354,21 @@ class CacheKeyGenerator:
             normalized = f"{prefix}:{key_hash[:32]}"
 
         return normalized
+
+    @classmethod
+    def _sanitize_func_name(cls, module: str, qualname: str) -> str:
+        """Sanitize module.qualname for SaaS cache-key compliance.
+
+        The SaaS ``func`` component must match ``[a-zA-Z0-9_.]{1,200}``
+        and must not contain ``..``.  Nested functions have qualnames like
+        ``outer.<locals>.inner`` and lambdas are ``<lambda>`` — the angle
+        brackets violate the regex.
+
+        This replaces every disallowed char with ``_``, collapses runs of
+        ``..`` into a single ``.``, and truncates to 200 chars.  The mapping
+        is deterministic: same function → same key.
+        """
+        raw = f"{module}.{qualname}"
+        sanitized = cls._FUNC_ALLOWED_RE.sub("_", raw)
+        sanitized = cls._DOUBLE_DOT_RE.sub(".", sanitized)
+        return sanitized[: cls._FUNC_NAME_MAX]

{cachekit-0.6.1 → cachekit-0.7.0}/src/cachekit/serializers/__init__.py

@@ -52,6 +52,7 @@ _serializer_lock = Lock()
 # This allows passing enable_integrity_checking parameter during instantiation
 SERIALIZER_REGISTRY = {
     "auto": AutoSerializer,  # Python-specific types (NumPy, pandas, datetime optimization)
+    "pythonic": AutoSerializer,  # Alias — preserves Python types (tuples, sets, frozensets, datetime, UUID)
     "default": StandardSerializer,  # Language-agnostic MessagePack for multi-language caches
     "std": StandardSerializer,  # Explicit StandardSerializer alias
     "arrow": None,  # Lazy-loaded: requires pyarrow from [data] extra
@@ -121,7 +122,7 @@ def get_serializer(name: str, enable_integrity_checking: bool = True) -> Seriali
             serializer_class = SERIALIZER_REGISTRY[name]
 
         # Instantiate with integrity checking configuration
-        if name in ("default", "std", "auto", "arrow", "orjson"):
+        if name in ("default", "std", "auto", "pythonic", "arrow", "orjson"):
             # All core serializers use enable_integrity_checking parameter
             serializer = serializer_class(enable_integrity_checking=enable_integrity_checking)
         else:

{cachekit-0.6.1 → cachekit-0.7.0}/src/cachekit/serializers/auto_serializer.py

@@ -9,6 +9,7 @@ Auto-detects and optimizes:
 - datetime/date/time (ISO-8601)
 - UUID (string representation)
 - set/frozenset (type-safe roundtrip)
+- tuple (recursive type-safe roundtrip)
 
 Uses MessagePack as the default format with graceful degradation for optional dependencies.
 
@@ -73,7 +74,7 @@ ORM_ERROR_MESSAGE = (
 
 CUSTOM_CLASS_ERROR_MESSAGE = (
     "AutoSerializer does not support custom classes. "
-    "Supported types: dict, list, str, int, float, bool, None, bytes, "
+    "Supported types: dict, list, tuple, str, int, float, bool, None, bytes, "
     "datetime, date, time, UUID, set, frozenset, NumPy arrays, pandas DataFrames.\n"
     "Options:\n"
     "  1. Convert to dict manually\n"
@@ -124,6 +125,26 @@ def _safe_hasattr(obj: Any, attr: str) -> bool:
         return False
 
 
+def _wrap_tuples(obj: Any) -> Any:
+    """Recursively wrap tuples in type markers before msgpack encoding.
+
+    Msgpack natively serializes tuples as arrays (same as lists), so the
+    ``default`` callback is never called for them. This pre-processor
+    converts tuples to ``{"__tuple__": True, "value": [...]}`` markers
+    that ``_auto_object_hook`` restores on deserialization.
+
+    Only affects tuples — all other types pass through unchanged and are
+    handled by msgpack's ``default`` callback (``_auto_default``).
+    """
+    if isinstance(obj, tuple):
+        return {"__tuple__": True, "value": [_wrap_tuples(x) for x in obj]}
+    if isinstance(obj, list):
+        return [_wrap_tuples(x) for x in obj]
+    if isinstance(obj, dict):
+        return {k: _wrap_tuples(v) for k, v in obj.items()}
+    return obj
+
+
 def _auto_default(obj: Any) -> Any:
     """Custom encoder for types not natively supported by MessagePack.
 
@@ -226,6 +247,14 @@ def _auto_object_hook(obj: Any) -> Any:
             except (ValueError, TypeError) as e:
                 raise SerializationError(f"Invalid UUID format in cached data: {value}") from e
 
+        if obj.get("__tuple__") is True:
+            if "value" not in obj:
+                raise SerializationError("Invalid tuple format: missing 'value' field in cached data")
+            value_list = obj["value"]
+            if not isinstance(value_list, list):
+                raise SerializationError(f"Invalid tuple format: expected list, got {type(value_list).__name__}")
+            return tuple(value_list)
+
         if obj.get("__set__") is True:
             if "value" not in obj:
                 raise SerializationError("Invalid set format: missing 'value' field in cached data")
@@ -748,6 +777,8 @@ class AutoSerializer:
 
     def _serialize_msgpack(self, obj: Any) -> bytes:
         """Serialize general object with MessagePack."""
+        # Pre-process tuples into markers (msgpack natively flattens them to lists)
+        obj = _wrap_tuples(obj)
         msgpack_data = msgpack.packb(obj, **self._msgpack_pack_opts)
 
         if self.enable_integrity_checking: