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

client_query_cache/_core/namespace.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from client_query_cache._core.canonical import Canonical
+    from client_query_cache._core.entries import CacheEntry
+    from client_query_cache._core.keys import AliasKey, CacheKey, NamespaceId
+
+
+@dataclass(slots=True)
+class IdentityState:
+    generation: int = 0
+    cached_ref_count: int = 0
+    inflight_ref_count: int = 0
+    alias_keys: set[AliasKey] = field(default_factory=set)
+
+    @property
+    def is_referenced(self) -> bool:
+        return self.cached_ref_count > 0 or self.inflight_ref_count > 0
+
+
+@dataclass(slots=True)
+class NamespaceState:
+    namespace: NamespaceId
+    lock: threading.Lock = field(default_factory=threading.Lock)
+    generation: int = 0
+    epoch: int = 0
+    index_generation: int = 0
+    identities: dict[Canonical, IdentityState] = field(default_factory=dict)
+    aliases: dict[AliasKey, Canonical] = field(default_factory=dict)
+    entry_index: dict[CacheEntry, CacheKey] = field(default_factory=dict)
+    identity_generation_watermark: int = 0

client_query_cache/_core/order_sensitive_keys.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from bson.int64 import Int64
+
+from client_query_cache._core.canonical import _OWN_TAGS as _CANONICAL_OWN_TAGS
+
+
+class _OrderTag:
+    __slots__ = ()
+
+
+_MAPPING_TAG = _OrderTag()
+_SEQUENCE_TAG = _OrderTag()
+_FLOAT_TAG = _OrderTag()
+_INT64_TAG = _OrderTag()
+_OWN_TAGS = (_MAPPING_TAG, _SEQUENCE_TAG, _FLOAT_TAG, _INT64_TAG, *_CANONICAL_OWN_TAGS)
+_TAGGED_TUPLE_SIZE = 2
+
+
+def _order_sensitive_key(
+    value: object, *, distinguish_numeric_subtypes: bool
+) -> object:
+    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):
+        return (
+            _MAPPING_TAG,
+            tuple(
+                (
+                    _order_sensitive_key(
+                        key, distinguish_numeric_subtypes=distinguish_numeric_subtypes
+                    ),
+                    _order_sensitive_key(
+                        item, distinguish_numeric_subtypes=distinguish_numeric_subtypes
+                    ),
+                )
+                for key, item in value.items()
+            ),
+        )
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return (
+            _SEQUENCE_TAG,
+            tuple(
+                _order_sensitive_key(
+                    item, distinguish_numeric_subtypes=distinguish_numeric_subtypes
+                )
+                for item in value
+            ),
+        )
+    if distinguish_numeric_subtypes:
+        if isinstance(value, Int64):
+            return (_INT64_TAG, value)
+        if isinstance(value, float):
+            return (_FLOAT_TAG, value)
+    return value
+
+
+def order_sensitive_key(value: object) -> object:
+    return _order_sensitive_key(value, distinguish_numeric_subtypes=False)
+
+
+def order_sensitive_discriminator_key(value: object) -> object:
+    return _order_sensitive_key(value, distinguish_numeric_subtypes=True)

client_query_cache/_core/projection.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+from typing import TYPE_CHECKING, Any
+
+import bson
+from bson.errors import BSONError
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from bson.codec_options import CodecOptions
+
+_ID_FIELD = "_id"
+
+
+def without_id(
+    document: Mapping[str, Any],
+    codec_options: CodecOptions[Any] | None = None,
+) -> Mapping[str, Any]:
+    if isinstance(document, MutableMapping):
+        document.pop(_ID_FIELD, None)
+        return document
+    stripped = {key: value for key, value in document.items() if key != _ID_FIELD}
+    if codec_options is None:
+        return stripped
+    try:
+        return bson.decode(
+            bson.encode(stripped, codec_options=codec_options),
+            codec_options=codec_options,
+        )
+    except BSONError, OverflowError:
+        return stripped
+
+
+def _is_include_value(value: object) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int | float):
+        return value != 0
+    return True
+
+
+def ensure_id_present_for_resolution(
+    projection: Mapping[str, Any] | Sequence[str] | None,
+) -> tuple[Mapping[str, Any] | Sequence[str] | None, bool]:
+    if not isinstance(projection, Mapping) or _ID_FIELD not in projection:
+        return projection, False
+    if _is_include_value(projection[_ID_FIELD]):
+        return projection, False
+    other_values = [value for key, value in projection.items() if key != _ID_FIELD]
+    if any(_is_include_value(value) for value in other_values):
+        server_projection = dict(projection)
+        server_projection[_ID_FIELD] = 1
+        return server_projection, True
+    server_projection = {
+        key: value for key, value in projection.items() if key != _ID_FIELD
+    }
+    return server_projection, True

client_query_cache/_core/read_validation.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+PIPELINE_UNSAFE_KEYS = frozenset(
+    {
+        "$lookup",
+        "$unionWith",
+        "$graphLookup",
+        "$out",
+        "$merge",
+        "$sample",
+        "$function",
+        "$accumulator",
+        "$rand",
+        "$sampleRate",
+        "$collStats",
+        "$indexStats",
+        "$planCacheStats",
+        "$meta",
+        "$text",
+    }
+)
+
+PIPELINE_BLOCKING_KEYS = frozenset({"$changeStream"})
+
+FILTER_UNSAFE_KEYS = frozenset(
+    {"$where", "$rand", "$sampleRate", "$function", "$accumulator", "$text"}
+)
+
+PROJECTION_UNSAFE_KEYS = frozenset({"$meta"})
+
+NONDETERMINISTIC_SYSTEM_VARIABLES = frozenset({"$$NOW", "$$CLUSTER_TIME"})
+
+_NO_UNSAFE_VARIABLES: frozenset[str] = frozenset()
+
+
+def _contains_unsafe_construct(
+    node: object,
+    unsafe_keys: frozenset[str],
+    unsafe_variables: frozenset[str] = _NO_UNSAFE_VARIABLES,
+) -> bool:
+    if isinstance(node, Mapping):
+        for key, value in node.items():
+            if key in unsafe_keys:
+                return True
+            if _contains_unsafe_construct(value, unsafe_keys, unsafe_variables):
+                return True
+        return False
+    if isinstance(node, str):
+        try:
+            if node in unsafe_variables:
+                return True
+        except TypeError:
+            return False
+        return any(node.startswith(f"{variable}.") for variable in unsafe_variables)
+    if isinstance(node, Sequence) and not isinstance(node, (bytes, bytearray)):
+        return any(
+            _contains_unsafe_construct(item, unsafe_keys, unsafe_variables)
+            for item in node
+        )
+    return False
+
+
+def is_pipeline_cacheable(pipeline: Sequence[Mapping[str, Any]]) -> bool:
+    return not _contains_unsafe_construct(
+        pipeline, PIPELINE_UNSAFE_KEYS, NONDETERMINISTIC_SYSTEM_VARIABLES
+    )
+
+
+def pipeline_blocks_full_materialization(pipeline: Sequence[Mapping[str, Any]]) -> bool:
+    return any(not PIPELINE_BLOCKING_KEYS.isdisjoint(stage) for stage in pipeline)
+
+
+def is_filter_cacheable(filter_query: Mapping[str, Any] | None) -> bool:
+    if filter_query is None:
+        return True
+    return not _contains_unsafe_construct(
+        filter_query, FILTER_UNSAFE_KEYS, NONDETERMINISTIC_SYSTEM_VARIABLES
+    )
+
+
+def is_projection_cacheable(
+    projection: Mapping[str, Any] | Sequence[str] | None,
+) -> bool:
+    if projection is None:
+        return True
+    return not _contains_unsafe_construct(projection, PROJECTION_UNSAFE_KEYS)

client_query_cache/_core/snapshots.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class CacheSnapshot:
+    lifecycle: str
+    used_bytes: int
+    shared_budget_bytes: int
+    max_entry_bytes: int
+    entry_count: int
+    hits: int
+    misses: int
+    evictions: int
+    bypasses: int
+    oversized_bypasses: int
+
+
+class CacheStatistics:
+    __slots__ = (
+        "_bypasses",
+        "_evictions",
+        "_hits",
+        "_lock",
+        "_misses",
+        "_oversized_bypasses",
+    )
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._hits = 0
+        self._misses = 0
+        self._evictions = 0
+        self._bypasses = 0
+        self._oversized_bypasses = 0
+
+    def record_hit(self) -> None:
+        with self._lock:
+            self._hits += 1
+
+    def record_miss(self) -> None:
+        with self._lock:
+            self._misses += 1
+
+    def record_evictions(self, count: int) -> None:
+        with self._lock:
+            self._evictions += count
+
+    def record_bypass(self) -> None:
+        with self._lock:
+            self._bypasses += 1
+
+    def record_oversized_bypass(self) -> None:
+        with self._lock:
+            self._oversized_bypasses += 1
+
+    def snapshot(self) -> tuple[int, int, int, int, int]:
+        with self._lock:
+            return (
+                self._hits,
+                self._misses,
+                self._evictions,
+                self._bypasses,
+                self._oversized_bypasses,
+            )

client_query_cache/_core/stream_cost.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import threading
+from collections import deque
+from dataclasses import dataclass
+
+from client_query_cache._core.errors import CacheConfigurationError
+
+INVALIDATION_LAG_CLOCK_SKEW_LIMITATION = (
+    "raw invalidation-delivery-lag values include unmeasured clock offset between "
+    "the mongod that originated the event and the observing host; they are not a "
+    "substitute for a same-clock, single-host latency measurement"
+)
+
+RESIDENT_BYTES_SCOPE = (
+    "manager-wide resident bytes across the shared LRU budget; not scoped to a "
+    "single namespace, collection, or stream"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class LagCaptureWindowConfig:
+    window_count: int
+    events_per_window: int
+    min_separation_events: int
+
+    def __post_init__(self) -> None:
+        if self.window_count <= 0:
+            message = "window_count must be positive"
+            raise CacheConfigurationError(message)
+        if self.events_per_window <= 0:
+            message = "events_per_window must be positive"
+            raise CacheConfigurationError(message)
+        if self.min_separation_events < 0:
+            message = "min_separation_events must not be negative"
+            raise CacheConfigurationError(message)
+
+
+DEFAULT_LAG_CAPTURE_WINDOW_CONFIG = LagCaptureWindowConfig(
+    window_count=10, events_per_window=100, min_separation_events=0
+)
+
+
+class LagCaptureWindows:
+    __slots__ = ("_config", "_current", "_lock", "_separation_remaining", "_windows")
+
+    def __init__(self, config: LagCaptureWindowConfig) -> None:
+        self._config = config
+        self._lock = threading.Lock()
+        self._windows: deque[tuple[float, ...]] = deque(maxlen=config.window_count)
+        self._current: list[float] = []
+        self._separation_remaining = 0
+
+    def record(self, raw_lag_seconds: float) -> bool:
+        with self._lock:
+            if self._separation_remaining > 0:
+                self._separation_remaining -= 1
+                return False
+            self._current.append(raw_lag_seconds)
+            if len(self._current) < self._config.events_per_window:
+                return True
+            self._windows.append(tuple(self._current))
+            self._current = []
+            self._separation_remaining = self._config.min_separation_events
+            return True
+
+    def reset(self) -> None:
+        with self._lock:
+            self._windows.clear()
+            self._current = []
+            self._separation_remaining = 0
+
+    def snapshot(self) -> tuple[tuple[float, ...], ...]:
+        with self._lock:
+            return tuple(self._windows)
+
+
+@dataclass(frozen=True, slots=True)
+class InvalidationApplyReading:
+    wall_seconds: float
+    monotonic_seconds: float
+
+
+@dataclass(frozen=True, slots=True)
+class StreamCostSnapshot:
+    database: str
+    stream_polls: int
+    logical_event_bytes: int
+    invalidations: int
+    invalidation_lag_windows: tuple[tuple[float, ...], ...]
+    invalidation_lag_clock_skew_limitation: str
+    invalidation_apply_readings: tuple[InvalidationApplyReading, ...]
+    resident_bytes: int
+    resident_bytes_scope: str
+
+
+class StreamCostStatistics:
+    __slots__ = (
+        "_apply_readings",
+        "_invalidations",
+        "_lag",
+        "_lock",
+        "_logical_event_bytes",
+        "_stream_polls",
+    )
+
+    def __init__(self, lag_config: LagCaptureWindowConfig) -> None:
+        self._lock = threading.Lock()
+        self._stream_polls = 0
+        self._logical_event_bytes = 0
+        self._invalidations = 0
+        self._lag = LagCaptureWindows(lag_config)
+        self._apply_readings: deque[InvalidationApplyReading] = deque(
+            maxlen=(lag_config.window_count + 1) * lag_config.events_per_window
+        )
+
+    def record_poll(self) -> None:
+        with self._lock:
+            self._stream_polls += 1
+
+    def record_logical_event_bytes(self, count: int) -> None:
+        with self._lock:
+            self._logical_event_bytes += count
+
+    def record_invalidation(
+        self, raw_lag_seconds: float, wall_seconds: float, monotonic_seconds: float
+    ) -> None:
+        with self._lock:
+            self._invalidations += 1
+            if self._lag.record(raw_lag_seconds):
+                self._apply_readings.append(
+                    InvalidationApplyReading(wall_seconds, monotonic_seconds)
+                )
+
+    def reset(self) -> None:
+        with self._lock:
+            self._stream_polls = 0
+            self._logical_event_bytes = 0
+            self._invalidations = 0
+            self._lag.reset()
+            self._apply_readings.clear()
+
+    def snapshot(
+        self,
+    ) -> tuple[
+        int,
+        int,
+        int,
+        tuple[tuple[float, ...], ...],
+        tuple[InvalidationApplyReading, ...],
+    ]:
+        with self._lock:
+            return (
+                self._stream_polls,
+                self._logical_event_bytes,
+                self._invalidations,
+                self._lag.snapshot(),
+                tuple(self._apply_readings),
+            )
+
+
+class StreamCostRegistry:
+    __slots__ = ("_lag_config", "_lock", "_streams")
+
+    def __init__(self, lag_config: LagCaptureWindowConfig) -> None:
+        self._lag_config = lag_config
+        self._lock = threading.Lock()
+        self._streams: dict[str, StreamCostStatistics] = {}
+
+    def _get_or_create(self, database: str) -> StreamCostStatistics:
+        with self._lock:
+            try:
+                return self._streams[database]
+            except KeyError:
+                stats = StreamCostStatistics(self._lag_config)
+                self._streams[database] = stats
+                return stats
+
+    def _get(self, database: str) -> StreamCostStatistics | None:
+        with self._lock:
+            try:
+                return self._streams[database]
+            except KeyError:
+                return None
+
+    def record_poll(self, database: str) -> None:
+        self._get_or_create(database).record_poll()
+
+    def record_logical_event_bytes(self, database: str, count: int) -> None:
+        self._get_or_create(database).record_logical_event_bytes(count)
+
+    def record_invalidation(
+        self,
+        database: str,
+        raw_lag_seconds: float,
+        wall_seconds: float,
+        monotonic_seconds: float,
+    ) -> None:
+        self._get_or_create(database).record_invalidation(
+            raw_lag_seconds, wall_seconds, monotonic_seconds
+        )
+
+    def reset(self, database: str) -> None:
+        stats = self._get(database)
+        if stats is not None:
+            stats.reset()
+
+    def reset_all(self) -> None:
+        with self._lock:
+            all_stats = list(self._streams.values())
+        for stats in all_stats:
+            stats.reset()
+
+    def snapshot(self, database: str, *, resident_bytes: int) -> StreamCostSnapshot:
+        stats = self._get(database)
+        if stats is None:
+            stream_polls, logical_event_bytes, invalidations = 0, 0, 0
+            lag_windows: tuple[tuple[float, ...], ...] = ()
+            apply_readings: tuple[InvalidationApplyReading, ...] = ()
+        else:
+            (
+                stream_polls,
+                logical_event_bytes,
+                invalidations,
+                lag_windows,
+                apply_readings,
+            ) = stats.snapshot()
+        return StreamCostSnapshot(
+            database=database,
+            stream_polls=stream_polls,
+            logical_event_bytes=logical_event_bytes,
+            invalidations=invalidations,
+            invalidation_lag_windows=lag_windows,
+            invalidation_lag_clock_skew_limitation=INVALIDATION_LAG_CLOCK_SKEW_LIMITATION,
+            invalidation_apply_readings=apply_readings,
+            resident_bytes=resident_bytes,
+            resident_bytes_scope=RESIDENT_BYTES_SCOPE,
+        )
+
+    def active_databases(self) -> list[str]:
+        with self._lock:
+            return list(self._streams)