[−][src]Struct isahc::HttpClient
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, prelude::*}; use std::time::Duration; let client = HttpClient::builder() .preferred_http_version(http::Version::HTTP_11) .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: HttpTryFrom<U>,
[src]
Uri: HttpTryFrom<U>,
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()?);
ⓘImportant traits for ResponseFuture<'_>pub fn get_async<U>(&self, uri: U) -> ResponseFuture where
Uri: HttpTryFrom<U>,
[src]
Uri: HttpTryFrom<U>,
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: HttpTryFrom<U>,
[src]
Uri: HttpTryFrom<U>,
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"]);
ⓘImportant traits for ResponseFuture<'_>pub fn head_async<U>(&self, uri: U) -> ResponseFuture where
Uri: HttpTryFrom<U>,
[src]
Uri: HttpTryFrom<U>,
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: HttpTryFrom<U>,
[src]
&self,
uri: U,
body: impl Into<Body>
) -> Result<Response<Body>, Error> where
Uri: HttpTryFrom<U>,
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 }"#)?;
ⓘImportant traits for ResponseFuture<'_>pub fn post_async<U>(&self, uri: U, body: impl Into<Body>) -> ResponseFuture where
Uri: HttpTryFrom<U>,
[src]
Uri: HttpTryFrom<U>,
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: HttpTryFrom<U>,
[src]
&self,
uri: U,
body: impl Into<Body>
) -> Result<Response<Body>, Error> where
Uri: HttpTryFrom<U>,
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 }"#)?;
ⓘImportant traits for ResponseFuture<'_>pub fn put_async<U>(&self, uri: U, body: impl Into<Body>) -> ResponseFuture where
Uri: HttpTryFrom<U>,
[src]
Uri: HttpTryFrom<U>,
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: HttpTryFrom<U>,
[src]
Uri: HttpTryFrom<U>,
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
.
ⓘImportant traits for ResponseFuture<'_>pub fn delete_async<U>(&self, uri: U) -> ResponseFuture where
Uri: HttpTryFrom<U>,
[src]
Uri: HttpTryFrom<U>,
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]
&self,
request: Request<B>
) -> Result<Response<Body>, Error>
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
RequestBuilderExt
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());
ⓘImportant traits for ResponseFuture<'_>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
Auto Trait Implementations
impl Send for HttpClient
impl Sync for HttpClient
impl Unpin for HttpClient
impl !UnwindSafe for HttpClient
impl !RefUnwindSafe for HttpClient
Blanket Implementations
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> From<T> for T
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,