Trait isahc::AsyncReadResponseExt

pub trait AsyncReadResponseExt<R: AsyncRead + Unpin> {
    fn consume(&mut self) -> ConsumeFuture<'_, R>;
    fn copy_to<'a, W>(&'a mut self, writer: W) -> CopyFuture<'a, R, W>
    where
        W: AsyncWrite + Unpin + 'a;
    fn bytes(&mut self) -> BytesFuture<'_, &mut R>;
    fn text(&mut self) -> TextFuture<'_, &mut R>;
    fn json<T>(&mut self) -> JsonFuture<'_, R, T>
    where
        T: DeserializeOwned;
}

Provides extension methods for consuming asynchronous HTTP response streams.

Required Methods

fn consume(&mut self) -> ConsumeFuture<'_, R>

Read any remaining bytes from the response body stream and discard them until the end of the stream is reached. It is usually a good idea to call this method before dropping a response if you know you haven’t read the entire response body.

Background

By default, if a response stream is dropped before it has been completely read from, then that HTTP connection will be terminated. Depending on which version of HTTP is being used, this may require closing the network connection to the server entirely. This can result in sub-optimal performance for making multiple requests, as it prevents Isahc from keeping the connection alive to be reused for subsequent requests.

If you are downloading a file on behalf of a user and have been requested to cancel the operation, then this is probably what you want. But if you are making many small API calls to a known server, then you may want to call consume() before dropping the response, as reading a few megabytes off a socket is usually more efficient in the long run than taking a hit on connection reuse, and opening new connections can be expensive.

Note that in HTTP/2 and newer, it is not necessary to close the network connection in order to interrupt the transfer of a particular response. If you know that you will be using only HTTP/2 or newer, then calling this method is probably unnecessary.

Examples

use isahc::prelude::*;

let mut response = isahc::get_async("https://example.org").await?;

println!("Status: {}", response.status());
println!("Headers: {:#?}", response.headers());

// Read and discard the response body until the end.
response.consume().await?;

fn copy_to<'a, W>(&'a mut self, writer: W) -> CopyFuture<'a, R, W>where
    W: AsyncWrite + Unpin + 'a,

Copy the response body into a writer asynchronously.

Returns the number of bytes that were written.

Examples

Copying the response into an in-memory buffer:

use isahc::prelude::*;

let mut buf = vec![];
isahc::get_async("https://example.org").await?
    .copy_to(&mut buf).await?;
println!("Read {} bytes", buf.len());

fn bytes(&mut self) -> BytesFuture<'_, &mut R>

Read the entire response body into memory.

Examples

use isahc::prelude::*;

let image_bytes = isahc::get_async("https://httpbin.org/image/jpeg")
    .await?
    .bytes()
    .await?;

fn text(&mut self) -> TextFuture<'_, &mut R>

Available on crate feature text-decoding only.

Read the response body as a string asynchronously.

This method consumes the entire response body stream and can only be called once.

Availability

This method is only available when the text-decoding feature is enabled, which it is by default.

Examples

use isahc::prelude::*;

let text = isahc::get_async("https://example.org").await?
    .text().await?;
println!("{}", text);

fn json<T>(&mut self) -> JsonFuture<'_, R, T>where
    T: DeserializeOwned,

Available on crate feature json only.

Deserialize the response body as JSON into a given type.

Caveats

Unlike its synchronous equivalent, this method reads the entire response body into memory before attempting deserialization. This is due to a Serde limitation since incremental partial deserializing is not supported.

Availability

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

Examples

use isahc::prelude::*;
use serde_json::Value;

let json: Value = isahc::get_async("https://httpbin.org/json").await?
    .json().await?;
println!("author: {}", json["slideshow"]["author"]);

Implementors

impl<R: AsyncRead + Unpin> AsyncReadResponseExt<R> for Response<R>