Crate chttp

source ·
Expand description

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.

Re-exports

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

Modules

Provides types for working with request and response bodies.
The HTTP client implementation.
Types for error handling.
Definition of all configurable client options.

Functions

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.