cachekit 0.8.0__tar.gz → 0.9.0__tar.gz

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

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

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

@@ -1,12 +1,11 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.8.0
+Version: 0.9.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -44,7 +43,7 @@ Home-Page: https://github.com/cachekit-io/cachekit-py
 Author-email: cachekit Contributors <noreply@cachekit.io>
 Maintainer-email: cachekit Contributors <noreply@cachekit.io>
 License: MIT
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Project-URL: Changelog, https://github.com/cachekit-io/cachekit-py/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/cachekit-io/cachekit-py#readme
@@ -119,7 +118,17 @@ Or with [uv][uv-url] (recommended):
 uv add cachekit
 ```
 
-### Setup (Redis — recommended default)
+### Setup (choose a backend)
+
+cachekit exposes one decorator API over a pluggable backend abstraction. Pick the
+backend that fits your infrastructure — they're peers behind the same `@cache` API:
+
+| Backend | Best for | Select with |
+|---------|----------|-------------|
+| Redis | Self-hosted, full control | `REDIS_URL` / `CACHEKIT_REDIS_URL` |
+| CachekitIO | Managed, zero-ops (alpha) | `CACHEKIT_API_KEY` |
+| Memcached | High-throughput, existing infra | `CACHEKIT_MEMCACHED_SERVERS` |
+| File / L1-only | Local dev, tests, no external deps | `CACHEKIT_FILE_CACHE_DIR` / `backend=None` |
 
 ```bash
 # Run Redis locally or use your existing infrastructure
@@ -129,7 +138,7 @@ export REDIS_URL="redis://localhost:6379"
 ```python
 from cachekit import cache
 
-@cache  # Uses Redis backend by default
+@cache  # Auto-detects backend (defaults to Redis at localhost)
 def expensive_api_call(user_id: int):
     return fetch_user_data(user_id)
 ```
@@ -207,26 +216,37 @@ def get_user_profile(user_id: int):
     return db.fetch_user(user_id)
 ```
 
-| Feature | `@cache.minimal` | `@cache.production` | `@cache.secure` | `@cache.io()` | `@cache.local()` |
-|:--------|:----------------:|:-------------------:|:---------------:|:-------------:|:----------------:|
-| Circuit Breaker | - | ✅ | ✅ | ✅ | - |
-| Adaptive Timeouts | - | ✅ | ✅ | ✅ | - |
-| Monitoring | - | ✅ Full | ✅ Full | ✅ Full | ✅ Basic |
-| Integrity Checking | - | ✅ Enabled | ✅ Enforced | ✅ Enabled | - |
-| Encryption | - | - | ✅ Required | - | - |
-| Backend | Redis | Redis | Redis | CachekitIO SaaS | In-process |
-| **Use Case** | High throughput | Production reliability | Compliance/security | Managed cloud | Opaque objects |
+| Feature | `@cache.minimal` | `@cache.dev` | `@cache.test` | `@cache.production` | `@cache.secure` |
+|:--------|:----------------:|:------------:|:-------------:|:-------------------:|:---------------:|
+| Circuit Breaker | - | ✅ | - | ✅ | ✅ |
+| Adaptive Timeouts | - | ✅ | - | ✅ | ✅ |
+| Backpressure | ✅ | ✅ | - | ✅ | ✅ |
+| Integrity Checking | - | ✅ | - | ✅ | ✅ 🔒 |
+| Encryption | - | - | - | - | ✅ Required |
+| L1 SWR | - | ✅ | - | ✅ | ✅ |
+| L1 Invalidation | - | - | - | ✅ | ✅ |
+| L1 Namespace Index | - | - | - | ✅ | ✅ |
+| Prometheus Metrics | - | - | - | ✅ | ✅ |
+| Tracing | - | ✅ | - | ✅ | ✅ |
+| Structured Logging | - | ✅ | - | ✅ | ✅ |
+| **Use Case** | High throughput | Local debugging | Deterministic tests | Production reliability | Compliance/security |
+
+> 🔒 `@cache.secure` forces `integrity_checking=True` — it cannot be overridden.
+>
+> **`@cache.io()`** mirrors `@cache.production` (full reliability + observability) but routes to the managed CachekitIO SaaS backend instead of Redis. **`@cache.local()`** is a separate in-process path backed by `ObjectCache` (raw object references, entry-count LRU, no serialization) — the reliability and encryption features listed above do not apply to it.
 
 <details>
-<summary><strong>Additional Presets</strong></summary>
+<summary><strong>Additional Presets: <code>@cache.dev</code> and <code>@cache.test</code></strong></summary>
+
+See the comparison table above for the exact feature set of each preset.
 
 ```python
-# Development: debugging with verbose output
+# Development: verbose logging, integrity checks on, Prometheus off
 @cache.dev
 def debug_expensive_call():
     return complex_computation()
 
-# Testing: deterministic, no randomness
+# Testing: deterministic, all protections off (no circuit breaker, no backpressure)
 @cache.test
 def test_cached_function():
     return fixed_test_value()
@@ -356,12 +376,36 @@ See [SECURITY.md][security-url] for vulnerability reporting and detailed documen
 
 </details>
 
-### Built-in Monitoring
+### Monitoring & Observability
 
-- **Prometheus metrics** - Production-ready observability
+- **Per-function statistics** - `cache_info()` on every decorated function, modelled on `functools.lru_cache`
+- **Prometheus metrics** - Recorded by default (your app owns exposition)
 - **Structured logging** - Context-aware with correlation IDs
 - **Health checks** - Comprehensive status endpoints
-- **Performance tracking** - Built-in latency monitoring
+
+Every decorated function exposes `cache_info()`, returning a `CacheInfo` named tuple with
+hit/miss counts, the L1/L2 split, and average backend latency:
+
+```python
+@cache()
+def get_score(x):
+    return x ** 2
+
+get_score(2)
+get_score(2)  # served from cache
+
+info = get_score.cache_info()
+# CacheInfo has 9 fields: hits, misses, l1_hits, l2_hits, maxsize,
+# currsize, l2_avg_latency_ms, last_operation_at, session_id
+assert info.l1_hits + info.l2_hits == info.hits  # every hit is L1 or L2
+```
+
+`maxsize` and `currsize` are always `None` (the cache lives in an external store, not a
+bounded in-process dict); they exist only for `lru_cache` API parity. See the
+[API Reference](docs/api-reference.md#per-function-statistics-via-cache_info) for the full
+field reference and a sample stats endpoint, and the
+[Prometheus Metrics guide](docs/features/prometheus-metrics.md) for metric names and
+exposition setup.
 
 <details>
 <summary><strong>Thread Safety Details</strong></summary>
@@ -381,8 +425,10 @@ def expensive_func(x):
 with ThreadPoolExecutor(max_workers=10) as executor:
     results = list(executor.map(expensive_func, range(100)))
 
-print(expensive_func.cache_info())
-# CacheInfo(hits=90, misses=10, maxsize=None, currsize=10)
+info = expensive_func.cache_info()
+# CacheInfo(hits=..., misses=..., l1_hits=..., l2_hits=...,
+#           maxsize=None, currsize=None, l2_avg_latency_ms=...,
+#           last_operation_at=..., session_id=...)
 ```
 
 </details>
@@ -459,7 +505,7 @@ See [CONTRIBUTING.md][contributing-url] for full development guidelines.
 
 | Component | Version |
 |:----------|:--------|
-| Python | 3.9+ |
+| Python | 3.10+ |
 
 ---
 

{cachekit-0.8.0 → cachekit-0.9.0}/README.md

@@ -65,7 +65,17 @@ Or with [uv][uv-url] (recommended):
 uv add cachekit
 ```
 
-### Setup (Redis — recommended default)
+### Setup (choose a backend)
+
+cachekit exposes one decorator API over a pluggable backend abstraction. Pick the
+backend that fits your infrastructure — they're peers behind the same `@cache` API:
+
+| Backend | Best for | Select with |
+|---------|----------|-------------|
+| Redis | Self-hosted, full control | `REDIS_URL` / `CACHEKIT_REDIS_URL` |
+| CachekitIO | Managed, zero-ops (alpha) | `CACHEKIT_API_KEY` |
+| Memcached | High-throughput, existing infra | `CACHEKIT_MEMCACHED_SERVERS` |
+| File / L1-only | Local dev, tests, no external deps | `CACHEKIT_FILE_CACHE_DIR` / `backend=None` |
 
 ```bash
 # Run Redis locally or use your existing infrastructure
@@ -75,7 +85,7 @@ export REDIS_URL="redis://localhost:6379"
 ```python
 from cachekit import cache
 
-@cache  # Uses Redis backend by default
+@cache  # Auto-detects backend (defaults to Redis at localhost)
 def expensive_api_call(user_id: int):
     return fetch_user_data(user_id)
 ```
@@ -153,26 +163,37 @@ def get_user_profile(user_id: int):
     return db.fetch_user(user_id)
 ```
 
-| Feature | `@cache.minimal` | `@cache.production` | `@cache.secure` | `@cache.io()` | `@cache.local()` |
-|:--------|:----------------:|:-------------------:|:---------------:|:-------------:|:----------------:|
-| Circuit Breaker | - | ✅ | ✅ | ✅ | - |
-| Adaptive Timeouts | - | ✅ | ✅ | ✅ | - |
-| Monitoring | - | ✅ Full | ✅ Full | ✅ Full | ✅ Basic |
-| Integrity Checking | - | ✅ Enabled | ✅ Enforced | ✅ Enabled | - |
-| Encryption | - | - | ✅ Required | - | - |
-| Backend | Redis | Redis | Redis | CachekitIO SaaS | In-process |
-| **Use Case** | High throughput | Production reliability | Compliance/security | Managed cloud | Opaque objects |
+| Feature | `@cache.minimal` | `@cache.dev` | `@cache.test` | `@cache.production` | `@cache.secure` |
+|:--------|:----------------:|:------------:|:-------------:|:-------------------:|:---------------:|
+| Circuit Breaker | - | ✅ | - | ✅ | ✅ |
+| Adaptive Timeouts | - | ✅ | - | ✅ | ✅ |
+| Backpressure | ✅ | ✅ | - | ✅ | ✅ |
+| Integrity Checking | - | ✅ | - | ✅ | ✅ 🔒 |
+| Encryption | - | - | - | - | ✅ Required |
+| L1 SWR | - | ✅ | - | ✅ | ✅ |
+| L1 Invalidation | - | - | - | ✅ | ✅ |
+| L1 Namespace Index | - | - | - | ✅ | ✅ |
+| Prometheus Metrics | - | - | - | ✅ | ✅ |
+| Tracing | - | ✅ | - | ✅ | ✅ |
+| Structured Logging | - | ✅ | - | ✅ | ✅ |
+| **Use Case** | High throughput | Local debugging | Deterministic tests | Production reliability | Compliance/security |
+
+> 🔒 `@cache.secure` forces `integrity_checking=True` — it cannot be overridden.
+>
+> **`@cache.io()`** mirrors `@cache.production` (full reliability + observability) but routes to the managed CachekitIO SaaS backend instead of Redis. **`@cache.local()`** is a separate in-process path backed by `ObjectCache` (raw object references, entry-count LRU, no serialization) — the reliability and encryption features listed above do not apply to it.
 
 <details>
-<summary><strong>Additional Presets</strong></summary>
+<summary><strong>Additional Presets: <code>@cache.dev</code> and <code>@cache.test</code></strong></summary>
+
+See the comparison table above for the exact feature set of each preset.
 
 ```python
-# Development: debugging with verbose output
+# Development: verbose logging, integrity checks on, Prometheus off
 @cache.dev
 def debug_expensive_call():
     return complex_computation()
 
-# Testing: deterministic, no randomness
+# Testing: deterministic, all protections off (no circuit breaker, no backpressure)
 @cache.test
 def test_cached_function():
     return fixed_test_value()
@@ -302,12 +323,36 @@ See [SECURITY.md][security-url] for vulnerability reporting and detailed documen
 
 </details>
 
-### Built-in Monitoring
+### Monitoring & Observability
 
-- **Prometheus metrics** - Production-ready observability
+- **Per-function statistics** - `cache_info()` on every decorated function, modelled on `functools.lru_cache`
+- **Prometheus metrics** - Recorded by default (your app owns exposition)
 - **Structured logging** - Context-aware with correlation IDs
 - **Health checks** - Comprehensive status endpoints
-- **Performance tracking** - Built-in latency monitoring
+
+Every decorated function exposes `cache_info()`, returning a `CacheInfo` named tuple with
+hit/miss counts, the L1/L2 split, and average backend latency:
+
+```python
+@cache()
+def get_score(x):
+    return x ** 2
+
+get_score(2)
+get_score(2)  # served from cache
+
+info = get_score.cache_info()
+# CacheInfo has 9 fields: hits, misses, l1_hits, l2_hits, maxsize,
+# currsize, l2_avg_latency_ms, last_operation_at, session_id
+assert info.l1_hits + info.l2_hits == info.hits  # every hit is L1 or L2
+```
+
+`maxsize` and `currsize` are always `None` (the cache lives in an external store, not a
+bounded in-process dict); they exist only for `lru_cache` API parity. See the
+[API Reference](docs/api-reference.md#per-function-statistics-via-cache_info) for the full
+field reference and a sample stats endpoint, and the
+[Prometheus Metrics guide](docs/features/prometheus-metrics.md) for metric names and
+exposition setup.
 
 <details>
 <summary><strong>Thread Safety Details</strong></summary>
@@ -327,8 +372,10 @@ def expensive_func(x):
 with ThreadPoolExecutor(max_workers=10) as executor:
     results = list(executor.map(expensive_func, range(100)))
 
-print(expensive_func.cache_info())
-# CacheInfo(hits=90, misses=10, maxsize=None, currsize=10)
+info = expensive_func.cache_info()
+# CacheInfo(hits=..., misses=..., l1_hits=..., l2_hits=...,
+#           maxsize=None, currsize=None, l2_avg_latency_ms=...,
+#           last_operation_at=..., session_id=...)
 ```
 
 </details>
@@ -405,7 +452,7 @@ See [CONTRIBUTING.md][contributing-url] for full development guidelines.
 
 | Component | Version |
 |:----------|:--------|
-| Python | 3.9+ |
+| Python | 3.10+ |
 
 ---
 

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

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cachekit"
-version = "0.8.0"
+version = "0.9.0"
 description = "Production-ready Redis caching for Python with intelligent reliability features and Rust-powered performance"
 readme = "README.md"
 license = {text = "MIT"}
@@ -36,7 +36,6 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -51,7 +50,7 @@ classifiers = [
     "Framework :: AsyncIO",
     "Typing :: Typed",
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 dependencies = [
     # Core Redis functionality
     "redis[hiredis]>=4.0.0",
@@ -101,7 +100,7 @@ include = ["LICENSE", "README.md"]
 # Ruff configuration
 [tool.ruff]
 line-length = 129
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = [
@@ -237,7 +236,11 @@ fuzz = [
 # Override vulnerable transitive dependencies
 [tool.uv]
 constraint-dependencies = [
-    "urllib3>=2.6.0",
+    "urllib3>=2.7.0",
     "fonttools>=4.60.2",
     "werkzeug>=3.1.4",
+    # pip is a dev-only transitive dep (pip-audit -> pip-api -> pip). 26.1.2 fixes
+    # PYSEC-2026-196 (entry-point path traversal), GHSA-58qw-9mgm-455v (tar/zip
+    # confusion) and GHSA-jp4c-xjxw-mgf9 (self-update import ordering).
+    "pip>=26.1.2",
 ]

{cachekit-0.8.0 → cachekit-0.9.0}/rust/Cargo.toml

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

{cachekit-0.8.0 → cachekit-0.9.0}/rust/README.md

@@ -65,7 +65,17 @@ Or with [uv][uv-url] (recommended):
 uv add cachekit
 ```
 
-### Setup (Redis — recommended default)
+### Setup (choose a backend)
+
+cachekit exposes one decorator API over a pluggable backend abstraction. Pick the
+backend that fits your infrastructure — they're peers behind the same `@cache` API:
+
+| Backend | Best for | Select with |
+|---------|----------|-------------|
+| Redis | Self-hosted, full control | `REDIS_URL` / `CACHEKIT_REDIS_URL` |
+| CachekitIO | Managed, zero-ops (alpha) | `CACHEKIT_API_KEY` |
+| Memcached | High-throughput, existing infra | `CACHEKIT_MEMCACHED_SERVERS` |
+| File / L1-only | Local dev, tests, no external deps | `CACHEKIT_FILE_CACHE_DIR` / `backend=None` |
 
 ```bash
 # Run Redis locally or use your existing infrastructure
@@ -75,7 +85,7 @@ export REDIS_URL="redis://localhost:6379"
 ```python
 from cachekit import cache
 
-@cache  # Uses Redis backend by default
+@cache  # Auto-detects backend (defaults to Redis at localhost)
 def expensive_api_call(user_id: int):
     return fetch_user_data(user_id)
 ```
@@ -153,26 +163,37 @@ def get_user_profile(user_id: int):
     return db.fetch_user(user_id)
 ```
 
-| Feature | `@cache.minimal` | `@cache.production` | `@cache.secure` | `@cache.io()` | `@cache.local()` |
-|:--------|:----------------:|:-------------------:|:---------------:|:-------------:|:----------------:|
-| Circuit Breaker | - | ✅ | ✅ | ✅ | - |
-| Adaptive Timeouts | - | ✅ | ✅ | ✅ | - |
-| Monitoring | - | ✅ Full | ✅ Full | ✅ Full | ✅ Basic |
-| Integrity Checking | - | ✅ Enabled | ✅ Enforced | ✅ Enabled | - |
-| Encryption | - | - | ✅ Required | - | - |
-| Backend | Redis | Redis | Redis | CachekitIO SaaS | In-process |
-| **Use Case** | High throughput | Production reliability | Compliance/security | Managed cloud | Opaque objects |
+| Feature | `@cache.minimal` | `@cache.dev` | `@cache.test` | `@cache.production` | `@cache.secure` |
+|:--------|:----------------:|:------------:|:-------------:|:-------------------:|:---------------:|
+| Circuit Breaker | - | ✅ | - | ✅ | ✅ |
+| Adaptive Timeouts | - | ✅ | - | ✅ | ✅ |
+| Backpressure | ✅ | ✅ | - | ✅ | ✅ |
+| Integrity Checking | - | ✅ | - | ✅ | ✅ 🔒 |
+| Encryption | - | - | - | - | ✅ Required |
+| L1 SWR | - | ✅ | - | ✅ | ✅ |
+| L1 Invalidation | - | - | - | ✅ | ✅ |
+| L1 Namespace Index | - | - | - | ✅ | ✅ |
+| Prometheus Metrics | - | - | - | ✅ | ✅ |
+| Tracing | - | ✅ | - | ✅ | ✅ |
+| Structured Logging | - | ✅ | - | ✅ | ✅ |
+| **Use Case** | High throughput | Local debugging | Deterministic tests | Production reliability | Compliance/security |
+
+> 🔒 `@cache.secure` forces `integrity_checking=True` — it cannot be overridden.
+>
+> **`@cache.io()`** mirrors `@cache.production` (full reliability + observability) but routes to the managed CachekitIO SaaS backend instead of Redis. **`@cache.local()`** is a separate in-process path backed by `ObjectCache` (raw object references, entry-count LRU, no serialization) — the reliability and encryption features listed above do not apply to it.
 
 <details>
-<summary><strong>Additional Presets</strong></summary>
+<summary><strong>Additional Presets: <code>@cache.dev</code> and <code>@cache.test</code></strong></summary>
+
+See the comparison table above for the exact feature set of each preset.
 
 ```python
-# Development: debugging with verbose output
+# Development: verbose logging, integrity checks on, Prometheus off
 @cache.dev
 def debug_expensive_call():
     return complex_computation()
 
-# Testing: deterministic, no randomness
+# Testing: deterministic, all protections off (no circuit breaker, no backpressure)
 @cache.test
 def test_cached_function():
     return fixed_test_value()
@@ -302,12 +323,36 @@ See [SECURITY.md][security-url] for vulnerability reporting and detailed documen
 
 </details>
 
-### Built-in Monitoring
+### Monitoring & Observability
 
-- **Prometheus metrics** - Production-ready observability
+- **Per-function statistics** - `cache_info()` on every decorated function, modelled on `functools.lru_cache`
+- **Prometheus metrics** - Recorded by default (your app owns exposition)
 - **Structured logging** - Context-aware with correlation IDs
 - **Health checks** - Comprehensive status endpoints
-- **Performance tracking** - Built-in latency monitoring
+
+Every decorated function exposes `cache_info()`, returning a `CacheInfo` named tuple with
+hit/miss counts, the L1/L2 split, and average backend latency:
+
+```python
+@cache()
+def get_score(x):
+    return x ** 2
+
+get_score(2)
+get_score(2)  # served from cache
+
+info = get_score.cache_info()
+# CacheInfo has 9 fields: hits, misses, l1_hits, l2_hits, maxsize,
+# currsize, l2_avg_latency_ms, last_operation_at, session_id
+assert info.l1_hits + info.l2_hits == info.hits  # every hit is L1 or L2
+```
+
+`maxsize` and `currsize` are always `None` (the cache lives in an external store, not a
+bounded in-process dict); they exist only for `lru_cache` API parity. See the
+[API Reference](docs/api-reference.md#per-function-statistics-via-cache_info) for the full
+field reference and a sample stats endpoint, and the
+[Prometheus Metrics guide](docs/features/prometheus-metrics.md) for metric names and
+exposition setup.
 
 <details>
 <summary><strong>Thread Safety Details</strong></summary>
@@ -327,8 +372,10 @@ def expensive_func(x):
 with ThreadPoolExecutor(max_workers=10) as executor:
     results = list(executor.map(expensive_func, range(100)))
 
-print(expensive_func.cache_info())
-# CacheInfo(hits=90, misses=10, maxsize=None, currsize=10)
+info = expensive_func.cache_info()
+# CacheInfo(hits=..., misses=..., l1_hits=..., l2_hits=...,
+#           maxsize=None, currsize=None, l2_avg_latency_ms=...,
+#           last_operation_at=..., session_id=...)
 ```
 
 </details>
@@ -405,7 +452,7 @@ See [CONTRIBUTING.md][contributing-url] for full development guidelines.
 
 | Component | Version |
 |:----------|:--------|
-| Python | 3.9+ |
+| Python | 3.10+ |
 
 ---
 

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

@@ -68,9 +68,10 @@ Example Usage:
     ```
 """
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 
-from typing import Any, Callable, TypeVar
+from collections.abc import Callable
+from typing import Any, TypeVar
 
 # Configure hiredis compatibility BEFORE any Redis imports
 # This prevents GIL warnings in Python 3.13+ free-threading mode

{cachekit-0.8.0 → cachekit-0.9.0}/src/cachekit/backends/memcached/backend.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import time
 from typing import Any, Optional
 
+from cachekit.backends.errors import BackendError, BackendErrorType
 from cachekit.backends.memcached.config import MAX_MEMCACHED_TTL, MemcachedBackendConfig
 from cachekit.backends.memcached.error_handler import classify_memcached_error
 
@@ -108,12 +109,32 @@ class MemcachedBackend:
         Raises:
             BackendError: If Memcached operation fails.
         """
+        # Guard client-side against oversized items. Memcached rejects items over its
+        # item-size limit (default 1 MiB), but with noreply that rejection is never read —
+        # the call appears to succeed and the entry is silently never cached. Fail loudly
+        # instead, so the caller can compress, shard, or switch backends.
+        max_size = self._config.max_item_size_bytes
+        if max_size and len(value) > max_size:
+            raise BackendError(
+                message=(
+                    f"Value for key {key!r} is {len(value)} bytes, which exceeds the Memcached "
+                    f"max item size of {max_size} bytes. Memcached cannot store it. Enable "
+                    f"compression, use a larger-payload backend (Redis/SaaS/File), or raise both "
+                    f"the server's -I limit and CACHEKIT_MEMCACHED_MAX_ITEM_SIZE_BYTES."
+                ),
+                error_type=BackendErrorType.PERMANENT,
+                operation="set",
+                key=key,
+            )
+
         expire = 0
         if ttl is not None and ttl > 0:
             expire = min(ttl, MAX_MEMCACHED_TTL)
 
         try:
-            self._client.set(self._prefixed_key(key), value, expire=expire)
+            # noreply=False so an oversized/error reply from the server is read and surfaced
+            # rather than silently swallowed (HashClient defaults to noreply=True).
+            self._client.set(self._prefixed_key(key), value, expire=expire, noreply=False)
         except Exception as exc:
             raise classify_memcached_error(exc, operation="set", key=key) from exc
 

{cachekit-0.8.0 → cachekit-0.9.0}/src/cachekit/backends/memcached/config.py

@@ -85,6 +85,16 @@ class MemcachedBackendConfig(BaseBackendConfig):
         default="",
         description="Optional prefix for all cache keys",
     )
+    max_item_size_bytes: int = Field(
+        default=1024 * 1024,
+        ge=0,
+        description=(
+            "Reject values larger than this BEFORE sending to Memcached (0 disables the check). "
+            "Memcached's default item-size limit is 1 MiB (server -I flag); oversized items are "
+            "rejected by the server, and with noreply that rejection is silent — so cachekit "
+            "guards client-side and fails loudly. Raise this only if the server's -I is raised too."
+        ),
+    )
 
     @field_validator("servers", mode="after")
     @classmethod

{cachekit-0.8.0 → cachekit-0.9.0}/src/cachekit/backends/redis/backend.py

@@ -107,15 +107,11 @@ class RedisBackend:
         try:
             client = self._get_client()
             value = client.get(key)
-            # Redis client with decode_responses=True returns str, need bytes
-            # But get() with binary data returns bytes if decode fails
-            # For safety, encode if we got str
-            if value is not None:
-                if isinstance(value, str):
-                    return value.encode("utf-8")
-                if isinstance(value, bytes):
-                    return value
-            return None
+            # The pool is configured with decode_responses=False (see redis/client.py),
+            # so Redis returns raw bytes, or None for a missing key. Cached payloads are
+            # binary (LZ4/Arrow/AES ciphertext) and must never be UTF-8 decoded. The
+            # isinstance check enforces the bytes|None contract without any str coercion.
+            return value if isinstance(value, bytes) else None
         except Exception as e:
             raise BackendError(
                 message=f"Redis GET failed: {e}",

{cachekit-0.8.0 → cachekit-0.9.0}/src/cachekit/backends/redis/client.py

@@ -78,7 +78,7 @@ def get_redis_client() -> redis.Redis:
                 # Use URL-based connection
                 _pool_instance = redis.ConnectionPool.from_url(
                     redis_config.redis_url,
-                    decode_responses=True,
+                    decode_responses=False,  # cached payloads are raw bytes (LZ4/Arrow/AES) — never UTF-8 decode
                     max_connections=redis_config.connection_pool_size,
                 )
 
@@ -120,7 +120,7 @@ async def get_async_redis_client() -> redis_async.Redis:
                 # Use URL-based connection
                 _async_pool_instance = redis_async.ConnectionPool.from_url(
                     redis_config.redis_url,
-                    decode_responses=True,
+                    decode_responses=False,  # cached payloads are raw bytes (LZ4/Arrow/AES) — never UTF-8 decode
                     max_connections=redis_config.connection_pool_size,
                 )