dialcache 0.25.0__py3-none-any.whl

dialcache/local.py

@@ -0,0 +1,77 @@
+"""Bounded process-local LRU storage with whole-millisecond expiry."""
+
+from __future__ import annotations
+
+import math
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Any
+
+from .clock import Clock, SystemClock
+from .errors import ConfigError
+
+MISSING = object()
+MAX_SAFE_INTEGER = 9_007_199_254_740_991
+
+
+@dataclass(frozen=True)
+class _Entry:
+    value: Any
+    expires_at_ms: int
+
+
+class LocalCache:
+    """Local entries are shared by the use cases on one cache instance.
+
+    Reads promote recency but never renew expiration. ``None`` is a present
+    value. A zero capacity disables storage while leaving policy eligibility
+    and coalescing to the core engine.
+    """
+
+    def __init__(self, max_size: int = 10_000, clock: Clock | None = None) -> None:
+        if (
+            isinstance(max_size, bool)
+            or not isinstance(max_size, int)
+            or max_size < 0
+            or max_size > MAX_SAFE_INTEGER
+        ):
+            raise ConfigError("local_max_size must be a nonnegative safe integer")
+        self.max_size = max_size
+        self.clock = clock if clock is not None else SystemClock()
+        self._entries: OrderedDict[str, _Entry] = OrderedDict()
+
+    def _get_entry(self, key: str, now_ms: float | None = None) -> _Entry | None:
+        entry = self._entries.get(key)
+        if entry is None:
+            return None
+        now = math.floor(self.clock.monotonic_ms() if now_ms is None else now_ms)
+        if now >= entry.expires_at_ms:
+            del self._entries[key]
+            return None
+        self._entries.move_to_end(key)
+        return entry
+
+    def get(self, key: str, now_ms: float | None = None) -> Any:
+        entry = self._get_entry(key, now_ms)
+        return MISSING if entry is None else entry.value
+
+    def read(self, key: str) -> tuple[bool, Any]:
+        entry = self._get_entry(key)
+        return (False, None) if entry is None else (True, entry.value)
+
+    def put(self, key: str, value: Any, ttl_sec: int) -> None:
+        if self.max_size == 0:
+            return
+        from .config import cache_ttl_sec_to_ms
+
+        ttl_ms = cache_ttl_sec_to_ms(ttl_sec)
+        self._entries[key] = _Entry(value, math.floor(self.clock.monotonic_ms()) + ttl_ms)
+        self._entries.move_to_end(key)
+        while len(self._entries) > self.max_size:
+            self._entries.popitem(last=False)
+
+    def clear(self) -> None:
+        self._entries.clear()
+
+    def __len__(self) -> int:
+        return len(self._entries)

dialcache/metrics.py

@@ -0,0 +1,39 @@
+"""Backend-neutral metrics observer contract."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Callable, Mapping
+from typing import Any, Protocol, TypeAlias
+
+MetricEvent: TypeAlias = dict[str, Any]
+
+
+class MetricsObserver(Protocol):
+    """Receive bounded events with the shared DialCache diagnostic labels.
+
+    Events use the cross-port names, including ``cacheNamespace``, ``useCase``
+    and ``keyType``. Observers are synchronous. Their failures never change a
+    cache call's outcome.
+    """
+
+    def observe(self, event: MetricEvent) -> None: ...
+
+
+Metrics: TypeAlias = MetricsObserver | Callable[[MetricEvent], None]
+
+
+def emit_metric(metrics: Metrics | None, event: str | Mapping[str, Any], **labels: Any) -> None:
+    if metrics is None:
+        return
+    payload = {"event": event, **labels} if isinstance(event, str) else dict(event)
+    try:
+        callback = metrics if callable(metrics) else metrics.observe
+        result = callback(payload)
+        # An async observer violates the synchronous contract. Do not schedule
+        # it, and avoid leaving an un-awaited coroutine warning behind.
+        if inspect.iscoroutine(result):
+            result.close()
+    except (Exception, asyncio.CancelledError):
+        pass

dialcache/protocol.py

@@ -0,0 +1,301 @@
+"""DialCache version-1 frames and payload envelopes, independent of Redis clients."""
+
+from __future__ import annotations
+
+import io
+import math
+import re
+from dataclasses import dataclass, field
+
+from .errors import DialCacheError
+from .key import _scalar_text
+from .serializer import Payload
+
+MAX_SAFE_INTEGER = 9_007_199_254_740_991
+MAX_SUPPORTED_DURATION_MS = 31_536_000_000
+MAX_TRACKED_REDIS_VALUE_TTL_MS = 3_600_000
+MAX_DECOMPRESSED_BYTES = 512 * 1024 * 1024
+
+
+class RedisPayloadError(DialCacheError):
+    """A Redis reply is not a bulk byte string or nil."""
+
+
+class RedisPayloadEncodingError(DialCacheError):
+    """An eligible frame carries an unsupported payload encoding."""
+
+
+class RedisProtocolError(DialCacheError):
+    """Redis returned an unexpected command reply."""
+
+
+@dataclass(frozen=True)
+class Frame:
+    created_at_ms: int
+    payload: Payload
+
+
+@dataclass(frozen=True)
+class Miss:
+    reason: str
+    observed_watermark_ms: int | None = None
+    kind: str = field(default="miss", init=False)
+
+
+ReadResult = Frame | Miss
+
+
+def valid_timestamp(value: object) -> bool:
+    return (
+        isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and 0 <= value <= MAX_SAFE_INTEGER
+        and value == int(value)
+    )
+
+
+def validate_timestamp(value: object) -> int:
+    if not valid_timestamp(value):
+        raise ValueError("DialCache timestamp must be a nonnegative safe integer")
+    return int(value)  # type: ignore[arg-type]
+
+
+def ceil_supported_cache_ttl_ms(value: float) -> int:
+    if (
+        not isinstance(value, (int, float))
+        or isinstance(value, bool)
+        or not 0 < value <= MAX_SUPPORTED_DURATION_MS
+    ):
+        raise ValueError("DialCache Redis TTL must be a positive finite duration")
+    result = math.ceil(value)
+    if not 0 < result <= MAX_SUPPORTED_DURATION_MS:
+        raise ValueError("DialCache Redis TTL must be positive and no greater than 365 days")
+    return result
+
+
+def validate_future_buffer_ms(value: object) -> int:
+    result = validate_timestamp(value)
+    if result > MAX_SUPPORTED_DURATION_MS:
+        raise ValueError("DialCache future buffer must be no greater than 365 days")
+    return result
+
+
+def utf8_bytes(value: str) -> bytes:
+    return _scalar_text(value, replace=True).encode("utf-8")
+
+
+def _payload_bytes(payload: Payload) -> bytes:
+    if isinstance(payload, bytes):
+        return payload
+    if isinstance(payload, str):
+        return utf8_bytes(payload)
+    raise TypeError("DialCache serializer payload must be str or immutable bytes")
+
+
+def encode_frame(payload: Payload, created_at_ms: int) -> bytes:
+    timestamp = validate_timestamp(created_at_ms)
+    return (
+        b"\x01"
+        + timestamp.to_bytes(8, "big")
+        + bytes([int(isinstance(payload, bytes))])
+        + _payload_bytes(payload)
+    )
+
+
+def _bulk(raw: object) -> bytes | None:
+    if raw is None or isinstance(raw, bytes):
+        return raw
+    raise RedisPayloadError("Invalid Redis read reply; expected immutable bytes or None")
+
+
+def _supported(raw: bytes) -> bool:
+    return len(raw) >= 10 and raw[0] == 1
+
+
+def _watermark(raw: bytes | None) -> int | None:
+    if raw is None or not re.fullmatch(rb"[0-9]+", raw):
+        return None
+    # Avoid Python's decimal conversion guard on hostile or huge numeric strings.
+    digits = raw.lstrip(b"0") or b"0"
+    if len(digits) > 16 or (len(digits) == 16 and digits > b"9007199254740991"):
+        return None
+    return int(digits)
+
+
+def _frame(raw: bytes) -> Frame:
+    tag = raw[9]
+    if tag == 0:
+        payload: Payload = raw[10:].decode("utf-8", errors="replace")
+    elif tag == 1:
+        payload = raw[10:]
+    else:
+        raise RedisPayloadEncodingError("Invalid DialCache Redis payload encoding")
+    return Frame(int.from_bytes(raw[1:9], "big"), payload)
+
+
+def decode_read(raw: object) -> ReadResult:
+    frame = _bulk(raw)
+    if frame is None:
+        return Miss("value_absent")
+    if not _supported(frame):
+        return Miss("unclassified")
+    return _frame(frame)
+
+
+def decode_tracked_read(raw: object, raw_watermark: object) -> ReadResult:
+    frame, watermark_bytes = _bulk(raw), _bulk(raw_watermark)
+    watermark = _watermark(watermark_bytes)
+    if frame is None:
+        return Miss("value_absent", watermark)
+    if not _supported(frame):
+        return Miss("unclassified", watermark)
+    if watermark_bytes is not None and watermark is None:
+        return Miss("unclassified")
+    timestamp = int.from_bytes(frame[1:9], "big")
+    if timestamp == 0:
+        return Miss("unclassified", watermark)
+    if watermark is not None and timestamp <= watermark:
+        return Miss("watermark_fenced", watermark)
+    return _frame(frame)
+
+
+def validate_set_reply(reply: object) -> None:
+    # redis-py maps the native OK status to True through its SET response callback.
+    if reply is not True and reply not in ("OK", b"OK"):
+        raise RedisProtocolError("Invalid Redis SET reply; expected OK")
+
+
+def validate_invalidation_reply(reply: object) -> None:
+    if type(reply) is not int or reply != 1:
+        raise RedisProtocolError("Invalid Redis invalidate reply; expected integer 1")
+
+
+@dataclass(frozen=True)
+class CompressionResult:
+    payload: Payload
+    outcome: str
+    original_bytes: int
+    stored_bytes: int
+
+
+@dataclass(frozen=True)
+class DecompressionResult:
+    payload: Payload
+    outcome: str
+
+
+def escape_raw_payload(payload: Payload) -> Payload:
+    if not isinstance(payload, (str, bytes)):
+        raise TypeError("DialCache serializer payload must be str or immutable bytes")
+    return b"\x00" + payload if isinstance(payload, bytes) and payload and payload[0] <= 2 else payload
+
+
+def compress_payload(
+    payload: Payload, threshold_bytes: int = 4096, level: int = 3, maximum: int = MAX_DECOMPRESSED_BYTES
+) -> CompressionResult:
+    import zstandard
+
+    raw = _payload_bytes(payload)
+    escaped = escape_raw_payload(payload)
+    stored_size = len(escaped) if isinstance(escaped, bytes) else len(raw)
+    if len(raw) < threshold_bytes:
+        return CompressionResult(escaped, "below_threshold", len(raw), stored_size)
+    if len(raw) > maximum:
+        return CompressionResult(escaped, "write_over_limit", len(raw), stored_size)
+    encoded = zstandard.ZstdCompressor(level=level).compress(raw)
+    if len(encoded) + 1 >= stored_size:
+        return CompressionResult(escaped, "not_smaller", len(raw), stored_size)
+    result = bytes([2 if isinstance(payload, bytes) else 1]) + encoded
+    return CompressionResult(result, "compressed", len(raw), len(result))
+
+
+class _CompressedInput(io.BytesIO):
+    """Distinguish iterator input exhaustion from a completed first frame."""
+
+    exhausted = False
+
+    def read(self, size: int = -1) -> bytes:
+        chunk = super().read(size)
+        if not chunk:
+            self.exhausted = True
+        return chunk
+
+
+def _failed_frame_exceeds_limit(encoded: bytes, maximum: int) -> bool:
+    import zstandard
+
+    # The iterator already failed before completing the first frame. Replaying
+    # only this error case cannot enter a valid second frame. Read exactly up
+    # to cap+1 to preserve limit-before-later-corruption classification without
+    # allocating the cap or repeating decompression on successful reads.
+    total = 0
+    try:
+        with zstandard.ZstdDecompressor().stream_reader(
+            io.BytesIO(encoded), read_across_frames=False
+        ) as reader:
+            while total <= maximum:
+                chunk = reader.read(min(64 * 1024, maximum + 1 - total))
+                total += len(chunk)
+                if total > maximum:
+                    return True
+                if not chunk:
+                    break
+    except (zstandard.ZstdError, ValueError, OverflowError, OSError):
+        pass
+    return False
+
+
+def decompress_payload(payload: Payload, maximum: int = MAX_DECOMPRESSED_BYTES) -> DecompressionResult:
+    if not isinstance(payload, bytes) or not payload:
+        return DecompressionResult(payload, "passthrough")
+    marker = payload[0]
+    if marker == 0:
+        value = payload[1:] if len(payload) > 1 and payload[1] <= 2 else payload
+        return DecompressionResult(value, "passthrough")
+    if marker not in (1, 2):
+        return DecompressionResult(payload, "passthrough")
+    import zstandard
+
+    try:
+        encoded = payload[1:]
+        content_size = zstandard.frame_content_size(encoded)
+        unknown_size = content_size in (-1, zstandard.CONTENTSIZE_UNKNOWN)
+        if unknown_size or content_size > maximum:
+            # Unlike repeated stream_reader reads, this iterator stops at the
+            # first completed frame, including an empty frame. Truncation makes
+            # it request more input and encounter EOF instead. Retain only
+            # actual output: unknown-size one-shot decode allocates its limit.
+            source = _CompressedInput(encoded)
+            chunks: list[bytes] = []
+            total = 0
+            try:
+                for chunk in zstandard.ZstdDecompressor().read_to_iter(
+                    source, write_size=min(64 * 1024, maximum + 1)
+                ):
+                    total += len(chunk)
+                    if total > maximum:
+                        return DecompressionResult(payload, "read_over_limit")
+                    # Known oversized frames can only return the raw input;
+                    # validate their stream without retaining unusable output.
+                    if unknown_size:
+                        chunks.append(chunk)
+            except zstandard.ZstdError:
+                chunks.clear()
+                outcome = (
+                    "read_over_limit" if _failed_frame_exceeds_limit(encoded, maximum) else "fallback_raw"
+                )
+                return DecompressionResult(payload, outcome)
+            if source.exhausted or not unknown_size:
+                return DecompressionResult(payload, "fallback_raw")
+            decoded = b"".join(chunks)
+        else:
+            decoded = zstandard.ZstdDecompressor().decompress(
+                encoded, max_output_size=max(1, maximum), allow_extra_data=True
+            )
+        if len(decoded) > maximum:
+            return DecompressionResult(payload, "read_over_limit")
+    except (zstandard.ZstdError, ValueError, OverflowError, OSError):
+        return DecompressionResult(payload, "fallback_raw")
+    return DecompressionResult(
+        decoded.decode("utf-8", errors="replace") if marker == 1 else decoded, "decompressed"
+    )

dialcache/redis.py

@@ -0,0 +1,213 @@
+"""Semantic Redis boundary and a resource-free adapter for redis.asyncio clients.
+
+The application owns connections and finite socket/retry budgets. Cancellation
+can stop a Python wait but cannot retract a dispatched Redis command. Writes
+may have executed after a connection error. Invalidation retries the idempotent
+script once with EVAL, preserving its original timestamp. This adapter never
+connects, disconnects, flushes, or closes the borrowed client.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from .protocol import (
+    ReadResult,
+    RedisProtocolError,
+    ceil_supported_cache_ttl_ms,
+    decode_read,
+    decode_tracked_read,
+    encode_frame,
+    validate_future_buffer_ms,
+    validate_invalidation_reply,
+    validate_set_reply,
+    validate_timestamp,
+)
+from .serializer import Payload
+
+
+@dataclass(frozen=True)
+class ReadRequest:
+    value_key: str
+    watermark_key: str | None = None
+
+
+class AbortSignal(Protocol):
+    @property
+    def aborted(self) -> bool: ...
+    def add_callback(self, callback: Callable[[], Any]) -> None: ...
+
+
+@dataclass(frozen=True)
+class ReadContext:
+    timeout_ms: float
+    signal: AbortSignal | None = None
+
+
+@dataclass(frozen=True)
+class WriteRequest:
+    value_key: str
+    cache_ttl_ms: float
+    value: Payload
+    created_at_ms: int
+
+
+@dataclass(frozen=True)
+class InvalidationRequest:
+    watermark_key: str
+    future_buffer_ms: int
+    invalidated_at_ms: int
+
+
+class RedisClient(Protocol):
+    def read(
+        self, request: ReadRequest, context: ReadContext | None = None
+    ) -> ReadResult | Awaitable[ReadResult]: ...
+    def write(self, request: WriteRequest) -> None | Awaitable[None]: ...
+    def invalidate(self, request: InvalidationRequest) -> None | Awaitable[None]: ...
+
+
+# Same atomic transition as the TypeScript/Go/Rust adapters. Values never write
+# watermarks. The clock sample belongs to one logical invalidation invocation.
+INVALIDATE_CACHE_SCRIPT = """local function parse_safe_integer(raw)
+  if not string.match(raw, "^%d+$") then
+    return nil
+  end
+  local value = tonumber(raw)
+  if not value or value > 9007199254740991 then
+    return nil
+  end
+  return value
+end
+
+local future_buffer_ms = parse_safe_integer(ARGV[1])
+if not future_buffer_ms or future_buffer_ms < 0 or future_buffer_ms > 31536000000 then
+  return redis.error_reply("ERR invalid DialCache future buffer")
+end
+local invalidated_at_ms = parse_safe_integer(ARGV[2])
+if not invalidated_at_ms or invalidated_at_ms > 9007199254740991 - future_buffer_ms then
+  return redis.error_reply("ERR invalid DialCache invalidatedAtMs")
+end
+
+local proposed_watermark = invalidated_at_ms + future_buffer_ms
+local raw_watermark = redis.pcall("GET", KEYS[1])
+if type(raw_watermark) == "table" and raw_watermark.err then
+  if not string.match(raw_watermark.err, "^WRONGTYPE ") then
+    return raw_watermark
+  end
+  -- A wrong-type key cannot contain a valid watermark. Treat it as absent so
+  -- the final SET repairs it, while preserving every other Redis error.
+  raw_watermark = false
+end
+local current_watermark = 0
+
+if raw_watermark then
+  local parsed_watermark = parse_safe_integer(raw_watermark)
+  if parsed_watermark then
+    current_watermark = parsed_watermark
+  end
+end
+
+local watermark = math.max(current_watermark, proposed_watermark)
+local current_ttl_ms = -2
+if raw_watermark then
+  current_ttl_ms = redis.call("PTTL", KEYS[1])
+end
+local desired_ttl_ms = math.max(
+  7200000,
+  watermark - invalidated_at_ms + 3600000 + 60000
+)
+if current_ttl_ms > desired_ttl_ms then
+  desired_ttl_ms = current_ttl_ms
+end
+
+local encoded_watermark = string.format("%.0f", watermark)
+if current_ttl_ms == -1 then
+  redis.call("SET", KEYS[1], encoded_watermark)
+else
+  redis.call("SET", KEYS[1], encoded_watermark, "PX", desired_ttl_ms)
+end
+
+return 1"""
+INVALIDATE_CACHE_SCRIPT_SHA1 = hashlib.sha1(INVALIDATE_CACHE_SCRIPT.encode()).hexdigest()
+
+
+class RedisAdapter:
+    """Borrow a redis.asyncio.Redis or RedisCluster with decode_responses=False.
+
+    Tracked Cluster reads require a client constructed for primary-only reads,
+    with unchanged connection settings and no READONLY connection hook. A
+    replica-configured client remains usable for untracked reads and mutations.
+    Tracked MGET is one atomic snapshot, including through client redirects.
+    ReadContext is informational; core owns its authoritative deadline.
+    """
+
+    def __init__(self, client: Any) -> None:
+        self.client = client
+
+    def _require_primary_connections(self) -> None:
+        message = (
+            "Tracked reads require a dedicated primary-only RedisCluster with unchanged connection settings"
+        )
+        try:
+            configuration = self.client.get_connection_kwargs()
+            safe = (
+                not self.client.read_from_replicas
+                and getattr(self.client, "load_balancing_strategy", None) is None
+                and isinstance(configuration, Mapping)
+                and configuration.get("redis_connect_func") is None
+            )
+        except Exception as error:
+            raise RedisProtocolError(message) from error
+        if not safe:
+            raise RedisProtocolError(message)
+
+    async def _command(self, key: str, *arguments: object, tracked_read: bool = False) -> Any:
+        options: dict[str, object] = {}
+        if hasattr(self.client, "get_node_from_key"):
+            if tracked_read:
+                self._require_primary_connections()
+            # RedisCluster initializes its topology lazily. Explicit routing
+            # must wait for that initialization before looking up the primary.
+            await self.client.initialize()
+            if tracked_read:
+                # Replica routing affects redirects too. Constructor-installed
+                # READONLY hooks survive flag changes and can serve a demoted
+                # primary without any redirect; never borrow those connections.
+                self._require_primary_connections()
+            options["target_nodes"] = self.client.get_node_from_key(key, replica=False)
+        return await self.client.execute_command(*arguments, **options)
+
+    async def read(self, request: ReadRequest, context: ReadContext | None = None) -> ReadResult:
+        if context is not None and context.signal is not None and context.signal.aborted:
+            raise asyncio.CancelledError()
+        if request.watermark_key is None:
+            return decode_read(await self._command(request.value_key, "GET", request.value_key))
+        result = await self._command(
+            request.value_key, "MGET", request.value_key, request.watermark_key, tracked_read=True
+        )
+        if not isinstance(result, (list, tuple)) or len(result) != 2:
+            raise RedisProtocolError("Invalid Redis MGET reply; expected two bulk strings")
+        return decode_tracked_read(result[0], result[1])
+
+    async def write(self, request: WriteRequest) -> None:
+        ttl = ceil_supported_cache_ttl_ms(request.cache_ttl_ms)
+        frame = encode_frame(request.value, request.created_at_ms)
+        result = await self._command(request.value_key, "SET", request.value_key, frame, "PX", str(ttl))
+        validate_set_reply(result)
+
+    async def invalidate(self, request: InvalidationRequest) -> None:
+        buffer = validate_future_buffer_ms(request.future_buffer_ms)
+        timestamp = validate_timestamp(request.invalidated_at_ms)
+        args = ("1", request.watermark_key, str(buffer), str(timestamp))
+        try:
+            result = await self._command(
+                request.watermark_key, "EVALSHA", INVALIDATE_CACHE_SCRIPT_SHA1, *args
+            )
+        except Exception:  # noqa: BLE001 -- Any EVALSHA rejection gets one idempotent recovery.
+            result = await self._command(request.watermark_key, "EVAL", INVALIDATE_CACHE_SCRIPT, *args)
+        validate_invalidation_reply(result)

dialcache/serializer.py

@@ -0,0 +1,55 @@
+"""Caller-supplied serialization and the portable JSON value binding."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable
+from typing import Protocol, TypeVar
+
+T = TypeVar("T")
+Payload = str | bytes
+
+
+class _Undefined:
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "UNDEFINED"
+
+
+UNDEFINED = _Undefined()
+JSON_UNDEFINED_SENTINEL = "__dialcache_json_undefined_v1__"
+
+
+class Serializer(Protocol[T]):
+    """Payloads are immutable. Asynchronous methods need an application deadline."""
+
+    def dump(self, value: T) -> Payload | Awaitable[Payload]: ...
+    def load(self, value: Payload) -> T | Awaitable[T]: ...
+
+
+class JsonSerializer:
+    """Compact native JSON, plus the cross-language top-level undefined sentinel.
+
+    Nonfinite numbers and values outside JSON's domain are rejected. For custom
+    Python types, supply a Serializer with an explicit portable representation.
+    """
+
+    def dump(self, value: object) -> str:
+        if value is UNDEFINED:
+            return JSON_UNDEFINED_SENTINEL
+        payload = json.dumps(value, ensure_ascii=False, separators=(",", ":"), allow_nan=False)
+        # JSON must escape lone surrogate units before the frame's UTF-8 text
+        # boundary replaces malformed text. This preserves JSON string values
+        # in the same way as well-formed ECMAScript JSON.stringify.
+        return payload.encode("utf-8", errors="backslashreplace").decode("utf-8")
+
+    def load(self, value: Payload) -> object:
+        payload = value.decode("utf-8", errors="replace") if isinstance(value, bytes) else value
+        if payload == JSON_UNDEFINED_SENTINEL:
+            return UNDEFINED
+        return json.loads(payload, parse_constant=self._reject_constant)
+
+    @staticmethod
+    def _reject_constant(value: str) -> object:
+        raise ValueError(f"Invalid JSON constant: {value}")