[][src]Crate chttp

The practical HTTP client that is fun to use.

cHTTP is an HTTP client that provides a clean and easy-to-use interface around the venerable libcurl.

Sending requests

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

use chttp;

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

Requests are performed synchronously, 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:

use chttp;

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

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

chttp::put("https://example.org", "have a salad")?;

Custom requests

cHTTP is not limited to canned HTTP verbs; you can customize requests by creating your own Request object and then sending that.

use chttp::{self, http};

let request = http::Request::post("https://example.org")
    .header("Content-Type", "application/json")
        "speed": "fast",
        "cool_name": true
let response = chttp::send(request)?;

Request options

How requests are sent can be customized using the Options struct, which provides various fields for setting timeouts, proxies, and other connection and protocol configuration. These options can be included right along your request as an extension object:

use chttp::{self, http, Options};
use std::time::Duration;

let request = http::Request::get("https://example.org")
        // Set a 5 second timeout.
let response = chttp::send(request)?;

Custom clients

The free-standing functions for sending request delegate to a shared client instance that is lazily instantiated with the default options. You can also create custom client instances of your own, which allows you to set default options for all requests and group related connections together. Each client has its own connection pool and event loop, so separating certain requests into separate clients can ensure that they are isolated from each other.

See the documentation for Client and ClientBuilder for more details on creating custom clients.


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.

Feature flags

cHTTP is designed to be as "pay-as-you-need" as possible using Cargo feature flags and optional dependencies. Unstable features are also initially released behind feature flags until they are stabilized. You can add the feature names below to your Cargo.toml file to enable them:

version = "0.3"
features = ["async-api"]

Below is a list of all available feature flags and their meanings.


Enable persistent HTTP cookie support. Enabled by default.


Enable HTTP/2 support in libcurl via libnghttp2. Enabled by default.


Enable convenience methods for parsing HTTP responses into JSON objects. Disabled by default.


Enable use of the Public Suffix List to filter out potentially malicious cross-domain cookies. Enabled by default.


Enable the async futures-based API. This allows you to take full advantage of cHTTP's asynchronous core. Currently behind a feature flag until the futures API stabilizes. This an unstable feature whose interface may change between patch releases.


Enable the new middleware API. Unstable until the API is finalized. This an unstable feature whose interface may change between patch releases.


pub use http;
pub use crate::body::Body;
pub use crate::client::Client;
pub use crate::error::Error;
pub use crate::options::*;



Provides types for working with request and response bodies.


The HTTP client implementation.


Cookie state management.


Types for error handling.


HTTP client middleware API.


Definition of all configurable client options.



Sends an HTTP DELETE request.


Sends an HTTP GET request.


Sends an HTTP HEAD request.


Sends an HTTP POST request.


Sends an HTTP PUT request.


Sends an HTTP request.


Gets a human-readable string with the version number of cHTTP and its dependencies.

Type Definitions


An HTTP request.


An HTTP response.