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

client_query_cache/_core/stream_events.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import datetime
+import time
+from typing import TYPE_CHECKING, Any
+
+from bson.datetime_ms import DatetimeMS
+
+from client_query_cache._core.keys import NamespaceId
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from pymongo.errors import OperationFailure
+
+    from client_query_cache._core.manager import CacheCore
+
+NONRESUMABLE_CHANGE_STREAM_ERROR_LABEL = "NonResumableChangeStreamError"
+CHANGE_STREAM_HISTORY_LOST_CODE = 286
+
+WRITE_OPERATION_TYPES = frozenset({"insert", "update", "replace", "delete"})
+
+INDEX_OPERATION_TYPES = frozenset({"createIndexes", "dropIndexes"})
+
+RELEVANT_OPERATION_TYPES = (
+    WRITE_OPERATION_TYPES
+    | INDEX_OPERATION_TYPES
+    | frozenset({"drop", "dropDatabase", "rename", "create", "invalidate"})
+)
+
+CHANGE_STREAM_PROJECTION: Mapping[str, int] = {
+    "_id": 1,
+    "operationType": 1,
+    "ns": 1,
+    "documentKey": 1,
+    "to": 1,
+    "clusterTime": 1,
+    "wallTime": 1,
+}
+
+
+def build_change_stream_pipeline() -> list[Mapping[str, Any]]:
+    return [
+        {"$match": {"operationType": {"$in": sorted(RELEVANT_OPERATION_TYPES)}}},
+        {"$project": dict(CHANGE_STREAM_PROJECTION)},
+    ]
+
+
+def _namespace_from_ns(ns: Mapping[str, Any]) -> NamespaceId:
+    return NamespaceId(ns["db"], ns["coll"])
+
+
+def _wall_time_seconds(value: datetime.datetime | DatetimeMS) -> float:
+    if isinstance(value, DatetimeMS):
+        return int(value) / 1000.0
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=datetime.UTC)
+    return value.timestamp()
+
+
+def _record_invalidation(
+    cache: CacheCore, database: str, event: Mapping[str, Any]
+) -> None:
+    wall_seconds = time.time()
+    monotonic_seconds = time.monotonic()
+    raw_lag_seconds = wall_seconds - _wall_time_seconds(event["wallTime"])
+    cache.record_invalidation_applied(
+        database, raw_lag_seconds, wall_seconds, monotonic_seconds
+    )
+
+
+def _route_write(cache: CacheCore, database: str, event: Mapping[str, Any]) -> None:
+    namespace = _namespace_from_ns(event["ns"])
+    if cache.has_namespace(namespace):
+        cache.record_write(namespace, event["documentKey"]["_id"])
+        _record_invalidation(cache, database, event)
+
+
+def _route_create(cache: CacheCore, database: str, event: Mapping[str, Any]) -> None:
+    namespace = _namespace_from_ns(event["ns"])
+    if cache.has_namespace(namespace):
+        cache.create_namespace(namespace)
+        _record_invalidation(cache, database, event)
+
+
+def _route_drop(cache: CacheCore, database: str, event: Mapping[str, Any]) -> None:
+    namespace = _namespace_from_ns(event["ns"])
+    if cache.has_namespace(namespace):
+        cache.clear_namespace(namespace)
+        _record_invalidation(cache, database, event)
+
+
+def _route_index_change(
+    cache: CacheCore, database: str, event: Mapping[str, Any]
+) -> None:
+    namespace = _namespace_from_ns(event["ns"])
+    if cache.has_namespace(namespace):
+        cache.record_index_change(namespace)
+        _record_invalidation(cache, database, event)
+
+
+def _route_rename(cache: CacheCore, database: str, event: Mapping[str, Any]) -> None:
+    source = _namespace_from_ns(event["ns"])
+    destination = _namespace_from_ns(event["to"])
+    invalidated = False
+    if cache.has_namespace(source):
+        cache.clear_namespace(source)
+        invalidated = True
+    if destination.database == database and cache.has_namespace(destination):
+        cache.clear_namespace(destination)
+        invalidated = True
+    if invalidated:
+        _record_invalidation(cache, database, event)
+
+
+def _route_invalidate(
+    cache: CacheCore, database: str, event: Mapping[str, Any]
+) -> None:
+    cache.set_database_available(database, available=False)
+    namespaces = cache.namespaces_for_database(database)
+    for namespace in namespaces:
+        cache.clear_namespace(namespace)
+    if namespaces:
+        _record_invalidation(cache, database, event)
+
+
+def route_change_event(
+    cache: CacheCore, database: str, event: Mapping[str, Any]
+) -> bool:
+    operation_type = event["operationType"]
+    if operation_type in WRITE_OPERATION_TYPES:
+        _route_write(cache, database, event)
+        return False
+    if operation_type in INDEX_OPERATION_TYPES:
+        _route_index_change(cache, database, event)
+        return False
+    if operation_type == "create":
+        _route_create(cache, database, event)
+        return False
+    if operation_type == "drop":
+        _route_drop(cache, database, event)
+        return False
+    if operation_type == "rename":
+        _route_rename(cache, database, event)
+        return False
+    if operation_type == "dropDatabase":
+        _route_invalidate(cache, database, event)
+        return True
+    _route_invalidate(cache, database, event)
+    return True
+
+
+def is_unresumable_change_stream_error(error: OperationFailure) -> bool:
+    return (
+        error.has_error_label(NONRESUMABLE_CHANGE_STREAM_ERROR_LABEL)
+        or error.code == CHANGE_STREAM_HISTORY_LOST_CODE
+    )

client_query_cache/_core/stream_health.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import enum
+import random
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+DEFAULT_BASE_DELAY_SECONDS = 0.1
+DEFAULT_MAX_DELAY_SECONDS = 30.0
+DEFAULT_MULTIPLIER = 2.0
+
+
+class StreamHealth(enum.Enum):
+    STARTING = "starting"
+    CONNECTING = "connecting"
+    HEALTHY = "healthy"
+    RECONNECTING = "reconnecting"
+    CLOSED = "closed"
+
+
+@dataclass(slots=True)
+class RetryBackoff:
+    base_seconds: float = DEFAULT_BASE_DELAY_SECONDS
+    max_seconds: float = DEFAULT_MAX_DELAY_SECONDS
+    multiplier: float = DEFAULT_MULTIPLIER
+    _attempt: int = field(default=0, init=False)
+    _saturated: bool = field(default=False, init=False)
+
+    def reset(self) -> None:
+        self._attempt = 0
+        self._saturated = False
+
+    def next_delay(
+        self, random_uniform: Callable[[float, float], float] = random.uniform
+    ) -> float:
+        if self._saturated:
+            return random_uniform(0.0, self.max_seconds)
+        cap = self.base_seconds * (self.multiplier**self._attempt)
+        if cap >= self.max_seconds:
+            self._saturated = True
+            cap = self.max_seconds
+        else:
+            self._attempt += 1
+        return random_uniform(0.0, cap)

client_query_cache/_core/stream_options.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from client_query_cache._core.errors import CacheConfigurationError
+
+DEFAULT_MAX_AWAIT_TIME_MS = 1_000
+MAX_AWAIT_TIME_MS = 2**31 - 1
+
+
+def validate_max_await_time_ms(value: int) -> None:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise CacheConfigurationError("max_await_time_ms must be a positive integer")
+    if not 1 <= value <= MAX_AWAIT_TIME_MS:
+        message = f"max_await_time_ms must be between 1 and {MAX_AWAIT_TIME_MS}"
+        raise CacheConfigurationError(message)

client_query_cache/_core/unique_keys.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import threading
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from client_query_cache._core.canonical import is_canonicalizable
+from client_query_cache._core.collation import normalize_collation
+from client_query_cache._core.identity_reads import NO_IDENTITY, extract_equality_value
+
+if TYPE_CHECKING:
+    from client_query_cache._core.keys import NamespaceId
+
+
+@dataclass(frozen=True, slots=True)
+class UniqueKeyDefinition:
+    fields: tuple[str, ...]
+    collation: Mapping[str, Any] | None
+
+
+def _is_eligible_index(index_spec: Mapping[str, Any]) -> bool:
+    try:
+        is_unique = index_spec["unique"]
+    except KeyError:
+        is_unique = False
+    if not is_unique:
+        return False
+    if "partialFilterExpression" in index_spec:
+        return False
+    try:
+        is_sparse = index_spec["sparse"]
+    except KeyError:
+        is_sparse = False
+    if is_sparse:
+        return False
+    return not any(value == "hashed" for value in index_spec["key"].values())
+
+
+def discover_unique_keys(
+    index_specs: Sequence[Mapping[str, Any]],
+) -> tuple[UniqueKeyDefinition, ...]:
+    unique_keys = []
+    for index_spec in index_specs:
+        if not _is_eligible_index(index_spec):
+            continue
+        try:
+            collation = index_spec["collation"]
+        except KeyError:
+            collation = None
+        unique_keys.append(
+            UniqueKeyDefinition(
+                fields=tuple(index_spec["key"]),
+                collation=normalize_collation(collation),
+            )
+        )
+    return tuple(unique_keys)
+
+
+def _extract_ordered_values(
+    filter_query: Mapping[str, Any], fields: tuple[str, ...]
+) -> tuple[Any, ...] | None:
+    values: list[Any] = []
+    for field in fields:
+        value = extract_equality_value(filter_query[field])
+        if value is NO_IDENTITY or not is_canonicalizable(value):
+            return None
+        if (
+            isinstance(value, Sequence)
+            and not isinstance(value, (str, bytes, bytearray))
+            and not value
+        ):
+            return None
+        values.append(value)
+    return tuple(values)
+
+
+def match_unique_key(
+    filter_query: object,
+    keys: Sequence[UniqueKeyDefinition],
+    effective_collation: Mapping[str, Any] | None,
+) -> tuple[UniqueKeyDefinition, tuple[Any, ...]] | None:
+    if not isinstance(filter_query, Mapping):
+        return None
+    filter_fields = set(filter_query)
+    for key in keys:
+        if key.collation != effective_collation:
+            continue
+        if filter_fields != set(key.fields):
+            continue
+        values = _extract_ordered_values(filter_query, key.fields)
+        if values is not None:
+            return key, values
+    return None
+
+
+@dataclass(frozen=True, slots=True)
+class UniqueKeyMetadata:
+    checked_index_generation: int
+    keys: tuple[UniqueKeyDefinition, ...]
+
+
+class UniqueKeyMetadataCache:
+    __slots__ = ("_entries", "_lock")
+
+    def __init__(self) -> None:
+        self._entries: dict[NamespaceId, UniqueKeyMetadata] = {}
+        self._lock = threading.Lock()
+
+    def get(self, namespace: NamespaceId) -> UniqueKeyMetadata | None:
+        with self._lock:
+            try:
+                return self._entries[namespace]
+            except KeyError:
+                return None
+
+    def put(self, namespace: NamespaceId, metadata: UniqueKeyMetadata) -> None:
+        with self._lock:
+            self._entries[namespace] = metadata

client_query_cache/asynchronous/__init__.py

@@ -0,0 +1,16 @@
+from client_query_cache._core.manager import CacheCore, CacheCoreConfig
+
+from .collection import CachedCollection
+from .database import CachedDatabase
+from .manager import CacheManager
+from .streams import ChangeStreamCoordinator, DatabaseStreamSupervisor
+
+__all__ = [
+    "CacheCore",
+    "CacheCoreConfig",
+    "CacheManager",
+    "CachedCollection",
+    "CachedDatabase",
+    "ChangeStreamCoordinator",
+    "DatabaseStreamSupervisor",
+]