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

grpc_server_kit/protocols.py

@@ -0,0 +1,114 @@
+"""Structural protocols (duck-typing seams) for gRPC settings and servers.
+
+Settings fields are declared as read-only properties, not plain attributes:
+protocol attributes are invariant under type checking, while read-only
+properties are covariant — implementations may narrow field types (e.g. a
+pydantic model typing ``compression_algorithm`` as a ``Literal``) and still
+satisfy the protocol.
+"""
+
+from typing import TYPE_CHECKING, Any, NewType, Protocol
+
+import grpc
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+# Typed DI key for the fully-qualified gRPC service name (avoids ambiguous bare `str`).
+GrpcServiceName = NewType("GrpcServiceName", str)
+
+
+class GrpcSettingsProtocol(Protocol):
+    """Protocol for gRPC channel-tuning settings."""
+
+    @property
+    def host(self) -> str: ...
+    @property
+    def port(self) -> int: ...
+    @property
+    def keepalive_time_ms(self) -> int: ...
+    @property
+    def keepalive_timeout_ms(self) -> int: ...
+    @property
+    def keepalive_permit_without_calls(self) -> bool: ...
+    @property
+    def http2_min_recv_ping_interval_without_data_ms(self) -> int: ...
+    @property
+    def http2_max_pings_without_data(self) -> int: ...
+    @property
+    def max_send_message_length(self) -> int: ...
+    @property
+    def max_receive_message_length(self) -> int: ...
+    @property
+    def max_metadata_size(self) -> int: ...
+    @property
+    def initial_stream_window_size(self) -> int: ...
+    @property
+    def initial_connection_window_size(self) -> int: ...
+    @property
+    def max_connection_idle_ms(self) -> int | None: ...
+    @property
+    def max_connection_age_ms(self) -> int | None: ...
+    @property
+    def max_connection_age_grace_ms(self) -> int | None: ...
+    @property
+    def compression_algorithm(self) -> str | None: ...
+    @property
+    def max_concurrent_rpcs(self) -> int | None: ...
+
+
+class GrpcSslSettingsProtocol(Protocol):
+    """Protocol for gRPC SSL/TLS settings."""
+
+    @property
+    def ssl_enabled(self) -> bool: ...
+    @property
+    def ssl_cert_file(self) -> str | None: ...
+    @property
+    def ssl_key_file(self) -> str | None: ...
+    @property
+    def ssl_ca_file(self) -> str | None: ...
+    @property
+    def ssl_client_auth(self) -> bool: ...
+    @property
+    def ssl_max_cert_size(self) -> int | None: ...
+
+
+class GrpcServerSettingsProtocol(GrpcSettingsProtocol, GrpcSslSettingsProtocol, Protocol):
+    """Protocol for the full gRPC server settings."""
+
+    @property
+    def grace_period(self) -> float: ...
+    @property
+    def enable_reflection(self) -> bool: ...
+    @property
+    def enable_channelz(self) -> bool: ...
+
+
+class GrpcServerProtocol(Protocol):
+    """Protocol for a synchronous gRPC server."""
+
+    def add_insecure_port(self, address: str) -> int: ...
+    def add_secure_port(self, address: str, credentials: grpc.ServerCredentials) -> int: ...
+    def start(self) -> None: ...
+    def stop(self, grace: float | None) -> None: ...
+
+
+class GrpcAsyncServerProtocol(Protocol):
+    """Protocol for an asynchronous gRPC server."""
+
+    def add_insecure_port(self, address: str) -> int: ...
+    def add_secure_port(self, address: str, credentials: grpc.ServerCredentials) -> int: ...
+    def start(self) -> "Coroutine[Any, Any, None]": ...
+    def stop(self, grace: float | None) -> "Coroutine[Any, Any, None]": ...
+    def wait_for_termination(self, timeout: float | None = None) -> "Coroutine[None, None, bool]": ...
+
+
+__all__ = [
+    "GrpcAsyncServerProtocol",
+    "GrpcServerProtocol",
+    "GrpcServerSettingsProtocol",
+    "GrpcServiceName",
+    "GrpcSettingsProtocol",
+    "GrpcSslSettingsProtocol",
+]

grpc_server_kit/server.py

@@ -0,0 +1,59 @@
+"""Common gRPC server utilities (sync and async)."""
+
+import logging
+import string
+
+from .credentials import load_server_credentials
+from .protocols import GrpcAsyncServerProtocol, GrpcServerProtocol, GrpcServerSettingsProtocol
+
+logger = logging.getLogger(__name__)
+
+# gRPC service names are dot-separated identifiers up to 253 characters
+# (per the gRPC naming and Health Checking Protocol conventions). One shared
+# validator serves reflection registration and the health servicer alike.
+SERVICE_NAME_MAX_LENGTH = 253
+_SERVICE_NAME_ALLOWED_CHARS = frozenset(string.ascii_letters + string.digits + "._-/")
+
+
+def is_valid_service_name(service: str) -> bool:
+    """Check a fully-qualified gRPC service name (character whitelist, no regex)."""
+    if not service or len(service) > SERVICE_NAME_MAX_LENGTH:
+        return False
+    return all(c in _SERVICE_NAME_ALLOWED_CHARS for c in service)
+
+
+def bind_server_port(
+    server: GrpcServerProtocol | GrpcAsyncServerProtocol,
+    settings: GrpcServerSettingsProtocol,
+) -> int:
+    """Bind gRPC server to the configured port with or without TLS.
+
+    Compatible with both sync and async gRPC servers.
+
+    Note:
+        If settings.port is 0, the OS will choose an available ephemeral port.
+        The actual port bound is returned by this function.
+
+    Args:
+        server: gRPC server instance (sync or async)
+        settings: Server settings including host, port, and SSL configuration
+
+    Returns:
+        The actual bound port number.
+    """
+    if not (0 <= settings.port <= 65535):
+        raise ValueError(f"Invalid port number: {settings.port}")
+
+    if not settings.host:
+        raise ValueError("Host cannot be empty")
+
+    bind_address = f"{settings.host}:{settings.port}"
+    if settings.ssl_enabled:
+        credentials = load_server_credentials(settings)
+        port = server.add_secure_port(bind_address, credentials)
+        logger.info("gRPC server with TLS", extra={"address": bind_address, "port": port})
+    else:
+        port = server.add_insecure_port(bind_address)
+        logger.info("gRPC server (insecure)", extra={"address": bind_address, "port": port})
+
+    return port

grpc_server_kit/settings.py

@@ -0,0 +1,151 @@
+"""Standardized gRPC server and health-check configuration models (pydantic).
+
+These are plain :class:`pydantic.BaseModel` building blocks meant to be nested
+inside a service's own ``BaseSettings`` (so environment loading and prefixes stay
+under the service's control). They structurally satisfy
+:class:`grpc_server_kit.protocols.GrpcServerSettingsProtocol`.
+
+This module is gated behind the ``[settings]`` optional dependency
+(``pip install grpc-server-kit[settings]``) which pulls in ``pydantic``.
+For a zero-dependency alternative see :class:`grpc_server_kit.config.GrpcServerConfig`.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from grpc_server_kit.constants import (
+    DEFAULT_GRACE_PERIOD,
+    DEFAULT_HEALTH_CACHE_TTL,
+    DEFAULT_HEALTH_CHECK_TIMEOUT,
+    DEFAULT_HOST,
+    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,
+    DEFAULT_PORT,
+)
+
+GrpcCompressionAlgorithm = Literal["deflate", "gzip"]
+
+
+class BaseHealthSettings(BaseModel):
+    """Base configuration for gRPC health checks.
+
+    Consumed by :meth:`grpc_server_kit.aio.GrpcApp.enable_health` as the source
+    of defaults when the app's settings object carries a ``health`` block.
+    """
+
+    cache_ttl: float = Field(
+        default=DEFAULT_HEALTH_CACHE_TTL,
+        ge=0,
+        description="Health check result cache TTL in seconds (0 disables caching)",
+    )
+    check_timeout: float = Field(
+        default=DEFAULT_HEALTH_CHECK_TIMEOUT, gt=0, description="Timeout for each health check run in seconds"
+    )
+
+
+class BaseGrpcServerSettings(BaseModel):
+    """Base gRPC server configuration.
+
+    Standardized settings for gRPC servers, including TLS, keepalive, and limits.
+    """
+
+    # Basic
+    host: str = Field(default=DEFAULT_HOST, min_length=1, description="gRPC server host")
+    port: int = Field(default=DEFAULT_PORT, ge=0, le=65535, description="gRPC server port (0 = ephemeral)")
+
+    # TLS/SSL settings
+    ssl_enabled: bool = Field(default=False, description="Enable TLS/SSL")
+    ssl_cert_file: str | None = Field(default=None, description="Path to server certificate")
+    ssl_key_file: str | None = Field(default=None, description="Path to server private key")
+    ssl_ca_file: str | None = Field(default=None, description="Path to CA certificate (for mTLS)")
+    ssl_client_auth: bool = Field(default=False, description="Require client certificate (mTLS)")
+    ssl_max_cert_size: int | None = Field(default=None, ge=1, description="Maximum certificate file size (bytes)")
+
+    # Keepalive settings
+    keepalive_time_ms: int = Field(
+        default=DEFAULT_KEEPALIVE_TIME_MS, ge=0, description="Time between keepalive pings (ms)"
+    )
+    keepalive_timeout_ms: int = Field(
+        default=DEFAULT_KEEPALIVE_TIMEOUT_MS, ge=0, description="Timeout for keepalive ping response (ms)"
+    )
+    keepalive_permit_without_calls: bool = Field(
+        default=False,
+        description="Allow keepalive pings without active RPCs",
+    )
+    http2_min_recv_ping_interval_without_data_ms: int = Field(
+        default=DEFAULT_HTTP2_MIN_RECV_PING_INTERVAL_WITHOUT_DATA_MS,
+        ge=0,
+        description="Minimum time between pings from client without data",
+    )
+    http2_max_pings_without_data: int = Field(
+        default=DEFAULT_HTTP2_MAX_PINGS_WITHOUT_DATA, ge=0, description="Max pings allowed without data before GOAWAY"
+    )
+
+    # Connection limits
+    max_concurrent_rpcs: int | None = Field(default=None, ge=1, description="Maximum concurrent RPCs")
+    max_connection_idle_ms: int | None = Field(default=None, ge=1, description="Max idle time (ms)")
+    max_connection_age_ms: int | None = Field(default=None, ge=1, description="Max connection age (ms)")
+    max_connection_age_grace_ms: int | None = Field(default=None, ge=1, description="Grace period (ms)")
+
+    # Message size limits
+    max_send_message_length: int = Field(
+        default=DEFAULT_MAX_SEND_MESSAGE_LENGTH, ge=1, description="Max send length (bytes)"
+    )
+    max_receive_message_length: int = Field(
+        default=DEFAULT_MAX_RECEIVE_MESSAGE_LENGTH, ge=1, description="Max receive length (bytes)"
+    )
+    max_metadata_size: int = Field(default=DEFAULT_MAX_METADATA_SIZE, ge=1, description="Max metadata size (bytes)")
+
+    # Compression
+    compression_algorithm: GrpcCompressionAlgorithm | None = Field(
+        default=None,
+        description="Default compression: deflate or gzip (None = no compression)",
+    )
+
+    # Flow control settings
+    initial_stream_window_size: int = Field(
+        default=DEFAULT_INITIAL_WINDOW_SIZE, ge=1, description="Initial stream window (bytes)"
+    )
+    initial_connection_window_size: int = Field(
+        default=DEFAULT_INITIAL_WINDOW_SIZE, ge=1, description="Initial connection window (bytes)"
+    )
+
+    # Features
+    enable_reflection: bool = Field(default=False, description="Enable gRPC reflection")
+    enable_channelz: bool = Field(default=False, description="Enable channelz for debugging")
+
+    # Graceful shutdown
+    grace_period: float = Field(
+        default=DEFAULT_GRACE_PERIOD, ge=0, description="Graceful shutdown grace period in seconds"
+    )
+
+    # Metrics (consumed by the dishka bundle / your own wiring)
+    metrics_enabled: bool = Field(default=False, description="Enable gRPC server metrics")
+
+    # Health (consumed by GrpcApp.enable_health as its defaults)
+    health: BaseHealthSettings = Field(default_factory=BaseHealthSettings, description="Health check configuration")
+
+    @model_validator(mode="after")
+    def _validate_ssl(self) -> "BaseGrpcServerSettings":
+        if self.ssl_enabled:
+            if not self.ssl_cert_file:
+                raise ValueError("gRPC ssl_cert_file is required when ssl_enabled=True")
+            if not self.ssl_key_file:
+                raise ValueError("gRPC ssl_key_file is required when ssl_enabled=True")
+            if self.ssl_client_auth and not self.ssl_ca_file:
+                raise ValueError("gRPC ssl_ca_file is required when ssl_client_auth=True")
+        return self
+
+
+__all__ = [
+    "BaseGrpcServerSettings",
+    "BaseHealthSettings",
+    "GrpcCompressionAlgorithm",
+]

grpc_server_kit/signals.py

@@ -0,0 +1,228 @@
+"""Signal handling for graceful gRPC server shutdown."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import functools
+import inspect
+import logging
+import signal
+import sys
+import types
+from typing import TYPE_CHECKING, Any, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Coroutine
+
+logger = logging.getLogger(__name__)
+
+_HANDLED_SIGNALS = (signal.SIGINT, signal.SIGTERM)
+
+# Handler value used by the standard `signal` module (SIG_DFL/SIG_IGN/callable/None).
+type _StdSignalHandler = Callable[[int, types.FrameType | None], Any] | int | signal.Handlers | None
+
+
+class SignalManager:
+    """Manager for signal handlers to avoid global state.
+
+    A manager can be reused across sequential runs: :meth:`reset` /
+    :meth:`reset_async` restore the signal handlers that were installed before
+    :meth:`setup` (not the OS defaults) and re-arm the manager for the next
+    setup/signal cycle.
+    """
+
+    def __init__(self) -> None:
+        self._handlers_set_up = False
+        self._used_loop_handlers = False
+        self._saved_std_handlers: dict[int, _StdSignalHandler] = {}
+        self._background_tasks: set[asyncio.Future[None]] = set()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._shutdown_in_progress = False
+
+    def setup(
+        self,
+        shutdown_callback: Callable[[str], None] | Callable[[str], Awaitable[None]],
+    ) -> None:
+        """Setup signal handlers for graceful shutdown.
+
+        Supports both synchronous and asynchronous callbacks. Degrades to a
+        warning (instead of crashing) when handlers cannot be installed — e.g.
+        when called from a non-main thread, where Python allows no signal
+        handling at all.
+        """
+        if self._handlers_set_up:
+            return
+
+        try:
+            self._loop = asyncio.get_running_loop()
+        except RuntimeError:
+            self._loop = None
+
+        is_async = inspect.iscoroutinefunction(shutdown_callback)
+
+        def handle_signal(sig_name: str) -> None:
+            if self._shutdown_in_progress:
+                logger.debug("Shutdown already in progress, ignoring signal", extra={"signal": sig_name})
+                return
+
+            self._shutdown_in_progress = True
+            logger.info("Received signal, starting shutdown", extra={"signal": sig_name})
+
+            if is_async:
+                # Always try to schedule on the captured loop if it exists
+                if self._loop and self._loop.is_running():
+
+                    def _schedule_callback() -> None:
+                        coro = shutdown_callback(sig_name)
+                        if self._loop is None:
+                            return
+
+                        task: asyncio.Task[None] = self._loop.create_task(cast("Coroutine[Any, Any, None]", coro))
+                        self._background_tasks.add(task)
+
+                        def _done_cb(t: asyncio.Task[None]) -> None:
+                            self._background_tasks.discard(t)
+                            try:
+                                t.result()
+                            except (asyncio.CancelledError, KeyboardInterrupt, SystemExit):
+                                pass
+                            except Exception:
+                                logger.exception("Error in async shutdown callback", extra={"signal": sig_name})
+
+                        task.add_done_callback(_done_cb)
+
+                    self._loop.call_soon_threadsafe(_schedule_callback)
+                else:
+                    # No running loop, fallback to sync if possible (unlikely for async callback)
+                    logger.warning("No running event loop to schedule async shutdown callback")
+            else:
+                # shutdown_callback is Callable[[str], None]
+                if self._loop and self._loop.is_running():
+                    self._loop.call_soon_threadsafe(lambda: shutdown_callback(sig_name))
+                else:
+                    shutdown_callback(sig_name)
+
+        if self._setup_loop_handlers(handle_signal):
+            self._used_loop_handlers = True
+        else:
+            self._setup_standard_handlers(handle_signal)
+
+        self._handlers_set_up = True
+
+    def _setup_loop_handlers(self, handle_signal: Callable[[str], None]) -> bool:
+        """Setup signal handlers using asyncio loop.
+
+        Returns:
+            True if handlers were successfully set up via loop, False otherwise.
+        """
+        if sys.platform != "win32" and self._loop:
+            try:
+                for sig in _HANDLED_SIGNALS:
+                    self._loop.add_signal_handler(sig, functools.partial(handle_signal, sig.name))
+            except (RuntimeError, ValueError):
+                return False
+            else:
+                return True
+
+        return False
+
+    def _setup_standard_handlers(self, handle_signal: Callable[[str], None]) -> None:
+        """Setup handlers via the standard signal module, saving the previous ones.
+
+        ``signal.signal`` raises ValueError outside the main thread — degrade to
+        a warning instead of crashing the caller after the server has started.
+        """
+
+        def _handler(signum: int, _frame: types.FrameType | None) -> None:
+            sig_name = f"signal {signum}"
+            with contextlib.suppress(ValueError, AttributeError):
+                sig_name = signal.Signals(signum).name
+            handle_signal(sig_name)
+
+        signals = _HANDLED_SIGNALS if sys.platform != "win32" else (signal.SIGINT,)
+        for sig in signals:
+            try:
+                previous = signal.signal(sig, _handler)
+            except (ValueError, OSError):
+                logger.warning(
+                    "Cannot install signal handler (non-main thread?); "
+                    "graceful shutdown by signal is disabled for this run",
+                    extra={"signal": sig.name},
+                )
+                return
+            self._saved_std_handlers[sig] = previous
+
+    def _restore_handlers(self) -> None:
+        """Restore the signal handlers that were in place before setup()."""
+        if self._used_loop_handlers and self._loop and self._loop.is_running():
+            for sig in _HANDLED_SIGNALS:
+                with contextlib.suppress(RuntimeError, ValueError):
+                    self._loop.remove_signal_handler(sig)
+
+        # Restore the exact previous handlers (NOT SIG_DFL: Python's default
+        # SIGINT handler is default_int_handler, and the host application may
+        # have installed its own handlers before us).
+        for signum, previous in self._saved_std_handlers.items():
+            with contextlib.suppress(ValueError, OSError, TypeError):
+                signal.signal(signum, previous)
+
+        self._saved_std_handlers.clear()
+        self._used_loop_handlers = False
+        self._handlers_set_up = False
+        self._shutdown_in_progress = False
+        self._loop = None
+
+    async def reset_async(self) -> None:
+        """Restore previous signal handlers and await pending shutdown callbacks."""
+        if not self._handlers_set_up:
+            return
+
+        pending = list(self._background_tasks)
+        self._restore_handlers()
+        if pending:
+            # We don't cancel them, we wait for them to finish naturally (shutdown callbacks)
+            await asyncio.gather(*pending, return_exceptions=True)
+        self._background_tasks.clear()
+
+    def reset(self) -> None:
+        """Restore previous signal handlers synchronously.
+
+        Note: This cancels pending background tasks. Use reset_async to wait
+        for them instead.
+        """
+        if not self._handlers_set_up:
+            return
+
+        self._restore_handlers()
+        for task in self._background_tasks:
+            if not task.done():
+                task.cancel()
+        self._background_tasks.clear()
+
+
+# Default instance for convenience, but allows creating independent managers
+_default_manager = SignalManager()
+
+
+def setup_signal_handlers(
+    shutdown_callback: Callable[[str], None] | Callable[[str], Awaitable[None]],
+) -> None:
+    """Setup signal handlers using the default manager."""
+    _default_manager.setup(shutdown_callback)
+
+
+def reset_signal_handlers() -> None:
+    """Reset signal handlers using the default manager.
+
+    Note: This is synchronous and cancels pending tasks.
+    """
+    _default_manager.reset()
+
+
+async def reset_signal_handlers_async() -> None:
+    """Reset signal handlers asynchronously using the default manager.
+
+    Awaits all pending background tasks.
+    """
+    await _default_manager.reset_async()