cachekit 0.10.0__tar.gz → 0.10.1__tar.gz

{cachekit-0.10.0 → cachekit-0.10.1}/Cargo.lock

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

{cachekit-0.10.0 → cachekit-0.10.1}/PKG-INFO

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

{cachekit-0.10.0 → cachekit-0.10.1}/pyproject.toml

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

{cachekit-0.10.0 → cachekit-0.10.1}/rust/Cargo.toml

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

{cachekit-0.10.0 → cachekit-0.10.1}/src/cachekit/__init__.py

@@ -68,7 +68,7 @@ Example Usage:
     ```
 """
 
-__version__ = "0.10.0"
+__version__ = "0.10.1"
 
 from collections.abc import Callable
 from typing import Any, TypeVar

{cachekit-0.10.0 → cachekit-0.10.1}/src/cachekit/cache_handler.py

@@ -32,6 +32,11 @@ if TYPE_CHECKING:
 # Python-specific type tags that no other-language SDK can decode.
 CROSS_SDK_SERIALIZER_NAMES = ("default", "std", "standard", "orjson", "arrow")
 
+# Serializer-name aliases collapsed to one canonical frame tag so interchangeable names stay
+# cache-compatible: an entry written as 'auto' must read back under 'pythonic' (its documented
+# alias) and vice-versa, instead of a serializer-mismatch that recomputes on every read (#167).
+_SERIALIZER_NAME_ALIASES = {"std": "default", "standard": "default", "pythonic": "auto"}
+
 # Global DI container instance with default registrations
 container = DIContainer()
 container.register(LoggerProvider, DefaultLoggerProvider)
@@ -348,7 +353,7 @@ class CacheSerializationHandler:
         # Extract string name for metadata storage (for protocol instances, use class name)
         if isinstance(serializer_name, str):
             # Canonicalize aliases to prevent envelope mismatch on deserialize
-            self._serializer_string_name = "default" if serializer_name in ("std", "standard") else serializer_name
+            self._serializer_string_name = _SERIALIZER_NAME_ALIASES.get(serializer_name, serializer_name)
         else:
             # Protocol instance - use class name for metadata
             self._serializer_string_name = type(serializer_name).__name__

{cachekit-0.10.0 → cachekit-0.10.1}/src/cachekit/serializers/auto_serializer.py

@@ -26,6 +26,7 @@ from typing import TYPE_CHECKING, Any, ClassVar, Optional
 from uuid import UUID
 
 import msgpack
+import xxhash
 
 if TYPE_CHECKING:
     import numpy as np
@@ -295,7 +296,8 @@ def _auto_object_hook(obj: Any) -> Any:
                 raise SerializationError("Cannot deserialize numpy array: numpy is not installed")
             if "data" not in obj or "shape" not in obj or "dtype" not in obj:
                 raise SerializationError("Invalid ndarray format: missing required fields in cached data")
-            return np.frombuffer(obj["data"], dtype=obj["dtype"]).reshape(obj["shape"])
+            # .copy(): writable result that does not alias the source buffer (the L1-cached bytes on a hit) — #157.
+            return np.frombuffer(obj["data"], dtype=obj["dtype"]).reshape(obj["shape"]).copy()
 
     return obj
 
@@ -492,15 +494,19 @@ class AutoSerializer:
         """
         # coerce unwrap's zero-copy memoryview; no-op when already bytes (enables .startswith below + Rust retrieve)
         data = bytes(data)
-        # Check for custom NumPy format
-        if data.startswith(b"NUMPY_RAW"):
+        # Custom NumPy format — raw [NUMPY_RAW...] or checksummed [8-byte xxHash3-64][NUMPY_RAW...].
+        # Detect by structure (like ArrowSerializer) so it is caught here, before the lossy
+        # retrieve()/msgpack fallback below — _deserialize_numpy strips + verifies the optional
+        # checksum and fails closed on mismatch (#155), even when no metadata is supplied.
+        if data.startswith(b"NUMPY_RAW") or (len(data) >= 17 and data[8:17] == b"NUMPY_RAW"):
             return self._deserialize_numpy(data)
 
         # Use metadata for format detection if available
         if metadata and hasattr(metadata, "original_type"):
             detected_format = metadata.original_type
 
-            # For specialized formats, call type-specific deserializers
+            # For specialized formats, call type-specific deserializers.
+            # _deserialize_numpy strips + verifies the optional xxHash3-64 checksum prefix itself.
             if detected_format == "numpy":
                 return self._deserialize_numpy(data)
             elif detected_format == "arrow":
@@ -513,31 +519,31 @@ class AutoSerializer:
                         "Install with: pip install 'cachekit[data]'"
                     )
             elif detected_format == "dataframe":
-                # For DataFrame and Series, we need to handle both Rust envelope and direct data
                 if self.enable_integrity_checking and len(data) > 4:
+                    # Unwrap the ByteStorage envelope. A checksum mismatch (raised by retrieve) fails
+                    # closed with a clear corruption error instead of being swallowed and re-parsed as
+                    # raw msgpack, which lost the diagnostic and produced a confusing error (#156).
+                    # The unpack/build sits OUTSIDE this guard so a genuine post-retrieve error surfaces
+                    # as itself rather than being mistaken for corruption.
                     try:
-                        # Try Rust envelope first
                         original_data, _ = self._byte_storage.retrieve(data)
-                        unpacked_data = msgpack.unpackb(original_data, **self._msgpack_unpack_opts)
-                        return self._deserialize_dataframe(unpacked_data)
-                    except Exception as e:
-                        # Fall back to direct unpacking
-                        logger.debug(f"Rust envelope parsing failed for DataFrame, falling back to direct unpacking: {e}")
-                # Direct msgpack data
+                    except (ValueError, SerializationError) as e:
+                        raise SerializationError(f"DataFrame integrity check failed (corrupted cache entry): {e}") from e
+                    unpacked_data = msgpack.unpackb(original_data, **self._msgpack_unpack_opts)
+                    return self._deserialize_dataframe(unpacked_data)
+                # Integrity off: data is direct msgpack (no envelope)
                 unpacked_data = msgpack.unpackb(data, **self._msgpack_unpack_opts)
                 return self._deserialize_dataframe(unpacked_data)
             elif detected_format == "series":
-                # For DataFrame and Series, we need to handle both Rust envelope and direct data
                 if self.enable_integrity_checking and len(data) > 4:
+                    # Same fail-closed contract as the DataFrame branch above (#156).
                     try:
-                        # Try Rust envelope first
                         original_data, _ = self._byte_storage.retrieve(data)
-                        unpacked_data = msgpack.unpackb(original_data, **self._msgpack_unpack_opts)
-                        return self._deserialize_series(unpacked_data)
-                    except Exception as e:
-                        # Fall back to direct unpacking
-                        logger.debug(f"Rust envelope parsing failed for Series, falling back to direct unpacking: {e}")
-                # Direct msgpack data
+                    except (ValueError, SerializationError) as e:
+                        raise SerializationError(f"Series integrity check failed (corrupted cache entry): {e}") from e
+                    unpacked_data = msgpack.unpackb(original_data, **self._msgpack_unpack_opts)
+                    return self._deserialize_series(unpacked_data)
+                # Integrity off: data is direct msgpack (no envelope)
                 unpacked_data = msgpack.unpackb(data, **self._msgpack_unpack_opts)
                 return self._deserialize_series(unpacked_data)
 
@@ -603,17 +609,20 @@ class AutoSerializer:
             return self._deserialize_numpy(data)
 
     def _serialize_numpy(self, arr: np.ndarray) -> bytes:  # type: ignore[name-defined]
-        """Serialize NumPy array with metadata, bypassing Rust ByteStorage.
+        """Serialize a NumPy array into the ``NUMPY_RAW`` binary format.
 
         Requires: numpy installed (HAS_NUMPY=True)
 
         Raises:
             RuntimeError: If numpy not installed
 
-        Skips Rust layer because:
-        - Compression ineffective on NumPy's random data patterns
-        - Native serialization already fast (~2ms)
-        - Rust overhead adds ~8ms with minimal benefit
+        When ``enable_integrity_checking`` is on (the default / ``@cache``), an 8-byte
+        xxHash3-64 checksum is prepended to the ``NUMPY_RAW`` payload with NO compression,
+        mirroring ``ArrowSerializer`` ([checksum][payload]). The numpy branch used to return
+        these bytes *unchecked*, so a corrupted entry was reconstructed as silently-wrong data
+        on read (#155). Compression is deliberately skipped: numpy is large, often-incompressible
+        binary, and LZ4 here measured ~100x slower with no size benefit. When integrity is off
+        (``@cache.minimal``), the raw payload is returned without a checksum (msgpack-off parity).
         """
         if not HAS_NUMPY:
             raise RuntimeError("NumPy not installed. Install with: pip install cachekit[data]")
@@ -627,7 +636,18 @@ class AutoSerializer:
         shape_len = len(shape_data).to_bytes(2, byteorder="little")
 
         # Combine: header + raw numpy bytes (zero-copy from NumPy)
-        return b"NUMPY_RAW" + dtype_len + dtype_str + shape_len + shape_data + arr.tobytes()
+        raw = b"NUMPY_RAW" + dtype_len + dtype_str + shape_len + shape_data + arr.tobytes()
+
+        if self.enable_integrity_checking:
+            # Checksum-only envelope: prepend the 8-byte xxHash3-64 of the payload, NO compression.
+            # numpy arrays are large, often-incompressible binary; routing them through ByteStorage's
+            # LZ4 measured ~100x slower to serialize, ~400x slower to read, and inflated incompressible
+            # data ~1.56x. This mirrors ArrowSerializer's [8-byte xxHash3-64][payload] scheme, giving
+            # the #155 integrity guarantee at ~0 cost. The read side strips + verifies in
+            # _deserialize_numpy. (No LZ4 here means numpy is genuinely uncompressed, so the
+            # metadata.compressed=False set in serialize() is correct — sidesteps #166 entirely.)
+            return xxhash.xxh3_64_digest(raw) + raw
+        return raw
 
     def _deserialize_numpy(self, data: bytes) -> np.ndarray:
         """Deserialize NumPy array from NUMPY_RAW binary format.
@@ -641,6 +661,16 @@ class AutoSerializer:
         if not HAS_NUMPY:
             raise RuntimeError("NumPy not installed. Install with: pip install cachekit[data]")
 
+        # Strip + verify the optional 8-byte xxHash3-64 checksum prefix written by integrity-on
+        # serialization. Detect by structure (like ArrowSerializer): a checksummed entry is
+        # [8-byte checksum][NUMPY_RAW...]; a raw entry (integrity-off / legacy) is [NUMPY_RAW...].
+        # A mismatch fails closed (#155) — never reconstructs the corrupted array.
+        if not data.startswith(b"NUMPY_RAW") and len(data) >= 17 and data[8:17] == b"NUMPY_RAW":
+            body = data[8:]
+            if xxhash.xxh3_64_digest(body) != data[:8]:
+                raise SerializationError("NumPy integrity check failed: xxHash3-64 checksum mismatch (corrupted cache entry)")
+            data = body
+
         if not data.startswith(b"NUMPY_RAW"):
             raise SerializationError("Invalid NumPy data format - expected NUMPY_RAW header")
 
@@ -666,9 +696,11 @@ class AutoSerializer:
                 shape.append(dim)
             shape = tuple(shape)
 
-            # Extract raw numpy bytes and reconstruct
+            # Extract raw numpy bytes and reconstruct. .copy() so the result is writable and does
+            # not alias the source bytes (the L1-cached buffer on a hit) — see #157. frombuffer alone
+            # returns a read-only view aliasing the input.
             raw_bytes = data[offset:]
-            arr = np.frombuffer(raw_bytes, dtype=dtype_str)
+            arr = np.frombuffer(raw_bytes, dtype=dtype_str).copy()
             return arr.reshape(shape)
         except (ValueError, IndexError, UnicodeDecodeError) as e:
             raise SerializationError(f"Failed to deserialize NumPy array: {e}") from e
@@ -729,8 +761,8 @@ class AutoSerializer:
         columns_data = {}
         for col, col_info in serialized["data"].items():
             if col_info["type"] == "numeric":
-                # Reconstruct from NumPy bytes
-                arr = np.frombuffer(col_info["data"], dtype=col_info["dtype"])
+                # Reconstruct from NumPy bytes; .copy() → writable, non-aliasing column (#157).
+                arr = np.frombuffer(col_info["data"], dtype=col_info["dtype"]).copy()
                 columns_data[col] = arr
             else:
                 # Use object data directly
@@ -793,7 +825,8 @@ class AutoSerializer:
             serialized = msgpack.unpackb(data, **self._msgpack_unpack_opts)
 
         if serialized["type"] == "numeric":
-            values = np.frombuffer(serialized["data"], dtype=serialized["dtype"])
+            # .copy() → writable Series values that do not alias the source buffer (#157).
+            values = np.frombuffer(serialized["data"], dtype=serialized["dtype"]).copy()
         else:
             values = serialized["data"]