Trait isahc::ReadResponseExt

source · 
pub trait ReadResponseExt<R: Read> {
    fn copy_to<W: Write>(&mut self, writer: W) -> Result<u64>;
    fn bytes(&mut self) -> Result<Vec<u8>>;
    fn text(&mut self) -> Result<String>;
    fn json<T>(&mut self) -> Result<T, Error>
    where
        T: DeserializeOwned;

    fn consume(&mut self) -> Result<()> { ... }
    fn copy_to_file<P: AsRef<Path>>(&mut self, path: P) -> Result<u64> { ... }
}
Expand description

Provides extension methods for consuming HTTP response streams.

Required Methods

Copy the response body into a writer.

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("https://example.org")?.copy_to(&mut buf)?;
println!("Read {} bytes", buf.len());

Read the entire response body into memory.

Examples
use isahc::prelude::*;

let image_bytes = isahc::get("https://httpbin.org/image/jpeg")?.bytes()?;
Available on crate feature text-decoding only.

Read the response body as a string.

The encoding used to decode the response body into a string depends on the response. If the body begins with a Byte Order Mark (BOM), then UTF-8, UTF-16LE or UTF-16BE is used as indicated by the BOM. If no BOM is present, the encoding specified in the charset parameter of the Content-Type header is used if present. Otherwise UTF-8 is assumed.

If the response body contains any malformed characters or characters not representable in UTF-8, the offending bytes will be replaced with U+FFFD REPLACEMENT CHARACTER, which looks like this: �.

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("https://example.org")?.text()?;
println!("{}", text);
Available on crate feature json only.

Deserialize the response body as JSON into a given type.

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("https://httpbin.org/json")?.json()?;
println!("author: {}", json["slideshow"]["author"]);

Provided Methods

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("https://example.org")?;

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

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

Write the response body to a file.

This method makes it convenient to download a file using a GET request and write it to a file synchronously in a single chain of calls.

Returns the number of bytes that were written.

Examples
use isahc::prelude::*;

isahc::get("https://httpbin.org/image/jpeg")?
    .copy_to_file("myimage.jpg")?;

Implementors