Crate chttp

The practical HTTP client that is fun to use.

Here are some of cHTTP’s key features:

• Full support for HTTP/1.1 and HTTP/2.
• Configurable request timeouts.
• Fully asynchronous core, with asynchronous and incremental reading and writing of request and response bodies.
• Offers an ergonomic synchronous API as well as an asynchronous API with support for async/await.
• Optional automatic redirect following.
• Sessions and cookie persistence.

Getting started

Sending requests is as easy as calling a single function. Let’s make a simple GET request to an example website:

use chttp::prelude::*;

let mut response = chttp::get("https://example.org")?;
println!("{}", response.text()?);

By default, sending a request will wait for the response, up until the response headers are received. The returned response struct includes the response body as an open stream implementing Read.

Sending a POST request is also easy, and takes an additional argument for the request body:

let response = chttp::post("https://httpbin.org/post", "make me a salad")?;

cHTTP provides several other simple functions for common HTTP request types:

chttp::put("https://httpbin.org/put", "have a salad")?;
chttp::head("https://httpbin.org/get")?;
chttp::delete("https://httpbin.org/delete")?;

If you want to customize the request by adding headers, setting timeouts, etc, then you can create a Request using a builder-style fluent interface, then finishing it off with a send:

use chttp::prelude::*;
use std::time::Duration;

let response = Request::post("https://httpbin.org/post")
    .header("Content-Type", "application/json")
    .timeout(Duration::from_secs(5))
    .body(r#"{
        "speed": "fast",
        "cool_name": true
    }"#)?
    .send()?;

Check out the examples directory in the project sources for even more examples.

Feature tour

Below is a brief overview of some notable features of cHTTP. Check out the rest of the documentation for even more guides and examples.

Easy request functions

You can start sending requests without any configuration by using the global functions in this module, including get, post, and send. These use a shared HTTP client instance with sane defaults, so it is easy to get up and running. They should work perfectly fine for many use-cases, so don’t about graduating to more complex APIs if you don’t need them.

Request and response traits

cHTTP includes a number of traits in the prelude module that extend the Request and Response types with a plethora of extra methods that make common tasks convenient and allow you to make more advanced configuration.

Some key traits to read about include RequestExt, RequestBuilderExt, and ResponseExt.

Custom clients

The free-standing functions for sending requests use a shared HttpClient instance, but you can also create your own client instances, which allows you to customize the default behavior for requests that use it.

See the documentation for HttpClient and HttpClientBuilder for more information on creating custom clients.

Asynchronous requests

Requests are always executed asynchronously under the hood. This allows a single client to execute a large number of requests concurrently with minimal overhead.

If you are writing an asynchronous application, you can additionally benefit from the async nature of the client by using the asynchronous methods available to prevent blocking threads in your code. All request methods have an asynchronous variant that ends with _async in the name. Here is our first example rewritten to use async/await syntax (nightly Rust only):

use chttp::prelude::*;

let mut response = chttp::get_async("https://httpbin.org/get").await?;
println!("{}", response.text_async().await?);

Logging

cHTTP logs quite a bit of useful information at various levels using the log crate.

If you set the log level to Trace for the chttp::wire target, cHTTP will also log all incoming and outgoing data while in flight. This may come in handy if you are debugging code and need to see the exact data being sent to the server and being received.

Re-exports

• pub use http;

Modules

• config
  Definition of all client and request configuration options.
• cookies
  Cookie state management.
• middleware
  HTTP client middleware API.
• prelude
  A “prelude” for importing common cHTTP types.

Structs

• Body
  Contains the body of an HTTP request or response.
• HttpClient
  An HTTP client for making requests.
• HttpClientBuilder
  An HTTP client builder, capable of creating custom HttpClient instances with customized behavior.
• ResponseFuture
  A future for a request being executed.

Enums

• Error
  All possible types of errors that can be returned from cHTTP.

Traits

• RequestBuilderExt
  Provides additional methods when building a request for configuring various execution-related options on how the request should be sent.
• RequestExt
  Extension methods on an HTTP request.
• ResponseExt
  Provides extension methods for working with HTTP responses.

Functions

• delete
  Send a DELETE request to the given URI.
• delete_async
  Send a DELETE request to the given URI asynchronously.
• get
  Send a GET request to the given URI.
• get_async
  Send a GET request to the given URI asynchronously.
• head
  Send a HEAD request to the given URI.
• head_async
  Send a HEAD request to the given URI asynchronously.
• post
  Send a POST request to the given URI with a given request body.
• post_async
  Send a POST request to the given URI asynchronously with a given request body.
• put
  Send a PUT request to the given URI with a given request body.
• put_async
  Send a PUT request to the given URI asynchronously with a given request body.
• send
  Send an HTTP request and return the HTTP response.
• send_async
  Send an HTTP request and return the HTTP response asynchronously.
• version
  Gets a human-readable string with the version number of cHTTP and its dependencies.