feat(grpc): mount_grpc — thin gRPC integration over grpc.aio with observability + reflection + TLS passthrough

- app.mount_grpc(servicer, add_to_server=..., port=50051) wires a grpc.aio
  server into ASGI lifespan (startup/shutdown hooks installed on first call)
- HawkAPIObservabilityInterceptor: context injection (hawkapi_app,
  hawkapi_request_id via _ContextProxy), structured logging to
  hawkapi.grpc logger, idempotent Prometheus counters/histograms
- Reflection toggle: reflection=True + reflection_service_names required;
  ConfigurationError with clear message if grpcio-reflection missing
- TLS passthrough: ssl_credentials -> add_secure_port
- Port-merge: same port -> shared grpc.aio.Server; different port -> new server
- Zero default runtime deps: grpcio imported lazily inside function bodies
- 19 tests in tests/unit/test_grpc.py (18 pass, 1 skipped without
  prometheus_client); all guarded by pytest.importorskip("grpc")
- docs/guide/grpc.md quickstart, full signature reference, roadmap
- pyproject.toml: grpc optional-dep extra + dev deps
- mkdocs.yml nav entry; CHANGELOG [Unreleased] bullet

Author: Berik Ashimov

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `app.mount_grpc(servicer, add_to_server=..., port=50051)` — thin gRPC integration over `grpc.aio`: ASGI lifespan-tied server lifecycle, built-in `HawkAPIObservabilityInterceptor` (structured logging + Prometheus metrics), context injection (`context.hawkapi_app`, `context.hawkapi_request_id`), reflection toggle with `reflection_service_names`, TLS passthrough via `ssl_credentials`, port-merge for multi-servicer setups; zero runtime deps on default path (`grpcio` imported lazily) (Tier 2 gRPC thin mount)
 - `app.mount_graphql(path, executor=...)` — thin GraphQL-over-HTTP adapter: POST + GET wire protocol, GraphiQL UI served to browsers, context injection via `context_factory`, and two optional adapters (`from_graphql_core`, `from_strawberry`) behind lazy imports; zero new runtime deps (Tier 2 GraphQL thin mount)
 - Feature flags subsystem: `FlagProvider` Protocol, built-in Static/Env/File providers (File with mtime hot-reload, JSON/TOML/YAML), `Flags` facade, `Depends(get_flags)` DI helper with per-request `EvalContext`, `@requires_flag` decorator (404 on off), plugin hook `on_flag_evaluated`; zero external deps (Tier 2 feature flags)
 - `hawkapi gen-client` CLI: generates zero-dep TypeScript (`client.ts`) + Python (`client.py`) client SDKs from OpenAPI 3.1 spec; msgspec-backed for Python, native fetch for TS (Tier 3 OpenAPI codegen)

docs/guide/grpc.md

@@ -0,0 +1,229 @@
+# gRPC
+
+HawkAPI ships a **thin gRPC mount** that wires a `grpc.aio` server into the
+ASGI lifespan — so your gRPC service starts and stops with your HTTP server,
+shares the same process, and gets built-in observability for free.
+
+## Installation
+
+```bash
+pip install hawkapi[grpc]
+# or with uv:
+uv add "hawkapi[grpc]"
+```
+
+## Quickstart
+
+### 1. Generate stubs
+
+```bash
+python -m grpc_tools.protoc \
+  -I proto \
+  --python_out=. \
+  --grpc_python_out=. \
+  proto/greeter.proto
+```
+
+This produces `greeter_pb2.py` and `greeter_pb2_grpc.py`.
+
+### 2. Implement and mount the servicer
+
+```python
+import hawkapi
+from greeter_pb2_grpc import GreeterServicer, add_GreeterServicer_to_server
+from greeter_pb2 import HelloReply
+
+app = hawkapi.HawkAPI()
+
+class MyGreeter(GreeterServicer):
+    async def SayHello(self, request, context):
+        return HelloReply(message=f"Hello, {request.name}!")
+
+app.mount_grpc(
+    MyGreeter(),
+    add_to_server=add_GreeterServicer_to_server,
+    port=50051,
+)
+```
+
+That's it. When the ASGI server starts (e.g. `uvicorn`), the gRPC server
+starts on `:50051` automatically.
+
+## ASGI lifespan integration
+
+`mount_grpc` installs startup / shutdown hooks on the first call, so:
+
+- **startup** — `grpc.aio.server` is created, servicers are registered, port
+  is bound, and `server.start()` is awaited.
+- **shutdown** — `server.stop(grace=5.0)` is awaited, draining in-flight RPCs.
+
+Use `autostart=False` if you need manual control:
+
+```python
+mount = app.mount_grpc(
+    MyGreeter(),
+    add_to_server=add_GreeterServicer_to_server,
+    port=50051,
+    autostart=False,
+)
+
+# Later:
+await mount.start()
+# ...
+await mount.stop(grace=10.0)
+```
+
+## Accessing the HawkAPI app from a handler
+
+The built-in observability interceptor attaches two attributes to the
+`ServicerContext` before delegating to your handler:
+
+| Attribute | Value |
+|---|---|
+| `context.hawkapi_app` | The `HawkAPI` application instance |
+| `context.hawkapi_request_id` | `uuid.uuid4().hex` — 32-char hex string |
+
+```python
+class MyServicer(EchoServicer):
+    async def Echo(self, request, context):
+        app = context.hawkapi_app          # HawkAPI instance
+        rid = context.hawkapi_request_id   # e.g. "a3f2..."
+        return EchoReply(message=request.message)
+```
+
+## TLS passthrough
+
+Pass a `grpc.ServerCredentials` object — HawkAPI calls
+`server.add_secure_port()` for you:
+
+```python
+import grpc
+
+credentials = grpc.ssl_server_credentials(
+    [(open("server.key", "rb").read(), open("server.crt", "rb").read())]
+)
+
+app.mount_grpc(
+    MyGreeter(),
+    add_to_server=add_GreeterServicer_to_server,
+    port=50051,
+    ssl_credentials=credentials,
+)
+```
+
+## Reflection
+
+Enable [gRPC server reflection](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md)
+so tools like `grpcurl` can discover your services at runtime.
+
+Requires `pip install hawkapi[grpc]` (includes `grpcio-reflection`).
+
+```python
+from grpc_reflection.v1alpha import reflection
+
+app.mount_grpc(
+    MyGreeter(),
+    add_to_server=add_GreeterServicer_to_server,
+    port=50051,
+    reflection=True,
+    reflection_service_names=[
+        "greeter.Greeter",          # your service name
+        reflection.SERVICE_NAME,    # the reflection service itself
+    ],
+)
+```
+
+!!! note
+    `reflection_service_names` is **required** when `reflection=True`.
+    A `ConfigurationError` is raised with a clear message if it is omitted.
+
+## Observability
+
+### Structured logs
+
+The built-in interceptor emits two `INFO` log records per RPC to
+`logging.getLogger("hawkapi.grpc")`:
+
+```json
+{"event": "grpc.request",  "method": "/greeter.Greeter/SayHello", "peer": "ipv6:[::1]:54321", "request_id": "a3f2..."}
+{"event": "grpc.response", "method": "/greeter.Greeter/SayHello", "code": "OK", "duration_ms": 1.234}
+```
+
+### Prometheus metrics
+
+When `prometheus_client` is installed, two metrics are registered globally:
+
+| Metric | Type | Labels |
+|---|---|---|
+| `hawkapi_grpc_requests_total` | Counter | `method`, `code` |
+| `hawkapi_grpc_request_duration_seconds` | Histogram | `method` |
+
+Metrics are created once (idempotent) — safe to import in tests multiple times.
+
+### Disabling observability
+
+```python
+app.mount_grpc(
+    MyGreeter(),
+    add_to_server=add_GreeterServicer_to_server,
+    observability=False,   # skip the built-in interceptor entirely
+)
+```
+
+## Multiple services on one port
+
+Call `mount_grpc` twice with the **same port** — servicers are merged onto one
+`grpc.aio.Server`:
+
+```python
+mount_a = app.mount_grpc(GreeterServicer(), add_to_server=add_GreeterServicer_to_server, port=50051)
+mount_b = app.mount_grpc(EchoServicer(),    add_to_server=add_EchoServicer_to_server,    port=50051)
+assert mount_a is mount_b   # same server
+```
+
+## Custom interceptors
+
+Pass additional `grpc.aio.ServerInterceptor` instances via `interceptors=`.
+The built-in observability interceptor always runs **first**:
+
+```python
+from my_auth import AuthInterceptor
+
+app.mount_grpc(
+    MyGreeter(),
+    add_to_server=add_GreeterServicer_to_server,
+    interceptors=[AuthInterceptor()],
+)
+```
+
+## Full signature reference
+
+```python
+app.mount_grpc(
+    servicer,                         # your servicer object
+    add_to_server=add_Foo_to_server,  # generated registration function
+    port=50051,                       # TCP port (default 50051)
+    host="[::]",                      # bind address (default all interfaces)
+    interceptors=(),                  # extra ServerInterceptor instances
+    observability=True,               # built-in interceptor (default on)
+    reflection=False,                 # gRPC server reflection
+    reflection_service_names=None,    # required when reflection=True
+    ssl_credentials=None,             # grpc.ServerCredentials for TLS
+    autostart=True,                   # start on ASGI lifespan (default on)
+    max_workers=None,                 # reserved, currently unused
+    options=(),                       # grpc channel options
+)
+```
+
+Returns a `GrpcMount` with:
+
+- `.server` — the underlying `grpc.aio.Server` (available after start)
+- `.port` — bound port
+- `.start()` — async, idempotent
+- `.stop(grace=5.0)` — async, safe no-op if not started
+
+## Roadmap
+
+- Bi-directional streaming support (infrastructure is in place; tests cover unary + server-streaming)
+- Per-mount Prometheus registry (currently uses the default global registry)
+- Health checking protocol (`grpc.health.v1`)

mkdocs.yml

@@ -53,6 +53,7 @@ nav:
       - Client codegen: guide/client-codegen.md
       - Feature flags: guide/feature-flags.md
       - GraphQL: guide/graphql.md
+      - gRPC: guide/grpc.md
       - Bulkhead: guide/bulkhead.md
       - Free-threaded Python (PEP 703): guide/free-threaded.md
       - Migration from FastAPI: guide/migration-from-fastapi.md

pyproject.toml

@@ -39,7 +39,8 @@ otel = ["opentelemetry-api>=1.20", "opentelemetry-sdk>=1.20"]
 metrics = ["prometheus-client>=0.20"]
 logging = ["structlog>=24.0"]
 redis = ["redis>=5.0"]
-all = ["hawkapi[pydantic,granian,uvloop,uvicorn,otel,metrics,logging,redis]"]
+grpc = ["grpcio>=1.60", "grpcio-reflection>=1.60"]
+all = ["hawkapi[pydantic,granian,uvloop,uvicorn,otel,metrics,logging,redis,grpc]"]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.24",
@@ -51,6 +52,9 @@ dev = [
     "pyright>=1.1",
     "libcst>=1.0",
     "fakeredis[lua]>=2.0",
+    "grpcio>=1.60",
+    "grpcio-reflection>=1.60",
+    "protobuf>=4.0",
 ]
 docs = [
     "mkdocs-material>=9.0",

src/hawkapi/__init__.py

@@ -29,6 +29,7 @@
         requires_flag,
     )
     from hawkapi.graphql import GraphQLExecutor
+    from hawkapi.grpc import GrpcMount, HawkAPIObservabilityInterceptor
     from hawkapi.middleware import Middleware
     from hawkapi.middleware.adaptive_concurrency import AdaptiveConcurrencyMiddleware
     from hawkapi.middleware.circuit_breaker import CircuitBreakerMiddleware
@@ -184,6 +185,9 @@
     "requires_flag": ("hawkapi.flags", "requires_flag"),
     # graphql
     "GraphQLExecutor": ("hawkapi.graphql", "GraphQLExecutor"),
+    # grpc
+    "GrpcMount": ("hawkapi.grpc", "GrpcMount"),
+    "HawkAPIObservabilityInterceptor": ("hawkapi.grpc", "HawkAPIObservabilityInterceptor"),
 }
 
 
@@ -283,4 +287,6 @@ def __getattr__(name: str) -> Any:
     "Flags",
     "StaticFlagProvider",
     "GraphQLExecutor",
+    "GrpcMount",
+    "HawkAPIObservabilityInterceptor",
 ]

src/hawkapi/app.py

@@ -254,6 +254,92 @@ async def _endpoint(request: Request) -> Any:
             name=f"graphql:{path}",
         )
 
+    def mount_grpc(
+        self,
+        servicer: object,
+        *,
+        add_to_server: Callable[[object, Any], None],
+        port: int = 50051,
+        host: str = "[::]",
+        interceptors: Any = (),
+        observability: bool = True,
+        reflection: bool = False,
+        reflection_service_names: Any = None,
+        ssl_credentials: Any = None,
+        autostart: bool = True,
+        max_workers: int | None = None,
+        options: Any = (),
+    ) -> Any:
+        """Mount a gRPC servicer and tie its lifecycle to ASGI lifespan.
+
+        Args:
+            servicer: The servicer object (from ``*_pb2_grpc.py``).
+            add_to_server: The generated ``add_XxxServicer_to_server`` function.
+            port: TCP port to listen on (default 50051).
+            host: Bind address (default ``"[::]"`` = all interfaces).
+            interceptors: Additional ``grpc.aio.ServerInterceptor`` instances.
+            observability: Install the built-in ``HawkAPIObservabilityInterceptor``
+                first (default True).
+            reflection: Enable gRPC server reflection (requires ``grpcio-reflection``
+                and ``reflection_service_names``).
+            reflection_service_names: Fully-qualified service names for reflection.
+            ssl_credentials: ``grpc.ServerCredentials`` for TLS; ``None`` = insecure.
+            autostart: Start automatically on ASGI lifespan startup (default True).
+            max_workers: Reserved for future thread-pool use; currently unused.
+            options: Extra ``(key, value)`` channel options for ``grpc.aio.server()``.
+
+        Returns:
+            A ``GrpcMount`` with ``.server``, ``.port``, ``.start()``, ``.stop(grace)``.
+        """
+        from hawkapi.grpc._interceptor import HawkAPIObservabilityInterceptor  # noqa: PLC0415
+        from hawkapi.grpc._mount import GrpcMount  # noqa: PLC0415
+
+        # Initialise mount registry on first call and install lifespan hooks once
+        if not hasattr(self, "_grpc_mounts"):
+            self._grpc_mounts: list[Any] = []
+            self._grpc_ports: dict[int, Any] = {}
+            self._hooks.on_startup(self._start_grpc_mounts)
+            self._hooks.on_shutdown(self._stop_grpc_mounts)
+
+        # Build interceptor list — observability interceptor goes first
+        all_interceptors: list[Any] = []
+        if observability:
+            all_interceptors.append(HawkAPIObservabilityInterceptor(self))
+        all_interceptors.extend(interceptors)
+
+        # Same port → reuse existing mount; different port → new mount
+        if port in self._grpc_ports:
+            mount: Any = self._grpc_ports[port]
+            mount._add_servicer(servicer, add_to_server)
+        else:
+            mount = GrpcMount(
+                port=port,
+                host=host,
+                interceptors=all_interceptors,
+                ssl_credentials=ssl_credentials,
+                reflection=reflection,
+                reflection_service_names=reflection_service_names,
+                options=options,
+                max_workers=max_workers,
+            )
+            mount._autostart = autostart
+            mount._add_servicer(servicer, add_to_server)
+            self._grpc_mounts.append(mount)
+            self._grpc_ports[port] = mount
+
+        return mount
+
+    async def _start_grpc_mounts(self) -> None:
+        """ASGI startup hook: start all autostart gRPC mounts."""
+        for mount in getattr(self, "_grpc_mounts", []):
+            if getattr(mount, "_autostart", True):
+                await mount._start()
+
+    async def _stop_grpc_mounts(self) -> None:
+        """ASGI shutdown hook: stop all gRPC mounts."""
+        for mount in getattr(self, "_grpc_mounts", []):
+            await mount._stop()
+
     def readiness_check(self, name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
         """Register a readiness check (decorator).
 

src/hawkapi/grpc/__init__.py

@@ -0,0 +1,13 @@
+"""gRPC thin-mount subsystem for HawkAPI."""
+
+from __future__ import annotations
+
+from hawkapi.grpc._interceptor import HawkAPIObservabilityInterceptor
+from hawkapi.grpc._mount import GrpcMount
+from hawkapi.grpc._reflection import ConfigurationError
+
+__all__ = [
+    "ConfigurationError",
+    "GrpcMount",
+    "HawkAPIObservabilityInterceptor",
+]