[][src]Module hyper::client

HTTP Client

There are two levels of APIs provided for construct HTTP clients:

  • The higher-level Client type.
  • The lower-level conn module.

Client

The Client is the main way to send HTTP requests to a server. The default Client provides these things on top of the lower-level API:

  • A default connector, able to resolve hostnames and connect to destinations over plain-text TCP.
  • A pool of existing connections, allowing better performance when making multiple requests to the same hostname.
  • Automatic setting of the Host header, based on the request Uri.
  • Automatic request retries when a pooled connection is closed by the server before any bytes have been written.

Many of these features can configured, by making use of Client::builder.

Example

For a small example program simply fetching a URL, take a look at the full client example.

extern crate hyper;

use hyper::{Client, Uri};
use hyper::rt::{self, Future, Stream};

let client = Client::new();

let fut = client

    // Make a GET /ip to 'http://httpbin.org'
    .get(Uri::from_static("http://httpbin.org/ip"))

    // And then, if the request gets a response...
    .and_then(|res| {
        println!("status: {}", res.status());

        // Concatenate the body stream into a single buffer...
        // This returns a new future, since we must stream body.
        res.into_body().concat2()
    })

    // And then, if reading the full body succeeds...
    .and_then(|body| {
        // The body is just bytes, but let's print a string...
        let s = ::std::str::from_utf8(&body)
            .expect("httpbin sends utf-8 JSON");

        println!("body: {}", s);

        // and_then requires we return a new Future, and it turns
        // out that Result is a Future that is ready immediately.
        Ok(())
    })

    // Map any errors that might have happened...
    .map_err(|err| {
        println!("error: {}", err);
    });

// A runtime is needed to execute our asynchronous code. In order to
// spawn the future into the runtime, it should already have been
// started and running before calling this code.
rt::spawn(fut);

Modules

conn

Lower-level client connection API.

connect

The Connect trait, and supporting types.

Structs

Builder

A builder to configure a new Client.

Client

A Client to make outgoing HTTP requests.

HttpConnector

A connector for the http scheme.

ResponseFuture

A Future that will resolve to an HTTP Response.