cachekit 0.6.1__tar.gz → 0.8.0__tar.gz

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

@@ -17,6 +17,43 @@ version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
 
+[[package]]
+name = "aead"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0"
+dependencies = [
+ "crypto-common",
+ "generic-array",
+]
+
+[[package]]
+name = "aes"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0"
+dependencies = [
+ "cfg-if",
+ "cipher",
+ "cpufeatures",
+ "zeroize",
+]
+
+[[package]]
+name = "aes-gcm"
+version = "0.10.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "831010a0f742e1209b3bcea8fab6a8e149051ba6099432c8cb2cc117dec3ead1"
+dependencies = [
+ "aead",
+ "aes",
+ "cipher",
+ "ctr",
+ "ghash",
+ "subtle",
+ "zeroize",
+]
+
 [[package]]
 name = "ahash"
 version = "0.8.12"
@@ -208,14 +245,17 @@ checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "cachekit-core"
-version = "0.1.1"
+version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3e264be91367e582a103017104f2fcc6f6f12ca59ded81f53016bc60752a94ae"
+checksum = "9622b3c3e47fcf7abfde287c557e6171674e37842a2dd26fda03f63720542f17"
 dependencies = [
+ "aes",
+ "aes-gcm",
  "byteorder",
  "bytes",
  "cbindgen",
  "generic-array",
+ "getrandom 0.2.17",
  "hkdf",
  "hmac",
  "lz4_flex",
@@ -224,14 +264,14 @@ dependencies = [
  "serde",
  "serde_bytes",
  "sha2",
- "thiserror 1.0.69",
+ "thiserror 2.0.18",
  "xxhash-rust",
  "zeroize",
 ]
 
 [[package]]
 name = "cachekit-rs"
-version = "0.6.1"
+version = "0.8.0"
 dependencies = [
  "cachekit-core",
  "criterion",
@@ -312,6 +352,16 @@ dependencies = [
  "half",
 ]
 
+[[package]]
+name = "cipher"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
+dependencies = [
+ "crypto-common",
+ "inout",
+]
+
 [[package]]
 name = "clap"
 version = "4.6.0"
@@ -444,6 +494,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
 dependencies = [
  "generic-array",
+ "rand_core 0.6.4",
  "typenum",
 ]
 
@@ -463,6 +514,15 @@ version = "0.0.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e2931af7e13dc045d8e9d26afccc6fa115d64e115c9c84b1166288b46f6782c2"
 
+[[package]]
+name = "ctr"
+version = "0.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0369ee1ad671834580515889b80f2ea915f23b8be8d0daa4bbaf2ac5c7590835"
+dependencies = [
+ "cipher",
+]
+
 [[package]]
 name = "debugid"
 version = "0.8.0"
@@ -639,8 +699,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
 dependencies = [
  "cfg-if",
+ "js-sys",
  "libc",
  "wasi",
+ "wasm-bindgen",
 ]
 
 [[package]]
@@ -668,6 +730,16 @@ dependencies = [
  "wasip3",
 ]
 
+[[package]]
+name = "ghash"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0d8a4362ccb29cb0b265253fb0a2728f592895ee6854fd9bc13f2ffda266ff1"
+dependencies = [
+ "opaque-debug",
+ "polyval",
+]
+
 [[package]]
 name = "gimli"
 version = "0.32.3"
@@ -820,6 +892,15 @@ dependencies = [
  "str_stack",
 ]
 
+[[package]]
+name = "inout"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01"
+dependencies = [
+ "generic-array",
+]
+
 [[package]]
 name = "is-terminal"
 version = "0.4.17"
@@ -909,9 +990,9 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "lz4_flex"
-version = "0.11.6"
+version = "0.12.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "373f5eceeeab7925e0c1098212f2fbc4d416adec9d35051a6ab251e824c1854a"
+checksum = "90071f8077f8e40adfc4b7fe9cd495ce316263f19e75c2211eeff3fdf475a3d9"
 dependencies = [
  "twox-hash",
 ]
@@ -1006,6 +1087,12 @@ version = "11.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"
 
+[[package]]
+name = "opaque-debug"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
+
 [[package]]
 name = "plotters"
 version = "0.3.7"
@@ -1034,6 +1121,18 @@ dependencies = [
  "plotters-backend",
 ]
 
+[[package]]
+name = "polyval"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d1fe60d06143b2430aa532c94cfe9e29783047f06c0d7fd359a9a51b729fa25"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "opaque-debug",
+ "universal-hash",
+]
+
 [[package]]
 name = "portable-atomic"
 version = "1.13.1"
@@ -1290,7 +1389,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6db2770f06117d490610c7488547d543617b21bfa07796d7a12f6f1bd53850d1"
 dependencies = [
  "rand_chacha",
- "rand_core",
+ "rand_core 0.9.5",
 ]
 
 [[package]]
@@ -1300,7 +1399,16 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
 dependencies = [
  "ppv-lite86",
- "rand_core",
+ "rand_core 0.9.5",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
+dependencies = [
+ "getrandom 0.2.17",
 ]
 
 [[package]]
@@ -1318,7 +1426,7 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "513962919efc330f829edb2535844d1b912b0fbe2ca165d613e4e8788bb05a5a"
 dependencies = [
- "rand_core",
+ "rand_core 0.9.5",
 ]
 
 [[package]]
@@ -1804,6 +1912,16 @@ version = "0.2.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
 
+[[package]]
+name = "universal-hash"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea"
+dependencies = [
+ "crypto-common",
+ "subtle",
+]
+
 [[package]]
 name = "untrusted"
 version = "0.9.0"

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

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

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

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cachekit"
-version = "0.6.1"
+version = "0.8.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.8.0}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cachekit-rs"
-version = "0.6.1"
+version = "0.8.0"
 edition = "2021"
 authors = ["cachekit Contributors"]
 description = "High-performance storage engine for caching with compression and encryption"
@@ -20,7 +20,7 @@ crate-type = ["cdylib", "rlib"]
 
 [dependencies]
 # Compression, checksums, encryption (https://crates.io/crates/cachekit-core)
-cachekit-core = { version = "=0.1.1", features = ["compression", "checksum", "messagepack", "encryption"] }
+cachekit-core = { version = "0.2.0", features = ["compression", "checksum", "messagepack", "encryption"] }
 
 # Python integration - optional for Rust-only builds
 pyo3 = { workspace = true, optional = true }

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

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

{cachekit-0.6.1 → cachekit-0.8.0}/src/cachekit/backends/base.py

@@ -188,10 +188,23 @@ class LockableBackend(Protocol):
     - Local-only: SQLite, FileSystem (single-process locking)
     - Not supported: HTTP (stateless), Memcached, S3
 
+    Contract — bare cache key:
+        ``acquire_lock`` receives the **bare cache key**, identical to what
+        ``get``/``set``/``delete`` receive. Callers MUST NOT append suffixes
+        like ``:lock`` before passing the key. Each backend owns its own
+        lock-namespace derivation:
+
+        - Redis: derives ``<key>:lock`` internally for the on-wire lock name.
+        - CachekitIO (SaaS): the lock endpoint is ``POST /v1/cache/{key}/lock`` —
+          no key derivation needed.
+
+        This convergence keeps the Python SDK byte-for-byte compatible with
+        the cachekit-rs and cachekit-ts SDKs at the protocol boundary.
+
     Example:
         >>> # Distributed locking pattern (async context):
         >>> # if hasattr(backend, 'acquire_lock'):
-        >>> #     async with backend.acquire_lock("lock:compute", timeout=30) as acquired:
+        >>> #     async with backend.acquire_lock("user:123:profile", timeout=30) as acquired:
         >>> #         if acquired:
         >>> #             result = expensive_computation()
     """
@@ -205,7 +218,10 @@ class LockableBackend(Protocol):
         """Acquire a distributed lock on key.
 
         Args:
-            key: Lock key (e.g., "lock:user:123")
+            key: Bare cache key (e.g., ``"user:123"``) — the SAME shape passed
+                to ``get``/``set``/``delete``. Implementations are responsible
+                for any internal lock-namespace derivation; callers MUST NOT
+                pre-suffix the key.
             timeout: How long to hold the lock (seconds) before auto-release
             blocking_timeout: Max time to wait for lock acquisition (None = non-blocking)
 
@@ -217,7 +233,7 @@ class LockableBackend(Protocol):
             BackendError: If backend operation fails
 
         Example:
-            >>> async with backend.acquire_lock("lock:key", timeout=30, blocking_timeout=5) as acquired:  # doctest: +SKIP
+            >>> async with backend.acquire_lock("user:123:profile", timeout=30, blocking_timeout=5) as acquired:  # doctest: +SKIP
             ...     if acquired:  # doctest: +SKIP
             ...         # Lock held, safe to proceed
             ...         pass  # doctest: +SKIP

{cachekit-0.6.1 → cachekit-0.8.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,111 @@ 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
+        ``lock_key`` is the bare cache key (LockableBackend contract). The SaaS lock
+        endpoint is ``POST /v1/cache/{key}/lock`` — no internal derivation is needed
+        because lock semantics live in the URL path, not the key namespace. Appending
+        ``:lock`` here would push the SaaS validator past its 7-segment canonical key
+        budget and trigger a 400 at the edge.
 
-        Returns:
-            Lock ID if acquired, None if failed
+        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.
+
+        Raises:
+            BackendError: For AUTHENTICATION and PERMANENT failures (bad key, bad key
+                format rejected by SaaS validator) — 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.8.0}/src/cachekit/backends/provider.py

@@ -102,32 +102,99 @@ class DefaultCacheClientProvider(CacheClientProvider):
 
 
 class DefaultBackendProvider(BackendProviderInterface):
-    """Default backend provider using Redis backend.
-
-    Creates RedisBackendProvider singleton with connection pooling.
-    Delegates to RedisBackendProvider.get_backend() for per-request wrappers.
-
-    For single-tenant deployments (default), sets tenant_context to "default".
-    For multi-tenant deployments, tenant_context must be set externally.
+    """Default backend provider with env-based auto-detection.
+
+    Selection is by a single, unambiguous environment signal. Priority order:
+        1. CACHEKIT_API_KEY            → CachekitIOBackend (SaaS)
+        2. CACHEKIT_REDIS_URL          → RedisBackend
+        3. CACHEKIT_MEMCACHED_SERVERS  → MemcachedBackend
+        4. CACHEKIT_FILE_CACHE_DIR     → FileBackend
+        5. REDIS_URL, or nothing set   → RedisBackend (12-factor / localhost default)
+
+    Setting more than one of the four prefixed selectors (1-4) raises
+    ``ConfigurationError`` — auto-detection must be unambiguous; pass
+    ``backend=`` explicitly to override. The non-prefixed ``REDIS_URL`` is only a
+    fallback and never counts as a conflict (12-factor convention).
+
+    CachekitIO/Memcached/File backends are stateless singletons (cached). Redis
+    backends are per-request tenant-scoped wrappers (not cached —
+    RedisBackendProvider.get_backend() reads the tenant_context ContextVar). For
+    single-tenant deployments (default), tenant_context is set to "default".
     """
 
+    # Prefixed selectors in priority order. REDIS_URL is the implicit fallback
+    # and intentionally excluded so it never triggers a conflict.
+    _SELECTORS = (
+        ("CACHEKIT_API_KEY", "cachekitio"),
+        ("CACHEKIT_REDIS_URL", "redis"),
+        ("CACHEKIT_MEMCACHED_SERVERS", "memcached"),
+        ("CACHEKIT_FILE_CACHE_DIR", "file"),
+    )
+
     def __init__(self):
-        self._provider = None
+        self._cachekitio_backend = None
+        self._redis_provider = None
+        self._memcached_backend = None
+        self._file_backend = None
+
+    def _detect(self):
+        """Return the chosen backend key, or None to use the Redis fallback.
+
+        Raises ConfigurationError if more than one prefixed selector is set.
+        """
+        import os
+
+        matched = [(env_var, key) for env_var, key in self._SELECTORS if os.environ.get(env_var)]
+        if len(matched) > 1:
+            from cachekit.config.validation import ConfigurationError
+
+            names = ", ".join(env_var for env_var, _ in matched)
+            raise ConfigurationError(
+                f"Ambiguous backend auto-detection: multiple selectors set ({names}). "
+                "Set exactly one of CACHEKIT_API_KEY / CACHEKIT_REDIS_URL / "
+                "CACHEKIT_MEMCACHED_SERVERS / CACHEKIT_FILE_CACHE_DIR, or pass backend= explicitly."
+            )
+        return matched[0][1] if matched else 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."""
+        choice = self._detect()
+
+        if choice == "cachekitio":
+            if self._cachekitio_backend is None:
+                from cachekit.backends.cachekitio import CachekitIOBackend
+
+                self._cachekitio_backend = CachekitIOBackend()
+            return self._cachekitio_backend
+
+        if choice == "memcached":
+            if self._memcached_backend is None:
+                from cachekit.backends.memcached import MemcachedBackend, MemcachedBackendConfig
+
+                self._memcached_backend = MemcachedBackend(MemcachedBackendConfig.from_env())
+            return self._memcached_backend
+
+        if choice == "file":
+            if self._file_backend is None:
+                from cachekit.backends.file import FileBackend, FileBackendConfig
+
+                self._file_backend = FileBackend(FileBackendConfig.from_env())
+            return self._file_backend
+
+        # choice == "redis" (explicit CACHEKIT_REDIS_URL) or None (REDIS_URL / localhost fallback).
+        # Tenant-scoped: call the provider each time so it re-reads tenant_context.
+        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.8.0}/src/cachekit/backends/redis/provider.py

@@ -327,7 +327,10 @@ class PerRequestRedisBackend:
         """Acquire distributed lock (LockableBackend protocol).
 
         Args:
-            key: Lock key (will be tenant-scoped)
+            key: Bare cache key (will be tenant-scoped and ``:lock``-suffixed internally).
+                The LockableBackend protocol passes the same key as ``get``/``set``/``delete``;
+                the ``:lock`` namespace is a Redis-backend implementation detail kept
+                on-wire for zero-migration compatibility with existing deployments.
             timeout: How long to hold lock (seconds) before auto-release
             blocking_timeout: Max time to wait for lock (None = non-blocking)
 
@@ -343,7 +346,11 @@ class PerRequestRedisBackend:
         """
         import asyncio
 
-        scoped_key = self._scoped_key(key)
+        # Derive the on-wire Redis lock name from the bare cache key: ``<scoped_key>:lock``.
+        # Keeping this suffix on the wire preserves compatibility with existing Redis
+        # deployments — the lock identity didn't change, only the protocol boundary
+        # (the wrapper no longer pollutes the cache_key passed in).
+        scoped_key = f"{self._scoped_key(key)}:lock"
         lock = None
         try:
             from redis.lock import Lock