pub struct HttpClient { /* private fields */ }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§
Source§impl HttpClient
impl HttpClient
Sourcepub fn new() -> Result<Self, Error>
pub fn new() -> Result<Self, Error>
Create a new HTTP client using the default configuration.
If the client fails to initialize, an error will be returned.
Sourcepub fn builder() -> HttpClientBuilder
pub fn builder() -> HttpClientBuilder
Create a new HttpClientBuilder for building a custom client.
Sourcepub fn get<U>(&self, uri: U) -> Result<Response<Body>, Error>
pub fn get<U>(&self, uri: U) -> Result<Response<Body>, Error>
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()?);Sourcepub fn get_async<U>(&self, uri: U) -> ResponseFuture<'_> ⓘ
pub fn get_async<U>(&self, uri: U) -> ResponseFuture<'_> ⓘ
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.
Sourcepub fn head<U>(&self, uri: U) -> Result<Response<Body>, Error>
pub fn head<U>(&self, uri: U) -> Result<Response<Body>, Error>
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"]);Sourcepub fn head_async<U>(&self, uri: U) -> ResponseFuture<'_> ⓘ
pub fn head_async<U>(&self, uri: U) -> ResponseFuture<'_> ⓘ
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.
Sourcepub fn post<U, B>(&self, uri: U, body: B) -> Result<Response<Body>, Error>
pub fn post<U, B>(&self, uri: U, body: B) -> Result<Response<Body>, Error>
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
}"#)?;Sourcepub fn post_async<U, B>(&self, uri: U, body: B) -> ResponseFuture<'_> ⓘ
pub fn post_async<U, B>(&self, uri: U, body: B) -> ResponseFuture<'_> ⓘ
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.
Sourcepub fn put<U, B>(&self, uri: U, body: B) -> Result<Response<Body>, Error>
pub fn put<U, B>(&self, uri: U, body: B) -> Result<Response<Body>, Error>
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
}"#)?;Sourcepub fn put_async<U, B>(&self, uri: U, body: B) -> ResponseFuture<'_> ⓘ
pub fn put_async<U, B>(&self, uri: U, body: B) -> ResponseFuture<'_> ⓘ
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.
Sourcepub fn delete<U>(&self, uri: U) -> Result<Response<Body>, Error>
pub fn delete<U>(&self, uri: U) -> Result<Response<Body>, Error>
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.
Sourcepub fn delete_async<U>(&self, uri: U) -> ResponseFuture<'_> ⓘ
pub fn delete_async<U>(&self, uri: U) -> ResponseFuture<'_> ⓘ
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.
Sourcepub fn send<B>(&self, request: Request<B>) -> Result<Response<Body>, Error>
pub fn send<B>(&self, request: Request<B>) -> Result<Response<Body>, Error>
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());Sourcepub fn send_async<B>(&self, request: Request<B>) -> ResponseFuture<'_> ⓘ
pub fn send_async<B>(&self, request: Request<B>) -> ResponseFuture<'_> ⓘ
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§
Source§impl Clone for HttpClient
impl Clone for HttpClient
Source§fn clone(&self) -> HttpClient
fn clone(&self) -> HttpClient
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more