kurrentdbclient 1.3.3__tar.gz → 1.3.5__tar.gz

{kurrentdbclient-1.3.3 → kurrentdbclient-1.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kurrentdbclient
-Version: 1.3.3
+Version: 1.3.5
 Summary: Python gRPC Client for KurrentDB
 License: BSD-3-Clause
 License-File: LICENSE
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python
 Classifier: Topic :: Database
 Classifier: Topic :: Database :: Front-Ends
@@ -56,10 +57,10 @@ with the KurrentDB team, and are officially supported by Kurrent Inc.
 Although not all aspects of the KurrentDB gRPC API are implemented, most
 features are presented in an easy-to-use interface.
 
-These clients have been tested to work with KurrentDB versions 25.0, 25.1, 26.0,
-and 26.1, and EventStoreDB versions 23.10 and 24.10, with and without SSL/TLS,
+These clients have been tested to work with KurrentDB versions 25.0, 25.1, 26.0, 26.1,
+and 26.2, and EventStoreDB versions 23.10 and 24.10, with and without SSL/TLS,
 in both single-server and cluster modes, across Python versions 3.10, 3.11, 3.12,
-3.13, and 3.14.
+3.13, 3.14, and 3.15.
 
 The test suite has 100% line and branch coverage. The code has typing annotations
 checked strictly with mypy. The code is formatted with black and isort, and checked
@@ -572,8 +573,8 @@ The table below describes the query string field-values supported by this client
 | GossipTimeout       | integer (default: 5)                                                  | The default value (in seconds) of the `timeout` argument of gossip read methods, such as `read_gossip()`.                                                         |
 | MaxDiscoverAttempts | integer (default: 10)                                                 | The number of attempts to read gossip when connecting or reconnecting to a cluster member.                                                                        |
 | DiscoveryInterval   | integer (default: 100)                                                | How long to wait (in milliseconds) between gossip retries.                                                                                                        |
-| KeepAliveInterval   | integer (default: `None`)                                             | The value (in milliseconds) of the "grpc.keepalive_ms" gRPC channel option.                                                                                       |
-| KeepAliveTimeout    | integer (default: `None`)                                             | The value (in milliseconds) of the "grpc.keepalive_timeout_ms" gRPC channel option.                                                                               |
+| KeepAliveInterval   | integer (default: `None`)                                             | The value (in milliseconds) of the "grpc.keepalive_time_ms" gRPC channel option.                                                                                  |
+| KeepAliveTimeout    | integer (default: `None`)                                             | The value (in milliseconds) of the "grpc.keepalive_timeout_ms" and "grpc.http2.ping_timeout_ms" gRPC channel options.                                             |
 | TlsCaFile           | string (default: `None`)                                              | Absolute filesystem path to file containing the CA certicate in PEM format. This will be used to verify the server's certificate.                                 |
 | UserCertFile        | string (default: `None`)                                              | Absolute filesystem path to file containing the X.509 user certificate in PEM format.                                                                             |
 | UserKeyFile         | string (default: `None`)                                              | Absolute filesystem path to file containing the X.509 user certificate's private key in PEM format.                                                               |

{kurrentdbclient-1.3.3 → kurrentdbclient-1.3.5}/README.md

@@ -22,10 +22,10 @@ with the KurrentDB team, and are officially supported by Kurrent Inc.
 Although not all aspects of the KurrentDB gRPC API are implemented, most
 features are presented in an easy-to-use interface.
 
-These clients have been tested to work with KurrentDB versions 25.0, 25.1, 26.0,
-and 26.1, and EventStoreDB versions 23.10 and 24.10, with and without SSL/TLS,
+These clients have been tested to work with KurrentDB versions 25.0, 25.1, 26.0, 26.1,
+and 26.2, and EventStoreDB versions 23.10 and 24.10, with and without SSL/TLS,
 in both single-server and cluster modes, across Python versions 3.10, 3.11, 3.12,
-3.13, and 3.14.
+3.13, 3.14, and 3.15.
 
 The test suite has 100% line and branch coverage. The code has typing annotations
 checked strictly with mypy. The code is formatted with black and isort, and checked
@@ -538,8 +538,8 @@ The table below describes the query string field-values supported by this client
 | GossipTimeout       | integer (default: 5)                                                  | The default value (in seconds) of the `timeout` argument of gossip read methods, such as `read_gossip()`.                                                         |
 | MaxDiscoverAttempts | integer (default: 10)                                                 | The number of attempts to read gossip when connecting or reconnecting to a cluster member.                                                                        |
 | DiscoveryInterval   | integer (default: 100)                                                | How long to wait (in milliseconds) between gossip retries.                                                                                                        |
-| KeepAliveInterval   | integer (default: `None`)                                             | The value (in milliseconds) of the "grpc.keepalive_ms" gRPC channel option.                                                                                       |
-| KeepAliveTimeout    | integer (default: `None`)                                             | The value (in milliseconds) of the "grpc.keepalive_timeout_ms" gRPC channel option.                                                                               |
+| KeepAliveInterval   | integer (default: `None`)                                             | The value (in milliseconds) of the "grpc.keepalive_time_ms" gRPC channel option.                                                                                  |
+| KeepAliveTimeout    | integer (default: `None`)                                             | The value (in milliseconds) of the "grpc.keepalive_timeout_ms" and "grpc.http2.ping_timeout_ms" gRPC channel options.                                             |
 | TlsCaFile           | string (default: `None`)                                              | Absolute filesystem path to file containing the CA certicate in PEM format. This will be used to verify the server's certificate.                                 |
 | UserCertFile        | string (default: `None`)                                              | Absolute filesystem path to file containing the X.509 user certificate in PEM format.                                                                             |
 | UserKeyFile         | string (default: `None`)                                              | Absolute filesystem path to file containing the X.509 user certificate's private key in PEM format.                                                               |

{kurrentdbclient-1.3.3 → kurrentdbclient-1.3.5}/kurrentdbclient/__init__.py

@@ -28,7 +28,7 @@ from kurrentdbclient.streams import (
     ReadResponse,
 )
 
-__version__ = "1.3.3"
+__version__ = "1.3.5"
 
 __all__ = [
     "DEFAULT_EXCLUDE_FILTER",

{kurrentdbclient-1.3.3 → kurrentdbclient-1.3.5}/kurrentdbclient/asyncio_client.py

@@ -65,6 +65,7 @@ from kurrentdbclient.exceptions import (
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Sequence
+    from uuid import UUID
 
     from kurrentdbclient.persistent import ConsumerStrategy, SubscriptionInfo
     from kurrentdbclient.projections import ProjectionState, ProjectionStatistics
@@ -80,6 +81,7 @@ def autoreconnect(f: _TCallable) -> _TCallable:
         client: AsyncKurrentDBClient, *args: Any, **kwargs: Any
     ) -> Any:
         await client.connect()
+        connection_id = client.connection_id
         try:
             return await f(client, *args, **kwargs)
 
@@ -92,7 +94,8 @@ def autoreconnect(f: _TCallable) -> _TCallable:
                 )
             ):
                 await client.reconnect(
-                    grpc_target(e.host, e.port) if e.host and e.port else None
+                    grpc_target(e.host, e.port) if e.host and e.port else None,
+                    connection_id=connection_id,
                 )
                 await asyncio.sleep(0.1)
                 return await f(client, *args, **kwargs)
@@ -100,13 +103,13 @@ def autoreconnect(f: _TCallable) -> _TCallable:
 
         except grpc.aio.UsageError as e:
             if "Channel is closed" in str(e):
-                await client.reconnect()
+                await client.reconnect(connection_id=connection_id)
                 await asyncio.sleep(0.1)
                 return await f(client, *args, **kwargs)
             raise  # pragma: no cover
 
         except ServiceUnavailableError:
-            await client.reconnect()
+            await client.reconnect(connection_id=connection_id)
             await asyncio.sleep(0.1)
             return await f(client, *args, **kwargs)
 
@@ -119,7 +122,7 @@ def retrygrpc(f: _TCallable) -> _TCallable:
         try:
             return await f(*args, **kwargs)
         except GrpcError:
-            await asyncio.sleep(0.1)
+            await asyncio.sleep(0.5)
             return await f(*args, **kwargs)
 
     return cast(_TCallable, retrygrpc_decorator)
@@ -143,6 +146,11 @@ class AsyncKurrentDBClient(BaseKurrentDBClient):
         self._is_reconnection_required = Event()
         self._connection_lock = Lock()
 
+    @property
+    def connection_id(self) -> UUID:
+        assert self._connection is not None
+        return self._connection.connection_id
+
     async def connect(self) -> None:
         if self._connection is None:
             async with self._connection_lock:
@@ -163,8 +171,12 @@ class AsyncKurrentDBClient(BaseKurrentDBClient):
     def connection_target(self) -> str:
         return self.connection.grpc_target
 
-    async def reconnect(self, grpc_target: str | None = None) -> None:
-        self._is_reconnection_required.set()
+    async def reconnect(
+        self, grpc_target: str | None = None, connection_id: UUID | None = None
+    ) -> None:
+        # Avoid reconnecting if client already has a new connection.
+        if connection_id is None or connection_id == self.connection_id:
+            self._is_reconnection_required.set()
         async with self._connection_lock:
             if self._is_reconnection_required.is_set():
                 new = await self._connect(grpc_target)

{kurrentdbclient-1.3.3 → kurrentdbclient-1.3.5}/kurrentdbclient/client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import contextlib
 import json
 import random
 import sys
@@ -62,6 +63,7 @@ from kurrentdbclient.events import (
     StreamStateCheck,
 )
 from kurrentdbclient.exceptions import (
+    AccessDeniedError,
     DiscoveryFailedError,
     FollowerNotFoundError,
     GrpcError,
@@ -81,6 +83,7 @@ from kurrentdbclient.gossip import (
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Sequence
+    from uuid import UUID
 
     from kurrentdbclient.persistent import (
         ConsumerStrategy,
@@ -116,9 +119,14 @@ def autoreconnect(f: _TCallable) -> _TCallable:
     def autoreconnect_decorator(*args: Any, **kwargs: Any) -> Any:
         client = args[0]
         assert isinstance(client, KurrentDBClient)
+        connection_id = client.connection_id
         try:
             return f(*args, **kwargs)
 
+        # TODO: Maybe refine the retry so that we do reconnect and try again when
+        #   there is connection failure after retrying without reconnecting because
+        #   the connection has changed. Need to think about this a bit more...
+
         except NodeIsNotLeaderError as e:
             if (
                 client.connection_spec.options.node_preference == NODE_PREFERENCE_LEADER
@@ -128,7 +136,8 @@ def autoreconnect(f: _TCallable) -> _TCallable:
                 )
             ):
                 client.reconnect(
-                    grpc_target(e.host, e.port) if e.host and e.port else None
+                    grpc_target(e.host, e.port) if e.host and e.port else None,
+                    connection_id=connection_id,
                 )
                 sleep(0.1)
                 return f(*args, **kwargs)
@@ -137,13 +146,13 @@ def autoreconnect(f: _TCallable) -> _TCallable:
         except ValueError as e:
             s = str(e)
             if "Channel closed!" in s or "Cannot invoke RPC on closed channel!" in s:
-                client.reconnect()
+                client.reconnect(connection_id=connection_id)
                 sleep(0.1)
                 return f(*args, **kwargs)
             raise  # pragma: no cover
 
         except ServiceUnavailableError:
-            client.reconnect()
+            client.reconnect(connection_id=connection_id)
             sleep(0.1)
             return f(*args, **kwargs)
 
@@ -208,12 +217,16 @@ class BaseKurrentDBClient(ABC):
 
         self._default_deadline = self.connection_spec.options.default_deadline
 
+        # GRPC options ref: https://grpc.github.io/grpc/core/group__grpc__arg__keys.html
         self.grpc_options: GrpcOptions = (
             ("grpc.max_receive_message_length", 17 * 1024 * 1024),
         )
         if self.connection_spec.options.keep_alive_interval is not None:
             self.grpc_options += (
-                ("grpc.keepalive_ms", self.connection_spec.options.keep_alive_interval),
+                (
+                    "grpc.keepalive_time_ms",
+                    self.connection_spec.options.keep_alive_interval,
+                ),
             )
         if self.connection_spec.options.keep_alive_timeout is not None:
             self.grpc_options += (
@@ -221,6 +234,12 @@ class BaseKurrentDBClient(ABC):
                     "grpc.keepalive_timeout_ms",
                     self.connection_spec.options.keep_alive_timeout,
                 ),
+                # gRPC closes a connection whose ping is not answered after
+                # this time (default 60s), not after keepalive_timeout_ms.
+                (
+                    "grpc.http2.ping_timeout_ms",
+                    self.connection_spec.options.keep_alive_timeout,
+                ),
             )
 
         self._call_metadata = (
@@ -312,6 +331,10 @@ class KurrentDBClient(BaseKurrentDBClient):
     def connection_target(self) -> str:
         return self._connection.grpc_target
 
+    @property
+    def connection_id(self) -> UUID:
+        return self._connection.connection_id
+
     @property
     def streams(self) -> StreamsService:
         return self._connection.streams
@@ -401,14 +424,22 @@ class KurrentDBClient(BaseKurrentDBClient):
 
         return connection
 
-    def reconnect(self, grpc_target: str | None = None) -> None:
-        self._is_reconnection_required.set()
+    def reconnect(
+        self, grpc_target: str | None = None, *, connection_id: UUID | None = None
+    ) -> None:
+        # Avoid reconnecting if client already has a new connection.
+        if connection_id is None or connection_id == self.connection_id:
+            self._is_reconnection_required.set()
+        # Single reconnection.
         with self._reconnection_lock:
             if self._is_reconnection_required.is_set():
                 new_conn = self._connect(grpc_target)
                 old_conn, self._connection = self._connection, new_conn
                 old_conn.close()
                 self._is_reconnection_required.clear()
+                # Exercise the connection (avoids delayed errors due to lazy channel)
+                with contextlib.suppress(AccessDeniedError):
+                    self._get_commit_position()
             else:  # pragma: no cover
                 # Todo: Test with concurrent writes to wrong node state.
                 pass
@@ -668,17 +699,19 @@ class KurrentDBClient(BaseKurrentDBClient):
         """
         Returns a sequence of recorded events from the named stream.
         """
-        with self.read_stream(
+        with self._read_stream(
             stream_name=stream_name,
             stream_position=stream_position,
             backwards=backwards,
             resolve_links=resolve_links,
             limit=limit,
             timeout=timeout,
-            credentials=credentials or self._call_credentials,
+            credentials=credentials,
         ) as events:
             return tuple(events)
 
+    @retrygrpc
+    @autoreconnect
     def read_stream(
         self,
         stream_name: str,
@@ -689,6 +722,30 @@ class KurrentDBClient(BaseKurrentDBClient):
         limit: int = sys.maxsize,
         timeout: float | None = None,
         credentials: grpc.CallCredentials | None = None,
+    ) -> AbstractReadResponse:
+        """
+        Reads recorded events from the named stream.
+        """
+        return self._read_stream(
+            stream_name=stream_name,
+            stream_position=stream_position,
+            backwards=backwards,
+            resolve_links=resolve_links,
+            limit=limit,
+            timeout=timeout,
+            credentials=credentials,
+        )
+
+    def _read_stream(
+        self,
+        stream_name: str,
+        *,
+        stream_position: int | None = None,
+        backwards: bool = False,
+        resolve_links: bool = False,
+        limit: int = sys.maxsize,
+        timeout: float | None = None,
+        credentials: grpc.CallCredentials | None = None,
     ) -> AbstractReadResponse:
         """
         Reads recorded events from the named stream.
@@ -704,6 +761,8 @@ class KurrentDBClient(BaseKurrentDBClient):
             credentials=credentials or self._call_credentials,
         )
 
+    @retrygrpc
+    @autoreconnect
     def read_all(
         self,
         *,
@@ -717,6 +776,36 @@ class KurrentDBClient(BaseKurrentDBClient):
         limit: int = sys.maxsize,
         timeout: float | None = None,
         credentials: grpc.CallCredentials | None = None,
+    ) -> AbstractReadResponse:
+        """
+        Reads recorded events in "all streams" in the database.
+        """
+        return self._read_all(
+            commit_position=commit_position,
+            backwards=backwards,
+            resolve_links=resolve_links,
+            filter_exclude=filter_exclude,
+            filter_include=filter_include,
+            filter_by_stream_name=filter_by_stream_name,
+            filter_by_prefix=filter_by_prefix,
+            limit=limit,
+            timeout=timeout,
+            credentials=credentials,
+        )
+
+    def _read_all(
+        self,
+        *,
+        commit_position: int | None = None,
+        backwards: bool = False,
+        resolve_links: bool = False,
+        filter_exclude: Sequence[str] = DEFAULT_EXCLUDE_FILTER,
+        filter_include: Sequence[str] = (),
+        filter_by_stream_name: bool = False,
+        filter_by_prefix: bool = False,
+        limit: int = sys.maxsize,
+        timeout: float | None = None,
+        credentials: grpc.CallCredentials | None = None,
     ) -> AbstractReadResponse:
         """
         Reads recorded events in "all streams" in the database.
@@ -735,6 +824,8 @@ class KurrentDBClient(BaseKurrentDBClient):
             credentials=credentials or self._call_credentials,
         )
 
+    @retrygrpc
+    @autoreconnect
     def read_index(
         self,
         index_name: str,
@@ -748,7 +839,7 @@ class KurrentDBClient(BaseKurrentDBClient):
         if not index_name.startswith("$idx-"):
             index_name = f"$idx-{index_name}"
 
-        return self.read_all(
+        return self._read_all(
             commit_position=commit_position,
             filter_include=(index_name,),
             filter_by_stream_name=True,
@@ -807,15 +898,34 @@ class KurrentDBClient(BaseKurrentDBClient):
         """
         Returns the current commit position of the database.
         """
-        read_response = self.streams.read(
+        return self._get_commit_position(
+            filter_exclude=filter_exclude,
+            filter_include=filter_include,
+            filter_by_stream_name=filter_by_stream_name,
+            timeout=timeout,
+            credentials=credentials,
+        )
+
+    def _get_commit_position(
+        self,
+        *,
+        filter_exclude: Sequence[str] = DEFAULT_EXCLUDE_FILTER,
+        filter_include: Sequence[str] = (),
+        filter_by_stream_name: bool = False,
+        timeout: float | None = None,
+        credentials: grpc.CallCredentials | None = None,
+    ) -> int:
+        """
+        Returns the current commit position of the database.
+        """
+        read_response = self._read_all(
             backwards=True,
             filter_exclude=filter_exclude,
             filter_include=filter_include,
             filter_by_stream_name=filter_by_stream_name,
             limit=1,
             timeout=timeout,
-            metadata=self._call_metadata,
-            credentials=credentials or self._call_credentials,
+            credentials=credentials,
         )
         recorded_events = tuple(read_response)
         if recorded_events:
@@ -895,6 +1005,45 @@ class KurrentDBClient(BaseKurrentDBClient):
         include_fell_behind: bool = False,
         timeout: float | None = None,
         credentials: grpc.CallCredentials | None = None,
+    ) -> AbstractCatchupSubscription:
+        """
+        Starts a catch-up subscription, from which all
+        recorded events in the database can be received.
+        """
+        return self._subscribe_to_all(
+            commit_position=commit_position,
+            from_end=from_end,
+            resolve_links=resolve_links,
+            filter_exclude=filter_exclude,
+            filter_include=filter_include,
+            filter_by_stream_name=filter_by_stream_name,
+            filter_by_prefix=filter_by_prefix,
+            include_checkpoints=include_checkpoints,
+            window_size=window_size,
+            checkpoint_interval_multiplier=checkpoint_interval_multiplier,
+            include_caught_up=include_caught_up,
+            include_fell_behind=include_fell_behind,
+            timeout=timeout,
+            credentials=credentials,
+        )
+
+    def _subscribe_to_all(
+        self,
+        *,
+        commit_position: int | None = None,
+        from_end: bool = False,
+        resolve_links: bool = False,
+        filter_exclude: Sequence[str] = DEFAULT_EXCLUDE_FILTER,
+        filter_include: Sequence[str] = (),
+        filter_by_stream_name: bool = False,
+        filter_by_prefix: bool = False,
+        include_checkpoints: bool = False,
+        window_size: int = DEFAULT_WINDOW_SIZE,
+        checkpoint_interval_multiplier: int = DEFAULT_CHECKPOINT_INTERVAL_MULTIPLIER,
+        include_caught_up: bool = False,
+        include_fell_behind: bool = False,
+        timeout: float | None = None,
+        credentials: grpc.CallCredentials | None = None,
     ) -> AbstractCatchupSubscription:
         """
         Starts a catch-up subscription, from which all
@@ -919,6 +1068,8 @@ class KurrentDBClient(BaseKurrentDBClient):
             credentials=credentials or self._call_credentials,
         )
 
+    @retrygrpc
+    @autoreconnect
     def subscribe_to_index(
         self,
         index_name: str,
@@ -931,7 +1082,7 @@ class KurrentDBClient(BaseKurrentDBClient):
         if not index_name.startswith("$idx-"):
             index_name = f"$idx-{index_name}"
 
-        return self.subscribe_to_all(
+        return self._subscribe_to_all(
             commit_position=commit_position,
             filter_include=(index_name,),
             filter_by_stream_name=True,
@@ -1411,6 +1562,24 @@ class KurrentDBClient(BaseKurrentDBClient):
         *,
         timeout: float | None = None,
         credentials: grpc.CallCredentials | None = None,
+    ) -> SubscriptionInfo:
+        """
+        Gets info for a persistent subscription.
+        """
+        return self._get_subscription_info(
+            group_name=group_name,
+            stream_name=stream_name,
+            timeout=timeout,
+            credentials=credentials,
+        )
+
+    def _get_subscription_info(
+        self,
+        group_name: str,
+        stream_name: str | None = None,
+        *,
+        timeout: float | None = None,
+        credentials: grpc.CallCredentials | None = None,
     ) -> SubscriptionInfo:
         """
         Gets info for a persistent subscription.
@@ -1744,7 +1913,7 @@ class KurrentDBClient(BaseKurrentDBClient):
         Updates a persistent subscription on one stream.
         """
 
-        info = self.get_subscription_info(
+        info = self._get_subscription_info(
             group_name=group_name,
             stream_name=stream_name,
             timeout=timeout,