Skip to main content

Module server

connectrpc

Module server 

Source
Available on crate feature server only.
Expand description

Hyper-based HTTP server for ConnectRPC.

This module provides the HTTP server implementation that handles incoming ConnectRPC requests and routes them to the appropriate handlers.

§TLS Support

When the tls feature is enabled, the server can be configured with a rustls::ServerConfig to serve requests over TLS:

ⓘ
let tls_config = Arc::new(rustls::ServerConfig::builder()
    .with_no_client_auth()
    .with_single_cert(certs, key)?);

Server::new(router)
    .with_tls(tls_config)
    .serve(addr).await?;

§Graceful Shutdown

Use BoundServer::serve_with_graceful_shutdown to stop accepting new connections when a signal future resolves, then drain in-flight connections before returning:

ⓘ
let bound = Server::bind("127.0.0.1:8080").await?;
bound
    .serve_with_graceful_shutdown(router, async {
        tokio::signal::ctrl_c().await.ok();
    })
    .await?;

§Connection Retirement

Retire long-lived connections proactively — recommended behind load balancers so clients reconnect periodically and traffic redistributes across restarts. Two independent triggers are available, and either, both, or neither may be set:

When both are set, whichever trigger fires first retires the connection. After a trigger fires the connection is force-closed once the shared grace period (with_max_connection_age_grace) elapses. Retirement is independent of whole-server graceful shutdown, which still drains in-flight requests indefinitely even while a connection is in its grace window.

§Maximum Concurrent Streams

Use Server::with_max_concurrent_streams (or the BoundServer equivalent) to bound the number of concurrent HTTP/2 streams (in-flight requests) a single connection may have open. This maps to hyper’s SETTINGS_MAX_CONCURRENT_STREAMS; it is left at hyper’s default (200) when unset. Raise it for high-fan-in internal services, or lower it as a cheap hardening measure against less-trusted clients.

§HTTP/2 Keepalive

Use Server::with_http2_keepalive_interval (or the BoundServer equivalent) to make the server send HTTP/2 keepalive PING frames and reclaim dead or half-open peers. Disabled by default. Once an interval is set, an unacknowledged PING after with_http2_keepalive_timeout (20 seconds by default) closes the connection. This detects long-lived server-streaming or bidirectional connections that have gone silent (NAT timeout, client crash, network partition) instead of leaving them half-open until the OS TCP timeout.

§Maximum Connection Idle

Use Server::with_max_connection_idle (or the BoundServer equivalent) to reclaim connections that have gone quiet. A connection is idle when it has no in-flight requests; once it stays idle for the configured duration it is retired through the same GOAWAY-then-grace path as maximum age, draining over the same grace period set by with_max_connection_age_grace. The idle timer resets on activity, so a connection with steady traffic is never retired. The window is evaluated lazily, so retirement happens between one and two times the configured duration after the last activity. When both limits are configured, whichever fires first wins.

For transport and HTTP/2 knobs that Server does not expose, drive ConnectRpcService directly from a hyper accept loop. The crate guide’s “Advanced transport configuration” section shows the hyper_util pattern.

Structs§

BoundServer
A server that has been bound to an address but not yet started.
PeerAddr
Remote socket address of the connected peer.
PeerCertsserver-tls
TLS client certificate chain presented by the peer (leaf first).
Server
ConnectRPC server built on hyper.

Constants§

DEFAULT_HEADER_READ_TIMEOUT
Default HTTP/1.1 header read timeout.
DEFAULT_HTTP2_ADAPTIVE_WINDOW
Default for HTTP/2 adaptive (BDP-based) flow-control window sizing.
DEFAULT_HTTP2_KEEPALIVE_TIMEOUT
Default timeout for an HTTP/2 keepalive PING acknowledgement.
DEFAULT_TLS_HANDSHAKE_TIMEOUTserver-tls
Default TLS handshake timeout.