cachekit 0.11.1__tar.gz → 0.14.0__tar.gz

{cachekit-0.11.1 → cachekit-0.14.0}/Cargo.lock

@@ -245,9 +245,9 @@ checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "cachekit-core"
-version = "0.2.1"
+version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "01870e86fa79ca9ee521b5b9c2bcff8428eab95fb343f75d35a6fce159bb1577"
+checksum = "9ee6235f73aefb0dc66b9cd0d333b9da928c8192e4234357a739fe756c2f8f23"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -271,7 +271,7 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.11.1"
+version = "0.14.0"
 dependencies = [
  "cachekit-core",
  "criterion",
@@ -468,9 +468,9 @@ dependencies = [
 
 [[package]]
 name = "crossbeam-epoch"
-version = "0.9.18"
+version = "0.9.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
 dependencies = [
  "crossbeam-utils",
 ]

{cachekit-0.11.1 → cachekit-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.11.1
+Version: 0.14.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -412,8 +412,9 @@ exposition setup.
 <summary><strong>Thread Safety Details</strong></summary>
 
 **Per-Function Statistics:**
-- Statistics tracked per decorated function (shared across all calls)
+- Statistics tracked per function identity (`module.qualname`), shared across all calls and across re-decorations of the same function
 - Thread-safe via RLock (all methods safe for concurrent access)
+- Fork-safe: a forked child starts with zeroed counters and its own session ID
 
 ```python
 from concurrent.futures import ThreadPoolExecutor
@@ -480,8 +481,8 @@ CACHEKIT_MEMCACHED_KEY_PREFIX="myapp:"                    # Default: "" (none)
 
 # Optional Configuration
 CACHEKIT_DEFAULT_TTL=3600
-CACHEKIT_MAX_CHUNK_SIZE_MB=100
-CACHEKIT_ENABLE_COMPRESSION=true
+CACHEKIT_MAX_VALUE_SIZE=104857600
+CACHEKIT_ARROW_COMPRESSION=zstd
 ```
 
 > [!NOTE]

{cachekit-0.11.1 → cachekit-0.14.0}/README.md

@@ -358,8 +358,9 @@ exposition setup.
 <summary><strong>Thread Safety Details</strong></summary>
 
 **Per-Function Statistics:**
-- Statistics tracked per decorated function (shared across all calls)
+- Statistics tracked per function identity (`module.qualname`), shared across all calls and across re-decorations of the same function
 - Thread-safe via RLock (all methods safe for concurrent access)
+- Fork-safe: a forked child starts with zeroed counters and its own session ID
 
 ```python
 from concurrent.futures import ThreadPoolExecutor
@@ -426,8 +427,8 @@ CACHEKIT_MEMCACHED_KEY_PREFIX="myapp:"                    # Default: "" (none)
 
 # Optional Configuration
 CACHEKIT_DEFAULT_TTL=3600
-CACHEKIT_MAX_CHUNK_SIZE_MB=100
-CACHEKIT_ENABLE_COMPRESSION=true
+CACHEKIT_MAX_VALUE_SIZE=104857600
+CACHEKIT_ARROW_COMPRESSION=zstd
 ```
 
 > [!NOTE]

{cachekit-0.11.1 → cachekit-0.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cachekit"
-version = "0.11.1"
+version = "0.14.0"
 description = "Production-ready Redis caching for Python with intelligent reliability features and Rust-powered performance"
 readme = "README.md"
 license = {text = "MIT"}
@@ -156,6 +156,7 @@ addopts = [
     "--doctest-modules",              # Validate docstring examples
     "--doctest-continue-on-failure",  # Report all doctest failures, not just first
     "--markdown-docs",                # Validate markdown documentation examples
+    "--benchmark-skip",               # pytest-benchmark tests run only via --benchmark-only (make benchmark)
 ]
 markers = [
     "asyncio: Async tests using pytest-asyncio",

{cachekit-0.11.1 → cachekit-0.14.0}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cachekit-rs"
-version = "0.11.1"
+version = "0.14.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.2.0", features = ["compression", "checksum", "messagepack", "encryption"] }
+cachekit-core = { version = "0.3.0", features = ["compression", "checksum", "messagepack", "encryption"] }
 
 # Python integration - optional for Rust-only builds
 pyo3 = { workspace = true, optional = true }

{cachekit-0.11.1 → cachekit-0.14.0}/rust/README.md

@@ -358,8 +358,9 @@ exposition setup.
 <summary><strong>Thread Safety Details</strong></summary>
 
 **Per-Function Statistics:**
-- Statistics tracked per decorated function (shared across all calls)
+- Statistics tracked per function identity (`module.qualname`), shared across all calls and across re-decorations of the same function
 - Thread-safe via RLock (all methods safe for concurrent access)
+- Fork-safe: a forked child starts with zeroed counters and its own session ID
 
 ```python
 from concurrent.futures import ThreadPoolExecutor
@@ -426,8 +427,8 @@ CACHEKIT_MEMCACHED_KEY_PREFIX="myapp:"                    # Default: "" (none)
 
 # Optional Configuration
 CACHEKIT_DEFAULT_TTL=3600
-CACHEKIT_MAX_CHUNK_SIZE_MB=100
-CACHEKIT_ENABLE_COMPRESSION=true
+CACHEKIT_MAX_VALUE_SIZE=104857600
+CACHEKIT_ARROW_COMPRESSION=zstd
 ```
 
 > [!NOTE]

{cachekit-0.11.1 → cachekit-0.14.0}/rust/src/lib.rs

@@ -30,6 +30,11 @@ fn _rust_serializer(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     // Add byte storage class
     m.add_class::<python_bindings::PyByteStorage>()?;
 
+    // Standalone integrity primitive — registered unconditionally (usable with
+    // the checksum feature alone; must not vanish when encryption is off)
+    m.add_function(wrap_pyfunction!(python_bindings::checksum_py, m)?)?;
+    m.add_function(wrap_pyfunction!(python_bindings::verify_checksum_py, m)?)?;
+
     // Add encryption functionality if feature is enabled
     #[cfg(feature = "encryption")]
     {
@@ -43,13 +48,13 @@ fn _rust_serializer(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     #[cfg(feature = "encryption")]
     m.add(
         "__description__",
-        "Raw byte storage with LZ4 compression, Blake3 checksums, and zero-knowledge encryption",
+        "Raw byte storage with LZ4 compression, xxHash3-64 checksums, and zero-knowledge encryption",
     )?;
 
     #[cfg(not(feature = "encryption"))]
     m.add(
         "__description__",
-        "Raw byte storage layer with LZ4 compression and Blake3 checksums",
+        "Raw byte storage layer with LZ4 compression and xxHash3-64 checksums",
     )?;
 
     Ok(())

{cachekit-0.11.1 → cachekit-0.14.0}/rust/src/python_bindings.rs

@@ -4,6 +4,7 @@
 //! All business logic is delegated to cachekit-core.
 
 use cachekit_core::ByteStorage;
+use pyo3::buffer::PyBuffer;
 use pyo3::exceptions::PyValueError;
 use pyo3::prelude::*;
 use pyo3::types::PyBytes;
@@ -38,9 +39,11 @@ impl PyByteStorage {
     /// Returns:
     ///     Bytes: Serialized StorageEnvelope
     pub fn store(&self, py: Python, data: &[u8], format: Option<String>) -> PyResult<Py<PyBytes>> {
-        let envelope_bytes = self
-            .inner
-            .store(data, format)
+        // Detach from the GIL: LZ4 + xxh3 on a large payload otherwise blocks every
+        // Python thread for the full compression duration (cachekit-core#45).
+        // Sound: `data` borrows an immutable `bytes` buffer kept alive by this call.
+        let envelope_bytes = py
+            .detach(|| self.inner.store(data, format))
             .map_err(|e| PyValueError::new_err(format!("Storage failed: {}", e)))?;
 
         Ok(PyBytes::new(py, &envelope_bytes).into())
@@ -53,22 +56,23 @@ impl PyByteStorage {
     ///
     /// Returns:
     ///     Tuple[bytes, str]: (original_data, format_identifier)
-    pub fn retrieve(&self, envelope_bytes: &[u8]) -> PyResult<(Vec<u8>, String)> {
-        self.inner
-            .retrieve(envelope_bytes)
+    pub fn retrieve(&self, py: Python, envelope_bytes: &[u8]) -> PyResult<(Vec<u8>, String)> {
+        // Detach from the GIL for decompression + checksum (see store()).
+        py.detach(|| self.inner.retrieve(envelope_bytes))
             .map_err(|e| PyValueError::new_err(format!("Retrieval failed: {}", e)))
     }
 
     /// Get compression ratio for given data
-    pub fn estimate_compression(&self, data: &[u8]) -> PyResult<f64> {
-        self.inner
-            .estimate_compression(data)
+    pub fn estimate_compression(&self, py: Python, data: &[u8]) -> PyResult<f64> {
+        // Full-payload LZ4 pass — same GIL-blocking profile as store().
+        py.detach(|| self.inner.estimate_compression(data))
             .map_err(|e| PyValueError::new_err(format!("Compression estimation failed: {}", e)))
     }
 
     /// Validate envelope without extracting data
-    pub fn validate(&self, envelope_bytes: &[u8]) -> PyResult<bool> {
-        Ok(self.inner.validate(envelope_bytes))
+    pub fn validate(&self, py: Python, envelope_bytes: &[u8]) -> PyResult<bool> {
+        // Full decompression + checksum under the hood — same GIL-blocking profile.
+        Ok(py.detach(|| self.inner.validate(envelope_bytes)))
     }
 
     /// Get security limits for clients
@@ -340,6 +344,47 @@ pub fn key_fingerprint_py(key: &[u8]) -> Vec<u8> {
     key_fingerprint(key).to_vec()
 }
 
+/// Compute the standalone xxHash3-64 checksum of `data` (8 bytes, big-endian).
+///
+/// Accepts any buffer-protocol object — `bytes`, `bytearray`, `memoryview`,
+/// Arrow buffers — so a serializer holding its payload as a `memoryview`
+/// (e.g. Arrow IPC) can hash it directly, without forcing a `bytes` copy.
+///
+/// NON-cryptographic: detects corruption, not tampering. For tamper-resistance
+/// use @cache.secure (AES-256-GCM), never this checksum. Produces the exact
+/// bytes embedded in every StorageEnvelope, without the LZ4 compression
+/// overhead — for serializers where compression is ineffective (Arrow IPC, JSON).
+#[pyfunction]
+#[pyo3(name = "checksum")]
+pub fn checksum_py(py: Python, data: PyBuffer<u8>) -> PyResult<Py<PyBytes>> {
+    let data = data.to_vec(py)?;
+    Ok(PyBytes::new(py, &cachekit_core::checksum(&data)).into())
+}
+
+/// Verify `data` against an expected 8-byte xxHash3-64 checksum.
+///
+/// Both arguments accept any buffer-protocol object (`bytes`, `bytearray`,
+/// `memoryview`, …) — the Arrow verify path slices a `memoryview` (`mv[8:]`),
+/// so a bytes-only signature would break the moment a serializer moves onto
+/// this FFI.
+///
+/// NON-cryptographic: detects corruption, not tampering (see `checksum`).
+/// Raises ValueError if `expected` is not exactly 8 bytes — a truncated
+/// checksum must fail loudly, never return a wrong verdict.
+#[pyfunction]
+#[pyo3(name = "verify_checksum")]
+pub fn verify_checksum_py(
+    py: Python,
+    data: PyBuffer<u8>,
+    expected: PyBuffer<u8>,
+) -> PyResult<bool> {
+    let expected: [u8; 8] = expected.to_vec(py)?.try_into().map_err(|v: Vec<u8>| {
+        PyValueError::new_err(format!("expected must be exactly 8 bytes, got {}", v.len()))
+    })?;
+    let data = data.to_vec(py)?;
+    Ok(cachekit_core::verify_checksum(&data, &expected))
+}
+
 /// Register encryption module with Python
 #[cfg(feature = "encryption")]
 pub fn register_encryption_module(m: &Bound<'_, PyModule>) -> PyResult<()> {

{cachekit-0.11.1 → cachekit-0.14.0}/src/cachekit/__init__.py

@@ -1,8 +1,8 @@
 r"""cachekit - Caching decorator for Python applications.
 
 A robust, production-ready Python library that provides intelligent caching
-capabilities with advanced features like chunked data handling, multi-serialization
-support, distributed locking, and automatic corruption detection.
+capabilities with advanced features like multi-serialization support,
+distributed locking, and automatic corruption detection.
 
 Supports pluggable backends: Redis (default), CachekitIO SaaS, File, and custom.
 
@@ -68,7 +68,7 @@ Example Usage:
     ```
 """
 
-__version__ = "0.11.1"
+__version__ = "0.14.0"
 
 from collections.abc import Callable
 from typing import Any, TypeVar
@@ -98,6 +98,16 @@ from .health import (
     health_check_handler,
 )
 
+# Interop mode (interop/v1): cross-SDK key generation and value codec.
+# The decorator API is @cache(interop="op", namespace="ns"); these helpers are
+# for manual key/value handling (debugging, out-of-band writers, migrations).
+from .interop import (
+    InteropError,
+    decode_interop_value,
+    encode_interop_value,
+    generate_interop_key,
+)
+
 # L1/L2 architecture integrated into standard cache interface
 # No separate imports needed - cache.minimal/.production/.secure handle L1+L2 transparently
 # Import reliability configuration
@@ -113,9 +123,13 @@ __all__ = [
     "CacheInfo",
     "CircuitBreakerConfig",
     "DecoratorConfig",
+    "decode_interop_value",
+    "encode_interop_value",
+    "generate_interop_key",
     "get_health_checker",
     "health_check_handler",
     "HealthCheckResult",
     "HealthLevel",
     "HealthStatus",
+    "InteropError",
 ]

{cachekit-0.11.1 → cachekit-0.14.0}/src/cachekit/backends/base.py

@@ -119,8 +119,10 @@ class TTLInspectableBackend(Protocol):
     TTL refresh for frequently-accessed keys.
 
     Not all backends support this capability:
-    - Supported: Redis, PostgreSQL, DynamoDB, SQLite, FileSystem
-    - Not supported: HTTP (stateless), Memcached (limited), S3 (limited)
+    - Supported: Redis, CachekitIO, File, PostgreSQL, DynamoDB, SQLite
+    - Not supported: HTTP (stateless), S3 (limited)
+    - Memcached: partial — implements ``refresh_ttl`` (via ``touch``) but NOT ``get_ttl``
+      (no protocol command to read remaining TTL), so it is not a full TTLInspectableBackend.
 
     Example:
         >>> # TTL inspection pattern (async context):

{cachekit-0.11.1 → cachekit-0.14.0}/src/cachekit/backends/cachekitio/backend.py

@@ -34,6 +34,20 @@ _logger = get_structured_logger(__name__)
 # preferring the header. See protocol spec/saas-api.md (DELETE .../lock).
 LOCK_ID_HEADER = "X-CacheKit-Lock-Id"
 
+# Protocol-canonical TTL header (spec/saas-api.md). The legacy X-TTL is sent
+# alongside it until the dual-reading server (saas#245) is deployed everywhere;
+# sending both is value-identical and safe against either server generation.
+# TODO(LAB-381 follow-up): drop X-TTL once saas#245 is live in prod.
+TTL_HEADER = "X-CacheKit-TTL"
+LEGACY_TTL_HEADER = "X-TTL"
+
+# Stale-while-revalidate (LAB-381, spec/saas-api.md#stale-while-revalidate).
+# STALE_TTL_HEADER rides PUTs to open a stale-grace window past the fresh TTL;
+# FRESHNESS_HEADER labels every GET/HEAD 200 as fresh|stale. Pre-SWR servers
+# ignore the former and never emit the latter.
+STALE_TTL_HEADER = "X-CacheKit-Stale-TTL"
+FRESHNESS_HEADER = "X-CacheKit-Freshness"
+
 
 def _inject_metrics_headers(stats: _FunctionStats | None) -> dict[str, str]:
     """Extract cache metrics and format as HTTP headers.
@@ -335,22 +349,62 @@ class CachekitIOBackend:
                     return None
             raise
 
-    def set(self, key: str, value: bytes, ttl: int | None = None) -> None:
+    @staticmethod
+    def _is_stale(response: httpx.Response) -> bool:
+        """Map the X-CacheKit-Freshness header to staleness (spec/saas-api.md).
+
+        Absent header = fresh (pre-SWR server); unrecognized value = stale
+        (revalidation is the conservative action). Tokens are lowercase and
+        case-sensitive per spec.
+        """
+        value = response.headers.get(FRESHNESS_HEADER)
+        return value is not None and value != "fresh"
+
+    def get_with_freshness(self, key: str) -> tuple[bytes, bool] | None:
+        """Retrieve value plus its SWR freshness (sync).
+
+        Returns:
+            ``(value, is_stale)`` on a hit — ``is_stale`` is True only for an
+            entry in its stale-grace window (LAB-381) — or None on a miss.
+
+        Raises:
+            BackendError: If operation fails (network, auth, etc.)
+        """
+        try:
+            response = self._request_sync("GET", key)
+            return response.content, self._is_stale(response)
+        except BackendError as exc:
+            if exc.original_exception and isinstance(exc.original_exception, httpx.HTTPStatusError):
+                if exc.original_exception.response.status_code == 404:
+                    return None
+            raise
+
+    def set(self, key: str, value: bytes, ttl: int | None = None, stale_ttl: int | None = None) -> None:
         """Store value in cache (sync).
 
         Args:
             key: Cache key
             value: Bytes to cache
             ttl: Time-to-live in seconds (optional)
+            stale_ttl: Stale-grace window in seconds past the fresh TTL
+                (LAB-381 SWR). Only honoured alongside an explicit ``ttl``;
+                pre-SWR servers ignore it.
 
         Raises:
             BackendError: If operation fails
         """
-        headers = {}
-        if ttl is not None:
-            headers["X-TTL"] = str(ttl)
+        self._request_sync("PUT", key, content=value, headers=self._set_headers(ttl, stale_ttl))
 
-        self._request_sync("PUT", key, content=value, headers=headers)
+    @staticmethod
+    def _set_headers(ttl: int | None, stale_ttl: int | None) -> dict[str, str]:
+        """PUT timing headers: canonical + legacy TTL (dual-send until saas#245 deploys), stale window."""
+        headers: dict[str, str] = {}
+        if ttl is not None:
+            headers[TTL_HEADER] = str(ttl)
+            headers[LEGACY_TTL_HEADER] = str(ttl)
+        if stale_ttl is not None and stale_ttl > 0 and ttl is not None:
+            headers[STALE_TTL_HEADER] = str(stale_ttl)
+        return headers
 
     def delete(self, key: str) -> bool:
         """Delete key from cache (sync).
@@ -457,22 +511,21 @@ class CachekitIOBackend:
                     return None
             raise
 
-    async def set_async(self, key: str, value: bytes, ttl: int | None = None) -> None:
+    async def set_async(self, key: str, value: bytes, ttl: int | None = None, stale_ttl: int | None = None) -> None:
         """Store value in cache (async).
 
         Args:
             key: Cache key
             value: Bytes to cache
             ttl: Time-to-live in seconds (optional)
+            stale_ttl: Stale-grace window in seconds past the fresh TTL
+                (LAB-381 SWR). Only honoured alongside an explicit ``ttl``;
+                pre-SWR servers ignore it.
 
         Raises:
             BackendError: If operation fails
         """
-        headers = {}
-        if ttl is not None:
-            headers["X-TTL"] = str(ttl)
-
-        await self._request_async("PUT", key, content=value, headers=headers)
+        await self._request_async("PUT", key, content=value, headers=self._set_headers(ttl, stale_ttl))
 
     async def delete_async(self, key: str) -> bool:
         """Delete key from cache (async).

cachekit-0.14.0/src/cachekit/backends/cachekitio/session.py

@@ -0,0 +1,59 @@
+"""Session headers for cachekit.io requests.
+
+Process session identity (UUID + start timestamp, PID-aware) lives in
+:mod:`cachekit.decorators.session` — the single source of truth shared
+with the decorator stats tracker. This module only assembles the SaaS
+HTTP headers from it.
+"""
+
+from __future__ import annotations
+
+import threading
+
+from cachekit.decorators.session import get_session_id, get_session_start_ms
+
+# Thread-local storage for header dict caching
+_thread_local = threading.local()
+
+
+def get_session_headers() -> dict[str, str]:
+    """Get session headers for cachekit.io requests.
+
+    Returns a dictionary containing X-CacheKit-Session-ID and
+    X-CacheKit-Session-Start headers needed for cachekit.io API requests.
+
+    The returned dict is cached in thread-local storage to avoid repeated
+    dictionary allocations and revalidated against the current session ID,
+    so a process restart or fork (PID change) transparently regenerates it.
+    A fresh copy is returned on each call to prevent accidental mutation of
+    cached data while maintaining efficiency.
+
+    Returns:
+        dict[str, str]: Headers dict with keys:
+            - X-CacheKit-Session-ID: Process session UUID
+            - X-CacheKit-Session-Start: Session start milliseconds
+
+    Example:
+        >>> headers = get_session_headers()
+        >>> "X-CacheKit-Session-ID" in headers
+        True
+        >>> "X-CacheKit-Session-Start" in headers
+        True
+        >>> headers["X-CacheKit-Session-Start"].isdigit()
+        True
+    """
+    session_id = get_session_id()
+    cached = getattr(_thread_local, "headers", None)
+    if cached is None or cached["X-CacheKit-Session-ID"] != session_id:
+        _thread_local.headers = {
+            "X-CacheKit-Session-ID": session_id,
+            "X-CacheKit-Session-Start": str(get_session_start_ms()),
+        }
+    return dict(_thread_local.headers)
+
+
+__all__ = [
+    "get_session_id",
+    "get_session_start_ms",
+    "get_session_headers",
+]

{cachekit-0.11.1 → cachekit-0.14.0}/src/cachekit/backends/file/backend.py

@@ -5,6 +5,7 @@ This module implements BaseBackend protocol for filesystem-based caching with:
 - Atomic writes via write-then-rename pattern
 - LRU eviction triggered at 90% capacity, evicting to 70%
 - TTL-based expiration with secure 14-byte header format
+- TTL inspection & refresh (TTLInspectableBackend): get_ttl / refresh_ttl off the header
 - Security features: O_NOFOLLOW, realpath resolution, permission enforcement
 - Blake2b key hashing (16 bytes hex = 32 chars) for filename safety
 """
@@ -571,6 +572,136 @@ class FileBackend:
                 "error": str(exc),
             }
 
+    # ==================== TTLInspectableBackend Protocol ====================
+
+    async def get_ttl(self, key: str) -> int | None:
+        """Remaining TTL in seconds, read from the on-disk expiry header (bytes [6:14]).
+
+        Returns None when the key is missing, permanent (expiry field == 0), or already
+        expired. Expired/corrupt entries are unlinked on read, mirroring ``get``/``exists``.
+
+        The sync file I/O inside an ``async`` signature intentionally matches the Redis
+        provider (async method wrapping a blocking client call); local disk reads are fast
+        and this keeps every backend's TTLInspectableBackend surface uniform.
+        """
+        file_path = self._key_to_path(key)
+
+        with self._lock:
+            try:
+                fd = os.open(file_path, os.O_RDONLY | os.O_NOFOLLOW)
+                fd_closed = False
+                try:
+                    self._acquire_file_lock(fd, exclusive=False)
+                    try:
+                        header = os.read(fd, HEADER_SIZE)
+                        if len(header) < HEADER_SIZE or header[0:2] != MAGIC or header[2] != FORMAT_VERSION:
+                            os.close(fd)
+                            fd_closed = True
+                            self._safe_unlink(file_path)
+                            return None
+
+                        expiry_timestamp = struct.unpack(">Q", header[6:14])[0]  # uint64 BE
+                        if expiry_timestamp == 0:
+                            return None  # permanent, no TTL to report
+
+                        remaining = expiry_timestamp - time.time()
+                        if remaining <= 0:
+                            # Expired: unlink and report absent (same as get/exists).
+                            os.close(fd)
+                            fd_closed = True
+                            self._safe_unlink(file_path)
+                            return None
+                        return int(remaining)  # whole-second granularity, matching Redis TTL
+                    finally:
+                        self._release_file_lock(fd)
+                finally:
+                    if not fd_closed:
+                        os.close(fd)
+
+            except FileNotFoundError:
+                return None
+            except OSError as exc:
+                if exc.errno in (errno.ENOENT, errno.ELOOP):
+                    return None  # missing, or symlink rejected by O_NOFOLLOW
+                raise BackendError(
+                    f"Failed to read cache file TTL: {exc}",
+                    error_type=self._classify_os_error(exc, is_directory=False),
+                    original_exception=exc,
+                    operation="get_ttl",
+                    key=key,
+                ) from exc
+
+    async def refresh_ttl(self, key: str, ttl: int) -> bool:
+        """Slide a key's expiry by rewriting the 8-byte timestamp field in place.
+
+        Returns True if the key existed and was refreshed, False if it is missing or already
+        expired (an expired entry is treated as absent and unlinked, mirroring ``get``). A
+        ``ttl`` of 0 makes the entry permanent, matching ``set``. No on-disk format change:
+        only bytes [6:14] are rewritten, so the payload and all other header fields are
+        untouched (and cross-SDK File readers stay compatible).
+        """
+        # Same TTL bounds as set() (security: prevent integer overflow/underflow).
+        if ttl == 0:
+            new_expiry = 0
+        elif ttl < 0 or ttl > MAX_TTL_SECONDS:
+            raise BackendError(
+                f"TTL {ttl} out of range [0, {MAX_TTL_SECONDS}] (max 10 years)",
+                BackendErrorType.PERMANENT,
+            )
+        else:
+            new_expiry = int(time.time() + ttl)
+
+        file_path = self._key_to_path(key)
+
+        with self._lock:
+            try:
+                fd = os.open(file_path, os.O_RDWR | os.O_NOFOLLOW)
+                fd_closed = False
+                try:
+                    self._acquire_file_lock(fd, exclusive=True)
+                    try:
+                        header = os.read(fd, HEADER_SIZE)
+                        if len(header) < HEADER_SIZE or header[0:2] != MAGIC or header[2] != FORMAT_VERSION:
+                            os.close(fd)
+                            fd_closed = True
+                            self._safe_unlink(file_path)
+                            return False
+
+                        current_expiry = struct.unpack(">Q", header[6:14])[0]
+                        if current_expiry > 0 and time.time() > current_expiry:
+                            # Already expired: treat as absent (mirror get/exists) and unlink.
+                            os.close(fd)
+                            fd_closed = True
+                            self._safe_unlink(file_path)
+                            return False
+
+                        # Overwrite ONLY the expiry field. ponytail: an 8-byte in-place write to
+                        # a fixed offset is atomic enough for a cache timestamp — a torn write on
+                        # power loss yields a wrong expiry, never a corrupt payload (magic/version
+                        # are untouched), so the entry just expires early/late. No rewrite-rename.
+                        os.lseek(fd, 6, os.SEEK_SET)
+                        os.write(fd, struct.pack(">Q", new_expiry))
+                        os.fsync(fd)
+                        return True
+                    finally:
+                        self._release_file_lock(fd)
+                finally:
+                    if not fd_closed:
+                        os.close(fd)
+
+            except FileNotFoundError:
+                return False
+            except OSError as exc:
+                if exc.errno in (errno.ENOENT, errno.ELOOP):
+                    return False  # missing, or symlink rejected by O_NOFOLLOW
+                raise BackendError(
+                    f"Failed to refresh cache file TTL: {exc}",
+                    error_type=self._classify_os_error(exc, is_directory=False),
+                    original_exception=exc,
+                    operation="refresh_ttl",
+                    key=key,
+                ) from exc
+
     # Private helper methods
 
     def _key_to_path(self, key: str) -> str: