From c4061b177dcd0884b27af1e961fd86a64f2b1dcc Mon Sep 17 00:00:00 2001 From: Ray Walker Date: Tue, 21 Jul 2026 12:16:56 +1000 Subject: [PATCH] docs(matrix): note per-backend TTL inspection for Python (LAB-446) The Python File backend now implements full TTL inspection/refresh (TTLInspectableBackend). Memcached implements refresh_ttl (via touch) only, NOT get_ttl (no protocol command to read remaining TTL; pymemcache HashClient exposes no meta protocol), so it is not a full TTLInspectableBackend and refresh_ttl_on_get does not apply to it. Add a per-backend note under the TTL management row and refresh the last-updated line. rs (LAB-429) and ts (LAB-430) must match this split (refresh-only Memcached, full File) when they add those backends. Co-Authored-By: Claude Opus 4.8 Co-authored-by: multica-agent --- sdk-feature-matrix.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/sdk-feature-matrix.md b/sdk-feature-matrix.md index 05c5fce..5d8abe9 100644 --- a/sdk-feature-matrix.md +++ b/sdk-feature-matrix.md @@ -6,7 +6,7 @@ **Feature parity and compliance status across all CacheKit SDK implementations.** -*Last updated: 2026-07-20 — LAB-381 stale-while-revalidate (server stale-grace) specified in [spec/saas-api.md](spec/saas-api.md#stale-while-revalidate)* +*Last updated: 2026-07-21 — LAB-446: Python File backend gains full TTL inspection/refresh; Memcached gains `refresh_ttl` (touch) only (see [TTL management note](#reliability-features))* @@ -88,11 +88,24 @@ | Distributed locking | ✅ | ✅ SaaS backend (`LockableBackend`) | ✅ SaaS backend only | ❌ | | L1/L2 dual-layer cache | ✅ | ✅ moka (native) / `l1` feature | ✅ | ❌ | | Cache stampede prevention | ✅ | ❌ | ✅ Version tokens + background L1 refresh | ❌ | -| TTL management | ✅ | ✅ `TtlInspectable` trait | ✅ | ❌ | +| TTL management | ✅ (see note) | ✅ `TtlInspectable` trait | ✅ | ❌ | | Stale-while-revalidate (server stale-grace) | 🚧 LAB-381 | ❌ | ❌ | ❌ | > **Lock id transport (CWE-532):** the unlock call carries the lock capability token in the `X-CacheKit-Lock-Id` request header, never the `?lock_id=` query string (which leaks via access/proxy logs and OTel `http.url` spans). SaaS dual-reads both during the rollout; SDKs migrate to header-only — Python (#131), TypeScript (#63), Rust (#24). See [spec/saas-api.md](spec/saas-api.md#delete-v1cachekeylock). +> [!NOTE] +> **TTL management is per-backend.** "TTL inspection/refresh" means the `TTLInspectableBackend` +> capability (`get_ttl` + `refresh_ttl`) that powers `refresh_ttl_on_get` threshold-based +> sliding expiration. +> - **Python (LAB-446):** supported on **Redis**, **CachekitIO**, and **File**. **Memcached** +> implements `refresh_ttl` (via the `touch` command) but **not** `get_ttl` — the Memcached +> protocol has no command to read a key's remaining TTL, and pymemcache's `HashClient` +> exposes no meta protocol — so Memcached is **not** a full `TTLInspectableBackend` and +> `refresh_ttl_on_get` does not apply to it (it warns once, then serves the hit). +> - **Rust / TypeScript:** parity for their existing backends is tracked separately; when a +> Memcached/File backend lands there it must match this Python split (refresh-only Memcached, +> full File) — see LAB-429 (rs) / LAB-430 (ts). + --- ## Developer Experience