client-query-cache 0.1.0__py3-none-any.whl

client_query_cache/__init__.py

@@ -0,0 +1,15 @@
+from .synchronous import (
+    CacheCore,
+    CacheCoreConfig,
+    CachedCollection,
+    CachedDatabase,
+    CacheManager,
+)
+
+__all__ = [
+    "CacheCore",
+    "CacheCoreConfig",
+    "CacheManager",
+    "CachedCollection",
+    "CachedDatabase",
+]

client_query_cache/_core/__init__.py

@@ -0,0 +1,44 @@
+from client_query_cache._core.entries import AdmissionOutcome, LookupResult
+from client_query_cache._core.errors import (
+    CacheClosedError,
+    CacheConfigurationError,
+    CacheError,
+    StreamLifecycleError,
+    StreamStartupError,
+    UnsupportedCacheRequestError,
+)
+from client_query_cache._core.keys import NamespaceId
+from client_query_cache._core.lifecycle import CacheLifecycleState
+from client_query_cache._core.manager import (
+    CacheCore,
+    CacheCoreConfig,
+    IdentityCapture,
+    NamespaceCapture,
+)
+from client_query_cache._core.snapshots import CacheSnapshot
+from client_query_cache._core.stream_cost import (
+    LagCaptureWindowConfig,
+    StreamCostSnapshot,
+)
+from client_query_cache._core.stream_health import StreamHealth
+
+__all__ = [
+    "AdmissionOutcome",
+    "CacheClosedError",
+    "CacheConfigurationError",
+    "CacheCore",
+    "CacheCoreConfig",
+    "CacheError",
+    "CacheLifecycleState",
+    "CacheSnapshot",
+    "IdentityCapture",
+    "LagCaptureWindowConfig",
+    "LookupResult",
+    "NamespaceCapture",
+    "NamespaceId",
+    "StreamCostSnapshot",
+    "StreamHealth",
+    "StreamLifecycleError",
+    "StreamStartupError",
+    "UnsupportedCacheRequestError",
+]

client_query_cache/_core/canonical.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from collections.abc import Hashable, Mapping, Sequence
+
+from client_query_cache._core.errors import UnsupportedCacheRequestError
+
+type Canonical = Hashable
+
+
+class _CanonicalTag:
+    __slots__ = ("_name",)
+
+    def __init__(self, name: str) -> None:
+        self._name = name
+
+    def __repr__(self) -> str:
+        return f"<canonical:{self._name}>"
+
+
+_MAPPING_TAG = _CanonicalTag("map")
+_SEQUENCE_TAG = _CanonicalTag("seq")
+_BOOL_TAG = _CanonicalTag("bool")
+_OWN_TAGS = (_MAPPING_TAG, _SEQUENCE_TAG, _BOOL_TAG)
+_TAGGED_TUPLE_SIZE = 2
+
+
+def canonicalize(value: object) -> Canonical:
+    if (
+        isinstance(value, tuple)
+        and len(value) == _TAGGED_TUPLE_SIZE
+        and any(value[0] is tag for tag in _OWN_TAGS)
+    ):
+        return value
+    if isinstance(value, Mapping):
+        pairs = [(canonicalize(key), canonicalize(item)) for key, item in value.items()]
+        items = tuple(sorted(pairs, key=lambda pair: repr(pair[0])))
+        return (_MAPPING_TAG, items)
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return (_SEQUENCE_TAG, tuple(canonicalize(item) for item in value))
+    if isinstance(value, bool):
+        return (_BOOL_TAG, value)
+    try:
+        hash(value)
+    except TypeError:
+        type_name = type(value).__name__
+        message = f"cannot canonicalize value of type {type_name!r} for a cache key"
+        raise UnsupportedCacheRequestError(message) from None
+    if value != value:  # noqa: PLR0124 (deliberate self-inequality check for NaN-like values)
+        type_name = type(value).__name__
+        message = (
+            f"cannot canonicalize a non-reflexive value of type {type_name!r} "
+            "for a cache key"
+        )
+        raise UnsupportedCacheRequestError(message)
+    return value
+
+
+def is_canonicalizable(value: object) -> bool:
+    try:
+        canonicalize(value)
+    except UnsupportedCacheRequestError:
+        return False
+    return True

client_query_cache/_core/codec.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import bson
+from bson.codec_options import CodecOptions
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from bson.codec_options import TypeRegistry
+
+_ENVELOPE_FIELD = "v"
+
+
+class _TypeRegistryIdentity:
+    __slots__ = ("_registry",)
+
+    def __init__(self, registry: TypeRegistry) -> None:
+        self._registry = registry
+
+    def __eq__(self, other: object) -> bool:
+        return (
+            isinstance(other, _TypeRegistryIdentity)
+            and self._registry is other._registry
+        )
+
+    def __hash__(self) -> int:
+        return id(self._registry)
+
+
+def encode_value(
+    value: object, codec_options: CodecOptions[Mapping[str, Any]] | None = None
+) -> bytes:
+    return bson.encode(
+        {_ENVELOPE_FIELD: value}, codec_options=codec_options or CodecOptions()
+    )
+
+
+def decode_value(
+    encoded: bytes, codec_options: CodecOptions[Mapping[str, Any]] | None = None
+) -> object:
+    return bson.decode(encoded, codec_options=codec_options)[_ENVELOPE_FIELD]
+
+
+def codec_fingerprint(codec_options: CodecOptions[Mapping[str, Any]]) -> object:
+    return (
+        codec_options.document_class,
+        codec_options.tz_aware,
+        codec_options.uuid_representation,
+        codec_options.unicode_decode_error_handler,
+        codec_options.tzinfo,
+        codec_options.datetime_conversion,
+        _TypeRegistryIdentity(codec_options.type_registry),
+    )

client_query_cache/_core/collation.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+_SIMPLE_LOCALE = "simple"
+
+
+def normalize_collation(
+    collation: Mapping[str, Any] | None,
+) -> Mapping[str, Any] | None:
+    if collation is None:
+        return None
+    try:
+        locale = collation["locale"]
+    except KeyError:
+        locale = None
+    if locale == _SIMPLE_LOCALE:
+        return None
+    return collation

client_query_cache/_core/collection_metadata.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from client_query_cache._core.collation import normalize_collation
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from client_query_cache._core.keys import NamespaceId
+
+
+@dataclass(frozen=True, slots=True)
+class CollectionMetadata:
+    checked_epoch: int
+    is_cacheable: bool
+    default_collation: Mapping[str, Any] | None
+
+
+class CollectionMetadataCache:
+    __slots__ = ("_entries", "_lock")
+
+    def __init__(self) -> None:
+        self._entries: dict[NamespaceId, CollectionMetadata] = {}
+        self._lock = threading.Lock()
+
+    def get(self, namespace: NamespaceId) -> CollectionMetadata | None:
+        with self._lock:
+            try:
+                return self._entries[namespace]
+            except KeyError:
+                return None
+
+    def put(self, namespace: NamespaceId, metadata: CollectionMetadata) -> None:
+        with self._lock:
+            self._entries[namespace] = metadata
+
+
+@dataclass(frozen=True, slots=True)
+class CollectionProbeResult:
+    is_cacheable: bool
+    default_collation: Mapping[str, Any] | None
+
+
+def interpret_list_collections_entry(
+    entry: Mapping[str, Any] | None,
+) -> CollectionProbeResult | None:
+    if entry is None:
+        return None
+    collection_type = entry["type"]
+    try:
+        options = entry["options"]
+    except KeyError:
+        options = {}
+    try:
+        collation = options["collation"]
+    except KeyError:
+        collation = None
+    default_collation = normalize_collation(collation)
+    return CollectionProbeResult(
+        is_cacheable=collection_type == "collection",
+        default_collation=default_collation,
+    )

client_query_cache/_core/entries.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from client_query_cache._core.canonical import Canonical
+    from client_query_cache._core.keys import NamespaceId
+
+
+class AdmissionOutcome(enum.Enum):
+    ADMITTED = "admitted"
+    DECLINED_OVERSIZE = "declined_oversize"
+    DECLINED_STALE = "declined_stale"
+    DECLINED_UNAVAILABLE = "declined_unavailable"
+    DECLINED_UNENCODABLE = "declined_unencodable"
+
+
+@dataclass(eq=False, slots=True)
+class CacheEntry:
+    generation_key: tuple[int, ...]
+    weight: int
+    value: bytes
+    namespace: NamespaceId
+    identity: Canonical | None
+
+
+@dataclass(frozen=True, slots=True)
+class LookupResult:
+    hit: bool
+    value: Any = None

client_query_cache/_core/errors.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+
+class CacheError(Exception):
+    pass
+
+
+class CacheConfigurationError(CacheError, ValueError):
+    pass
+
+
+class UnsupportedCacheRequestError(CacheError, TypeError):
+    pass
+
+
+class CacheClosedError(CacheError):
+    pass
+
+
+class StreamStartupError(CacheError):
+    pass
+
+
+class StreamLifecycleError(CacheError):
+    pass

client_query_cache/_core/identity_reads.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+from bson.errors import BSONError
+from bson.regex import Regex
+
+from client_query_cache._core.codec import decode_value, encode_value
+
+if TYPE_CHECKING:
+    from bson.codec_options import CodecOptions
+
+_ID_FIELD = "_id"
+
+
+class _NoIdentity:
+    __slots__ = ()
+
+
+NO_IDENTITY = _NoIdentity()
+
+
+def _is_query_operator_mapping(value: Mapping[str, Any]) -> bool:
+    return any(key.startswith("$") for key in value)
+
+
+def _is_regex(value: object) -> bool:
+    return isinstance(value, re.Pattern | Regex)
+
+
+def extract_equality_value(value: object) -> object:
+    if value is None:
+        return NO_IDENTITY
+    if isinstance(value, Mapping) and _is_query_operator_mapping(value):
+        return NO_IDENTITY
+    if _is_regex(value):
+        return NO_IDENTITY
+    return value
+
+
+def extract_id_identity(filter_query: object) -> object:
+    if filter_query is None:
+        return NO_IDENTITY
+    if not isinstance(filter_query, Mapping):
+        if _is_regex(filter_query):
+            return NO_IDENTITY
+        return filter_query
+    if set(filter_query) != {_ID_FIELD}:
+        return NO_IDENTITY
+    return extract_equality_value(filter_query[_ID_FIELD])
+
+
+def normalize_identity_for_cache_key(
+    identity: object,
+    read_codec_options: CodecOptions[Any],
+    stream_codec_options: CodecOptions[Any],
+) -> object:
+    try:
+        encoded = encode_value(identity, read_codec_options)
+        return decode_value(encoded, stream_codec_options)
+    except BSONError:
+        return identity

client_query_cache/_core/keys.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, NamedTuple
+
+from client_query_cache._core.canonical import canonicalize
+from client_query_cache._core.order_sensitive_keys import order_sensitive_key
+
+if TYPE_CHECKING:
+    from client_query_cache._core.canonical import Canonical
+
+
+class NamespaceId(NamedTuple):
+    database: str
+    collection: str
+
+
+@dataclass(frozen=True, slots=True)
+class IdentityCacheKey:
+    namespace: NamespaceId
+    identity: Canonical
+    read_shape: Canonical
+
+
+@dataclass(frozen=True, slots=True)
+class NamespaceCacheKey:
+    namespace: NamespaceId
+    discriminator: Canonical
+
+
+type CacheKey = IdentityCacheKey | NamespaceCacheKey
+
+type AliasKey = tuple[Canonical, Canonical, Canonical]
+
+
+def canonical_alias_key(
+    definition: object, value: object, collation: object
+) -> AliasKey:
+    return (
+        canonicalize(definition),
+        canonicalize(order_sensitive_key(value)),
+        canonicalize(collation),
+    )

client_query_cache/_core/lifecycle.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import enum
+
+
+class CacheLifecycleState(enum.Enum):
+    ACTIVE = "active"
+    CLOSED = "closed"

client_query_cache/_core/locking.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import threading
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+class LockOrderViolationError(RuntimeError):
+    pass
+
+
+class LockOrderGuard:
+    __slots__ = ("_state",)
+
+    def __init__(self) -> None:
+        self._state = threading.local()
+
+    @contextmanager
+    def namespace_section(self) -> Iterator[None]:
+        with self._section(entering="in_namespace", forbidden="in_lru"):
+            yield
+
+    @contextmanager
+    def lru_section(self) -> Iterator[None]:
+        with self._section(entering="in_lru", forbidden="in_namespace"):
+            yield
+
+    @contextmanager
+    def _section(self, *, entering: str, forbidden: str) -> Iterator[None]:
+        if getattr(self._state, forbidden, False):
+            message = f"cannot enter {entering!r} section while holding {forbidden!r}"
+            raise LockOrderViolationError(message)
+        setattr(self._state, entering, True)
+        try:
+            yield
+        finally:
+            setattr(self._state, entering, False)

client_query_cache/_core/lru.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import threading
+from collections import OrderedDict
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from client_query_cache._core.entries import CacheEntry
+    from client_query_cache._core.keys import CacheKey
+    from client_query_cache._core.locking import LockOrderGuard
+
+
+class WeightedLru:
+    __slots__ = (
+        "_guard",
+        "_lock",
+        "_max_entry_bytes",
+        "_order",
+        "_shared_budget_bytes",
+        "_used_bytes",
+    )
+
+    def __init__(
+        self,
+        *,
+        shared_budget_bytes: int,
+        max_entry_bytes: int,
+        guard: LockOrderGuard,
+    ) -> None:
+        self._shared_budget_bytes = shared_budget_bytes
+        self._max_entry_bytes = max_entry_bytes
+        self._guard = guard
+        self._order: OrderedDict[CacheKey, CacheEntry] = OrderedDict()
+        self._used_bytes = 0
+        self._lock = threading.Lock()
+
+    @property
+    def max_entry_bytes(self) -> int:
+        return self._max_entry_bytes
+
+    @property
+    def shared_budget_bytes(self) -> int:
+        return self._shared_budget_bytes
+
+    def is_oversize(self, weight: int) -> bool:
+        return weight > self._max_entry_bytes
+
+    def snapshot_usage(self) -> tuple[int, int]:
+        with self._guard.lru_section(), self._lock:
+            return self._used_bytes, len(self._order)
+
+    def peek(self, key: CacheKey) -> CacheEntry | None:
+        with self._guard.lru_section(), self._lock:
+            try:
+                return self._order[key]
+            except KeyError:
+                return None
+
+    def touch(self, key: CacheKey) -> None:
+        with self._guard.lru_section(), self._lock:
+            if key in self._order:
+                self._order.move_to_end(key)
+
+    def conditional_put(
+        self, key: CacheKey, entry: CacheEntry
+    ) -> tuple[bool, CacheEntry | None, list[CacheEntry]]:
+        evicted: list[CacheEntry] = []
+        with self._guard.lru_section(), self._lock:
+            try:
+                current = self._order[key]
+            except KeyError:
+                current = None
+            if current is not None and current.generation_key >= entry.generation_key:
+                return False, None, evicted
+            if current is not None:
+                self._used_bytes -= current.weight
+                del self._order[key]
+            self._order[key] = entry
+            self._used_bytes += entry.weight
+            while self._used_bytes > self._shared_budget_bytes:
+                oldest_key, oldest_entry = next(iter(self._order.items()))
+                del self._order[oldest_key]
+                self._used_bytes -= oldest_entry.weight
+                evicted.append(oldest_entry)
+            return True, current, evicted
+
+    def contains_exact(self, key: CacheKey, entry: CacheEntry) -> bool:
+        with self._guard.lru_section(), self._lock:
+            try:
+                return self._order[key] is entry
+            except KeyError:
+                return False
+
+    def remove_exact(self, key: CacheKey, entry: CacheEntry) -> bool:
+        with self._guard.lru_section(), self._lock:
+            try:
+                current = self._order[key]
+            except KeyError:
+                return False
+            if current is entry:
+                del self._order[key]
+                self._used_bytes -= entry.weight
+                return True
+            return False
+
+    def clear_all(self) -> None:
+        with self._guard.lru_section(), self._lock:
+            self._order.clear()
+            self._used_bytes = 0