Struct Response 

pub struct Response { /* private fields */ }

A response to a request.

Arrives from a request; it is not constructed directly. Reading the body consumes it, so a second read fails. Self::try_clone gets a copy that can be read separately.

Implementations

impl Response

pub fn status(&self) -> StatusCode

The response’s status.

pub fn status_text(&self) -> &'static str

The canonical reason phrase for the status, or empty for a code with no well-known one.

Always the canonical phrase. HTTP/1 lets a server send its own, which is not surfaced here; HTTP/2 and HTTP/3 carry none at all.

pub fn ok(&self) -> bool

Whether the status is in the 2xx range.

pub fn headers(&self) -> &HeaderMap

The response’s headers.

pub fn url(&self) -> &Url

The URL the response came from, after any redirects.

pub fn redirected(&self) -> bool

Whether a redirect was followed to reach this response.

pub fn version(&self) -> Version

The HTTP version the response arrived over.

pub fn peer(&self) -> &PeerInformation

The peer that sent the response.

pub fn try_clone(&self) -> Result<Self, FaithError>

Copy the response, so the body can be read twice.

Both copies read the same underlying body, and neither is disturbed by the other having been cloned. Fails if the body has already been read.

pub fn body_used(&self) -> bool

Whether the body has been read, or handed out as a stream.

pub async fn bytes(&self) -> Result<Vec<u8>, FaithError>

Read the whole body.

Consumes it, so a second read fails. A request’s integrity is verified here, once the whole body is in hand.

pub async fn text(&self) -> Result<String, FaithError>

Read the whole body as text.

Decoded as UTF-8, with invalid sequences replaced by U+FFFD.

pub async fn json<T: DeserializeOwned>(&self) -> Result<T, FaithError>

Read the whole body and deserialise it from JSON.

Reads into memory before parsing, which can cost twice the body’s size; Self::body_stream avoids that.

pub fn body_stream(&self) -> Result<Option<BodyReader>, FaithError>

The body as a stream of chunks, decoded under whichever coding was negotiated.

None for a response that cannot carry a body. Callable more than once: every stream a response hands out reads from its one position in the body, so one taken after part of the body was read continues from there. Dropping a stream gives the response’s claim on the body up, stopping the transfer once no clone still wants it. Fails if the body has already been read to the end or discarded.

pub async fn discard(&self)

Give up on the body, releasing the connection back to the pool.

Worth doing when the body is not wanted: left unread, the claim on it is held until the response drops. Gives up this response’s claim only, so a clone still reading carries on; when it was the last claim, resolves once the transfer has been stopped: the stream reset on HTTP/2 and HTTP/3, the connection drained back to the pool or closed on HTTP/1.

pub async fn timing(&self) -> RequestTiming

The timing of the request that produced this response, once its body has ended.

pub async fn trailers(&self) -> Trailers

The trailers, once the body has ended.

A body that is never read never ends, so this waits indefinitely; see Trailers.

pub async fn write_to_file( &self, path: impl AsRef<Path>, options: &FileDestination, on_progress: impl FnMut(FileProgress), ) -> Result<FileWritten, FaithError>

Write the body to a file, reporting progress as the bytes land.

on_progress is called with the bytes written so far and the advertised length when it is known, at most every 50ms, and once more when the last byte is written.

impl Response

pub fn into_http(self) -> Result<Response<ResponseBody>, FaithError>

Convert into an http::Response, for code written against the wider ecosystem.

Fails if the body is already being consumed elsewhere. A response that cannot carry a body yields an empty one.

Trait Implementations

impl Clone for Response

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Response

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl TryFrom<Response> for Response<ResponseBody>

type Error = FaithError

The type returned in the event of a conversion error.

fn try_from(response: Response) -> Result<Self, Self::Error>

Performs the conversion.