cachekit 0.16.0__tar.gz → 0.17.0__tar.gz

{cachekit-0.16.0 → cachekit-0.17.0}/Cargo.lock

@@ -245,9 +245,9 @@ checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "cachekit-core"
-version = "0.3.0"
+version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ee6235f73aefb0dc66b9cd0d333b9da928c8192e4234357a739fe756c2f8f23"
+checksum = "6aba1513135a7b92a124ad6983f7e80e5f5c78c4f9c74384079efa3fbf491eab"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -271,7 +271,7 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.16.0"
+version = "0.17.0"
 dependencies = [
  "cachekit-core",
  "criterion",

{cachekit-0.16.0 → cachekit-0.17.0}/PKG-INFO

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

{cachekit-0.16.0 → cachekit-0.17.0}/pyproject.toml

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

{cachekit-0.16.0 → cachekit-0.17.0}/rust/Cargo.toml

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

{cachekit-0.16.0 → cachekit-0.17.0}/src/cachekit/__init__.py

@@ -67,7 +67,7 @@ Example Usage:
     ```
 """
 
-__version__ = "0.16.0"
+__version__ = "0.17.0"
 
 from collections.abc import Callable
 from typing import Any, TypeVar

{cachekit-0.16.0 → cachekit-0.17.0}/src/cachekit/backends/base.py

@@ -4,13 +4,14 @@ This module defines the storage backend contract using PEP 544 protocol-based ab
 All L2 backends (Redis, HTTP, etc.) must implement BaseBackend protocol.
 
 Optional capability protocols (TTLInspectableBackend, LockableBackend,
-TimeoutConfigurableBackend) enable advanced features with graceful degradation.
+TimeoutConfigurableBackend, BufferReadableBackend, BufferWritableBackend)
+enable advanced features with graceful degradation.
 """
 
 from __future__ import annotations
 
-from collections.abc import AsyncIterator
-from typing import Any, Optional, Protocol, runtime_checkable
+from collections.abc import AsyncIterator, Callable
+from typing import Any, BinaryIO, Optional, Protocol, runtime_checkable
 
 # Re-export BackendError for convenience (public API)
 from cachekit.backends.errors import BackendError  # noqa: F401
@@ -212,6 +213,53 @@ class BufferReadableBackend(Protocol):
         ...
 
 
+@runtime_checkable
+class BufferWritableBackend(Protocol):
+    """Optional protocol for backends that can accept a value written incrementally through a
+    seekable sink, instead of one materialized ``bytes`` blob (LAB-766, write-side twin of
+    ``BufferReadableBackend``).
+
+    Lets large values (e.g. multi-GB Arrow IPC) reach storage without the whole serialized
+    payload ever existing in memory. Only the File backend implements this today; backends that
+    don't are simply written via ``set`` as usual (the caller falls back transparently).
+
+    Why a writer callback and not an ``Iterable[bytes]``: the Arrow envelope stores an
+    xxHash3-64 checksum BEFORE the payload it covers, so the producer must patch bytes it has
+    already emitted once the stream is complete. A forward-only chunk iterator cannot express
+    that without serializing twice; a seekable sink can. This deliberately scopes the protocol
+    to random-access backends (File) — a forward-only transport (chunked HTTP upload) needs a
+    different contract and is out of scope until a backend demands it.
+
+    Contract:
+    - ``write_payload`` receives a writable, seekable binary sink positioned at the START of
+      the payload region. Producers MUST anchor seeks with ``tell()`` (never absolute offset 0):
+      backends may keep private framing before the payload.
+    - The value becomes visible under ``key`` only if ``write_payload`` returns successfully;
+      on any exception the backend discards the partial write, leaves any previous value for
+      the key intact, and re-raises the producer's exception unwrapped (so serialization errors
+      keep their type for the caller's error handling).
+    - ``ttl`` semantics are identical to ``set``.
+    - A successful ``set_streaming(key, w, ttl)`` is observably identical to
+      ``set(key, full_bytes, ttl)`` for the same payload bytes — same readback via
+      ``get``/``get_buffer``, same expiry, same size-limit enforcement (violations raise
+      ``BackendError`` and nothing is stored).
+    """
+
+    def set_streaming(self, key: str, write_payload: Callable[[BinaryIO], None], ttl: Optional[int] = None) -> None:
+        """Store the payload produced by ``write_payload`` under ``key``, never holding it whole.
+
+        Args:
+            key: Cache key to store
+            write_payload: Callable that writes the complete payload to the provided sink
+            ttl: Time-to-live in seconds (None = no expiry), same semantics as ``set``
+
+        Raises:
+            BackendError: If the backend operation fails (I/O, size limits, TTL bounds)
+            Exception: Whatever ``write_payload`` raises, unwrapped (partial write discarded)
+        """
+        ...
+
+
 @runtime_checkable
 class LockableBackend(Protocol):
     """Optional protocol for backends supporting distributed locking.

{cachekit-0.16.0 → cachekit-0.17.0}/src/cachekit/backends/file/backend.py

@@ -20,8 +20,9 @@ import platform
 import struct
 import threading
 import time
+from collections.abc import Callable
 from pathlib import Path
-from typing import Any
+from typing import Any, BinaryIO
 
 from cachekit.backends.errors import BackendError, BackendErrorType
 
@@ -330,29 +331,8 @@ class FileBackend:
 
         file_path = self._key_to_path(key)
 
-        # Calculate expiry timestamp (0 = never expire)
-        if ttl is None or ttl == 0:
-            expiry_timestamp = 0
-        else:
-            # Validate TTL bounds (security: prevent integer overflow/underflow)
-            if ttl < 0 or ttl > MAX_TTL_SECONDS:
-                raise BackendError(
-                    f"TTL {ttl} out of range [0, {MAX_TTL_SECONDS}] (max 10 years)",
-                    BackendErrorType.PERMANENT,
-                )
-            expiry_timestamp = int(time.time() + ttl)
-
-        # Build header (14 bytes)
-        header = (
-            MAGIC  # [0:2] Magic bytes
-            + bytes([FORMAT_VERSION])  # [2:3] Version
-            + bytes([RESERVED])  # [3:4] Reserved
-            + struct.pack(">H", 0)  # [4:6] Flags (no compression/encryption yet)
-            + struct.pack(">Q", expiry_timestamp)  # [6:14] Expiry timestamp
-        )
-
-        # Combine header + payload
-        file_data = header + value
+        # Combine header (14 bytes) + payload
+        file_data = self._build_header(self._expiry_from_ttl(ttl)) + value
 
         # Generate temp file name
         temp_path = self._generate_temp_path(file_path)
@@ -360,15 +340,7 @@ class FileBackend:
         with self._lock:
             try:
                 # Check entry count BEFORE write (security: prevent file persisting on error)
-                # Allow overwrites (existing key doesn't increase count)
-                if self.config.max_entry_count > 0:
-                    _, entry_count = self._calculate_cache_size()
-                    # Only check if this is a NEW entry (not overwriting existing)
-                    if not os.path.exists(file_path) and entry_count >= self.config.max_entry_count:
-                        raise BackendError(
-                            f"Entry count {entry_count} would exceed max_entry_count ({self.config.max_entry_count})",
-                            BackendErrorType.PERMANENT,
-                        )
+                self._check_entry_capacity(file_path)
 
                 # Write to temp file with O_NOFOLLOW for security
                 fd = os.open(
@@ -410,6 +382,105 @@ class FileBackend:
                     key=key,
                 ) from exc
 
+    def set_streaming(self, key: str, write_payload: Callable[[BinaryIO], None], ttl: int | None = None) -> None:
+        """Store a streamed value with the same atomicity, locking, and limits as ``set`` (LAB-766).
+
+        ``write_payload`` receives a writable, seekable buffered binary file positioned at the
+        start of the payload region (just past this backend's 14-byte header) and must write the
+        complete payload — record batch by record batch, so the full value never exists in
+        memory. The temp-file + atomic-rename pattern from ``set`` is preserved: a failed stream
+        never leaves a partial value visible under ``key``, and any previous value for the key
+        survives. Producer exceptions propagate unwrapped (after the temp file is discarded) so
+        serialization errors keep their type for the caller.
+
+        ``max_value_mb`` is enforced AFTER the stream completes (``fstat`` on the temp file,
+        before the rename): a streaming write cannot know its size upfront. The caller-side byte
+        budget (CACHEKIT_MAX_VALUE_SIZE, enforced incrementally by the serializer) bounds the
+        transient disk usage of an over-limit attempt.
+
+        Args:
+            key: Cache key to store
+            write_payload: Callable that writes the complete payload to the provided file
+            ttl: Time-to-live in seconds (None or 0 = never expire), same semantics as ``set``
+
+        Raises:
+            BackendError: If the write fails (disk full, permissions, size/TTL limits, etc.)
+        """
+        header = self._build_header(self._expiry_from_ttl(ttl))
+        file_path = self._key_to_path(key)
+        temp_path = self._generate_temp_path(file_path)
+
+        committed = False
+        try:
+            # Check entry count BEFORE write (security: prevent file persisting on error)
+            with self._lock:
+                self._check_entry_capacity(file_path)
+
+            # Stream OUTSIDE self._lock: unlike set()'s bounded os.write, the producer runs
+            # the whole serialization here (minutes for multi-GB frames), and holding the
+            # process-wide lock would block every other FileBackend op for that window. The
+            # in-process lock isn't what makes this safe anyway — the temp path is unique
+            # per pid+ns, the flock gives cross-process exclusion, and the rename commit
+            # below is atomic. Write to temp file with O_NOFOLLOW for security.
+            fd = os.open(
+                temp_path,
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                self.config.permissions,
+            )
+            f: BinaryIO | None = None
+            try:
+                # Acquire exclusive write lock
+                self._acquire_file_lock(fd, exclusive=True)
+                try:
+                    f = os.fdopen(fd, "wb")  # buffered writer; takes ownership of fd
+                    f.write(header)
+                    write_payload(f)
+                    f.flush()
+
+                    # Enforce max_value_mb on the real on-disk size (fstat, not tell():
+                    # the producer may have seeked back to patch bytes it already wrote).
+                    payload_size = os.fstat(fd).st_size - HEADER_SIZE
+                    max_bytes = self.config.max_value_mb * 1024 * 1024
+                    if payload_size > max_bytes:
+                        raise BackendError(
+                            f"Value size {payload_size} exceeds max_value_mb ({self.config.max_value_mb}MB)",
+                            BackendErrorType.PERMANENT,
+                        )
+
+                    # fsync to ensure data is on disk
+                    os.fsync(fd)
+                finally:
+                    self._release_file_lock(fd)
+            finally:
+                if f is not None:
+                    f.close()
+                else:
+                    os.close(fd)
+
+            # Commit under the process lock: atomic rename + eviction bookkeeping only.
+            with self._lock:
+                os.rename(temp_path, file_path)
+                committed = True
+
+                # Trigger eviction if over threshold
+                self._maybe_evict()
+
+        except OSError as exc:
+            raise BackendError(
+                f"Failed to write cache file: {exc}",
+                error_type=self._classify_os_error(exc, is_directory=False),
+                original_exception=exc,
+                operation="set_streaming",
+                key=key,
+            ) from exc
+        finally:
+            # Any failure — backend I/O, size limit, or a producer exception (which
+            # propagates unwrapped per the BufferWritableBackend contract, so callers keep
+            # its type and log it once) — discards the partial write. finally (not a
+            # BaseException catch) so even KeyboardInterrupt can't leak a temp file.
+            if not committed:
+                self._safe_unlink(temp_path)
+
     def delete(self, key: str) -> bool:
         """Delete key from file storage.
 
@@ -640,16 +711,8 @@ class FileBackend:
         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)
+        # Same TTL bounds as set()/set_streaming (security: prevent integer overflow/underflow).
+        new_expiry = self._expiry_from_ttl(ttl)
 
         file_path = self._key_to_path(key)
 
@@ -704,6 +767,50 @@ class FileBackend:
 
     # Private helper methods
 
+    @staticmethod
+    def _expiry_from_ttl(ttl: int | None) -> int:
+        """Expiry timestamp for a TTL (0 = never expire), with TTL bounds validation.
+
+        Raises:
+            BackendError: If TTL is negative or exceeds MAX_TTL_SECONDS (security:
+                prevent integer overflow/underflow in the packed uint64 timestamp)
+        """
+        if ttl is None or ttl == 0:
+            return 0
+        if ttl < 0 or ttl > MAX_TTL_SECONDS:
+            raise BackendError(
+                f"TTL {ttl} out of range [0, {MAX_TTL_SECONDS}] (max 10 years)",
+                BackendErrorType.PERMANENT,
+            )
+        return int(time.time() + ttl)
+
+    @staticmethod
+    def _build_header(expiry_timestamp: int) -> bytes:
+        """Build the 14-byte on-disk entry header."""
+        return (
+            MAGIC  # [0:2] Magic bytes
+            + bytes([FORMAT_VERSION])  # [2:3] Version
+            + bytes([RESERVED])  # [3:4] Reserved
+            + struct.pack(">H", 0)  # [4:6] Flags (no compression/encryption yet)
+            + struct.pack(">Q", expiry_timestamp)  # [6:14] Expiry timestamp
+        )
+
+    def _check_entry_capacity(self, file_path: str) -> None:
+        """Reject a NEW entry when max_entry_count is reached (overwrites always pass).
+
+        Raises:
+            BackendError: If storing a new entry would exceed max_entry_count
+        """
+        if self.config.max_entry_count <= 0:
+            return
+        _, entry_count = self._calculate_cache_size()
+        # Only check if this is a NEW entry (not overwriting existing)
+        if not os.path.exists(file_path) and entry_count >= self.config.max_entry_count:
+            raise BackendError(
+                f"Entry count {entry_count} would exceed max_entry_count ({self.config.max_entry_count})",
+                BackendErrorType.PERMANENT,
+            )
+
     def _key_to_path(self, key: str) -> str:
         """Convert cache key to file path using blake2b hash.
 

{cachekit-0.16.0 → cachekit-0.17.0}/src/cachekit/cache_handler.py

@@ -11,9 +11,16 @@ import hashlib
 import threading
 import warnings
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any, Optional, Protocol, TypeGuard, Union, runtime_checkable
-
-from cachekit.backends.base import BackendError, BaseBackend, BufferHandle, BufferReadableBackend, TTLInspectableBackend
+from typing import TYPE_CHECKING, Any, BinaryIO, Optional, Protocol, TypeGuard, Union, runtime_checkable
+
+from cachekit.backends.base import (
+    BackendError,
+    BaseBackend,
+    BufferHandle,
+    BufferReadableBackend,
+    BufferWritableBackend,
+    TTLInspectableBackend,
+)
 from cachekit.backends.provider import (
     BackendProviderInterface,
     DefaultBackendProvider,
@@ -221,6 +228,15 @@ def supports_buffer_read(backend: BaseBackend) -> TypeGuard[BufferReadableBacken
     return hasattr(backend, "get_buffer")
 
 
+def supports_streaming_write(backend: BaseBackend) -> TypeGuard[BufferWritableBackend]:
+    """Type guard: backend can accept an incrementally-streamed value via set_streaming (LAB-766, File only).
+
+    Returns:
+        True if backend implements BufferWritableBackend (used for the streaming Arrow write path).
+    """
+    return hasattr(backend, "set_streaming")
+
+
 class SWRCapableBackend(Protocol):
     """Backend with server-signaled stale-while-revalidate reads (LAB-381).
 
@@ -932,6 +948,54 @@ class CacheSerializationHandler:
             and getattr(self._base_serializer, "return_format", None) == "pandas"
         )
 
+    def supports_streaming_write(self) -> bool:
+        """True iff writes can stream the envelope to a capable backend (LAB-766).
+
+        Eligible only for PLAINTEXT Arrow:
+        - encrypted values can never stream (AES-256-GCM emits its auth tag only after the
+          whole ciphertext exists, so the secure path stays on buffered ``set(bytes)``);
+        - interop/v1 stores raw documents with no CK envelope (different serializer, no benefit);
+        - non-Arrow serializers materialize their output in one shot anyway.
+
+        The backend must also support streaming writes (File only today); that is checked
+        separately at the cache-handler layer, so True here on a non-streaming backend simply
+        means the write falls back to the buffered path.
+        """
+        return not self.encryption and not self.interop_mode and self._serializer_string_name == "arrow"
+
+    def write_serialized_to(self, sink: BinaryIO, data: Any) -> None:
+        """Streaming twin of :meth:`serialize_data` (LAB-766): write the SAME envelope bytes into
+        ``sink`` without ever materializing the payload in memory.
+
+        Only valid when :meth:`supports_streaming_write` is True (plaintext Arrow — no
+        encryption wrapper, so no tenant extraction / AAD / cache_key binding applies). The
+        envelope is byte-identical to a buffered ``serialize_data`` of the same value: frame
+        prefix first (metadata is deterministic per serializer config), then the Arrow
+        serializer streams ``[checksum][IPC record batches]`` directly into the sink.
+
+        The L2 oversized-entry ceiling (``max_value_size``, issue #163) is enforced
+        incrementally mid-stream instead of on the finished blob — same limit, same ValueError,
+        but an over-limit stream aborts early instead of materializing first.
+
+        Raises:
+            TypeError: If data is not a DataFrame or dict of arrays
+            ValueError: If the envelope would exceed max_value_size
+            SerializationError: If Arrow serialization fails
+        """
+        from cachekit.serializers.arrow_serializer import ArrowSerializer  # already loaded on the arrow path
+
+        serializer = self._base_serializer
+        if not isinstance(serializer, ArrowSerializer):
+            # supports_streaming_write() gates callers to the arrow serializer; anything else
+            # here is a caller bug — fail loud rather than stream a wrong envelope.
+            raise SerializationError(f"write_serialized_to requires the arrow serializer, got {type(serializer).__name__}")
+
+        metadata = serializer.serialization_metadata()
+        prefix = SerializationWrapper.wrap_prefix(metadata.to_dict(), self._serializer_string_name)
+        sink.write(prefix)
+        budget = get_settings().max_value_size - len(prefix)
+        serializer.serialize_to_sink(data, sink, max_bytes=budget)
+
     def deserialize_data(self, data: str | bytes | memoryview, cache_key: str = "") -> Any:
         """Deserialize data from cache storage with cache_key verification.
 
@@ -1413,7 +1477,11 @@ class CacheOperationHandler:
             kwargs: Function kwargs (for tenant extraction in encryption)
 
         Returns:
-            Serialized bytes (for L1 cache storage), or None if serialization failed
+            Serialized bytes when the buffered path stored the value (eligible for L1
+            backfill), or None when there is nothing for L1: the value was STREAMED to the
+            backend (success — L1 intentionally skipped, LAB-766), the streaming attempt
+            failed (logged, never retried buffered), or serialization failed. None is NOT
+            a failure signal.
 
         Note:
             Requires cache_handler to be set via set_cache_handler() before calling.
@@ -1423,6 +1491,28 @@ class CacheOperationHandler:
             if self._cache_handler is None:
                 raise RuntimeError("Cache handler must be set before calling store_result")
 
+            # Streaming write fast path (LAB-766): plaintext Arrow to a streaming-writable
+            # backend (File) writes the envelope without ever materializing it. SWR
+            # (stale_ttl) stays buffered — no streaming backend signals freshness today.
+            # getattr guards custom CacheHandlerStrategy impls that predate set_streaming.
+            if stale_ttl is None and self.serialization_handler.supports_streaming_write():
+                set_streaming = getattr(self._cache_handler, "set_streaming", None)
+                if set_streaming is not None:
+                    streamed = set_streaming(
+                        cache_key,
+                        lambda sink: self.serialization_handler.write_serialized_to(sink, result),
+                        ttl,
+                    )
+                    if streamed is not None:
+                        # Streamed (True) or attempt failed and was logged (False — do NOT
+                        # retry buffered: that re-materializes the payload this path exists
+                        # to avoid). Either way return None: a multi-GB envelope must never
+                        # be copied into L1 (mirrors the mmap read path's L1 exclusion, #171).
+                        if streamed:
+                            get_logger().cache_stored(cache_key, ttl)
+                        return None
+                    # None: backend can't stream — fall through to the buffered path.
+
             # Pass cache_key for AAD binding (required for encrypted data)
             serialized_data = self.serialization_handler.serialize_data(result, args, kwargs, cache_key)
             # Only thread the SWR kwarg when set: strategy implementations without
@@ -1461,7 +1551,11 @@ class CacheOperationHandler:
             kwargs: Function kwargs (for tenant extraction in encryption)
 
         Returns:
-            Serialized bytes (for L1 cache storage), or None if serialization failed
+            Serialized bytes when the buffered path stored the value (eligible for L1
+            backfill), or None when there is nothing for L1: the value was STREAMED to the
+            backend (success — L1 intentionally skipped, LAB-766), the streaming attempt
+            failed (logged, never retried buffered), or serialization failed. None is NOT
+            a failure signal.
 
         Note:
             Requires cache_handler to be set via set_cache_handler() before calling.
@@ -1471,6 +1565,25 @@ class CacheOperationHandler:
             if self._cache_handler is None:
                 raise RuntimeError("Cache handler must be set before calling store_result_async")
 
+            # Streaming write fast path (LAB-766) — async twin of store_result's gate. The
+            # whole stream (pyarrow serialization included) runs in the handler's thread
+            # pool, which also moves the blocking serialize OFF the event loop (the buffered
+            # path below serializes on the loop thread).
+            if self.serialization_handler.supports_streaming_write():
+                set_streaming_async = getattr(self._cache_handler, "set_streaming_async", None)
+                if set_streaming_async is not None:
+                    streamed = await set_streaming_async(
+                        cache_key,
+                        lambda sink: self.serialization_handler.write_serialized_to(sink, result),
+                        ttl,
+                    )
+                    if streamed is not None:
+                        # See store_result: never retry buffered on failure, never hand the
+                        # envelope to L1 on success.
+                        if streamed:
+                            get_logger().cache_stored(cache_key, ttl)
+                        return None
+
             # Pass cache_key for AAD binding (required for encrypted data)
             serialized_data = self.serialization_handler.serialize_data(result, args, kwargs, cache_key)
             await self._cache_handler.set_async(cache_key, serialized_data, ttl)
@@ -1607,6 +1720,16 @@ class CacheHandlerStrategy(Protocol):
         """Set value in cache with TTL and optional metadata."""
         ...
 
+    def set_streaming(self, key: str, write_payload: Callable[[BinaryIO], None], ttl: Optional[int] = None) -> Optional[bool]:
+        """Stream a value to a streaming-writable backend (LAB-766); None when unsupported."""
+        ...
+
+    async def set_streaming_async(
+        self, key: str, write_payload: Callable[[BinaryIO], None], ttl: Optional[int] = None
+    ) -> Optional[bool]:
+        """Async variant of set_streaming."""
+        ...
+
     def delete(self, key: str) -> bool:
         """Delete key from cache."""
         ...
@@ -1860,6 +1983,47 @@ class StandardCacheHandler:
             get_logger().error(f"Unexpected error setting key {key}: {e}")
             return False
 
+    def set_streaming(self, key: str, write_payload: Callable[[BinaryIO], None], ttl: Optional[int] = None) -> Optional[bool]:
+        """Stream a value to a streaming-writable backend (LAB-766).
+
+        Returns:
+            None when the backend doesn't implement BufferWritableBackend — the caller falls
+            back to the buffered ``set``. True on success. False when the streaming attempt
+            failed (logged, mirroring ``set``'s degradation contract); the caller must NOT
+            retry with the buffered path — that would re-materialize the very payload this
+            path exists to keep out of memory.
+        """
+        if not supports_streaming_write(self.backend):
+            return None
+        try:
+            self._with_backpressure_and_timeout(self.backend.set_streaming, key, write_payload, ttl)
+            return True
+        except BackendError as e:
+            get_logger().error(f"Backend error streaming key {redact_cache_key(key)}: {e}")
+            return False
+        except Exception as e:
+            # Producer-side failure (serialization error, max_value_size budget): the backend
+            # already discarded its partial write; surface the real cause, not a backend error.
+            get_logger().error(f"Streaming serialization failed for key {redact_cache_key(key)}: {e}")
+            return False
+
+    async def set_streaming_async(
+        self, key: str, write_payload: Callable[[BinaryIO], None], ttl: Optional[int] = None
+    ) -> Optional[bool]:
+        """Async variant of :meth:`set_streaming`: the whole stream — pyarrow serialization
+        included — runs in the thread pool, keeping blocking IPC writes off the event loop."""
+        if not supports_streaming_write(self.backend):
+            return None
+        try:
+            await self._with_backpressure_and_timeout_async(self.backend.set_streaming, key, write_payload, ttl)
+            return True
+        except BackendError as e:
+            get_logger().error(f"Backend error streaming key {redact_cache_key(key)}: {e}")
+            return False
+        except Exception as e:
+            get_logger().error(f"Streaming serialization failed for key {redact_cache_key(key)}: {e}")
+            return False
+
     def delete(self, key: str) -> bool:
         """Delete key from cache using backend.
 

{cachekit-0.16.0 → cachekit-0.17.0}/src/cachekit/config/settings.py

@@ -105,7 +105,9 @@ class CachekitConfig(BaseSettings):
             "'zstd'/'lz4' shrink the stored payload but must be decompressed into the heap on read. "
             "'none' stores uncompressed Arrow IPC, which lets the File backend serve plaintext "
             "DataFrame reads via a zero-copy mmap (low steady-state read RSS; peak transiently "
-            "higher) at the cost of a larger payload. Env: CACHEKIT_ARROW_COMPRESSION."
+            "higher) at the cost of a larger payload. Writes are codec-independent: plaintext "
+            "Arrow streams to the File backend without materializing the payload (encrypted "
+            "values stay buffered). Env: CACHEKIT_ARROW_COMPRESSION."
         ),
     )
     retry_on_timeout: bool = Field(