Struct under::Response

pub struct Response(_);

An HTTP response.

An HTTP Response consists of a head (a status code and some headers), and a body (which may be empty). This type offers convenient helpers for constructing HTTP responses for you for common use-cases.

Examples

use under::{Request, Response, HttpEntity};

// Here, we're defining an endpoint for our server.
async fn handle_get(request: Request) -> Result<Response, anyhow::Error> {
    let target = request.fragment_str("target").unwrap_or("world");
    Ok(Response::text(format!("hello, {}", target)))
}

let mut http = under::http();
http
    .at("/hello").get(handle_get)
    .at("/hello/{target}").get(handle_get);
http.prepare();
let mut response = http.handle(Request::get("/hello")?).await?;
assert_eq!(response.status(), http::StatusCode::OK);
let body = response.data(512).into_text().await?;
assert_eq!(body, "hello, world");

Implementations

impl Response

pub fn empty_200() -> Self

Creates an empty response with a status code of 200.

See Response::empty_status for more information.

Example

let response = Response::empty_200();
assert_eq!(response.status(), http::StatusCode::OK);

pub fn empty_204() -> Self

Creates an empty response with a status code of 204.

See Response::empty_status for more information.

Examples

let response = Response::empty_204();
assert_eq!(response.status(), http::StatusCode::NO_CONTENT);

pub fn empty_404() -> Self

Creates an empty response with a status code of 404.

See Response::empty_status for more information.

Examples

let response = Response::empty_404();
assert_eq!(response.status(), http::StatusCode::NOT_FOUND);

pub fn empty_500() -> Self

Creates an empty response with a status code of 500.

See Response::empty_status for more information.

Examples

let response = Response::empty_500();
assert_eq!(response.status(), http::StatusCode::INTERNAL_SERVER_ERROR);

pub fn see_other<T>(location: T) -> Result<Self, Error>where
    HeaderValue: TryFrom<T>,
    <HeaderValue as TryFrom<T>>::Error: Into<Error>,

Creates a redirect (using See Other) to the given location.

Errors

This attempts to convert the location into a http::HeaderValue; however, the conversion may fail (for reasons specified on http::HeaderValue::from_str). It may also fail to construct the underlying response.

Examples

let response = Response::see_other("/foo").unwrap();
assert_eq!(response.status(), http::StatusCode::SEE_OTHER);

pub fn permanent_redirect<T>(location: T) -> Result<Self, Error>where
    HeaderValue: TryFrom<T>,
    <HeaderValue as TryFrom<T>>::Error: Into<Error>,

Creates a permanent redirect to the given location.

Errors

This attempts to convert the location into a http::HeaderValue; however, the conversion may fail (for reasons specified on http::HeaderValue::from_str). It may also fail to construct the underlying response.

Examples

let response = Response::permanent_redirect("/foo").unwrap();
assert_eq!(response.status(), http::StatusCode::PERMANENT_REDIRECT);

pub fn temporary_redirect<T>(location: T) -> Result<Self, Error>where
    HeaderValue: TryFrom<T>,
    <HeaderValue as TryFrom<T>>::Error: Into<Error>,

Creates a temporary redirect to the given location.

Errors

This attempts to convert the location into a http::HeaderValue; however, the conversion may fail (for reasons specified on http::HeaderValue::from_str). It may also fail to construct the underlying response.

Examples

let response = Response::temporary_redirect("/foo").unwrap();
assert_eq!(response.status(), http::StatusCode::TEMPORARY_REDIRECT);

pub fn empty_status(status: StatusCode) -> Self

Creates a response with an empty body and a set status. The Content-Type is not set.

Examples

let response = Response::empty_status(http::StatusCode::NOT_FOUND);
assert_eq!(response.status(), http::StatusCode::NOT_FOUND);

pub fn text<V: Into<String>>(body: V) -> Self

Creates a response with the given text body. The returned response has a Content-Type of text/plain; charset=utf-8.

Examples

let response = Response::text("hello, world");

pub fn json<V: Serialize>(body: &V) -> Result<Self, Error>

Creates a response with the given JSON body. The returned response has a Content-Type of application/json; charset=utf-8.

Errors

This errors if the underlying JSON serialization fails; and it will return that exact error.

Examples

let response = Response::json(&serde_json::json!({ "hello": "world" }))?;

pub fn set_status<S: Into<StatusCode>>(&mut self, status: S)

Sets the current responses’s status code.

Examples

let mut response = Response::empty_404();
response.set_status(http::StatusCode::OK);
assert_eq!(response.status(), http::StatusCode::OK);

pub fn with_status<S: Into<StatusCode>>(self, status: S) -> Self

Returns a response with the new status code.

Examples

let response = Response::empty_404();
let response = response.with_status(http::StatusCode::OK);
assert_eq!(response.status(), http::StatusCode::OK);

pub fn state<T: Send + Sync + 'static>(&self) -> Option<&T>

Returns state information provided by the crate::middleware::StateMiddleware middleware. This is a shortcut to retrieving the crate::middleware::State extension from the response.

Examples

use under::middleware::State;
let mut response = Response::empty_200();
response.extensions_mut().insert(State(123u32));
assert_eq!(response.state::<u32>(), Some(&123u32));

pub fn ext<T: Send + Sync + 'static>(&self) -> Option<&T>

Retrieves a specific extension from the extensions map. This is the same as calling Self::extensions.get wit the given type parameter.

Examples

let mut response = Response::empty_200();
assert_eq!(response.ext::<u32>(), None);

pub fn ext_mut<T: Send + Sync + 'static>(&mut self) -> Option<&mut T>

Retrieves a mutable reference to the specific extension from the extensions map. This is the same as calling Self::extensions_mut.get_mut with the given type parameter.

Examples

let mut response = Response::empty_200();
assert_eq!(response.ext_mut::<u32>(), None);

pub fn set_ext<T: Send + Sync + 'static>(&mut self, value: T) -> &mut Self

Sets the value of the specific extension in the extensions map. This is the same as calling Self::extensions_mut.insert with the given parameter.

Examples

let mut response = Response::empty_200();
response.set_ext(123u32);
assert_eq!(response.ext::<u32>(), Some(&123u32));

pub fn with_ext<T: Send + Sync + 'static>(self, value: T) -> Self

Sets the value of the specific extension in the extensions map, consuming self, and then returning the new value. This is the same as calling Self::set_ext, but it consumes self.

Examples

let response = Response::empty_200();
let response = response.with_ext(123u32);
assert_eq!(response.ext::<u32>(), Some(&123u32));

pub fn remove_ext<T: Send + Sync + 'static>(&mut self) -> Option<T>

Removes the specific extension from the extensions map. This is the same as calling Self::extensions_mut.remove with the given type parameter.

Examples

let mut response = Response::empty_200()
    .with_ext(123u32);
assert_eq!(response.ext::<u32>(), Some(&123u32));
response.remove_ext::<u32>();
assert_eq!(response.ext::<u32>(), None);

pub fn without_ext<T: Send + Sync + 'static>(self) -> Self

Removes the specific extension from the extensions map, consuming self, and then returning the removed value. This is the same as calling Self::remove_ext, but it consumes self.

Examples

let response = Response::empty_200()
    .with_ext(123u32);
assert_eq!(response.ext::<u32>(), Some(&123u32));
let response = response.without_ext::<u32>();
assert_eq!(response.ext::<u32>(), None);

pub fn status(&self) -> StatusCode

Returns the http::StatusCode.

Examples

let response = Response::default();
assert_eq!(response.status(), http::StatusCode::OK);

pub fn extensions(&self) -> &Extensions

Returns a reference to the associated extensions.

Examples

let response = Response::default();
assert!(response.extensions().get::<i32>().is_none());

pub fn extensions_mut(&mut self) -> &mut Extensions

Returns a mutable reference to the associated extensions.

Examples

let mut response = Response::default();
response.extensions_mut().insert("hello");
assert_eq!(response.extensions().get(), Some(&"hello"));

pub fn headers(&self) -> &HeaderMap<HeaderValue>

Returns a reference to the associated header field map.

Examples

let response = Response::default();
assert!(response.headers().is_empty());

pub fn headers_mut(&mut self) -> &mut HeaderMap<HeaderValue>

Returns a mutable reference to the associated header field map.

Examples

let mut response = Response::default();
response.headers_mut().insert(HOST, HeaderValue::from_static("world"));
assert!(!response.headers().is_empty());

Trait Implementations

impl CookieExt for Response

fn cookies(&self) -> Option<&CookieJar>

Returns the extracted cookie jar. If no cookie jar had been extracted (i.e., the CookieMiddleware was not used), then this will return None.

fn cookies_mut(&mut self) -> &mut CookieJar

Returns the mutable cookie jar. If no cookie jar had been extracted (i.e. the CookieMiddleware was not used), then this will return an empty cookie jar.

fn with_cookies(self, jar: CookieJar) -> Self

Returns self with the given cookie jar. This replaces (and drops) the current cookie jar, if one exists.

fn cookie(&self, name: &str) -> Option<&str>

Returns the value for the cookie with the given name. If no cookie jar is set, it returns None; if no cookie with the given name exists, it returns None; otherwise, it returns its value.

fn add_cookie(&mut self, cookie: Cookie<'static>)

Adds the given cookie to the current cookie jar. This addition does add to the delta, and creates the cookie jar if it does not exist.

fn with_cookie(self, cookie: Cookie<'static>) -> Self

Adds the given cookie to the cookie jar. This is essentially the same as Self::add_cookie.

impl Debug for Response

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

Formats the value using the given formatter.

impl Default for Response

fn default() -> Self

Returns the “default value” for a type.

impl From<Response<Body>> for Response

fn from(hy: Response<Body>) -> Self

Converts to this type from the input type.

impl From<Response> for Response<Body>

fn from(this: Response) -> Self

Converts to this type from the input type.

impl HttpEntity for Response

fn body_mut(&mut self) -> &mut Body

Returns a mutable reference to the body of the request. This is used for all other methods in HasBody.

fn headers(&self) -> &HeaderMap<HeaderValue>

Returns a reference to the associated header field map.

fn headers_mut(&mut self) -> &mut HeaderMap<HeaderValue>

Returns a mutable reference to the associated header field map.

fn set_body<I: Into<Body>>(&mut self, body: I) -> &mut Self

Sets the body of the request to the given body. This causes the previous body to be dropped in place.

fn with_body<I: Into<Body>>(self, body: I) -> Self

Sets the body of the request to the given body, consuming self. This causes the previous body to be dropped in place.

fn take_body(&mut self) -> Body

Takes the body from this request, and replaces it with an empty body. The previous body is replaced with an empty body; thus, attempting to read the body more than once will cause successive attempts to fail.

fn set_json<V: Serialize>(&mut self, new_body: &V) -> Result<&mut Self, Error>

Available on crate feature json only.

Replaces the contents of the body with the given JSON body. Note that this does not update the Content-Type; the caller is responsible for that.

fn with_json<V: Serialize>(self, new_body: &V) -> Result<Self, Error>

Available on crate feature json only.

Replaces the contents of the body with the given JSON body, consuming self. Note that this does not update the Content-Type; the caller is responsible for that.

fn data(&mut self, limit: u64) -> DataStream

Creates a data stream of the body. This consumes the body, and produces a stream that can then be read from. A limit must be provided, which is the maximum number of bytes that can be read from the stream. For most operations, exceeding this limit will cause an error.

fn header<H: AsHeaderName>(&self, key: H) -> Option<&HeaderValue>

Retrieves the given header specified here.

fn header_all<H: AsHeaderName>(&self, key: H) -> GetAll<'_, HeaderValue>

Retrieves all potential values for the given header specified here.

fn set_header<H, V>(&mut self, key: H, value: V) -> Result<(), Error>where
    H: IntoHeaderName,
    V: TryInto<HeaderValue>,
    Error: From<<V as TryInto<HeaderValue>>::Error>,

Sets the given header to the given value. If there already was a header, it is replaced with the given value.

fn with_header<H, V>(self, key: H, value: V) -> Result<Self, Error>where
    H: IntoHeaderName,
    V: TryInto<HeaderValue>,
    Error: From<<V as TryInto<HeaderValue>>::Error>,

Sets the given header, consuming self and returning a new version with the given header. This can be useful for builder patterns. Otherwise, this acts the same as Self::set_header.

fn add_header<H, V>(&mut self, key: H, value: V) -> Result<(), Error>where
    H: IntoHeaderName,
    V: TryInto<HeaderValue>,
    Error: From<<V as TryInto<HeaderValue>>::Error>,

Sets the given header to the given value. If there already was a header, it is appended with the given value.

fn with_add_header<H, V>(self, key: H, value: V) -> Result<Self, Error>where
    H: IntoHeaderName,
    V: TryInto<HeaderValue>,
    Error: From<<V as TryInto<HeaderValue>>::Error>,

Sets the given header, consuming self and returning a new version with the given header. This can be useful for builder patterns. Otherwise, this acts the same as Self::add_header.

fn content_type(&self) -> Option<Mime>

Retrieves the content type of the body. This is normally pulled from the Content-Type header of the request, and parsed into a mime; if the header does not exist, or is not a proper mime type, this will return None.

fn as_sniff<'life0, 'async_trait, T>(
    &'life0 mut self,
    limit: u64
) -> Pin<Box<dyn Future<Output = Result<T, UnderError>> + Send + 'async_trait>>where
    T: 'async_trait + DeserializeOwned,
    Self: Send + 'async_trait,
    'life0: 'async_trait,

Available on crate feature serde only.

Attempts to parse the body based off of the content-type header; currently, it can sniff any activated serde features (e.g. json, cbor, msgpack). If the content-type is one of those, it forwards the call to the respective functions (DataStream::into_json, [DataStream::into_cbor], [DataStream::into_msgpack]), thereby consuming the body. If it cannot find the content type, or the content type is not one of those, it will return an error.

fn as_sniff_form<'life0, 'async_trait, T>(
    &'life0 mut self,
    limit: u64
) -> Pin<Box<dyn Future<Output = Result<T, UnderError>> + Send + 'async_trait>>where
    T: 'async_trait + DeserializeOwned + FromForm,
    Self: Send + 'async_trait,
    'life0: 'async_trait,

Attempts to parse the body based off of the content type header; currently, it can sniff any activated serde features (e.g. json, cbor, msgpack), or x-www-form-urlencoded. If the content-type is one of those, it forwards the call to the respective functions (DataStream::into_json, [DataStream::into_cbor], [DataStream::into_msgpack], DataStream::into_form), thereby consuming the body. If it cannot find the content type, or the content type is not one of those, it will return an error.

impl IntoResponse for Response

fn into_response(self) -> Result<Response, Error>

Converts the current type into a response.