[][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")?;
chttp::head("https://example.org")?;
chttp::delete("https://example.org")?;

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")
    .body(r#"{
        "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")
    .extension(Options::default()
        // Set a 5 second timeout.
        .with_timeout(Some(Duration::from_secs(5))))
    .body(())?;
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.

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.

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:

[dependencies.chttp]
version = "0.3"
features = ["async-api"]

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

cookies

Enable persistent HTTP cookie support. Enabled by default.

http2

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

json

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

psl

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

async-api

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.

middleware-api

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

Re-exports

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

Modules

body

Provides types for working with request and response bodies.

client

The HTTP client implementation.

cookies

Cookie state management.

error

Types for error handling.

middleware

HTTP client middleware API.

options

Definition of all configurable client options.

Functions

delete

Sends an HTTP DELETE request.

get

Sends an HTTP GET request.

head

Sends an HTTP HEAD request.

post

Sends an HTTP POST request.

put

Sends an HTTP PUT request.

send

Sends an HTTP request.

version

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

Type Definitions

Request

An HTTP request.

Response

An HTTP response.