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

grpc_server_kit/aio/runtime.py

@@ -0,0 +1,206 @@
+"""Runtime helpers for gRPC server lifecycle (async)."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from typing import TYPE_CHECKING
+
+from ..constants import DEFAULT_GRACE_PERIOD
+from ..signals import SignalManager
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from ..protocols import GrpcAsyncServerProtocol
+
+logger = logging.getLogger(__name__)
+
+# After a successful stop() the server's termination waiter resolves promptly;
+# this cap only guards against non-conforming server implementations.
+_POST_STOP_TERMINATION_TIMEOUT = 1.0
+
+
+class ServerLifecycleManager:
+    """Manages the lifecycle of an async gRPC server.
+
+    Args:
+        server: The async gRPC server to manage.
+        address: Human-readable bind address used for logging.
+        grace_period: Graceful shutdown grace period in seconds. ``None`` maps
+            to gRPC's own semantics: all in-flight RPCs are aborted immediately.
+        signal_manager: Optional custom signal manager.
+    """
+
+    def __init__(
+        self,
+        server: GrpcAsyncServerProtocol,
+        address: str,
+        grace_period: float | None = DEFAULT_GRACE_PERIOD,
+        signal_manager: SignalManager | None = None,
+    ) -> None:
+        if grace_period is not None and grace_period < 0:
+            raise ValueError(f"grace_period must be non-negative, got {grace_period}")
+
+        self._server = server
+        self._address = address
+        self._grace_period = grace_period
+        self._signal_manager = signal_manager or SignalManager()
+        self._stop_event = asyncio.Event()
+        self._stop_reason = "terminated"
+        self._handlers_set_up = False
+
+    async def __aenter__(self) -> GrpcAsyncServerProtocol:
+        """Async context manager entry: start the server."""
+        await self._server.start()
+        logger.info("gRPC server started", extra={"address": self._address})
+        return self._server
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Async context manager exit: stop the server."""
+        await self.stop()
+
+    def request_shutdown(self, reason: str = "requested") -> None:
+        """Request a graceful shutdown, honored by the running or the next :meth:`run` loop.
+
+        Idempotent: repeated requests are ignored and the FIRST reason is kept,
+        since that is what actually triggered the shutdown. A request made
+        before :meth:`run` starts is remembered, so a signal racing startup is
+        never lost.
+
+        Safe to call from the event loop (e.g. from a handler or a background
+        task); from other threads use ``loop.call_soon_threadsafe``.
+        """
+        if self._stop_event.is_set():
+            logger.debug("Shutdown already requested, ignoring", extra={"reason": reason})
+            return
+        self._stop_reason = reason
+        self._stop_event.set()
+
+    async def run(self, setup_signals: bool = True) -> None:
+        """Run the server until termination, shutdown request, or signal."""
+        self._handlers_set_up = setup_signals
+        if not self._stop_event.is_set():
+            # Fresh run: forget why the PREVIOUS run stopped. When a shutdown is
+            # already pending for this run, its reason is kept instead.
+            self._stop_reason = "terminated"
+
+        # Install signal handlers BEFORE starting the server so a setup failure
+        # can never leave a started server running with no way to stop it.
+        if setup_signals:
+            self._signal_manager.setup(self._on_signal)
+
+        try:
+            await self._server.start()
+        except BaseException:
+            if setup_signals:
+                await self._signal_manager.reset_async()
+            raise
+        logger.info("gRPC server started", extra={"address": self._address})
+
+        wait_task: asyncio.Task[bool] = asyncio.create_task(
+            self._server.wait_for_termination(), name=f"grpc-server-wait:{self._address}"
+        )
+        stop_task = asyncio.create_task(self._stop_event.wait(), name=f"grpc-server-stop-event:{self._address}")
+
+        try:
+            done, _ = await asyncio.wait(
+                [wait_task, stop_task],
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            for t in done:
+                t.result()
+        except asyncio.CancelledError:
+            self._stop_reason = "cancelled"
+            raise
+        except KeyboardInterrupt:
+            self._stop_reason = "keyboard_interrupt"
+            raise
+        finally:
+            stop_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await stop_task
+
+            # Stop the server BEFORE touching wait_task: cancelling a task that
+            # awaits the server's shared termination future would poison that
+            # future and break stop() itself. After a successful stop the
+            # termination waiter completes on its own.
+            try:
+                await self.stop()
+                with contextlib.suppress(asyncio.CancelledError, TimeoutError):
+                    await asyncio.wait_for(wait_task, timeout=_POST_STOP_TERMINATION_TIMEOUT)
+            finally:
+                if not wait_task.done():
+                    wait_task.cancel()
+                    with contextlib.suppress(asyncio.CancelledError):
+                        await wait_task
+
+                # Re-arm AFTER this run has fully stopped (never at the start of
+                # the next one): a shutdown requested between runs must be
+                # honored by the next run, not silently discarded. The stop
+                # reason survives for post-run introspection.
+                self._stop_event = asyncio.Event()
+
+    async def stop(self) -> None:
+        """Stop the server gracefully, then restore signal handlers.
+
+        Signal handlers stay installed through the whole drain so a repeated
+        SIGINT/SIGTERM during the grace period is absorbed (logged and ignored)
+        instead of killing the process mid-drain.
+        """
+        logger.info("Shutting down gRPC server...", extra={"reason": self._stop_reason})
+
+        # Use a task and shield to ensure stop() completes even if this task is cancelled
+        stop_task: asyncio.Task[None] = asyncio.create_task(self._server.stop(grace=self._grace_period))
+        try:
+            await asyncio.shield(stop_task)
+        except asyncio.CancelledError:
+            # If the waiter is cancelled, re-await the task so shutdown still
+            # completes, then let the cancellation propagate.
+            await stop_task
+            raise
+        finally:
+            if self._handlers_set_up:
+                self._handlers_set_up = False
+                await self._signal_manager.reset_async()
+
+        logger.info("gRPC server stopped")
+
+    async def _on_signal(self, sig_name: str) -> None:
+        """Signal handler."""
+        self.request_shutdown(f"signal_{sig_name}")
+
+
+async def run_async_grpc_server(
+    server: GrpcAsyncServerProtocol,
+    *,
+    address: str,
+    grace_period: float | None = DEFAULT_GRACE_PERIOD,
+    setup_signals: bool = True,
+    signal_manager: SignalManager | None = None,
+) -> None:
+    """Start gRPC server and handle graceful shutdown lifecycle.
+
+    Uses ServerLifecycleManager to orchestrate the server runtime.
+
+    Args:
+        server: The async gRPC server to run.
+        address: Human-readable bind address used for logging.
+        grace_period: Graceful shutdown grace period in seconds. ``None`` maps
+            to gRPC's own semantics: all in-flight RPCs are aborted immediately.
+        setup_signals: Whether to install SIGINT/SIGTERM handlers.
+        signal_manager: Optional custom signal manager (a fresh one is created if omitted).
+    """
+    manager = ServerLifecycleManager(
+        server=server,
+        address=address,
+        grace_period=grace_period,
+        signal_manager=signal_manager,
+    )
+    await manager.run(setup_signals=setup_signals)

grpc_server_kit/aio/server.py

@@ -0,0 +1,191 @@
+"""gRPC server creation and configuration helpers (async)."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+import grpc
+
+from ..options import build_grpc_options
+from ..protocols import GrpcAsyncServerProtocol, GrpcServerSettingsProtocol
+from ..server import is_valid_service_name
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+try:
+    from grpc_reflection.v1alpha import reflection
+except ImportError:
+    reflection = None
+
+try:
+    from grpc_channelz.v1 import channelz
+except ImportError:
+    channelz = None
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncServer(GrpcAsyncServerProtocol):
+    """Thin, typed wrapper over :class:`grpc.aio.Server`.
+
+    Exposes the surface the kit needs (ports, lifecycle, servicer registration)
+    with precise types; everything else is reachable via :attr:`raw_server`.
+    Generated ``add_*Servicer_to_server`` functions accept this wrapper directly.
+    """
+
+    def __init__(self, server: grpc.aio.Server) -> None:
+        self._server = server
+
+    @property
+    def raw_server(self) -> grpc.aio.Server:
+        """Get the underlying gRPC server."""
+        return self._server
+
+    def add_generic_rpc_handlers(self, generic_rpc_handlers: Sequence[grpc.GenericRpcHandler]) -> None:
+        """Register generic RPC handlers (used by generated registration functions)."""
+        self._server.add_generic_rpc_handlers(generic_rpc_handlers)
+
+    def add_registered_method_handlers(self, service_name: str, method_handlers: dict[str, Any]) -> None:
+        """Register per-method handlers (used by newer generated registration functions)."""
+        self._server.add_registered_method_handlers(service_name, method_handlers)
+
+    def add_insecure_port(self, address: str) -> int:
+        """Add insecure port; delegates to underlying server and returns int."""
+        return int(self._server.add_insecure_port(address))
+
+    def add_secure_port(self, address: str, credentials: grpc.ServerCredentials) -> int:
+        """Add secure port; delegates to underlying server and returns int."""
+        return int(self._server.add_secure_port(address, credentials))
+
+    async def start(self) -> None:
+        """Start the server."""
+        await self._server.start()
+
+    async def stop(self, grace: float | None) -> None:
+        """Stop the server."""
+        if grace is not None and grace < 0:
+            raise ValueError(f"grace must be non-negative or None, got {grace}")
+        await self._server.stop(grace)
+
+    async def wait_for_termination(self, timeout: float | None = None) -> bool:
+        """Wait for server termination.
+
+        Returns:
+            True if the server has terminated, False if the timeout expired before termination.
+        """
+        result = await self._server.wait_for_termination(timeout)
+        return result if isinstance(result, bool) else bool(result)
+
+
+def create_async_grpc_server(
+    *,
+    interceptors: list[grpc.aio.ServerInterceptor],
+    settings: GrpcServerSettingsProtocol,
+    register_servicers: Callable[[grpc.aio.Server], None] | None = None,
+    enable_reflection: bool = False,
+    reflection_service_names: Sequence[str] | None = None,
+    enable_channelz: bool = False,
+) -> AsyncServer:
+    """Create async gRPC server, register servicers, and optionally enable debug services.
+
+    Args:
+        interceptors: List of async gRPC interceptors
+        settings: gRPC server settings
+        register_servicers: Optional callback to register gRPC servicers (servicers can
+            also be registered later on the returned server)
+        enable_reflection: Whether to enable gRPC reflection
+        reflection_service_names: List of service names to expose via reflection
+        enable_channelz: Whether to enable gRPC channelz
+
+    Returns:
+        Configured async gRPC server ready to be started
+
+    Raises:
+        ValueError: If reflection is enabled but service names are not provided
+        ImportError: If reflection or channelz packages are missing when enabled
+    """
+    server_wrapper = create_base_async_grpc_server(interceptors, settings)
+    if register_servicers is not None:
+        # register_servicers expects the raw grpc.aio.Server
+        register_servicers(server_wrapper.raw_server)
+
+    if enable_reflection:
+        if reflection is None:
+            raise ImportError(
+                "grpcio-reflection is not installed. "
+                "Please install it with 'pip install grpcio-reflection' "
+                "or use 'grpc-server-kit[reflection]' optional dependency."
+            )
+
+        validated_names = validate_reflection_service_names(reflection_service_names)
+        reflection.enable_server_reflection(
+            [*validated_names, reflection.SERVICE_NAME],
+            server_wrapper.raw_server,
+        )
+        logger.info("gRPC reflection enabled")
+
+    if enable_channelz:
+        if channelz is None:
+            raise ImportError(
+                "grpcio-channelz is not installed. "
+                "Please install it with 'pip install grpcio-channelz' "
+                "or use 'grpc-server-kit[channelz]' optional dependency."
+            )
+
+        channelz.add_channelz_servicer(server_wrapper.raw_server)
+        logger.info("Channelz enabled")
+
+    return server_wrapper
+
+
+def validate_reflection_service_names(service_names: Sequence[str] | None) -> list[str]:
+    """Validate and normalize (strip, dedupe) reflection service names.
+
+    Raises:
+        ValueError: If the list is empty or contains invalid service names.
+    """
+    if not service_names:
+        raise ValueError("reflection_service_names must be provided when reflection is enabled")
+
+    validated_names: list[str] = []
+    for name in service_names:
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError(f"Invalid service name: {name}")
+
+        clean_name = name.strip()
+        if not is_valid_service_name(clean_name):
+            raise ValueError(f"Invalid gRPC service name format: {clean_name}")
+
+        if clean_name not in validated_names:
+            validated_names.append(clean_name)
+
+    return validated_names
+
+
+def create_base_async_grpc_server(
+    interceptors: list[grpc.aio.ServerInterceptor],
+    settings: GrpcServerSettingsProtocol,
+) -> AsyncServer:
+    """Create and configure basic async gRPC server.
+
+    Args:
+        interceptors: List of async gRPC interceptors
+        settings: gRPC server settings
+
+    Returns:
+        Configured but not started async gRPC server wrapper
+    """
+    if settings.max_concurrent_rpcs is not None and settings.max_concurrent_rpcs < 1:
+        raise ValueError(
+            f"max_concurrent_rpcs must be >= 1 (or None for unlimited), got {settings.max_concurrent_rpcs}"
+        )
+
+    server = grpc.aio.server(
+        interceptors=interceptors,
+        options=build_grpc_options(settings),
+        maximum_concurrent_rpcs=settings.max_concurrent_rpcs,
+    )
+
+    return AsyncServer(server)

grpc_server_kit/config.py

@@ -0,0 +1,100 @@
+"""Zero-dependency gRPC server configuration (pure stdlib dataclass).
+
+:class:`GrpcServerConfig` structurally satisfies
+:class:`grpc_server_kit.protocols.GrpcServerSettingsProtocol` without pulling in
+pydantic. Services that want environment loading and validation via pydantic
+should use :class:`grpc_server_kit.settings.BaseGrpcServerSettings` (the
+``[settings]`` extra) — both shapes are interchangeable everywhere the kit
+accepts settings.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+from .constants import (
+    DEFAULT_GRACE_PERIOD,
+    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,
+)
+
+__all__ = ["GrpcServerConfig"]
+
+
+@dataclasses.dataclass(kw_only=True, slots=True)
+class GrpcServerConfig:
+    """gRPC server configuration with production-grade defaults (stdlib only)."""
+
+    # Basic
+    host: str = DEFAULT_HOST
+    port: int = DEFAULT_PORT
+
+    # TLS/SSL
+    ssl_enabled: bool = False
+    ssl_cert_file: str | None = None
+    ssl_key_file: str | None = None
+    ssl_ca_file: str | None = None
+    ssl_client_auth: bool = False
+    ssl_max_cert_size: int | None = None
+
+    # Keepalive
+    keepalive_time_ms: int = DEFAULT_KEEPALIVE_TIME_MS
+    keepalive_timeout_ms: int = DEFAULT_KEEPALIVE_TIMEOUT_MS
+    keepalive_permit_without_calls: bool = False
+    http2_min_recv_ping_interval_without_data_ms: int = DEFAULT_HTTP2_MIN_RECV_PING_INTERVAL_WITHOUT_DATA_MS
+    http2_max_pings_without_data: int = DEFAULT_HTTP2_MAX_PINGS_WITHOUT_DATA
+
+    # Connection limits
+    max_concurrent_rpcs: int | None = None
+    max_connection_idle_ms: int | None = None
+    max_connection_age_ms: int | None = None
+    max_connection_age_grace_ms: int | None = None
+
+    # Message size limits
+    max_send_message_length: int = DEFAULT_MAX_SEND_MESSAGE_LENGTH
+    max_receive_message_length: int = DEFAULT_MAX_RECEIVE_MESSAGE_LENGTH
+    max_metadata_size: int = DEFAULT_MAX_METADATA_SIZE
+
+    # Compression
+    compression_algorithm: str | None = None
+
+    # Flow control
+    initial_stream_window_size: int = DEFAULT_INITIAL_WINDOW_SIZE
+    initial_connection_window_size: int = DEFAULT_INITIAL_WINDOW_SIZE
+
+    # Features
+    enable_reflection: bool = False
+    enable_channelz: bool = False
+
+    # Graceful shutdown
+    grace_period: float = DEFAULT_GRACE_PERIOD
+
+    # Metrics
+    metrics_enabled: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.host:
+            raise ValueError("host cannot be empty")
+        if not (0 <= self.port <= 65535):
+            raise ValueError(f"port must be within [0, 65535], got {self.port}")
+        if self.grace_period < 0:
+            raise ValueError(f"grace_period must be non-negative, got {self.grace_period}")
+        if self.max_concurrent_rpcs is not None and self.max_concurrent_rpcs < 1:
+            raise ValueError(
+                f"max_concurrent_rpcs must be >= 1 (or None for unlimited), got {self.max_concurrent_rpcs}"
+            )
+        if self.ssl_enabled:
+            if not self.ssl_cert_file:
+                raise ValueError("ssl_cert_file is required when ssl_enabled=True")
+            if not self.ssl_key_file:
+                raise ValueError("ssl_key_file is required when ssl_enabled=True")
+            if self.ssl_client_auth and not self.ssl_ca_file:
+                raise ValueError("ssl_ca_file is required when ssl_client_auth=True")

grpc_server_kit/constants.py

@@ -0,0 +1,34 @@
+"""gRPC server constants and default values."""
+
+# Bind address
+DEFAULT_HOST = "[::]"
+DEFAULT_PORT = 50051
+
+# Message size limits
+DEFAULT_MAX_SEND_MESSAGE_LENGTH = 4 * 1024 * 1024  # 4 MB
+DEFAULT_MAX_RECEIVE_MESSAGE_LENGTH = 4 * 1024 * 1024  # 4 MB
+DEFAULT_MAX_METADATA_SIZE = 8 * 1024  # 8 KB (grpc-core default soft limit)
+
+# Keepalive settings
+DEFAULT_KEEPALIVE_TIME_MS = 7200000  # 2 hours
+DEFAULT_KEEPALIVE_TIMEOUT_MS = 20000  # 20 seconds
+DEFAULT_HTTP2_MIN_RECV_PING_INTERVAL_WITHOUT_DATA_MS = 300000  # 5 minutes
+DEFAULT_HTTP2_MAX_PINGS_WITHOUT_DATA = 2
+
+# Flow control (HTTP/2 default initial window)
+DEFAULT_INITIAL_WINDOW_SIZE = 65535
+
+# Graceful shutdown
+DEFAULT_GRACE_PERIOD = 5.0  # seconds
+
+# gRPC Health Checking Protocol v1 (single source of truth for the name)
+HEALTH_SERVICE_NAME = "grpc.health.v1.Health"
+
+# Health checking defaults. The cache TTL matches the Watch check interval so
+# that concurrent watchers and Check probes amortize onto one real dependency
+# check per interval instead of each running their own.
+DEFAULT_HEALTH_CACHE_TTL = 5.0  # seconds; 0 disables caching
+DEFAULT_HEALTH_CHECK_TIMEOUT = 10.0  # seconds; one full check round
+DEFAULT_HEALTH_CHECK_INTERVAL = 5.0  # seconds; Watch polling interval
+DEFAULT_HEALTH_HEARTBEAT_INTERVAL = 60.0  # seconds; Watch resend-if-unchanged
+DEFAULT_CHECKER_TIMEOUT = 5.0  # seconds; a single dependency checker (pg/redis)

grpc_server_kit/credentials.py

@@ -0,0 +1,112 @@
+"""SSL/TLS credentials loading for gRPC server."""
+
+import logging
+import os
+import stat
+from pathlib import Path
+
+import grpc
+
+from .protocols import GrpcSslSettingsProtocol
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MAX_CERT_SIZE = 1024 * 1024  # 1MB
+
+
+def load_server_credentials(settings: GrpcSslSettingsProtocol, strict: bool = True) -> grpc.ServerCredentials:
+    """Load TLS credentials for secure gRPC server.
+
+    Args:
+        settings: SSL/TLS configuration protocol
+        strict: If True (default), fail on insecure file permissions (Unix only)
+
+    Returns:
+        Configured gRPC ServerCredentials
+
+    Raises:
+        ValueError: If configuration is invalid or files are too large/invalid
+        FileNotFoundError: If certificate/key files are missing
+        PermissionError: If files cannot be accessed due to permissions
+        OSError: If other I/O errors occur
+    """
+    if not settings.ssl_cert_file or not settings.ssl_key_file:
+        raise ValueError("SSL enabled but ssl_cert_file or ssl_key_file not provided")
+
+    max_size = settings.ssl_max_cert_size or DEFAULT_MAX_CERT_SIZE
+
+    cert = _read_cert_file(settings.ssl_cert_file, "certificate", max_size=max_size, strict=strict)
+    key = _read_cert_file(settings.ssl_key_file, "private key", max_size=max_size, strict=strict)
+
+    ca_cert = None
+    if settings.ssl_ca_file:
+        ca_cert = _read_cert_file(settings.ssl_ca_file, "CA certificate", max_size=max_size, strict=strict)
+
+    return grpc.ssl_server_credentials(
+        [(key, cert)],
+        root_certificates=ca_cert,
+        require_client_auth=settings.ssl_client_auth,
+    )
+
+
+def _read_cert_file(path_str: str, label: str, max_size: int = DEFAULT_MAX_CERT_SIZE, strict: bool = True) -> bytes:
+    """Read and validate certificate/key file."""
+    path = Path(path_str)
+    if not path.exists():
+        raise FileNotFoundError(f"{label.capitalize()} file not found: {path}")
+    if not path.is_file():
+        raise ValueError(f"Path is not a file: {path}")
+
+    _check_permissions(path, label, strict=strict)
+
+    stats = path.stat()
+    if stats.st_size > max_size:
+        raise ValueError(f"{label.capitalize()} file too large ({stats.st_size} bytes): {path}")
+
+    try:
+        data = path.read_bytes()
+        _validate_pem(data, label)
+    except PermissionError as e:
+        raise PermissionError(f"Permission denied reading {label} file {path}: {e}") from e
+    except OSError as e:
+        raise OSError(f"Unexpected error reading {label} file {path}: {e}") from e
+    else:
+        return data
+
+
+def _validate_pem(data: bytes, label: str) -> None:
+    """Light sanity check that the file contains a PEM block.
+
+    Deliberately permissive: accepts preambles before the block (e.g. ``openssl``
+    text output), any PEM type (PKCS#8, PKCS#1, SEC1, encrypted keys), and CA
+    bundles with multiple blocks. Real validation belongs to the TLS stack —
+    this only catches obviously wrong files (empty, DER, JSON, ...).
+    """
+    if not data.strip():
+        raise ValueError(f"Empty {label} file")
+    if b"-----BEGIN " not in data or b"-----END " not in data:
+        raise ValueError(f"{label.capitalize()} file does not contain a PEM block")
+
+
+def _check_permissions(path: Path, label: str, strict: bool = True) -> None:
+    """Check file permissions for security (Unix only)."""
+    if os.name == "nt":
+        if label == "private key":
+            logger.debug(
+                f"Skipping permission check for {label} on Windows. "
+                "Ensure only the service user has access to this file.",
+                extra={"path": str(path)},
+            )
+        return
+
+    mode = path.stat().st_mode
+    # Fail if world-readable or group-readable private keys on Unix
+    if label == "private key" and (mode & stat.S_IRWXG or mode & stat.S_IRWXO):
+        msg = (
+            f"Sensitive file {path} has too permissive permissions ({oct(mode & 0o777)}). "
+            "Private keys must be readable only by owner (chmod 600)."
+        )
+        if strict:
+            raise PermissionError(msg)
+        else:
+            logger.warning(msg, extra={"path": str(path)})

grpc_server_kit/dishka/__init__.py

@@ -0,0 +1,38 @@
+"""Dishka dependency-injection integration for the gRPC server (``[dishka]`` extra).
+
+A thin, curated re-export of Dishka's official ``grpcio`` integration. The shared,
+transport-agnostic helpers (``inject``, ``FromDishka``, ``GrpcioProvider``,
+``from_context``) live here; the async server interceptor is
+:class:`grpc_server_kit.aio.dishka.DishkaAioInterceptor`.
+
+Example:
+    from dishka import make_async_container
+    from grpc_server_kit.dishka import FromDishka, inject
+    from grpc_server_kit.aio.dishka import DishkaAioInterceptor
+
+    container = make_async_container(MyProvider())
+    server = (
+        AsyncGrpcServerBuilder(settings)
+        .with_interceptors([DishkaAioInterceptor(container)])
+        .with_servicers(register)
+        .build()
+    )
+
+    class MyServicer(...):
+        @inject
+        async def MyMethod(self, request, context, service: FromDishka[MyService]):
+            ...
+"""
+
+from dishka import from_context
+from dishka.integrations.grpcio import FromDishka, GrpcioProvider, inject
+
+from grpc_server_kit.dishka.settings import GrpcServerSettingsProvider
+
+__all__ = [
+    "FromDishka",
+    "GrpcServerSettingsProvider",
+    "GrpcioProvider",
+    "from_context",
+    "inject",
+]