Struct isahc::HttpClient[−][src]

pub struct HttpClient { /* fields omitted */ }
Expand description

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::*, HttpClient};

// 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::*,
    HttpClient,
};
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.

Implementations

Create a new HTTP client using the default configuration.

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

Create a new HttpClientBuilder for building a custom client.

Get the configured cookie jar for this HTTP client, if any.

Availability

This method is only available when the cookies feature is enabled.

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::*, HttpClient};

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

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.

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

use isahc::{prelude::*, HttpClient};

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

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.

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::*, HttpClient};

let client = HttpClient::new()?;

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

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.

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::*, HttpClient};

let client = HttpClient::new()?;

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

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.

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.

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.

Send an HTTP request and return the HTTP response.

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 consuming it will close the connection early without downloading the rest of the response body.

The response body is provided as a stream that 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.

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.

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

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

Examples

use isahc::{prelude::*, HttpClient, Request};

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());

Send an HTTP request and return the HTTP response asynchronously.

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 consuming it will close the connection early without downloading the rest of the response body.

The response body is provided as a stream that 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.

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.

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

To execute a request synchronously, see HttpClient::send.

Examples

use isahc::{prelude::*, HttpClient, Request};

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Performs the conversion.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more