[−][src]Struct isahc::HttpClient

pub struct HttpClient { /* fields omitted */ }

An HTTP client for making requests.

An HttpClient instance acts as a session for executing one or more HTTP requests, and also allows you to set common protocol settings that should be applied to all requests made with the client.

HttpClient is entirely thread-safe, and implements both Send and Sync. You are free to create clients outside the context of the "main" thread, or move them between threads. You can even invoke many requests simultaneously from multiple threads, since doing so doesn't need a mutable reference to the client. This is fairly cheap to do as well, since internally requests use lock-free message passing to get things going.

The client maintains a connection pool internally and is not cheap to create, so we recommend creating a client once and re-using it throughout your code. Creating a new client for every request would decrease performance significantly, and might cause errors to occur under high workloads, caused by creating too many system resources like sockets or threads.

It is not universally true that you should use exactly one client instance in an application. All HTTP requests made with the same client will share any session-wide state, like cookies or persistent connections. It may be the case that it is better to create separate clients for separate areas of an application if they have separate concerns or are making calls to different servers. If you are creating an API client library, that might be a good place to maintain your own internal client.

Examples

use isahc::prelude::*;

// Create a new client using reasonable defaults.
let client = HttpClient::new()?;

// Make some requests.
let mut response = client.get("https://example.org")?;
assert!(response.status().is_success());

println!("Response:\n{}", response.text()?);

Customizing the client configuration:

use isahc::{
    config::{RedirectPolicy, VersionNegotiation},
    prelude::*,
};
use std::time::Duration;

let client = HttpClient::builder()
    .version_negotiation(VersionNegotiation::http11())
    .redirect_policy(RedirectPolicy::Limit(10))
    .timeout(Duration::from_secs(20))
    // May return an error if there's something wrong with our configuration
    // or if the client failed to start up.
    .build()?;

let response = client.get("https://example.org")?;
assert!(response.status().is_success());

See the documentation on HttpClientBuilder for a comprehensive look at what can be configured.

Methods

impl HttpClient[src]

pub fn new() -> Result<Self, Error>[src]

Create a new HTTP client using the default configuration.

If the client fails to initialize, an error will be returned.

pub fn builder() -> HttpClientBuilder[src]

Create a new HttpClientBuilder for building a custom client.

pub fn get<U>(&self, uri: U) -> Result<Response<Body>, Error> where
    Uri: TryFrom<U>,
    <Uri as TryFrom<U>>::Error: Into<Error>, [src]

Send a GET request to the given URI.

To customize the request further, see HttpClient::send. To execute the request asynchronously, see HttpClient::get_async.

Examples

use isahc::prelude::*;

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

pub fn get_async<U>(&self, uri: U) -> ResponseFuture where
    Uri: TryFrom<U>,
    <Uri as TryFrom<U>>::Error: Into<Error>, [src]

Send a GET request to the given URI asynchronously.

To customize the request further, see HttpClient::send_async. To execute the request synchronously, see HttpClient::get.

pub fn head<U>(&self, uri: U) -> Result<Response<Body>, Error> where
    Uri: TryFrom<U>,
    <Uri as TryFrom<U>>::Error: Into<Error>, [src]

Send a HEAD request to the given URI.

To customize the request further, see HttpClient::send. To execute the request asynchronously, see HttpClient::head_async.

Examples

let response = client.head("https://example.org")?;
println!("Page size: {:?}", response.headers()["content-length"]);

pub fn head_async<U>(&self, uri: U) -> ResponseFuture where
    Uri: TryFrom<U>,
    <Uri as TryFrom<U>>::Error: Into<Error>, [src]

Send a HEAD request to the given URI asynchronously.

To customize the request further, see HttpClient::send_async. To execute the request synchronously, see HttpClient::head.

pub fn post<U>(
    &self,
    uri: U,
    body: impl Into<Body>
) -> Result<Response<Body>, Error> where
    Uri: TryFrom<U>,
    <Uri as TryFrom<U>>::Error: Into<Error>, [src]

Send a POST request to the given URI with a given request body.

To customize the request further, see HttpClient::send. To execute the request asynchronously, see HttpClient::post_async.

Examples

use isahc::prelude::*;

let client = HttpClient::new()?;

let response = client.post("https://httpbin.org/post", r#"{
    "speed": "fast",
    "cool_name": true
}"#)?;

pub fn post_async<U>(&self, uri: U, body: impl Into<Body>) -> ResponseFuture where
    Uri: TryFrom<U>,
    <Uri as TryFrom<U>>::Error: Into<Error>, [src]

Send a POST request to the given URI asynchronously with a given request body.

To customize the request further, see HttpClient::send_async. To execute the request synchronously, see HttpClient::post.

pub fn put<U>(
    &self,
    uri: U,
    body: impl Into<Body>
) -> Result<Response<Body>, Error> where
    Uri: TryFrom<U>,
    <Uri as TryFrom<U>>::Error: Into<Error>, [src]

Send a PUT request to the given URI with a given request body.

To customize the request further, see HttpClient::send. To execute the request asynchronously, see HttpClient::put_async.

Examples

use isahc::prelude::*;

let client = HttpClient::new()?;

let response = client.put("https://httpbin.org/put", r#"{
    "speed": "fast",
    "cool_name": true
}"#)?;

pub fn put_async<U>(&self, uri: U, body: impl Into<Body>) -> ResponseFuture where
    Uri: TryFrom<U>,
    <Uri as TryFrom<U>>::Error: Into<Error>, [src]

Send a PUT request to the given URI asynchronously with a given request body.

To customize the request further, see HttpClient::send_async. To execute the request synchronously, see HttpClient::put.

pub fn delete<U>(&self, uri: U) -> Result<Response<Body>, Error> where
    Uri: TryFrom<U>,
    <Uri as TryFrom<U>>::Error: Into<Error>, [src]

Send a DELETE request to the given URI.

To customize the request further, see HttpClient::send. To execute the request asynchronously, see HttpClient::delete_async.

pub fn delete_async<U>(&self, uri: U) -> ResponseFuture where
    Uri: TryFrom<U>,
    <Uri as TryFrom<U>>::Error: Into<Error>, [src]

Send a DELETE request to the given URI asynchronously.

To customize the request further, see HttpClient::send_async. To execute the request synchronously, see HttpClient::delete.

pub fn send<B: Into<Body>>(
    &self,
    request: Request<B>
) -> Result<Response<Body>, Error>[src]

Send an HTTP request and return the HTTP response.

The response body is provided as a stream that may only be consumed once.

This client's configuration can be overridden for this request by configuring the request using methods provided by the Configurable trait.

Upon success, will return a Response containing the status code, response headers, and response body from the server. The Response is returned as soon as the HTTP response headers are received; the connection will remain open to stream the response body in real time. Dropping the response body without fully consume it will close the connection early without downloading the rest of the response body.

Note that the actual underlying socket connection isn't necessarily closed on drop. It may remain open to be reused if pipelining is being used, the connection is configured as keep-alive, and so on.

Since the response body is streamed from the server, it may only be consumed once. If you need to inspect the response body more than once, you will have to either read it into memory or write it to a file.

The response body is not a direct stream from the server, but uses its own buffering mechanisms internally for performance. It is therefore undesirable to wrap the body in additional buffering readers.

To execute the request asynchronously, see HttpClient::send_async.

Examples

use isahc::prelude::*;

let client = HttpClient::new()?;

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

let response = client.send(request)?;
assert!(response.status().is_success());

pub fn send_async<B: Into<Body>>(&self, request: Request<B>) -> ResponseFuture[src]

Send an HTTP request and return the HTTP response asynchronously.

See HttpClient::send for further details.

Examples

use isahc::prelude::*;

let client = HttpClient::new()?;

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

let response = client.send_async(request).await?;
assert!(response.status().is_success());

Trait Implementations

impl Debug for HttpClient[src]

Auto Trait Implementations

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized, [src]

impl<T> Borrow<T> for T where
    T: ?Sized, [src]

impl<T> BorrowMut<T> for T where
    T: ?Sized, [src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, [src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, [src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, [src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.