grpc-server-kit 0.1.0__py3-none-any.whl

grpc_server_kit/dishka/settings.py

@@ -0,0 +1,41 @@
+"""Dishka provider exposing gRPC server settings + service name to the container.
+
+Shared (sync) provider: it only holds an already-built settings object, so it lives at
+the top level rather than under ``aio``.
+"""
+
+from __future__ import annotations
+
+from dishka import Provider, Scope, provide
+
+from grpc_server_kit.protocols import GrpcServerSettingsProtocol, GrpcServiceName
+
+
+class GrpcServerSettingsProvider(Provider):
+    """Provide the gRPC server settings (as ``GrpcServerSettingsProtocol``) and service name.
+
+    Construct with the service's settings object (anything structurally satisfying
+    ``GrpcServerSettingsProtocol`` — e.g. ``BaseGrpcServerSettings``) and the fully-qualified
+    gRPC service name. Replaces the per-service settings-aliasing boilerplate that the other
+    kit providers depend on.
+    """
+
+    scope = Scope.APP
+
+    def __init__(self, settings: GrpcServerSettingsProtocol, *, service_name: str) -> None:
+        super().__init__()
+        self._settings = settings
+        self._service_name = service_name
+
+    @provide
+    def settings(self) -> GrpcServerSettingsProtocol:
+        """Provide the gRPC server settings."""
+        return self._settings
+
+    @provide
+    def service_name(self) -> GrpcServiceName:
+        """Provide the fully-qualified gRPC service name (typed DI key)."""
+        return GrpcServiceName(self._service_name)
+
+
+__all__ = ["GrpcServerSettingsProvider"]

grpc_server_kit/interceptors/__init__.py

@@ -0,0 +1,15 @@
+"""Shared, transport-agnostic interceptor helpers.
+
+The async server interceptors live under :mod:`grpc_server_kit.aio.interceptors`; this
+package holds only the shared constants and utilities they build on.
+"""
+
+from .constants import SKIPPED_HEALTH_METHODS, X_REQUEST_ID
+from .utils import is_server_error, resolve_status_code
+
+__all__ = [
+    "SKIPPED_HEALTH_METHODS",
+    "X_REQUEST_ID",
+    "is_server_error",
+    "resolve_status_code",
+]

grpc_server_kit/interceptors/constants.py

@@ -0,0 +1,44 @@
+"""Constants shared across gRPC interceptors."""
+
+from grpc_server_kit.constants import HEALTH_SERVICE_NAME
+
+# gRPC Health methods to skip in metrics, logging, tracing, and error tracking
+# (derived from the single canonical health service name).
+SKIPPED_HEALTH_METHODS = frozenset(
+    {
+        f"/{HEALTH_SERVICE_NAME}/Check",
+        f"/{HEALTH_SERVICE_NAME}/Watch",
+    }
+)
+
+# Common header names
+X_REQUEST_ID = "x-request-id"
+
+# Context variable names
+REQUEST_ID_KEY = "request_id"
+METHOD_KEY = "method"
+
+# OpenTelemetry semantic-convention attributes
+OTEL_RPC_SYSTEM = "rpc.system"
+OTEL_RPC_METHOD = "rpc.method"
+OTEL_RPC_SERVICE = "rpc.service"
+OTEL_RPC_GRPC_STATUS_CODE = "rpc.grpc.status_code"
+OTEL_REQUEST_ID = "request.id"
+
+# Sentry tag names
+SENTRY_GRPC_METHOD = "grpc_method"
+SENTRY_REQUEST_ID = "request_id"
+
+__all__ = [
+    "METHOD_KEY",
+    "OTEL_REQUEST_ID",
+    "OTEL_RPC_GRPC_STATUS_CODE",
+    "OTEL_RPC_METHOD",
+    "OTEL_RPC_SERVICE",
+    "OTEL_RPC_SYSTEM",
+    "REQUEST_ID_KEY",
+    "SENTRY_GRPC_METHOD",
+    "SENTRY_REQUEST_ID",
+    "SKIPPED_HEALTH_METHODS",
+    "X_REQUEST_ID",
+]

grpc_server_kit/interceptors/utils.py

@@ -0,0 +1,74 @@
+"""Utility functions for gRPC interceptors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import grpc
+
+
+def is_server_error(code: grpc.StatusCode) -> bool:
+    """Check if the gRPC status code is a server-side error (5xx equivalent).
+
+    Server-side errors include internal failures, timeouts, and unavailability.
+    If the code is not one of these, it is either OK or a client-side error (4xx equivalent).
+    """
+    return code in (
+        grpc.StatusCode.INTERNAL,
+        grpc.StatusCode.UNKNOWN,
+        grpc.StatusCode.DATA_LOSS,
+        grpc.StatusCode.UNIMPLEMENTED,
+        grpc.StatusCode.UNAVAILABLE,
+        grpc.StatusCode.DEADLINE_EXCEEDED,
+    )
+
+
+def resolve_status_code(
+    exc: BaseException | None,
+    context: Any,
+    default: grpc.StatusCode = grpc.StatusCode.UNKNOWN,
+) -> grpc.StatusCode:
+    """Best-effort gRPC status code for a finished or failed RPC.
+
+    Prefers the exception's own ``code()`` (client-style ``RpcError``); falls
+    back to the servicer context's code (set by ``abort()`` / ``set_code()``)
+    when the exception carries no code or only a generic ``UNKNOWN``; returns
+    ``default`` when neither yields a :class:`grpc.StatusCode`.
+    """
+    exc_code = _status_code_of_exception(exc)
+    if exc_code is not None and exc_code is not grpc.StatusCode.UNKNOWN:
+        return exc_code
+
+    ctx_code = _status_code_of_context(context)
+    if ctx_code is not None and ctx_code is not grpc.StatusCode.OK:
+        return ctx_code
+    if exc_code is not None:
+        # UNKNOWN from the exception and nothing better on the context.
+        return exc_code
+    if ctx_code is not None:
+        return ctx_code
+
+    return default
+
+
+def _status_code_of_exception(exc: BaseException | None) -> grpc.StatusCode | None:
+    if exc is None:
+        return None
+    code_func = getattr(exc, "code", None)
+    if callable(code_func):
+        code = code_func()
+        if isinstance(code, grpc.StatusCode):
+            return code
+    return None
+
+
+def _status_code_of_context(context: Any) -> grpc.StatusCode | None:
+    code_func = getattr(context, "code", None)
+    if not callable(code_func):
+        return None
+    try:
+        code = code_func()
+    except Exception:
+        # Non-conforming context objects fall through to the default.
+        return None
+    return code if isinstance(code, grpc.StatusCode) else None

grpc_server_kit/observability/__init__.py

@@ -0,0 +1,12 @@
+"""Optional observability wiring for the gRPC server.
+
+Submodules are import-gated by their own extras so importing this package never
+pulls heavy dependencies:
+
+- ``grpc_server_kit.observability.protocols`` — SDK-free seam protocols (core)
+- ``grpc_server_kit.observability.metrics`` — Prometheus metrics (``[metrics]`` extra)
+- ``grpc_server_kit.observability.sentry``  — Sentry adapter (``[sentry]`` extra)
+
+OpenTelemetry instrumentation for the async server lives at
+``grpc_server_kit.aio.observability.tracing`` (``[tracing]`` extra).
+"""

grpc_server_kit/observability/metrics.py

@@ -0,0 +1,116 @@
+"""Prometheus metric definitions for the gRPC server (``[metrics]`` extra).
+
+``GrpcServerMetrics`` structurally satisfies
+:class:`grpc_server_kit.aio.interceptors.protocols.GrpcServerMetricsProtocol`, so it can
+be passed straight to ``AsyncMetricsInterceptor``.
+"""
+
+from __future__ import annotations
+
+from grpc_server_kit.observability.naming import make_metric_name
+
+try:
+    from prometheus_client import REGISTRY, CollectorRegistry, Counter, Histogram
+
+    HAS_PROMETHEUS = True
+except ImportError:  # pragma: no cover - exercised only when the [metrics] extra is absent
+    HAS_PROMETHEUS = False
+
+__all__ = [
+    "DEFAULT_GRPC_BUCKETS",
+    "GrpcServerMetrics",
+    "get_grpc_server_metrics",
+    "make_metric_name",
+]
+
+# Default histogram buckets for gRPC request duration (seconds).
+DEFAULT_GRPC_BUCKETS = (0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0)
+
+_MISSING_MESSAGE = "Install grpc-server-kit[metrics] (prometheus-client) to use gRPC server metrics"
+
+
+class GrpcServerMetrics:
+    """gRPC server metrics.
+
+    Metrics:
+        - ``grpc_requests_total`` (Counter) — labels: service, method, status, grpc_code
+        - ``grpc_request_duration_seconds`` (Histogram) — labels: service, method
+    """
+
+    def __init__(
+        self,
+        prefix: str | None = None,
+        buckets: tuple[float, ...] = DEFAULT_GRPC_BUCKETS,
+        registry: CollectorRegistry | None = None,
+    ) -> None:
+        """Initialize gRPC server metrics.
+
+        Args:
+            prefix: Optional metric name prefix.
+            buckets: Histogram buckets for request duration.
+            registry: Collector registry to register with (defaults to the global one).
+
+        Raises:
+            ImportError: If prometheus-client is not installed.
+        """
+        if not HAS_PROMETHEUS:
+            raise ImportError(_MISSING_MESSAGE)
+
+        self.buckets: tuple[float, ...] = tuple(buckets)
+        reg = registry if registry is not None else REGISTRY
+        self.requests_total = Counter(
+            make_metric_name("grpc_requests_total", prefix),
+            "Total number of gRPC requests",
+            ["service", "method", "status", "grpc_code"],
+            registry=reg,
+        )
+        self.request_duration = Histogram(
+            make_metric_name("grpc_request_duration_seconds", prefix),
+            "gRPC request duration in seconds",
+            ["service", "method"],
+            buckets=list(buckets),
+            registry=reg,
+        )
+
+    def record_request(
+        self,
+        service: str,
+        method: str,
+        status: str,
+        grpc_code: str,
+        duration: float,
+    ) -> None:
+        """Record a completed gRPC request."""
+        self.requests_total.labels(service=service, method=method, status=status, grpc_code=grpc_code).inc()
+        self.request_duration.labels(service=service, method=method).observe(duration)
+
+
+_SERVER_METRICS_CACHE: dict[str | None, GrpcServerMetrics] = {}
+
+
+def get_grpc_server_metrics(
+    prefix: str | None = None,
+    buckets: tuple[float, ...] | None = None,
+) -> GrpcServerMetrics:
+    """Get (or lazily create) a cached ``GrpcServerMetrics`` for the given prefix.
+
+    Caching by prefix avoids Prometheus "duplicated timeseries" errors when the helper
+    is called more than once for the same prefix.
+
+    Raises:
+        ValueError: If the prefix is already cached with DIFFERENT buckets —
+            silently returning the old instance would record latencies into the
+            wrong histogram bounds with no error.
+    """
+    requested = tuple(buckets) if buckets is not None else DEFAULT_GRPC_BUCKETS
+    cached = _SERVER_METRICS_CACHE.get(prefix)
+    if cached is not None:
+        if buckets is not None and requested != cached.buckets:
+            raise ValueError(
+                f"GrpcServerMetrics for prefix {prefix!r} already exists with buckets "
+                f"{cached.buckets}; cannot re-create it with {requested}"
+            )
+        return cached
+    metrics = GrpcServerMetrics(prefix=prefix, buckets=requested)
+    _SERVER_METRICS_CACHE[prefix] = metrics
+    return metrics

grpc_server_kit/observability/naming.py

@@ -0,0 +1,26 @@
+"""Metric naming helpers (pure stdlib, backend-neutral)."""
+
+from __future__ import annotations
+
+import re
+
+_PREFIX_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+
+def make_metric_name(name: str, prefix: str | None = None) -> str:
+    """Combine ``prefix`` and ``name`` per metric identifier conventions.
+
+    Raises:
+        ValueError: If the prefix is not a valid metric name fragment.
+    """
+    if prefix:
+        if not _PREFIX_PATTERN.match(prefix):
+            raise ValueError(
+                f"Invalid metric prefix: {prefix!r}. Prefixes must start with a letter or "
+                "underscore and contain only letters, numbers, or underscores."
+            )
+        return f"{prefix}_{name}"
+    return name
+
+
+__all__ = ["make_metric_name"]

grpc_server_kit/observability/protocols.py

@@ -0,0 +1,86 @@
+"""Observability seam protocols (duck-typing, SDK-free).
+
+Pure structural protocols that the kit's interceptors call without knowing the
+concrete backend. The names are vendor-neutral: an OpenTelemetry tracer, the
+Sentry SDK adapter, or any test double with the same shape fits. Downstream
+frameworks (e.g. servicewright) adapt to these shapes — protocols match
+structurally, so no import dependency is required in either direction.
+"""
+
+from __future__ import annotations
+
+from contextlib import AbstractContextManager
+from types import TracebackType
+from typing import Protocol, runtime_checkable
+
+type SpanAttributeValue = str | int | float | bool | list[str] | list[int] | list[float] | list[bool]
+
+
+@runtime_checkable
+class SpanProtocol(Protocol):
+    """A tracing span context manager."""
+
+    def set_attribute(self, key: str, value: SpanAttributeValue) -> None:
+        """Attach a typed attribute to the span."""
+        ...
+
+    def record_exception(self, exception: Exception) -> None:
+        """Record an exception against the span."""
+        ...
+
+    def __enter__(self) -> SpanProtocol: ...
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None: ...
+
+
+@runtime_checkable
+class TracerProtocol(Protocol):
+    """Mints spans for the active trace."""
+
+    def start_as_current_span(self, name: str) -> SpanProtocol:
+        """Start a span and make it current for its ``with`` block."""
+        ...
+
+
+class ErrorReporterProtocol(Protocol):
+    """Error-reporting seam (vendor-neutral; any tracker with this shape fits)."""
+
+    def isolate(self) -> AbstractContextManager[object]:
+        """Return a context manager forking an isolated per-unit scope.
+
+        Tags and breadcrumbs set inside the block must not leak into other
+        concurrent units of work. Backends without scope isolation may return
+        ``contextlib.nullcontext()``.
+        """
+        ...
+
+    def capture_exception(self, error: Exception) -> None:
+        """Report an exception to the error tracker."""
+        ...
+
+    def add_breadcrumb(
+        self,
+        message: str,
+        category: str = "default",
+        level: str = "info",
+        data: dict[str, object] | None = None,
+    ) -> None:
+        """Attach a breadcrumb to the current scope."""
+        ...
+
+    def set_tags(self, **tags: str) -> None:
+        """Set tags on the current scope."""
+        ...
+
+
+__all__ = [
+    "ErrorReporterProtocol",
+    "SpanAttributeValue",
+    "SpanProtocol",
+    "TracerProtocol",
+]

grpc_server_kit/observability/sentry.py

@@ -0,0 +1,63 @@
+"""Sentry adapter implementing the kit's ``ErrorReporterProtocol`` over ``sentry-sdk``.
+
+Requires the ``[sentry]`` extra. Pass a ``SentrySdkAdapter`` instance to
+``AsyncSentryInterceptor`` to report unexpected gRPC errors to Sentry.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from contextlib import AbstractContextManager
+
+try:
+    import sentry_sdk
+
+    HAS_SENTRY = True
+except ImportError:  # pragma: no cover - exercised only when the [sentry] extra is absent
+    HAS_SENTRY = False
+
+__all__ = ["SentrySdkAdapter"]
+
+_MISSING_MESSAGE = "Install grpc-server-kit[sentry] (sentry-sdk) to use the Sentry adapter"
+
+
+class SentrySdkAdapter:
+    """Adapts the global ``sentry-sdk`` API to ``ErrorReporterProtocol``."""
+
+    def __init__(self) -> None:
+        """Initialize the adapter.
+
+        Raises:
+            ImportError: If sentry-sdk is not installed.
+        """
+        if not HAS_SENTRY:
+            raise ImportError(_MISSING_MESSAGE)
+
+    def isolate(self) -> AbstractContextManager[object]:
+        """Fork an isolated Sentry scope for one unit of work.
+
+        Without this, concurrent asyncio tasks share one isolation scope and
+        contaminate each other's tags/breadcrumbs.
+        """
+        return sentry_sdk.isolation_scope()
+
+    def add_breadcrumb(
+        self,
+        message: str,
+        category: str = "default",
+        level: str = "info",
+        data: dict[str, object] | None = None,
+    ) -> None:
+        """Add a breadcrumb to the current Sentry scope."""
+        sentry_sdk.add_breadcrumb(message=message, category=category, level=level, data=data or {})
+
+    def capture_exception(self, error: Exception) -> None:
+        """Capture an exception in Sentry."""
+        sentry_sdk.capture_exception(error)
+
+    def set_tags(self, **tags: str) -> None:
+        """Set tags on the current Sentry scope."""
+        for key, value in tags.items():
+            sentry_sdk.set_tag(key, value)

grpc_server_kit/options.py

@@ -0,0 +1,136 @@
+"""gRPC server options and compression configuration."""
+
+from __future__ import annotations
+
+from .constants import (
+    DEFAULT_HTTP2_MAX_PINGS_WITHOUT_DATA,
+    DEFAULT_HTTP2_MIN_RECV_PING_INTERVAL_WITHOUT_DATA_MS,
+    DEFAULT_INITIAL_WINDOW_SIZE,
+    DEFAULT_KEEPALIVE_TIME_MS,
+    DEFAULT_KEEPALIVE_TIMEOUT_MS,
+    DEFAULT_MAX_METADATA_SIZE,
+    DEFAULT_MAX_RECEIVE_MESSAGE_LENGTH,
+    DEFAULT_MAX_SEND_MESSAGE_LENGTH,
+)
+from .protocols import GrpcSettingsProtocol
+
+type GrpcOption = tuple[str, int]
+type GrpcOptions = list[GrpcOption]
+
+COMPRESSION_ALGORITHMS = {
+    "none": 0,
+    "deflate": 1,
+    "gzip": 2,
+}
+
+
+def build_grpc_options(settings: GrpcSettingsProtocol) -> GrpcOptions:
+    """Build gRPC server options from settings.
+
+    Settings fields set to ``None`` fall back to the kit's defaults; invalid
+    values fail loudly — a misconfigured server must not start.
+
+    Args:
+        settings: gRPC configuration settings following GrpcSettingsProtocol
+
+    Returns:
+        List of tuples containing gRPC channel options
+
+    Raises:
+        ValueError: If any option value is negative or the compression
+            algorithm is not supported.
+    """
+    options: GrpcOptions = [
+        # Message size
+        (
+            "grpc.max_send_message_length",
+            _require_option(
+                settings.max_send_message_length, "max_send_message_length", DEFAULT_MAX_SEND_MESSAGE_LENGTH
+            ),
+        ),
+        (
+            "grpc.max_receive_message_length",
+            _require_option(
+                settings.max_receive_message_length, "max_receive_message_length", DEFAULT_MAX_RECEIVE_MESSAGE_LENGTH
+            ),
+        ),
+        (
+            "grpc.max_metadata_size",
+            _require_option(settings.max_metadata_size, "max_metadata_size", DEFAULT_MAX_METADATA_SIZE),
+        ),
+        # Keepalive
+        (
+            "grpc.keepalive_time_ms",
+            _require_option(settings.keepalive_time_ms, "keepalive_time_ms", DEFAULT_KEEPALIVE_TIME_MS),
+        ),
+        (
+            "grpc.keepalive_timeout_ms",
+            _require_option(settings.keepalive_timeout_ms, "keepalive_timeout_ms", DEFAULT_KEEPALIVE_TIMEOUT_MS),
+        ),
+        ("grpc.keepalive_permit_without_calls", int(settings.keepalive_permit_without_calls)),
+        (
+            "grpc.http2.min_recv_ping_interval_without_data_ms",
+            _require_option(
+                settings.http2_min_recv_ping_interval_without_data_ms,
+                "http2_min_recv_ping_interval_without_data_ms",
+                DEFAULT_HTTP2_MIN_RECV_PING_INTERVAL_WITHOUT_DATA_MS,
+            ),
+        ),
+        (
+            "grpc.http2.max_pings_without_data",
+            _require_option(
+                settings.http2_max_pings_without_data,
+                "http2_max_pings_without_data",
+                DEFAULT_HTTP2_MAX_PINGS_WITHOUT_DATA,
+            ),
+        ),
+        # Flow control
+        (
+            "grpc.http2.initial_stream_window_size",
+            _require_option(
+                settings.initial_stream_window_size, "initial_stream_window_size", DEFAULT_INITIAL_WINDOW_SIZE
+            ),
+        ),
+        (
+            "grpc.http2.initial_connection_window_size",
+            _require_option(
+                settings.initial_connection_window_size, "initial_connection_window_size", DEFAULT_INITIAL_WINDOW_SIZE
+            ),
+        ),
+    ]
+
+    # Optional: connection limits (omitted entirely when not configured)
+    for option_name, value, setting_name in (
+        ("grpc.max_concurrent_streams", settings.max_concurrent_rpcs, "max_concurrent_rpcs"),
+        ("grpc.max_connection_idle_ms", settings.max_connection_idle_ms, "max_connection_idle_ms"),
+        ("grpc.max_connection_age_ms", settings.max_connection_age_ms, "max_connection_age_ms"),
+        ("grpc.max_connection_age_grace_ms", settings.max_connection_age_grace_ms, "max_connection_age_grace_ms"),
+    ):
+        if value is not None:
+            options.append((option_name, _require_non_negative(value, setting_name)))
+
+    # Compression
+    if settings.compression_algorithm:
+        algo = settings.compression_algorithm.lower()
+        if algo not in COMPRESSION_ALGORITHMS:
+            supported = ", ".join(sorted(COMPRESSION_ALGORITHMS))
+            raise ValueError(
+                f"Unsupported compression_algorithm: {settings.compression_algorithm!r}. Supported: {supported}"
+            )
+        options.append(("grpc.default_compression_algorithm", COMPRESSION_ALGORITHMS[algo]))
+
+    return options
+
+
+def _require_option(value: int | None, name: str, default: int) -> int:
+    """Return ``default`` when unset; reject negative values loudly."""
+    if value is None:
+        return default
+    return _require_non_negative(value, name)
+
+
+def _require_non_negative(value: int, name: str) -> int:
+    """Validate that a configured option value is non-negative."""
+    if value < 0:
+        raise ValueError(f"{name} must be non-negative, got {value}")
+    return value