Struct BoundServer 

pub struct BoundServer { /* private fields */ }

Available on crate feature server only.

A server that has been bound to an address but not yet started.

Implementations

impl BoundServer

pub fn local_addr(&self) -> Result<SocketAddr>

Get the local address the server is bound to.

pub fn with_tls(self, config: Arc<ServerConfig>) -> Self

Available on crate feature server-tls only.

Enable TLS with the given rustls server configuration.

pub fn with_tls_handshake_timeout(self, timeout: Duration) -> Self

Available on crate feature server-tls only.

Set the TLS handshake timeout.

Defaults to DEFAULT_TLS_HANDSHAKE_TIMEOUT (10 seconds).

pub fn with_header_read_timeout( self, timeout: impl Into<Option<Duration>>, ) -> Self

Set the HTTP/1.1 header read timeout.

Defaults to DEFAULT_HEADER_READ_TIMEOUT (30 seconds). Bounds how long the server waits to read a complete set of request headers, measured from when hyper begins reading a new request; on a keep-alive connection this also bounds the idle wait between requests. A peer that connects (or finishes a request) and then stalls without sending the next request’s headers is disconnected, which mitigates slowloris-style connection-exhaustion attacks. Pass None to disable.

Applies to HTTP/1.1 only; it does not bound idle or stalled HTTP/2 connections — use with_max_connection_age to retire those by age.

pub fn with_http1_keep_alive(self, enabled: bool) -> Self

Enable or disable HTTP/1.1 keep-alive.

When disabled, the server sends Connection: close and handles only one request per TCP connection. This avoids stale-connection races where the server closes an idle connection at the same time the client sends a new request on it.

HTTP/2 multiplexing is unaffected.

pub fn with_max_connection_age(self, max_age: Duration) -> Self

Set a maximum age for each accepted HTTP connection.

Disabled by default. When enabled, the age is measured from the start of HTTP serving (after any TLS handshake) and each connection gets a symmetric ±10% jitter to avoid reconnect bursts. Once the age expires, the server begins graceful shutdown for that connection — HTTP/2 connections receive a GOAWAY, HTTP/1.1 connections have keep-alive disabled — then waits up to with_max_connection_age_grace for in-flight requests before force-closing it.

Panics

Panics if max_age is zero — a zero age is rejected rather than silently retiring every connection the instant it starts serving.

pub fn with_max_connection_age_grace(self, grace: Duration) -> Self

Set the grace period used after a retired connection begins shutdown.

Defaults to five seconds. This single grace period is shared by all three retirement triggers — with_max_connection_age, with_max_connection_idle, and with_max_requests_per_connection — and applies to whichever one fires. Setting it without enabling any trigger has no effect, and the three cannot be tuned independently. Whole-server graceful shutdown still waits indefinitely for in-flight requests.

pub fn with_max_connection_idle(self, duration: Duration) -> Self

Retire a connection that has had no in-flight requests for duration.

Disabled by default. This complements with_max_connection_age: age caps a connection’s total lifetime regardless of use, while idle reclaims connections that have gone quiet (clients behind NAT, bursty workloads, pooled clients holding connections they no longer need).

A connection is idle when it has zero in-flight requests. The idle timer resets on activity: any request that starts, or completes, during an idle window keeps the connection alive. Once a connection stays idle for the full duration, the server begins graceful shutdown for it — HTTP/2 connections receive a GOAWAY, HTTP/1.1 connections have keep-alive disabled — then waits up to with_max_connection_age_grace (a grace period shared with maximum age) for any straggling request before force-closing it.

The idle window is evaluated lazily — it is re-checked when the timer expires rather than re-armed at the instant of each request — so a connection is retired between one and two times duration after its last activity. Size duration against that upper bound. Unlike maximum age, idle reaping applies no jitter.

When both an idle timeout and a max age are configured, whichever fires first retires the connection. Whole-server graceful shutdown still waits indefinitely for in-flight requests, and is never capped by the idle grace period.

Panics

Panics if duration is zero — a zero idle timeout is rejected rather than silently retiring every connection the instant it falls idle.

pub fn with_http2_adaptive_window(self, enabled: bool) -> Self

Enable or disable HTTP/2 adaptive flow-control window sizing.

Enabled by default (DEFAULT_HTTP2_ADAPTIVE_WINDOW). When enabled, hyper grows the stream and connection flow-control windows based on the measured bandwidth-delay product, which improves throughput on high-latency, high-bandwidth links at the cost of slightly higher per-connection memory under load.

Adaptive sizing and an explicit window size are mutually exclusive: enabling adaptive sizing overrides any window set via with_http2_initial_stream_window_size or with_http2_initial_connection_window_size. Whichever is set last wins.

pub fn with_http2_initial_stream_window_size( self, size: impl Into<Option<u32>>, ) -> Self

Set the HTTP/2 initial stream-level flow-control window size, in bytes.

Controls the per-stream SETTINGS_INITIAL_WINDOW_SIZE advertised to clients. Supplying a size turns adaptive sizing off, mirroring grpc-go semantics; passing None leaves hyper’s default in place and does not change the adaptive flag. The window can be raised above hyper’s 64 KiB default to improve throughput when adaptive sizing is not wanted.

The adaptive toggle and the explicit window are last-write-wins: a later with_http2_adaptive_window(true) re-enables autotuning and the explicit window is ignored. Per HTTP/2, the window must not exceed 2^31 - 1; larger values are a protocol error.

pub fn with_http2_initial_connection_window_size( self, size: impl Into<Option<u32>>, ) -> Self

Set the HTTP/2 initial connection-level flow-control window size, in bytes.

Controls the whole-connection flow-control window, which bounds the total unacknowledged data across all streams on the connection. Supplying a size turns adaptive sizing off, mirroring grpc-go semantics; passing None leaves hyper’s default in place and does not change the adaptive flag.

The adaptive toggle and the explicit window are last-write-wins: a later with_http2_adaptive_window(true) re-enables autotuning and the explicit window is ignored. Per HTTP/2, the window must not exceed 2^31 - 1; larger values are a protocol error.

pub fn with_max_concurrent_streams(self, max_streams: u32) -> Self

Set the maximum number of concurrent HTTP/2 streams per connection.

This maps to hyper’s HTTP/2 SETTINGS_MAX_CONCURRENT_STREAMS, which the server advertises to each peer. A client may have at most this many in-flight requests (streams) open at once on a single connection; attempts to exceed it are refused with a REFUSED_STREAM error and can be safely retried. The setting has no effect on HTTP/1.1 connections, which are not multiplexed.

Left at hyper’s default (200) when unset. Raise it for high-fan-in internal services that multiplex many concurrent RPCs over one connection, or lower it as an additional hardening measure when serving less-trusted clients.

Panics

Panics if max_streams is zero — advertising a limit of zero refuses every stream, leaving a server that accepts connections but rejects all requests. It is rejected at configuration time rather than silently producing a dead server.

pub fn with_max_requests_per_connection(self, max: NonZeroU64) -> Self

Retire each accepted connection after it has dispatched max requests.

Disabled by default. The request count is per-connection: every inbound request (each HTTP/2 stream, or each HTTP/1.1 request) is counted, and once the maxth request has been dispatched the server begins graceful shutdown for that connection — HTTP/2 connections receive a GOAWAY, HTTP/1.1 connections have keep-alive disabled — then waits up to with_max_connection_age_grace for in-flight requests before force-closing it. The maxth request itself still completes; subsequent requests are turned away.

max is a soft floor rather than an exact cap: under HTTP/2 a client may open several streams concurrently before the GOAWAY takes effect, so the connection is retired at or after the maxth request, not strictly at it.

This is the count-based complement of with_max_connection_age; both may be set at once, in which case whichever trigger fires first retires the connection. Whole-server graceful shutdown still drains in-flight requests indefinitely.

max is a NonZeroU64 so that “retire after zero requests” — which would refuse every connection before it served anything — is unrepresentable. (This differs from with_max_connection_age, which takes a plain Duration and panics on a zero value.)

pub fn with_http2_keepalive_interval(self, interval: Duration) -> Self

Set the interval between HTTP/2 keepalive PING frames sent on an otherwise idle connection.

Disabled by default. When set, the server sends a PING after the connection has been idle for interval and, if the peer fails to acknowledge it within with_http2_keepalive_timeout, closes the connection. This detects dead or half-open peers (NAT timeout, client crash, network partition) on long-lived server-streaming or bidirectional connections that would otherwise sit half-open until the OS TCP timeout, holding a task and file descriptor.

Affects HTTP/2 connections only; HTTP/1.1 is unaffected. Note the spelling difference from the HTTP/1.1 toggle with_http1_keep_alive (keep_alive): these HTTP/2 knobs use keepalive as a single word.

Panics

Panics if interval is zero — a zero interval would request an unbounded PING flood rather than periodic keepalives.

pub fn with_http2_keepalive_timeout(self, timeout: Duration) -> Self

Set how long to wait for an HTTP/2 keepalive PING acknowledgement before closing the connection.

Defaults to DEFAULT_HTTP2_KEEPALIVE_TIMEOUT (20 seconds). This only takes effect once with_http2_keepalive_interval is set — setting it without an interval has no effect.

pub async fn serve( self, router: Router, ) -> Result<(), Box<dyn Error + Send + Sync>>

Start serving requests with the given router.

Runs until the process is killed. For graceful shutdown use serve_with_graceful_shutdown.

pub async fn serve_with_graceful_shutdown<F>( self, router: Router, signal: F, ) -> Result<(), Box<dyn Error + Send + Sync>>

where F: Future<Output = ()> + Send + 'static,

Start serving requests, shutting down gracefully when signal resolves.

When the shutdown signal fires, the server:

1. drops the listener (new connection attempts are refused with RST),
2. signals every open connection to wind down — HTTP/2 connections receive a GOAWAY (using the standard two-phase GOAWAY/PING/GOAWAY sequence so racing client streams are handled correctly); HTTP/1.1 connections have keep-alive disabled so they close after the in-flight request,
3. waits for all in-flight requests to complete before returning Ok(()).

In-flight requests are not cancelled; this method waits indefinitely for them. For bounded shutdown (e.g. Kubernetes preStop hooks with a deadline), wrap this call in tokio::time::timeout:

tokio::time::timeout(
    Duration::from_secs(30),
    bound.serve_with_graceful_shutdown(router, signal),
)
.await??;

Example

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

pub async fn serve_with_service<D: Dispatcher>( self, service: ConnectRpcService<D>, ) -> Result<(), Box<dyn Error + Send + Sync>>

Start serving requests with the given ConnectRpcService.

This is useful when you want to share a service between multiple servers, or when you’ve wrapped the service with additional tower layers.

pub async fn serve_with_service_and_shutdown<D, F>( self, service: ConnectRpcService<D>, signal: F, ) -> Result<(), Box<dyn Error + Send + Sync>>

where D: Dispatcher, F: Future<Output = ()> + Send + 'static,

Start serving requests with the given service, with graceful shutdown.

See serve_with_graceful_shutdown for behaviour and limitations.