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

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

@@ -1,12 +1,14 @@
 Metadata-Version: 2.3
 Name: client-query-cache
-Version: 0.4.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.
 

{client_query_cache-0.4.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.
 

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

@@ -1,9 +1,13 @@
 [project]
 name = "client-query-cache"
-version = "0.4.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]]

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

@@ -1,12 +1,16 @@
 [project]
 name = "client-query-cache"
-version = "0.4.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]

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.4.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.4.0 → client_query_cache-0.5.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.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.4.0 → client_query_cache-0.5.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.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()