kurrentdbclient 0.3__py3-none-any.whl

kurrentdbclient/exceptions.py

@@ -0,0 +1,239 @@
+# -*- coding: utf-8 -*-
+from typing import Dict, Optional, Union
+
+import grpc
+
+
+class KurrentDBClientException(Exception):
+    """
+    Base class for exceptions raised by the client.
+    """
+
+
+class ProgrammingError(Exception):
+    """
+    Raised when programming errors are encountered.
+    """
+
+
+class GrpcError(KurrentDBClientException):
+    """
+    Base class for exceptions raised by gRPC.
+    """
+
+
+class ExceptionThrownByHandler(GrpcError):
+    """
+    Raised when gRPC service returns RpcError with status
+    code "UNKNOWN" and details "Exception was thrown by handler.".
+    """
+
+
+class ServiceUnavailable(GrpcError):
+    """
+    Raised when gRPC service is unavailable.
+    """
+
+
+class SSLError(ServiceUnavailable):
+    """
+    Raised when gRPC service is unavailable due to SSL error.
+    """
+
+
+class DeadlineExceeded(KurrentDBClientException):
+    """
+    Base class for exceptions involving deadlines being exceeded.
+    """
+
+
+class GrpcDeadlineExceeded(GrpcError, DeadlineExceeded):
+    """
+    Raised when gRPC operation times out.
+    """
+
+
+class CancelledByClient(KurrentDBClientException):
+    """
+    Raised when gRPC operation is cancelled.
+    """
+
+
+class AbortedByServer(GrpcError):
+    """
+    Raised when gRPC operation is aborted.
+    """
+
+
+class ConsumerTooSlow(AbortedByServer):
+    """
+    Raised when buffer is overloaded.
+    """
+
+
+class NodeIsNotLeader(KurrentDBClientException):
+    """
+    Raised when client attempts to write to a node that is not a leader.
+    """
+
+    @property
+    def leader_grpc_target(self) -> Optional[str]:
+        if (
+            self.args
+            and isinstance(self.args[0], (grpc.Call, grpc.aio.AioRpcError))
+            and self.args[0].code() == grpc.StatusCode.NOT_FOUND
+            and self.args[0].details() == "Leader info available"
+        ):
+            # The typing of trailing_metadata is a mess.
+            rpc_error = self.args[0]
+            trailing_metadata: Dict[str, Union[str, bytes]]
+            if isinstance(rpc_error, grpc.Call):
+                trailing_metadata = {
+                    m.key: m.value for m in rpc_error.trailing_metadata()  # type: ignore[attr-defined]
+                }
+            else:
+                assert isinstance(rpc_error, grpc.aio.AioRpcError)
+                trailing_metadata = rpc_error.trailing_metadata()  # type: ignore[assignment]
+
+            host = trailing_metadata["leader-endpoint-host"]
+            port = trailing_metadata["leader-endpoint-port"]
+            if isinstance(host, bytes):
+                host = host.decode("utf-8")  # pragma: no cover
+            if isinstance(port, bytes):
+                port = port.decode("utf-8")  # pragma: no cover
+            return f"{host}:{port}"
+        else:
+            return None
+
+
+class NotFound(KurrentDBClientException):
+    """
+    Raised when stream or subscription or projection is not found.
+    """
+
+
+class AlreadyExists(KurrentDBClientException):
+    """
+    Raised when creating something, e.g. a persistent subscription, that already exists.
+    """
+
+
+class SubscriptionConfirmationError(KurrentDBClientException):
+    """
+    Raised when subscription confirmation fails.
+    """
+
+
+class WrongCurrentVersion(KurrentDBClientException):
+    """
+    Raised when expected position does not match the
+    stream position of the last event in a stream.
+    """
+
+
+WrongExpectedVersion = WrongCurrentVersion
+
+
+class AccessDeniedError(KurrentDBClientException):
+    """
+    Raised when access is denied by the server.
+    """
+
+
+class StreamIsDeleted(KurrentDBClientException):
+    """
+    Raised when reading from or appending to a stream that has been
+    tombstoned, and when deleting a stream that has been deleted
+    whilst expecting the stream exists, and when getting or setting
+    metadata for a stream that has been tombstoned, and when deleting
+    a stream that has been tombstoned, and when tombstoning a stream
+    that has been tombstoned.
+    """
+
+
+class AppendDeadlineExceeded(DeadlineExceeded):
+    """
+    Raised when append operation is timed out by the server.
+    """
+
+
+class UnknownError(KurrentDBClientException):
+    """
+    Raised when append operation fails with an "unknown" error.
+    """
+
+
+class InvalidTransactionError(KurrentDBClientException):
+    """
+    Raised when append operation fails with an "invalid transaction" error.
+    """
+
+
+class OperationFailed(GrpcError):
+    """
+    Raised when an operation fails (e.g. deleting a projection that isn't disabled).
+    """
+
+
+class MaximumAppendSizeExceededError(KurrentDBClientException):
+    """
+    Raised when append operation fails with a "maximum append size exceeded" error.
+    """
+
+
+class BadRequestError(KurrentDBClientException):
+    """
+    Raised when append operation fails with a "bad request" error.
+    """
+
+
+class DiscoveryFailed(KurrentDBClientException):
+    """
+    Raised when client fails to satisfy node preference using gossip cluster info.
+    """
+
+
+class LeaderNotFound(DiscoveryFailed):
+    """
+    Raised when NodePreference is 'follower' but the cluster has no such nodes.
+    """
+
+
+class FollowerNotFound(DiscoveryFailed):
+    """
+    Raised when NodePreference is 'follower' but the cluster has no such nodes.
+    """
+
+
+class ReadOnlyReplicaNotFound(DiscoveryFailed):
+    """
+    Raised when NodePreference is 'readonlyreplica' but the cluster has no such nodes.
+    """
+
+
+class ExceptionIteratingRequests(KurrentDBClientException):
+    """
+    Raised when a persistent subscription errors whilst iterating requests.
+
+    This helps debugging because otherwise we just get a gRPC error
+    that says "Exception iterating requests!"
+    """
+
+
+class FailedPrecondition(KurrentDBClientException):
+    """
+    Raised when a "failed precondition" status error is encountered.
+    """
+
+
+class MaximumSubscriptionsReached(FailedPrecondition):
+    """
+    Raised when trying to read from a persistent subscription that
+    is already being read by the maximum number of subscribers.
+    """
+
+
+class InternalError(GrpcError):
+    """
+    Raised when a grpc INTERNAL error is encountered.
+    """

kurrentdbclient/gossip.py

@@ -0,0 +1,104 @@
+# -*- coding: utf-8 -*-
+from dataclasses import dataclass
+from typing import Optional, Sequence, Union
+
+import grpc
+import grpc.aio
+
+from kurrentdbclient.common import (
+    AsyncGrpcStreamers,
+    GrpcStreamers,
+    KurrentDBService,
+    Metadata,
+    TGrpcStreamers,
+    handle_rpc_error,
+)
+from kurrentdbclient.connection_spec import ConnectionSpec
+from kurrentdbclient.protos.Grpc import gossip_pb2, gossip_pb2_grpc, shared_pb2
+
+
+@dataclass
+class ClusterMember:
+    state: str
+    address: str
+    port: int
+
+
+NODE_STATE_LEADER = "NODE_STATE_LEADER"
+NODE_STATE_FOLLOWER = "NODE_STATE_FOLLOWER"
+NODE_STATE_REPLICA = "NODE_STATE_REPLICA"
+NODE_STATE_OTHER = "NODE_STATE_OTHER"
+GOSSIP_API_NODE_STATES_MAPPING = {
+    gossip_pb2.MemberInfo.VNodeState.Follower: NODE_STATE_FOLLOWER,
+    gossip_pb2.MemberInfo.VNodeState.Leader: NODE_STATE_LEADER,
+    gossip_pb2.MemberInfo.VNodeState.ReadOnlyReplica: NODE_STATE_REPLICA,
+}
+
+
+class BaseGossipService(KurrentDBService[TGrpcStreamers]):
+    def __init__(
+        self,
+        channel: Union[grpc.Channel, grpc.aio.Channel],
+        connection_spec: ConnectionSpec,
+        grpc_streamers: TGrpcStreamers,
+    ):
+        super().__init__(connection_spec=connection_spec, grpc_streamers=grpc_streamers)
+        self._stub = gossip_pb2_grpc.GossipStub(channel)  # type: ignore[no-untyped-call]
+
+    @staticmethod
+    def _construct_cluster_members(
+        cluster_info: gossip_pb2.ClusterInfo,
+    ) -> Sequence[ClusterMember]:
+        members = []
+        for member_info in cluster_info.members:
+            member = ClusterMember(
+                GOSSIP_API_NODE_STATES_MAPPING.get(member_info.state, NODE_STATE_OTHER),
+                member_info.http_end_point.address,
+                member_info.http_end_point.port,
+            )
+            members.append(member)
+        return tuple(members)
+
+
+class AsyncGossipService(BaseGossipService[AsyncGrpcStreamers]):
+    async def read(
+        self,
+        timeout: Optional[float] = None,
+        metadata: Optional[Metadata] = None,
+        credentials: Optional[grpc.CallCredentials] = None,
+    ) -> Sequence[ClusterMember]:
+        try:
+            read_resp = await self._stub.Read(
+                shared_pb2.Empty(),
+                timeout=timeout,
+                metadata=self._metadata(metadata),
+                credentials=credentials,
+            )
+        except grpc.RpcError as e:
+            raise handle_rpc_error(e) from None
+
+        return self._construct_cluster_members(read_resp)
+
+
+class GossipService(BaseGossipService[GrpcStreamers]):
+    """
+    Encapsulates the 'gossip.Gossip' gRPC service.
+    """
+
+    def read(
+        self,
+        timeout: Optional[float] = None,
+        metadata: Optional[Metadata] = None,
+        credentials: Optional[grpc.CallCredentials] = None,
+    ) -> Sequence[ClusterMember]:
+        try:
+            read_resp = self._stub.Read(
+                shared_pb2.Empty(),
+                timeout=timeout,
+                metadata=self._metadata(metadata),
+                credentials=credentials,
+            )
+        except grpc.RpcError as e:
+            raise handle_rpc_error(e) from None
+
+        return self._construct_cluster_members(read_resp)

kurrentdbclient/instrumentation/opentelemetry/__init__.py

@@ -0,0 +1,185 @@
+# -*- coding: utf-8 -*-
+from __future__ import annotations
+
+from typing import Any, Collection
+
+# Note: namespace pacakge issue? don't understand why this and not e.g. utils.unwrap
+from opentelemetry.instrumentation.instrumentor import (  # type: ignore[attr-defined]
+    BaseInstrumentor,
+)
+from opentelemetry.instrumentation.utils import unwrap
+from opentelemetry.semconv.schemas import Schemas
+from opentelemetry.trace import Tracer, get_tracer
+
+from kurrentdbclient import AsyncKurrentDBClient, KurrentDBClient
+from kurrentdbclient.instrumentation.opentelemetry.grpc import (
+    try_unwrap_opentelemetry_intercept_grpc_server_stream,
+    try_wrap_opentelemetry_intercept_grpc_server_stream,
+)
+from kurrentdbclient.instrumentation.opentelemetry.package import _instruments
+from kurrentdbclient.instrumentation.opentelemetry.spanners import (
+    span_append_to_stream,
+    span_catchup_subscription,
+    span_get_stream,
+    span_persistent_subscription,
+    span_read_stream,
+)
+from kurrentdbclient.instrumentation.opentelemetry.utils import apply_spanner
+from kurrentdbclient.instrumentation.opentelemetry.version import __version__
+
+
+class _RedefinedBaseInstrumentor(BaseInstrumentor):  # type: ignore[misc]
+    pass
+
+
+class _BaseInstrumentor(_RedefinedBaseInstrumentor):
+    instrument_get_and_read_stream = False
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return _instruments
+
+    def _instrument(self, **kwargs: Any) -> None:
+        instrument_get_and_read_stream = bool(
+            kwargs.get("instrument_get_and_read_stream")
+        )
+        self.instrument_get_and_read_stream = instrument_get_and_read_stream
+
+    def _get_tracer(self, **kwargs: Any) -> Tracer:
+        tracer_provider = kwargs.get("tracer_provider")
+        tracer = get_tracer(
+            __name__,
+            __version__,
+            tracer_provider=tracer_provider,
+            schema_url=Schemas.V1_25_0.value,
+        )
+        return tracer
+
+
+class KurrentDBClientInstrumentor(_BaseInstrumentor):
+    def _instrument(self, **kwargs: Any) -> None:
+        super()._instrument(**kwargs)
+
+        tracer = self._get_tracer(**kwargs)
+
+        apply_spanner(
+            patched_class=KurrentDBClient,
+            spanned_func=KurrentDBClient.append_to_stream,
+            spanner_func=span_append_to_stream,
+            tracer=tracer,
+        )
+        apply_spanner(
+            patched_class=KurrentDBClient,
+            spanned_func=KurrentDBClient.subscribe_to_stream,
+            spanner_func=span_catchup_subscription,
+            tracer=tracer,
+        )
+        apply_spanner(
+            patched_class=KurrentDBClient,
+            spanned_func=KurrentDBClient.subscribe_to_all,
+            spanner_func=span_catchup_subscription,
+            tracer=tracer,
+        )
+        apply_spanner(
+            patched_class=KurrentDBClient,
+            spanned_func=KurrentDBClient.read_subscription_to_stream,
+            spanner_func=span_persistent_subscription,
+            tracer=tracer,
+        )
+        apply_spanner(
+            patched_class=KurrentDBClient,
+            spanned_func=KurrentDBClient.read_subscription_to_all,
+            spanner_func=span_persistent_subscription,
+            tracer=tracer,
+        )
+        if self.instrument_get_and_read_stream:
+            apply_spanner(
+                patched_class=KurrentDBClient,
+                spanned_func=KurrentDBClient.read_stream,
+                spanner_func=span_read_stream,
+                tracer=tracer,
+            )
+            apply_spanner(
+                patched_class=KurrentDBClient,
+                spanned_func=KurrentDBClient.get_stream,
+                spanner_func=span_get_stream,
+                tracer=tracer,
+            )
+
+        # Because its server streaming wrapper doesn't return an
+        # object with a cancel() method, so we can't stop them.
+        try_wrap_opentelemetry_intercept_grpc_server_stream()
+
+    def _uninstrument(self, **kwargs: Any) -> None:
+        unwrap(KurrentDBClient, "append_to_stream")
+        unwrap(KurrentDBClient, "subscribe_to_stream")
+        unwrap(KurrentDBClient, "subscribe_to_all")
+        unwrap(KurrentDBClient, "read_subscription_to_stream")
+        unwrap(KurrentDBClient, "read_subscription_to_all")
+
+        if self.instrument_get_and_read_stream:
+            unwrap(KurrentDBClient, "get_stream")
+            unwrap(KurrentDBClient, "read_stream")
+
+        try_unwrap_opentelemetry_intercept_grpc_server_stream()
+
+
+class AsyncKurrentDBClientInstrumentor(_BaseInstrumentor):
+    def _instrument(self, **kwargs: Any) -> None:
+        super()._instrument(**kwargs)
+
+        tracer = self._get_tracer(**kwargs)
+
+        apply_spanner(
+            patched_class=AsyncKurrentDBClient,
+            spanned_func=AsyncKurrentDBClient.append_to_stream,
+            spanner_func=span_append_to_stream,
+            tracer=tracer,
+        )
+        apply_spanner(
+            patched_class=AsyncKurrentDBClient,
+            spanned_func=AsyncKurrentDBClient.subscribe_to_stream,
+            spanner_func=span_catchup_subscription,
+            tracer=tracer,
+        )
+        apply_spanner(
+            patched_class=AsyncKurrentDBClient,
+            spanned_func=AsyncKurrentDBClient.subscribe_to_all,
+            spanner_func=span_catchup_subscription,
+            tracer=tracer,
+        )
+        apply_spanner(
+            patched_class=AsyncKurrentDBClient,
+            spanned_func=AsyncKurrentDBClient.read_subscription_to_stream,
+            spanner_func=span_persistent_subscription,
+            tracer=tracer,
+        )
+        apply_spanner(
+            patched_class=AsyncKurrentDBClient,
+            spanned_func=AsyncKurrentDBClient.read_subscription_to_all,
+            spanner_func=span_persistent_subscription,
+            tracer=tracer,
+        )
+        if self.instrument_get_and_read_stream:
+            apply_spanner(
+                patched_class=AsyncKurrentDBClient,
+                spanned_func=AsyncKurrentDBClient.read_stream,
+                spanner_func=span_read_stream,
+                tracer=tracer,
+            )
+            apply_spanner(
+                patched_class=AsyncKurrentDBClient,
+                spanned_func=AsyncKurrentDBClient.get_stream,
+                spanner_func=span_get_stream,
+                tracer=tracer,
+            )
+
+    def _uninstrument(self, **kwargs: Any) -> None:
+        unwrap(AsyncKurrentDBClient, "append_to_stream")
+        unwrap(AsyncKurrentDBClient, "subscribe_to_stream")
+        unwrap(AsyncKurrentDBClient, "subscribe_to_all")
+        unwrap(AsyncKurrentDBClient, "read_subscription_to_stream")
+        unwrap(AsyncKurrentDBClient, "read_subscription_to_all")
+
+        if self.instrument_get_and_read_stream:
+            unwrap(AsyncKurrentDBClient, "get_stream")
+            unwrap(AsyncKurrentDBClient, "read_stream")

kurrentdbclient/instrumentation/opentelemetry/attributes.py

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+
+from opentelemetry.semconv._incubating.attributes import db_attributes
+from opentelemetry.semconv.attributes import exception_attributes, server_attributes
+
+
+class Attributes:
+    DB_OPERATION = db_attributes.DB_OPERATION
+    DB_SYSTEM = db_attributes.DB_SYSTEM
+    DB_USER = db_attributes.DB_USER
+    EVENTSTOREDB_STREAM = "db.kurrentdb.stream"
+    EVENTSTOREDB_SUBSCRIPTION_ID = "db.kurrentdb.subscription.id"
+    EVENTSTOREDB_EVENT_ID = "db.kurrentdb.event.id"
+    EVENTSTOREDB_EVENT_TYPE = "db.kurrentdb.event.type"
+    EXCEPTION_ESCAPED = exception_attributes.EXCEPTION_ESCAPED
+    EXCEPTION_MESSAGE = exception_attributes.EXCEPTION_MESSAGE
+    EXCEPTION_STACKTRACE = exception_attributes.EXCEPTION_STACKTRACE
+    EXCEPTION_TYPE = exception_attributes.EXCEPTION_TYPE
+    SERVER_ADDRESS = server_attributes.SERVER_ADDRESS
+    SERVER_PORT = server_attributes.SERVER_PORT