client-query-cache 0.4.0__tar.gz → 0.6.0__tar.gz

{client_query_cache-0.4.0 → client_query_cache-0.6.0}/PKG-INFO

@@ -1,12 +1,20 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: client-query-cache
-Version: 0.4.0
+Version: 0.6.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>>
+License-Expression: Apache-2.0
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
 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 +22,10 @@ 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/)
+[![PyPI](https://img.shields.io/pypi/v/client-query-cache?color=lightgrey)](https://pypi.org/project/client-query-cache/)
+[![Python](https://img.shields.io/pypi/pyversions/client-query-cache)](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/alessio-locatelli/client-query-cache/actions/workflows/test.yml)
+[![Typing](https://img.shields.io/pypi/types/client-query-cache)](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.
 

{client_query_cache-0.4.0 → client_query_cache-0.6.0}/README.md

@@ -1,6 +1,9 @@
 # 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/)
+[![PyPI](https://img.shields.io/pypi/v/client-query-cache?color=lightgrey)](https://pypi.org/project/client-query-cache/)
+[![Python](https://img.shields.io/pypi/pyversions/client-query-cache)](https://alessio-locatelli.github.io/client-query-cache/getting-started/installation/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/alessio-locatelli/client-query-cache/actions/workflows/test.yml)
+[![Typing](https://img.shields.io/pypi/types/client-query-cache)](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.
 

{client_query_cache-0.4.0 → client_query_cache-0.6.0}/pyproject.toml

@@ -1,9 +1,19 @@
 [project]
 name = "client-query-cache"
-version = "0.4.0"
+version = "0.6.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"
+license = "Apache-2.0"
+classifiers = [
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
 dependencies = ["pymongo>=4.18.1"]
 
 [[project.authors]]
@@ -42,6 +52,7 @@ dev = [
     "opentelemetry-api>=1.45.0",
     "opentelemetry-sdk>=1.45.0",
     "types-psutil>=7.2.2.20260906",
+    "psutil>=7.2.2",
     "dnspython>=2.8.0",
     "python-snappy>=0.7.3",
     "pytest-xdist[psutil]>=3.8.0",

{client_query_cache-0.4.0 → client_query_cache-0.6.0}/pyproject.toml.orig

@@ -1,12 +1,22 @@
 [project]
 name = "client-query-cache"
-version = "0.4.0"
+version = "0.6.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"
+license = "Apache-2.0"
+classifiers = [
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Topic :: Database",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
 dependencies = ["pymongo>=4.18.1"]
 
 [project.urls]
@@ -41,6 +51,7 @@ dev = [
   "opentelemetry-api>=1.45.0",
   "opentelemetry-sdk>=1.45.0",
   "types-psutil>=7.2.2.20260906",
+  "psutil>=7.2.2",
   "dnspython>=2.8.0",
   "python-snappy>=0.7.3",
   "pytest-xdist[psutil]>=3.8.0",

{client_query_cache-0.4.0 → client_query_cache-0.6.0}/src/client_query_cache/_core/entries.py

@@ -32,3 +32,4 @@ class CacheEntry:
 class LookupResult:
     hit: bool
     value: Any = None
+    deferred_miss: bool = False

{client_query_cache-0.4.0 → client_query_cache-0.6.0}/src/client_query_cache/_core/manager.py

@@ -54,6 +54,8 @@ DEFAULT_MAX_ENTRY_BYTES = 1 * 1024 * 1024
 
 _NOT_INDEXED = object()
 _DEFAULT_DATABASE_AVAILABILITY = (True, 0)
+_MISS = LookupResult(hit=False)
+_DEFERRED_MISS = LookupResult(hit=False, deferred_miss=True)
 
 logger = logging.getLogger(__name__)
 
@@ -313,6 +315,9 @@ class _CacheCoreLifecycle(_CacheCoreBase):
             self._database_namespaces.clear()
         logger.info("cache manager closed")
 
+    def record_miss(self) -> None:
+        self._statistics.record_miss()
+
     def record_bypass(self, reason: BypassReason = BypassReason.UNSPECIFIED) -> None:
         self._statistics.record_bypass(reason)
 
@@ -908,6 +913,7 @@ class _CacheCoreLookup(_CacheCoreBase):
         discriminator: object,
         *,
         codec_options: CodecOptions[Any] | None = None,
+        defer_miss: bool = False,
     ) -> LookupResult:
         self._ensure_active()
         if not self._is_database_available(namespace.database):
@@ -917,18 +923,22 @@ class _CacheCoreLookup(_CacheCoreBase):
         key = NamespaceCacheKey(namespace, canonical_discriminator)
         entry = self._lru.peek(key)
         if entry is None:
-            self._statistics.record_miss()
-            return LookupResult(hit=False)
+            return self._namespace_miss(defer_miss=defer_miss)
         state = self._namespace(namespace)
         with self._namespace_section(state):
             valid = (state.generation,) == entry.generation_key
         if not valid:
-            self._statistics.record_miss()
-            return LookupResult(hit=False)
+            return self._namespace_miss(defer_miss=defer_miss)
         self._lru.touch(key)
         self._statistics.record_hit()
         return LookupResult(hit=True, value=decode_value(entry.value, codec_options))
 
+    def _namespace_miss(self, *, defer_miss: bool) -> LookupResult:
+        if defer_miss:
+            return _DEFERRED_MISS
+        self._statistics.record_miss()
+        return _MISS
+
     def resolve_alias(
         self,
         namespace: NamespaceId,

client_query_cache-0.6.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.4.0 → client_query_cache-0.6.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.4.0 → client_query_cache-0.6.0}/src/client_query_cache/asynchronous/collection.py

@@ -209,15 +209,21 @@ class CachedCollection[DocumentType: Mapping[str, Any]]:
                     cache.current_index_generation(namespace),
                 )
             )
+            discovers_unique_keys = identity is NO_IDENTITY and known_keys is None
             lookup_result = cache.lookup_namespace(
-                namespace, discriminator, codec_options=codec_options
+                namespace,
+                discriminator,
+                codec_options=codec_options,
+                defer_miss=discovers_unique_keys,
             )
             if lookup_result.hit:
                 return cast("DocumentType | None", lookup_result.value)
-            if identity is NO_IDENTITY and known_keys is None:
+            if discovers_unique_keys:
                 unique_key_match = await self._match_unique_key(
                     filter_query, effective_collation
                 )
+                if unique_key_match is None and lookup_result.deferred_miss:
+                    cache.record_miss()
         if unique_key_match is not None:
             key_definition, key_values = unique_key_match
             return await self._find_one_by_unique_key(

{client_query_cache-0.4.0 → client_query_cache-0.6.0}/src/client_query_cache/asynchronous/manager.py

@@ -81,7 +81,8 @@ class CacheManager[DocumentType: Mapping[str, Any]]:
         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)
@@ -159,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.4.0 → client_query_cache-0.6.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.4.0 → client_query_cache-0.6.0}/src/client_query_cache/synchronous/collection.py

@@ -209,15 +209,21 @@ class CachedCollection[DocumentType: Mapping[str, Any]]:
                     cache.current_index_generation(namespace),
                 )
             )
+            discovers_unique_keys = identity is NO_IDENTITY and known_keys is None
             lookup_result = cache.lookup_namespace(
-                namespace, discriminator, codec_options=codec_options
+                namespace,
+                discriminator,
+                codec_options=codec_options,
+                defer_miss=discovers_unique_keys,
             )
             if lookup_result.hit:
                 return cast("DocumentType | None", lookup_result.value)
-            if identity is NO_IDENTITY and known_keys is None:
+            if discovers_unique_keys:
                 unique_key_match = self._match_unique_key(
                     filter_query, effective_collation
                 )
+                if unique_key_match is None and lookup_result.deferred_miss:
+                    cache.record_miss()
         if unique_key_match is not None:
             key_definition, key_values = unique_key_match
             return self._find_one_by_unique_key(

{client_query_cache-0.4.0 → client_query_cache-0.6.0}/src/client_query_cache/synchronous/manager.py

@@ -81,7 +81,8 @@ class CacheManager[DocumentType: Mapping[str, Any]]:
         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)

{client_query_cache-0.4.0 → client_query_cache-0.6.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()