Crate hyperdriver

Hyperdriver

Building the missing middle for network services in Rust.

This crate is an alternative to hyper-util, providing a more fully-featured interface for building Clients and Servers on top of the hyper crate. It is developed more speadily, but this means that it has a less stable interface between minor versions than hyper-util, which is trying to carefully consider some of the available design choices.

This crate supports HTTP/1.1 and HTTP/2, as well as a pluggable transport mechanism so that you can implement your own transports. Out of the box, it supports TCP, Unix Domain Sockets, and in-memory byte streams, all with TLS support.

The TLS support here should be additionally general enough to wrap any byte stream which implements AsyncRead + AsyncWrite, so you can use it with other libraries.

A tour

Hyperdriver provides Client and Server types, which are the main entry points for most high level use cases. The Client type is designed for making requests to servers, and is similar to the one found in reqwest, but with a bit more pluggability and flexibility.

The server is modeled after the features provided by the hyper pre-1.0 server, and the axum server, but again with a more pluggable and composable design.

Both are heavily reliant on the tower tower::Service trait, and should compose well with other tower-based services, such as those from tower-http.

When you don’t need that much customization, the defaults and regular implementations of both Client and Server should be sufficient, and will help to avoid the type complexity that comes with using layers of tower::Layers.

Using tower::Service based types

The tower::Service based types implemented for this crate are almost exclucively provided in the crate::service module.

When assembling a tower::Service, it is often useful to do so with a tower::ServiceBuilder and a collection of tower::Layers. This is a common pattern in the tower ecosystem, and hyperdriver is no exception. It is important to note that typing for these kinds of services can be a bit tricky and unweildy. For instance, you can’t dynamically decide to apply a Layer to a builder, you have to use an Option so that they type of the resulting layer is effectively Option<Layer>. Alternatively, you can use tower::ServiceBuilder::boxed to create a boxed service.

Hyperdriver provides a helpful crate::service::OptionLayer type which can be used to wrap layers without box-ing the error type (as the one from tower does). See crate::service::OptionLayerExt for an ergomic way to use this with the tower::ServiceBuilder type.

Building Servers

A server ends up being a “double service”. Each http::Request is handled by a service, and returns a http::Response. The server itself requires a service which can create a new service for each request, which is often called a MakeService in the tower ecosystem. This two-layer design can be confusing.

If your server’s service is clone-able, you can use SharedService to wrap it. This will mean that the Server will clone the service for each incoming connection. Otherwise, you should implement a MakeService, which is a service that accepts a reference to a connection type, and returns an appropriate service for handling the ensuing request.

See the crate::server module for more information on building servers.

Building Clients

A client can also be composed of services. In this case, there is only one “service”, it must accept a http::Request and return a http::Response. At the inner-most level, there is a connection step, where the http::Request is coupled with a connection, to be used to send the request. At this point, the service will switch from accepting a http::Request to accepting an ExecuteRequest type, which includes the request and the connection.

The default way to do this in hyperdriver is to use the crate::client::ConnectionPoolService type, which implements connections and connection pooling. Many middleware services can be applied both above (when the service only has an http::Request) and below (when the service has an ExecuteRequest) this type. Some middleware might have slightly different behavior. For example, the SetHostHeader middleware will apply the Host header to the request based on the version of the request if the connection is not available yet. Usually this is not desired, since an HTTP/1.1 request might be internally upgraded to HTTP/2, and the Host header should be removed. In this case, the SetHostHeader middleware should be applied after the ConnectionPoolService.

Bodies

The hyper ecosystem relies on the http_body::Body trait to represent the body of a request or response. This is implemented for many types, and so can be tricky to unify. Many ecosystem crates (axum, reqwest, tonic, etc.) implement their own body type, which sometimes can be used to encapsulate other bodies.

Hyperdriver provides a Body type which is a wrapper around a http_body::Body type, but it is intentionally minimal. If you need a unifying body type, you can reach for http_body_util::combinators::UnsyncBoxBody or http_body_util::combinators::BoxBody, which provide dynamic dispact bodies over any implementor of the http_body::Body type. The Body is most useful for simple cases where you want to unify a request and response body. hyper provides the hyper::body::Incoming type, which is what all incoming bodies are provided as by both hyper and this crate. Body is a wrapper around this type and known, in memory bodies, which can be convenient for simple services, but notably do not support streaming or chunked-encoded bodies.

Re-exports

pub use body::Body;

pub use client::Client;client

pub use server::Server;server

Modules

body

A wrapper Body type with limited support for in-memory bodies and hyper::body::Incoming. Optionally includes support for axum bodies.

bridge

Utilities for bridging to hyper traits from other runtimes.

clientclient

HTTP client library for Rust, built on top of hyper.

info

Connection Information

serverserver

A server framework with connection management, automatic HTTP/1.1 and HTTP/2 switching, and pluggable acceptors, protocols, and services.

service

A collection of utilities for working with Service types and Servers.

stream

Utilities for working across types of streams inside a single connector, to allow the upstream routing table to select the most appropriate type of conenction.

Traits

IntoRequestParts

Turn the item into http::request::Parts infallibly