gRPC and Connect¶

h2corn hosts Connect-generated ASGI applications for the Connect protocol, native gRPC, and gRPC-Web. h2corn handles HTTP transport, including HTTP/2 for native gRPC; the ASGI application owns RPC routing, codecs, handlers, and status behavior.

Host a generated Connect application¶

Requires CPython 3.11 or newer; see Python compatibility and wheels for platform support.

Install h2corn and the published Connect Python package:

pip install h2corn connectrpc "protobuf-py<0.7"

ConnectRPC currently requires the pre-0.7 protobuf-py module layout.

Generate a Connect ASGI application with the Connect Python guide. Serve that application directly or mount it in an ASGI framework such as Starlette or FastAPI.

Enable native gRPC¶

Native gRPC admission is opt-in. For the CLI, pass --grpc:

h2corn myservice.asgi:app --grpc

Replace myservice.asgi:app with your ASGI application's module:object import target. For embedded servers, set Config(grpc=True) on Server or serve. The grpc configuration reference lists its accepted media types and the other supported input forms.

The setting controls whether native gRPC requests reach the ASGI application; it does not authenticate clients or restrict network access. Use a dedicated listener and network policy when native gRPC should be isolated. Connect and gRPC-Web requests use the ordinary HTTP path and do not need this admission setting.

Example service¶

The repository's Notebook service shows a Connect service alongside an HTTP health endpoint. Its companion roundtrip.py demonstrates a native gRPC client call and graceful server shutdown.

HTTP/2, TLS, and proxies¶

Native gRPC uses HTTP/2. Use HTTP/2 prior knowledge (h2c) for cleartext native gRPC connections. For direct TLS, ALPN negotiates h2; any HTTP/1.1 fallback is separate and does not carry native gRPC. For production, terminate TLS in h2corn or at a reverse proxy. With a proxy, keep HTTP/2 on the proxy-to-h2corn hop over a private h2c connection. The proxy guide covers that trust boundary and forwarding headers; Direct TLS covers TLS and ALPN in h2corn.

Forwarded client identity is not trusted just because a request contains forwarding headers. Enable proxy-headers only when forwarded-allow-ips limits trust to known proxy peers. When a proxy terminates TLS, h2corn sees the cleartext backend connection and does not expose that edge connection through its ASGI TLS extension.

Request policies and deadlines¶

With native gRPC enabled, unmatched gRPC requests bypass the ordinary global request-body size and body-idle limits. The global HTTP/2 response-stall and transport write limits remain active. A matching RequestPolicy replaces all three of its values and can set explicit body-size, body-idle, and response-stall limits for a service path.

Connect and gRPC-Web requests remain ordinary HTTP and use the global body-size and body-idle limits unless a request policy matches. A body-idle timeout is not an RPC deadline; it bounds time between request-body data. The HTTP/2 response-stall timeout bounds flow-control stalls, while the transport write timeout bounds pending frame output and flushing. See the canonical entries for max-request-body-size, timeout-request-body-idle, h2-timeout-response-stall, and h2-timeout-write.