client-query-cache 0.3.0__tar.gz → 0.5.0__tar.gz

{client_query_cache-0.3.0 → client_query_cache-0.5.0}/PKG-INFO

@@ -1,12 +1,14 @@
 Metadata-Version: 2.3
 Name: client-query-cache
-Version: 0.3.0
+Version: 0.5.0
 Summary: Client-side caching for PyMongo, kept coherent using MongoDB change streams.
 Author: Alessio Locatelli
 Author-email: Alessio Locatelli <<software.development@secure.mailbox.org>>
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Requires-Dist: pymongo>=4.18.1
 Requires-Dist: opentelemetry-api>=1.45.0 ; extra == 'otel'
-Requires-Python: >=3.14.6
+Requires-Python: >=3.14
 Project-URL: Repository, https://github.com/alessio-locatelli/client-query-cache
 Project-URL: Documentation, https://alessio-locatelli.github.io/client-query-cache/
 Provides-Extra: otel
@@ -14,7 +16,7 @@ Description-Content-Type: text/markdown
 
 # Coherent client-side caching for PyMongo
 
-[![Python 3.14.6+](https://img.shields.io/badge/python-3.14.6%2B-blue.svg)](https://www.python.org/downloads/)
+[![Supported Python versions on PyPI](https://img.shields.io/pypi/pyversions/client-query-cache.svg)](https://pypi.org/project/client-query-cache/)
 
 `client-query-cache` uses MongoDB change streams to keep cached reads coherent. It supports synchronous and asyncio applications without requiring a separate cache server.
 
@@ -45,7 +47,7 @@ with (
     MongoClient("mongodb://localhost:27017") as client,
     CacheManager(client) as cache,
 ):
-    users = cache.cached(client["my_database"]["users"])
+    users = cache.get_cached_collection(client["my_database"]["users"])
     users.find_one({"_id": "alice"})  # Reads from MongoDB.
     users.find_one({"_id": "alice"})  # Repeated reads can use the cache.
 ```

{client_query_cache-0.3.0 → client_query_cache-0.5.0}/README.md

@@ -1,6 +1,6 @@
 # Coherent client-side caching for PyMongo
 
-[![Python 3.14.6+](https://img.shields.io/badge/python-3.14.6%2B-blue.svg)](https://www.python.org/downloads/)
+[![Supported Python versions on PyPI](https://img.shields.io/pypi/pyversions/client-query-cache.svg)](https://pypi.org/project/client-query-cache/)
 
 `client-query-cache` uses MongoDB change streams to keep cached reads coherent. It supports synchronous and asyncio applications without requiring a separate cache server.
 
@@ -31,7 +31,7 @@ with (
     MongoClient("mongodb://localhost:27017") as client,
     CacheManager(client) as cache,
 ):
-    users = cache.cached(client["my_database"]["users"])
+    users = cache.get_cached_collection(client["my_database"]["users"])
     users.find_one({"_id": "alice"})  # Reads from MongoDB.
     users.find_one({"_id": "alice"})  # Repeated reads can use the cache.
 ```

{client_query_cache-0.3.0 → client_query_cache-0.5.0}/pyproject.toml

@@ -1,9 +1,13 @@
 [project]
 name = "client-query-cache"
-version = "0.3.0"
+version = "0.5.0"
 description = "Client-side caching for PyMongo, kept coherent using MongoDB change streams."
 readme = "README.md"
-requires-python = ">=3.14.6"
+requires-python = ">=3.14"
+classifiers = [
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
 dependencies = ["pymongo>=4.18.1"]
 
 [[project.authors]]
@@ -46,6 +50,8 @@ dev = [
     "python-snappy>=0.7.3",
     "pytest-xdist[psutil]>=3.8.0",
     "pytest-cov>=7.1.0",
+    "pyyaml>=6.0.3",
+    "types-pyyaml>=6.0.12.20260906",
 ]
 docs = [
     "mike",
@@ -61,16 +67,11 @@ build-backend = "uv_build"
 [tool.uv]
 environments = ["sys_platform == 'linux'"]
 
-[tool.uv.build-backend]
-module-root = "src"
-
 [tool.uv.sources.mike]
 git = "https://github.com/squidfunk/mike.git"
 rev = "2d4ad799442f4592db8ad53b179bfb33db8c69ac"
 
 [tool.slotscheck]
-strict-imports = true
-require-superclass = true
 require-subclass = true
 exclude-modules = """
 (

{client_query_cache-0.3.0 → client_query_cache-0.5.0}/pyproject.toml.orig

@@ -1,12 +1,16 @@
 [project]
 name = "client-query-cache"
-version = "0.3.0"
+version = "0.5.0"
 description = "Client-side caching for PyMongo, kept coherent using MongoDB change streams."
 authors = [
   { name = "Alessio Locatelli", email = "<software.development@secure.mailbox.org>" },
 ]
 readme = "README.md"
-requires-python = ">=3.14.6"
+requires-python = ">=3.14"
+classifiers = [
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+]
 dependencies = ["pymongo>=4.18.1"]
 
 [project.urls]
@@ -45,6 +49,8 @@ dev = [
   "python-snappy>=0.7.3",
   "pytest-xdist[psutil]>=3.8.0",
   "pytest-cov>=7.1.0",
+  "pyyaml>=6.0.3",
+  "types-pyyaml>=6.0.12.20260906",
 ]
 docs = ["mike", "tomli-w>=1.2.0", "zensical>=0.0.68"]
 memory = ["pytest-memray>=1.11.0"]
@@ -53,18 +59,17 @@ memory = ["pytest-memray>=1.11.0"]
 requires = ["uv_build>=0.12.18,<0.13.0"]
 build-backend = "uv_build"
 
-[tool.uv.build-backend]
-module-root = "src"
-
 [tool.uv]
+# uv 0.12.9 / lock context: https://docs.astral.sh/uv/reference/settings/#environments
+# The default is all environments. We override it because development dependencies and their lock resolution target Linux.
 environments = ["sys_platform == 'linux'"]
 
 [tool.uv.sources]
 mike = { git = "https://github.com/squidfunk/mike.git", rev = "2d4ad799442f4592db8ad53b179bfb33db8c69ac" } # pragma: allowlist secret
 
 [tool.slotscheck]
-strict-imports = true
-require-superclass = true
+# slotscheck 0.21.0: https://github.com/ariebovenberg/slotscheck/blob/v0.21.0/src/slotscheck/config.py
+# require-subclass: The default is false. We override it because subclasses must preserve their slotted parent's memory contract.
 require-subclass = true
 exclude-modules = '''
 (
@@ -77,10 +82,15 @@ exclude-modules = '''
 paths = ["src", "tests", "benchmarks", ".vulture_whitelist"]
 
 [tool.ruff-extra-rules]
+# ruff-extra-rules v0.5.0: https://github.com/alessio-locatelli/ruff-extra-rules/blob/v0.5.0/README.md
+# The default is false. We override it because hook runs should apply available repairs.
 fix = true
 exclude = ["specifications"]
 extend-select = ["unused-pytriage"]
 [tool.ruff-extra-rules.meaningless-vars]
+# ruff-extra-rules v0.5.0: https://github.com/alessio-locatelli/ruff-extra-rules/tree/v0.5.0/src/pre_commit_hooks/ast_checks
+# For meaningless-vars, redundant-assignment, redundant-type-conversion, redundant-dict-get, and defined-far-from-use level:
+# The default is conservative. We override it because repository quality checks must include the broader supported simplifications and naming diagnostics.
 level = "aggressive"
 [tool.ruff-extra-rules.redundant-assignment]
 level = "aggressive"

client_query_cache-0.5.0/src/client_query_cache/_core/stream_activation.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+from time import monotonic
+
+from client_query_cache._core.stream_health import RetryBackoff
+
+
+def _startup_jitter(_low: float, cap: float) -> float:
+    return random.uniform(cap / 2, cap)
+
+
+@dataclass(slots=True)
+class StartupRetry:
+    deadline: float = 0.0  # Zero permits the first attempt.
+    backoff: RetryBackoff = field(default_factory=RetryBackoff)
+
+    def ready(self) -> bool:
+        return monotonic() >= self.deadline
+
+    def failed(self) -> None:
+        self.deadline = monotonic() + self.backoff.next_delay(_startup_jitter)
+
+
+@dataclass(slots=True)
+class StreamActivation[Supervisor, Completion]:
+    supervisor: Supervisor
+    completion: Completion
+    pending: bool = True
+    retry: StartupRetry = field(default_factory=StartupRetry)

{client_query_cache-0.3.0 → client_query_cache-0.5.0}/src/client_query_cache/_core/stream_health.py

@@ -63,6 +63,10 @@ class StreamHealthRegistry:
             str, StreamHealthStatus | Callable[[], StreamHealthStatus]
         ] = {}  # Can be empty.
 
+    def record_connecting(self, database_name: str) -> None:
+        with self._lock:
+            self._states[database_name] = StreamHealthStatus.CONNECTING
+
     def record_starting(
         self, database_name: str, health: Callable[[], StreamHealthStatus]
     ) -> None:

{client_query_cache-0.3.0 → client_query_cache-0.5.0}/src/client_query_cache/asynchronous/collection.py

@@ -178,7 +178,7 @@ class CachedCollection[DocumentType: Mapping[str, Any]]:
             )
         effective_collation = effective_find_one_collation(
             collation,
-            self._database.manager.default_collation_for(self._namespace()),
+            self._database.manager._default_collation_for(self._namespace()),  # noqa: SLF001
         )
         if collation is None and effective_collation is not None:
             read_shape = canonicalize(
@@ -195,7 +195,7 @@ class CachedCollection[DocumentType: Mapping[str, Any]]:
             )
         namespace = self._namespace()
         cache = self._database.manager.cache_core
-        known_keys = await self._database.manager.unique_keys_for(namespace)
+        known_keys = await self._database.manager._unique_keys_for(namespace)  # noqa: SLF001
         unique_key_match = (
             match_unique_key(filter_query, known_keys, effective_collation)
             if identity is NO_IDENTITY and known_keys is not None
@@ -495,7 +495,7 @@ class CachedCollection[DocumentType: Mapping[str, Any]]:
     async def _match_unique_key(
         self, filter_query: object, effective_collation: Mapping[str, Any] | None
     ) -> tuple[UniqueKeyDefinition, tuple[Any, ...]] | None:
-        keys = await self._database.manager.unique_keys_for(
+        keys = await self._database.manager._unique_keys_for(  # noqa: SLF001
             self._namespace(), self._list_indexes_probe
         )
         if not keys:
@@ -655,7 +655,7 @@ class CachedCollection[DocumentType: Mapping[str, Any]]:
         return self._forced_database
 
     async def _cache_ineligibility_reason(self) -> BypassReason | None:
-        return await self._database.manager.cache_ineligibility_reason(
+        return await self._database.manager._cache_ineligibility_reason(  # noqa: SLF001
             self._namespace(), self._probe_collection
         )
 

{client_query_cache-0.3.0 → client_query_cache-0.5.0}/src/client_query_cache/asynchronous/manager.py

@@ -76,21 +76,13 @@ class CacheManager[DocumentType: Mapping[str, Any]]:
     def active_stream_cost_databases(self) -> list[str]:
         return self._cache.active_stream_cost_databases()
 
-    async def ensure_cache_eligible(
-        self,
-        namespace: NamespaceId,
-        collection_probe: Callable[[], Awaitable[CollectionProbeResult | None]],
-    ) -> bool:
-        return (
-            await self.cache_ineligibility_reason(namespace, collection_probe) is None
-        )
-
-    async def cache_ineligibility_reason(
+    async def _cache_ineligibility_reason(
         self,
         namespace: NamespaceId,
         collection_probe: Callable[[], Awaitable[CollectionProbeResult | None]],
     ) -> BypassReason | None:
-        await self._coordinator.activate_database(namespace.database)
+        if await self._coordinator.activate_database(namespace.database) is None:
+            return BypassReason.STREAM_UNAVAILABLE
         if not self._cache.is_database_available(namespace.database):
             return BypassReason.STREAM_UNAVAILABLE
         current_epoch = self._cache.current_epoch(namespace)
@@ -112,23 +104,25 @@ class CacheManager[DocumentType: Mapping[str, Any]]:
             self._metadata.put(namespace, cached)
         return cached.bypass_reason
 
-    def default_collation_for(self, namespace: NamespaceId) -> Mapping[str, Any] | None:
+    def _default_collation_for(
+        self, namespace: NamespaceId
+    ) -> Mapping[str, Any] | None:
         cached = self._metadata.get(namespace)
         return cached.default_collation if cached is not None else None
 
     @overload
-    async def unique_keys_for(
+    async def _unique_keys_for(
         self,
         namespace: NamespaceId,
         list_indexes: Callable[[], Awaitable[Sequence[Mapping[str, Any]] | None]],
     ) -> tuple[UniqueKeyDefinition, ...]: ...
 
     @overload
-    async def unique_keys_for(
+    async def _unique_keys_for(
         self, namespace: NamespaceId, list_indexes: None = None
     ) -> tuple[UniqueKeyDefinition, ...] | None: ...
 
-    async def unique_keys_for(
+    async def _unique_keys_for(
         self,
         namespace: NamespaceId,
         list_indexes: Callable[[], Awaitable[Sequence[Mapping[str, Any]] | None]]
@@ -154,7 +148,7 @@ class CacheManager[DocumentType: Mapping[str, Any]]:
     def __getitem__(self, name: str) -> CachedDatabase[DocumentType]:
         return CachedDatabase(self, self._client[name])
 
-    def cached(
+    def get_cached_collection(
         self, collection: AsyncCollection[DocumentType]
     ) -> CachedCollection[DocumentType]:
         if collection.database.client is not self._client:
@@ -166,8 +160,10 @@ class CacheManager[DocumentType: Mapping[str, Any]]:
         return CachedCollection(CachedDatabase(self, collection.database), collection)
 
     async def close(self) -> None:
-        await self._coordinator.close()
-        self._cache.close()
+        try:
+            await self._coordinator.close()
+        finally:
+            self._cache.close()
 
     async def __aenter__(self) -> Self:
         return self

{client_query_cache-0.3.0 → client_query_cache-0.5.0}/src/client_query_cache/asynchronous/streams.py

@@ -9,6 +9,7 @@ from bson.errors import BSONError
 from pymongo.errors import OperationFailure, PyMongoError
 
 from client_query_cache._core.errors import StreamLifecycleError, StreamStartupError
+from client_query_cache._core.stream_activation import StreamActivation
 from client_query_cache._core.stream_events import (
     build_change_stream_pipeline,
     is_unresumable_change_stream_error,
@@ -38,14 +39,28 @@ MINIMUM_SERVER_VERSION = (8, 0)
 logger = logging.getLogger(__name__)
 
 
+async def _join_cleanup(task: asyncio.Task[None]) -> None:
+    cancelled = False
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            cancelled = True
+    task.result()
+    if cancelled:
+        raise asyncio.CancelledError
+
+
 class DatabaseStreamSupervisor:
     __slots__ = (
         "_backoff",
         "_cache",
+        "_closed_stream",
         "_database",
         "_health",
         "_max_await_time_ms",
         "_resume_token",
+        "_shutdown_task",
         "_stop_event",
         "_stream",
         "_task",
@@ -65,9 +80,11 @@ class DatabaseStreamSupervisor:
         self._max_await_time_ms = max_await_time_ms
         self._health = StreamHealth.STARTING
         self._stream: AsyncDatabaseChangeStream[Any] | None = None
+        self._closed_stream: AsyncDatabaseChangeStream[Any] | None = None
         self._resume_token: Mapping[str, Any] | None = None
         self._stop_event = asyncio.Event()
         self._task: asyncio.Task[None] | None = None
+        self._shutdown_task: asyncio.Task[None] | None = None
         self._cache.set_database_available(self._database.name, available=False)
 
     @property
@@ -96,29 +113,30 @@ class DatabaseStreamSupervisor:
             )
             raise StreamStartupError(message) from exc
         except asyncio.CancelledError:
-            self._set_health(StreamHealth.CLOSED)
-            stream = self._stream
-            if stream is not None:
-                try:
-                    await stream.close()
-                except PyMongoError:
-                    pass
+            await self.stop()
             raise
         if self._stop_event.is_set():
-            assert self._stream is not None
-            try:
-                await self._stream.close()
-            except PyMongoError:
-                pass
-            self._set_health(StreamHealth.CLOSED)
+            await self.stop()
             message = "stop() was called while start() was still connecting"
             raise StreamLifecycleError(message)
         self._set_health(StreamHealth.HEALTHY)
         self._task = asyncio.ensure_future(self._run())
 
-    async def stop(self) -> None:
+    def request_stop(self) -> None:
         self._stop_event.set()
         self._set_health(StreamHealth.CLOSED)
+        if self._task is not None:
+            self._task.cancel()
+
+    async def stop(self) -> None:
+        self.request_stop()
+        if self._shutdown_task is None or (
+            self._shutdown_task.done() and self._stream is not self._closed_stream
+        ):
+            self._shutdown_task = asyncio.create_task(self._finish_stop())
+        await _join_cleanup(self._shutdown_task)
+
+    async def _finish_stop(self) -> None:
         task = self._task
         if task is not None:
             task.cancel()
@@ -136,6 +154,7 @@ class DatabaseStreamSupervisor:
                     extra={"database": self._database.name},
                     exc_info=True,
                 )
+        self._closed_stream = stream
         self._set_health(StreamHealth.CLOSED)
 
     def _set_health(self, health: StreamHealth) -> None:
@@ -177,11 +196,6 @@ class DatabaseStreamSupervisor:
                 await previous_stream.close()
             except PyMongoError:
                 pass
-        if self._stop_event.is_set():
-            try:
-                await self._stream.close()
-            except PyMongoError:
-                pass
 
     async def _interruptible_sleep(self, delay: float) -> bool:
         try:
@@ -268,12 +282,14 @@ class DatabaseStreamSupervisor:
 
 class ChangeStreamCoordinator:
     __slots__ = (
+        "_activations",
         "_cache",
         "_client",
         "_closed",
         "_health_registry",
         "_lock",
         "_max_await_time_ms",
+        "_shutdown_task",
         "_supervisors",
     )
 
@@ -287,49 +303,109 @@ class ChangeStreamCoordinator:
         self._client = client
         self._max_await_time_ms = max_await_time_ms
         self._cache = cache
+        self._activations: dict[
+            str, StreamActivation[DatabaseStreamSupervisor, asyncio.Event]
+        ] = {}  # Can be empty.
         self._supervisors: dict[str, DatabaseStreamSupervisor] = {}
         self._closed = False
         self._health_registry = StreamHealthRegistry()
         self._lock = asyncio.Lock()
+        self._shutdown_task: asyncio.Task[None] | None = None
 
     async def activate_database(self, name: str) -> DatabaseStreamSupervisor | None:
         async with self._lock:
             if self._closed:
                 raise StreamLifecycleError("coordinator is closed")
             try:
-                supervisor = self._supervisors[name]
+                return self._supervisors[name]
             except KeyError:
-                supervisor = DatabaseStreamSupervisor(
-                    self._client[name],
-                    self._cache,
-                    max_await_time_ms=self._max_await_time_ms,
+                pass
+            try:
+                activation = self._activations[name]
+            except KeyError:
+                activation = None
+            if activation is not None and (
+                activation.pending or not activation.retry.ready()
+            ):
+                return None
+            supervisor = DatabaseStreamSupervisor(
+                self._client[name],
+                self._cache,
+                max_await_time_ms=self._max_await_time_ms,
+            )
+            if activation is None:
+                activation = StreamActivation(supervisor, asyncio.Event())
+                self._activations[name] = activation
+            else:
+                activation.supervisor = supervisor
+                activation.pending = True
+                activation.completion.clear()
+            self._health_registry.record_connecting(name)
+        published = False
+        try:
+            try:
+                await supervisor.start()
+            except StreamStartupError:
+                async with self._lock:
+                    if not self._closed:
+                        activation.retry.failed()
+                        self._health_registry.record_startup_failure(name)
+                logger.warning(
+                    "change stream startup failed for database %r; reads for "
+                    "this database will bypass the cache",
+                    name,
+                    exc_info=True,
                 )
-                self._health_registry.record_starting(name, supervisor.health_status)
-                try:
-                    await supervisor.start()
-                except StreamStartupError:
-                    self._health_registry.record_startup_failure(name)
-                    logger.warning(
-                        "change stream startup failed for database %r; reads for "
-                        "this database will bypass the cache",
-                        name,
-                        exc_info=True,
-                    )
-                    return None
-                except asyncio.CancelledError:
-                    self._health_registry.record_startup_failure(name)
-                    raise
+                return None
+            async with self._lock:
+                if self._closed:
+                    raise StreamLifecycleError("coordinator is closed")
                 self._supervisors[name] = supervisor
+                del self._activations[name]
+                self._health_registry.record_starting(name, supervisor.health_status)
+                published = True
             return supervisor
+        finally:
+            if not published:
+                try:
+                    await supervisor.stop()
+                finally:
+                    async with self._lock:
+                        if not self._closed:
+                            self._health_registry.record_startup_failure(name)
+                        activation.pending = False
+                        activation.completion.set()
+            else:
+                activation.completion.set()
 
     def stream_health_snapshot(self, database_name: str) -> StreamHealthSnapshot:
         return self._health_registry.snapshot(database_name)
 
     async def close(self) -> None:
-        async with self._lock:
+        if self._shutdown_task is None:
             self._closed = True
             self._health_registry.close()
-            supervisors = list(self._supervisors.values())
-            self._supervisors.clear()
+            supervisors = tuple(self._supervisors.values())
+            activations = tuple(self._activations.values())
+            for supervisor in supervisors:
+                supervisor.request_stop()
+            for activation in activations:
+                activation.supervisor.request_stop()
+            self._shutdown_task = asyncio.create_task(
+                self._finish_close(supervisors, activations)
+            )
+        await _join_cleanup(self._shutdown_task)
+
+    async def _finish_close(
+        self,
+        supervisors: tuple[DatabaseStreamSupervisor, ...],
+        activations: tuple[
+            StreamActivation[DatabaseStreamSupervisor, asyncio.Event], ...
+        ],
+    ) -> None:
+        for activation in activations:
+            await activation.completion.wait()
         for supervisor in supervisors:
             await supervisor.stop()
+        self._activations.clear()
+        self._supervisors.clear()

{client_query_cache-0.3.0 → client_query_cache-0.5.0}/src/client_query_cache/synchronous/collection.py

@@ -178,7 +178,7 @@ class CachedCollection[DocumentType: Mapping[str, Any]]:
             )
         effective_collation = effective_find_one_collation(
             collation,
-            self._database.manager.default_collation_for(self._namespace()),
+            self._database.manager._default_collation_for(self._namespace()),  # noqa: SLF001
         )
         if collation is None and effective_collation is not None:
             read_shape = canonicalize(
@@ -195,7 +195,7 @@ class CachedCollection[DocumentType: Mapping[str, Any]]:
             )
         namespace = self._namespace()
         cache = self._database.manager.cache_core
-        known_keys = self._database.manager.unique_keys_for(namespace)
+        known_keys = self._database.manager._unique_keys_for(namespace)  # noqa: SLF001
         unique_key_match = (
             match_unique_key(filter_query, known_keys, effective_collation)
             if identity is NO_IDENTITY and known_keys is not None
@@ -491,7 +491,7 @@ class CachedCollection[DocumentType: Mapping[str, Any]]:
     def _match_unique_key(
         self, filter_query: object, effective_collation: Mapping[str, Any] | None
     ) -> tuple[UniqueKeyDefinition, tuple[Any, ...]] | None:
-        keys = self._database.manager.unique_keys_for(
+        keys = self._database.manager._unique_keys_for(  # noqa: SLF001
             self._namespace(), self._list_indexes_probe
         )
         if not keys:
@@ -651,7 +651,7 @@ class CachedCollection[DocumentType: Mapping[str, Any]]:
         return self._forced_database
 
     def _cache_ineligibility_reason(self) -> BypassReason | None:
-        return self._database.manager.cache_ineligibility_reason(
+        return self._database.manager._cache_ineligibility_reason(  # noqa: SLF001
             self._namespace(), self._probe_collection
         )
 

{client_query_cache-0.3.0 → client_query_cache-0.5.0}/src/client_query_cache/synchronous/manager.py

@@ -76,19 +76,13 @@ class CacheManager[DocumentType: Mapping[str, Any]]:
     def active_stream_cost_databases(self) -> list[str]:
         return self._cache.active_stream_cost_databases()
 
-    def ensure_cache_eligible(
-        self,
-        namespace: NamespaceId,
-        collection_probe: Callable[[], CollectionProbeResult | None],
-    ) -> bool:
-        return self.cache_ineligibility_reason(namespace, collection_probe) is None
-
-    def cache_ineligibility_reason(
+    def _cache_ineligibility_reason(
         self,
         namespace: NamespaceId,
         collection_probe: Callable[[], CollectionProbeResult | None],
     ) -> BypassReason | None:
-        self._coordinator.activate_database(namespace.database)
+        if self._coordinator.activate_database(namespace.database) is None:
+            return BypassReason.STREAM_UNAVAILABLE
         if not self._cache.is_database_available(namespace.database):
             return BypassReason.STREAM_UNAVAILABLE
         current_epoch = self._cache.current_epoch(namespace)
@@ -110,23 +104,25 @@ class CacheManager[DocumentType: Mapping[str, Any]]:
             self._metadata.put(namespace, cached)
         return cached.bypass_reason
 
-    def default_collation_for(self, namespace: NamespaceId) -> Mapping[str, Any] | None:
+    def _default_collation_for(
+        self, namespace: NamespaceId
+    ) -> Mapping[str, Any] | None:
         cached = self._metadata.get(namespace)
         return cached.default_collation if cached is not None else None
 
     @overload
-    def unique_keys_for(
+    def _unique_keys_for(
         self,
         namespace: NamespaceId,
         list_indexes: Callable[[], Sequence[Mapping[str, Any]] | None],
     ) -> tuple[UniqueKeyDefinition, ...]: ...
 
     @overload
-    def unique_keys_for(
+    def _unique_keys_for(
         self, namespace: NamespaceId, list_indexes: None = None
     ) -> tuple[UniqueKeyDefinition, ...] | None: ...
 
-    def unique_keys_for(
+    def _unique_keys_for(
         self,
         namespace: NamespaceId,
         list_indexes: Callable[[], Sequence[Mapping[str, Any]] | None] | None = None,
@@ -151,7 +147,7 @@ class CacheManager[DocumentType: Mapping[str, Any]]:
     def __getitem__(self, name: str) -> CachedDatabase[DocumentType]:
         return CachedDatabase(self, self._client[name])
 
-    def cached(
+    def get_cached_collection(
         self, collection: Collection[DocumentType]
     ) -> CachedCollection[DocumentType]:
         if collection.database.client is not self._client:

{client_query_cache-0.3.0 → client_query_cache-0.5.0}/src/client_query_cache/synchronous/streams.py

@@ -9,6 +9,7 @@ from bson.errors import BSONError
 from pymongo.errors import OperationFailure, PyMongoError
 
 from client_query_cache._core.errors import StreamLifecycleError, StreamStartupError
+from client_query_cache._core.stream_activation import StreamActivation
 from client_query_cache._core.stream_events import (
     build_change_stream_pipeline,
     is_unresumable_change_stream_error,
@@ -103,41 +104,45 @@ class DatabaseStreamSupervisor:
             )
             raise StreamStartupError(message) from exc
         with self._lifecycle_lock:
-            if self._stop_event.is_set():
-                assert self._stream is not None
-                try:
-                    self._stream.close()
-                except PyMongoError:
-                    pass
-                self._set_health(StreamHealth.CLOSED)
-                message = "stop() was called while start() was still connecting"
-                raise StreamLifecycleError(message)
-            self._set_health(StreamHealth.HEALTHY)
-            self._thread = threading.Thread(
-                target=self._run,
-                name=f"client-query-cache-stream-{self._database.name}",
-                daemon=True,
-            )
-            self._thread.start()
+            stopped = self._stop_event.is_set()
+            if not stopped:
+                self._set_health(StreamHealth.HEALTHY)
+                self._thread = threading.Thread(
+                    target=self._run,
+                    name=f"client-query-cache-stream-{self._database.name}",
+                    daemon=True,
+                )
+                self._thread.start()
+        if stopped:
+            self.stop()
+            message = "stop() was called while start() was still connecting"
+            raise StreamLifecycleError(message)
 
-    def stop(self) -> None:
+    def request_stop(self) -> None:
         with self._lifecycle_lock:
             self._stop_event.set()
             self._set_health(StreamHealth.CLOSED)
+
+    def stop(self) -> None:
+        self.request_stop()
+        with self._lifecycle_lock:
             stream = self._stream
-            if stream is not None:
-                try:
-                    stream.close()
-                except PyMongoError:
-                    logger.warning(
-                        "change stream close failed during shutdown",
-                        extra={"database": self._database.name},
-                        exc_info=True,
-                    )
             thread = self._thread
+        if stream is not None:
+            try:
+                stream.close()
+            except PyMongoError:
+                logger.warning(
+                    "change stream close failed during shutdown",
+                    extra={"database": self._database.name},
+                    exc_info=True,
+                )
         if thread is not None:
             thread.join()
-        self._set_health(StreamHealth.CLOSED)
+        with self._lifecycle_lock:
+            if self._stream is stream:
+                self._stream = None
+            self._set_health(StreamHealth.CLOSED)
 
     def _ensure_server_supports_expanded_events(self) -> None:
         server_info = self._database.client.server_info()
@@ -168,11 +173,13 @@ class DatabaseStreamSupervisor:
                 previous_stream.close()
             except PyMongoError:
                 pass
+
         if self._stop_event.is_set():
             try:
                 self._stream.close()
             except PyMongoError:
                 pass
+            self._stream = None
 
     def _set_health(self, health: StreamHealth) -> None:
         with self._lifecycle_lock:
@@ -262,12 +269,14 @@ class DatabaseStreamSupervisor:
 
 class ChangeStreamCoordinator:
     __slots__ = (
+        "_activations",
         "_cache",
         "_client",
         "_closed",
         "_health_registry",
         "_lock",
         "_max_await_time_ms",
+        "_shutdown_complete",
         "_supervisors",
     )
 
@@ -281,46 +290,105 @@ class ChangeStreamCoordinator:
         self._client = client
         self._max_await_time_ms = max_await_time_ms
         self._cache = cache
+        self._activations: dict[
+            str, StreamActivation[DatabaseStreamSupervisor, threading.Event]
+        ] = {}  # Can be empty.
         self._supervisors: dict[str, DatabaseStreamSupervisor] = {}
         self._closed = False
         self._health_registry = StreamHealthRegistry()
         self._lock = threading.Lock()
+        self._shutdown_complete = threading.Event()
 
     def activate_database(self, name: str) -> DatabaseStreamSupervisor | None:
         with self._lock:
             if self._closed:
                 raise StreamLifecycleError("coordinator is closed")
             try:
-                supervisor = self._supervisors[name]
+                return self._supervisors[name]
             except KeyError:
-                supervisor = DatabaseStreamSupervisor(
-                    self._client[name],
-                    self._cache,
-                    max_await_time_ms=self._max_await_time_ms,
+                pass
+            try:
+                activation = self._activations[name]
+            except KeyError:
+                activation = None
+            if activation is not None and (
+                activation.pending or not activation.retry.ready()
+            ):
+                return None
+            supervisor = DatabaseStreamSupervisor(
+                self._client[name],
+                self._cache,
+                max_await_time_ms=self._max_await_time_ms,
+            )
+            if activation is None:
+                activation = StreamActivation(supervisor, threading.Event())
+                self._activations[name] = activation
+            else:
+                activation.supervisor = supervisor
+                activation.pending = True
+                activation.completion.clear()
+            self._health_registry.record_connecting(name)
+        published = False
+        try:
+            try:
+                supervisor.start()
+            except StreamStartupError:
+                with self._lock:
+                    if not self._closed:
+                        activation.retry.failed()
+                        self._health_registry.record_startup_failure(name)
+                logger.warning(
+                    "change stream startup failed for database %r; reads for "
+                    "this database will bypass the cache",
+                    name,
+                    exc_info=True,
                 )
-                self._health_registry.record_starting(name, supervisor.health_status)
-                try:
-                    supervisor.start()
-                except StreamStartupError:
-                    self._health_registry.record_startup_failure(name)
-                    logger.warning(
-                        "change stream startup failed for database %r; reads for "
-                        "this database will bypass the cache",
-                        name,
-                        exc_info=True,
-                    )
-                    return None
+                return None
+            with self._lock:
+                if self._closed:
+                    raise StreamLifecycleError("coordinator is closed")
                 self._supervisors[name] = supervisor
+                del self._activations[name]
+                self._health_registry.record_starting(name, supervisor.health_status)
+                published = True
             return supervisor
+        finally:
+            if not published:
+                try:
+                    supervisor.stop()
+                finally:
+                    with self._lock:
+                        if not self._closed:
+                            self._health_registry.record_startup_failure(name)
+                        activation.pending = False
+                        activation.completion.set()
+            else:
+                activation.completion.set()
 
     def stream_health_snapshot(self, database_name: str) -> StreamHealthSnapshot:
         return self._health_registry.snapshot(database_name)
 
     def close(self) -> None:
         with self._lock:
-            self._closed = True
-            self._health_registry.close()
-            supervisors = list(self._supervisors.values())
-            self._supervisors.clear()
-        for supervisor in supervisors:
-            supervisor.stop()
+            owns_cleanup = not self._closed
+            if owns_cleanup:
+                self._closed = True
+                self._health_registry.close()
+                supervisors = tuple(self._supervisors.values())
+                activations = tuple(self._activations.values())
+                for supervisor in supervisors:
+                    supervisor.request_stop()
+                for activation in activations:
+                    activation.supervisor.request_stop()
+                self._supervisors.clear()
+                self._activations.clear()
+        if not owns_cleanup:
+            self._shutdown_complete.wait()
+            return
+        try:
+            for activation in activations:
+                activation.completion.wait()
+            for supervisor in supervisors:
+                supervisor.stop()
+        finally:
+            self._shutdown_complete.set()