Crate generic_async_http_client

A generic async HTTP request create.

It is meant to be a thin wrapper around various HTTP clients and handles TLS, serialization and parsing.

The main goal is to allow binaries (that pull in some libraries that make use of a HTTP client) to specify what implementation should be used.

And if there is a Proxy. If not specified auto detection is performed by looking at HTTP_PROXY.

Also, you can Mock the webserver side for tests.

Features

You need to specify via features what crates are used to do the actual work.

feature flag	Meaning
use_hyper	Use hyper for HTTP
use_async_h1	Use async_h1 for HTTP
rustls_byoc	Add support for HTTPS via rustls - You need to set a CryptoProvider
rustls_ring	Like rustls_byoc but use ring for crypto
rustls_aws_lc_rs	Like rustls_byoc but use aws-lc-rs for crypto
rustls_fips	Like rustls_byoc but use aws-lc-rs in FIPS mode for crypto
proxies	Add support for Socks5 and HTTP proxy
hyper_native_tls	Use hyper for HTTP and do HTTPS via native_tls
async_native_tls	Use async_h1 for HTTP and do HTTPS via native_tls
http2	Use http2 if available (only works with use_hyper)

Without anything specified you will end up with No HTTP backend was selected. If you use this crate for a library, please reexport the appropriate features.

Motivation

Rust offers different async runtimes that - on a high level - offer the same thing: asynchronous functions for files, sockets and so on.

So if you write a lib and need some basic stuff (like an http client) you sometimes have to make choices that are not what your crates users would have liked. For example: I wrote a webserver based on hyper and wanted to add ACME. A crate I found did what I needed but used async-h1 and async-std. While that worked, it did increase the binary size and crates I depend on by a good amount.

So I wrote this. You can specify which backend to use. In the Webserver case, using tokio which is already a dependency VS async-std did lead to 81 less crates and a 350kB smaller binary. Using (and async-acme):

[profile.release]
lto = "fat"
codegen-units = 1

Also for http clients: there should be a way to add a proxy for all libs that use it.

Plans

2. Add Sessions - to make multiple requests more efficient
3. Add a cookie jar for the sessions
4. Allow a Body to be streamed from a server
5. Allow a Body to be streamed to a server

Example

#[derive(Serialize)]
struct ContactForm {
    email: String,
    text: String,
}
async fn post_form(form: &ContactForm) -> Result<(), Error> {
   let req = Request::post("http://example.com/").form(form)?;
   assert_eq!(req.exec().await?.text().await?, "ok");
   Ok(())
}

If performing more than one HTTP Request you should favor the use of [Session] over Request.

Modules

proxyproxies

Structs

Body

A Body for the Request. You will most likely use Request::body directly.

HeaderName

A HTTP Header Name

HeaderValue

A HTTP Header Value

Mocktest and mock_tests

Mock Responses and validate Requests. All responses of a thread will be checked against the Mock if at least one Endpoint is Mocked. Otherwise a normal web request is done

MockedEndpointtest and mock_tests

A mocked HTTP Endpoint.

Request

Builds a HTTP request, poll it to query

Response

The response of a webserver. Headers and Status are available from the start, the body must be polled/awaited again

Enums

Error

MockErrtest and mock_tests