[−][src]Crate chttp

The practical HTTP client that is fun to use.

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::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://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::prelude::*;

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

There are a number of options involved in request execution that can be configured for a request, such as timeouts, proxies, and other connection and protocol configuration. These can be customized by using extension methods provided by the RequestBuilderExt trait:

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

let response = Request::get("https://example.org")
    .timeout(Duration::from_secs(5))
    .body(())?
    .send()?;

Configuration related to sending requests is stored inside the request struct using http::Extensions.

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.

Asynchronous API and execution

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 only):

let mut response = chttp::get_async("https://example.org").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 extern crate http;

Modules

config	Definition of all client and request configuration options.
cookies	Cookie state management.
middleware	HTTP client middleware API.
prelude

Structs

Body	Contains the body of an HTTP request or response.
Client	An HTTP client for making requests.
ClientBuilder	An HTTP client builder, capable of creating custom `Client` instances with customized behavior.

Enums

Error

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

Functions

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