Struct HttpServer 

pub struct HttpServer { /* private fields */ }

An HTTP server.

Serves a set of routes (HTTP or gRPC) over a connection-oriented listener, optionally with TLS.

Routes

Routes are accumulated on the server itself: HTTP routes via add_routes, gRPC services via add_grpc_service. Both can be called as many times as needed, and both feed the same router, because a gRPC service is a route set like any other – one whose paths follow the gRPC naming convention. The final router is built once, when the server is converted into a supervisor.

The server will respond accordingly depending on whether or not at least one gRPC service was configured. For example, when an unknown gRPC service/operation is called, it will receive a gRPC-specific response indicating as such, rather than a generic HTTP “404 Not Found” response.

A caller that has already built the exact router it wants can hand it over with with_routes, which bypasses all of the above.

Peer address

Every request carries the address of the peer that sent it, which handlers read with the ConnectInfo<ConnectionAddress> extractor:

• Over TCP, with or without TLS, it’s the peer’s socket address.
• Over a Unix domain socket, it’s the identity of the peer process: its PID, UID, and GID. The identity is captured once, when the peer connects, so it’s fixed for the life of the connection, and the PID may refer to a process that has since exited. When the platform doesn’t provide the PID, or the lookup fails, it holds the reason instead.

Supervision

The server must be run under supervision, and can be converted to a Supervisor to do so. A number of child workers handle various aspects of the server and connection lifecycle:

• A dedicated worker accepts new connections from the configured listener.
• For TLS-enabled servers, an interstitial worker is spawned to handle the initial TLS handshake, which helps avoid head-of-line blocking when accepting subsequent connections due to the amount of time it can take to perform the TLS handshake.
• Connections are driven on their own worker for isolation. - Background tasks (related to HTTP/2) may also be spawned as individual workers.

Shutdown

A nested supervisor has no shutdown timeout of its own, so each connection bounds its own drain, and is halted if it overruns that bound. See with_graceful_shutdown_timeout for what sets it and what the default is. The whole subtree is also halted if its owner’s timeout expires.

Assertions

HttpServer can optionally assert particular information at runtime when the server identifier is set (see with_server_id):

• the bound listen address (BoundListenAddress, with an identifier of http-server-<server ID>)

Implementations

impl HttpServer

pub fn from_listen_address(listen_address: ListenAddress) -> Self

Creates a server that will listen on the given address, with no routes attached.

pub fn add_routes(self, routes: Router) -> Self

Adds HTTP routes to this server.

Can be called more than once, in which case the route sets are merged.

Panics

Panics if routes defines the same path as an existing route on this server.

pub fn add_grpc_service<S>(self, service: S) -> Self

where S: Service<Request<GrpcBody>, Error = Infallible> + NamedService + Clone + Send + Sync + 'static, S::Response: IntoResponse, S::Future: Send + 'static,

Adds a gRPC service to this server.

The service’s routes are served from the same listener, and alongside the same HTTP routes, as everything else attached to this server.

Can be called more than once to attach several services.

pub fn with_routes(self, routes: Router) -> Self

Serves the given router, ignoring any routes otherwise attached to this server.

Any existing routes, whether HTTP or gRPC, will be ignored entirely.

pub fn with_http2_config(self, config: Http2Config) -> Self

Sets the HTTP/2 settings for the server.

Defaults to Http2Config::default(), which enables neither keepalive nor a connection age limit.

pub fn with_http2_only(self) -> Self

Restricts the server to HTTP/2.

By default, the protocol is detected per connection: a client that opens with the HTTP/2 connection preface is served over HTTP/2, and anything else is served over HTTP/1.1. Restricting the server to HTTP/2 skips that detection, so an HTTP/1.1 client is rejected at the protocol level rather than being routed and answered.

This is worth setting on an endpoint that only ever serves gRPC, where an HTTP/1.1 request is a client error worth surfacing as one. Leave it off for any endpoint that also serves REST-ful routes.

Defaults to accepting both HTTP/1.1 and HTTP/2.

pub fn with_server_id(self, id: impl Into<MetaString>) -> Self

Sets the server identifier to use when asserting any facts for this server.

The identifier also distinguishes this server from any other running under the same supervisor: it becomes part of the name the subtree reports, so that logs and per-worker task metrics can be attributed to a specific endpoint. Set it on any server that shares a supervisor with another, even when nothing consumes the assertions.

If no identifier is set, no assertions will be made at runtime, and the subtree reports a bare http_server.

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

Sets how long an individual connection is given to drain during shutdown.

When shutdown is signalled, a connection stops accepting new requests and finishes what is already in flight. This bounds that: a connection that hasn’t finished by then gives up and closes, logging a warning, so one wedged peer can’t hold the subtree open.

It also sets each connection’s shutdown timeout, to this value plus a small amount of slack, after which the connection is halted. Connections bound themselves, so the timeout only comes into play for one that ignores its own deadline.

Defaults to 30 seconds, matching the default shutdown timeout a topology gives its components. Lower it for an endpoint that should be abandoned quickly; raise it for one serving long-running requests that are worth waiting for.

pub fn with_tls_config(self, config: ServerConfig) -> Self

Sets the TLS configuration for the server.

This enables TLS, after which the server only accepts connections that are encrypted with TLS.

Defaults to TLS being disabled.

pub fn with_worker_pool(self, handle: Handle) -> Self

Runs this server’s tasks on the given runtime.

Every task the server runs is placed here: accepting connections, TLS handshakes, serving connections, and the futures hyper hands to the server’s executor. Only the subtree’s own supervisor loop stays on the runtime it was spawned on, since that is where children are registered rather than run.

Use this to keep the server off the runtime that its owner runs on – a topology component’s server belongs on the shared worker pool rather than on the runtime driving the topology, since request handling and TLS handshake crypto are both compute-heavy enough to add scheduling latency to everything else there.

Defaults to running on whichever runtime the subtree was spawned on.

pub fn into_supervisor(self) -> Supervisor

Converts this server into a supervisor.

The supervisor is configured to drive an accept loop on the configured listen address, and any resulting connections will be spawned and handled on the supervisor.