Trait under::HttpEntity

source · 
pub trait HttpEntity: Sized {

Show 18 methods    fn body_mut(&mut self) -> &mut Body;
    fn headers(&self) -> &HeaderMap<HeaderValue>;
    fn headers_mut(&mut self) -> &mut HeaderMap<HeaderValue>;

    fn set_body<I: Into<Body>>(&mut self, body: I) -> &mut Self { ... }
    fn with_body<I: Into<Body>>(self, body: I) -> Self { ... }
    fn take_body(&mut self) -> Body { ... }
    fn set_json<V: Serialize>(
        &mut self,
        new_body: &V
    ) -> Result<&mut Self, Error> { ... }
    fn with_json<V: Serialize>(self, new_body: &V) -> Result<Self, Error> { ... }
    fn data(&mut self, limit: u64) -> DataStream { ... }
    fn header<H: AsHeaderName>(&self, key: H) -> Option<&HeaderValue> { ... }
    fn header_all<H: AsHeaderName>(&self, key: H) -> GetAll<'_, HeaderValue> { ... }
    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>,
    { ... }
    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>,
    { ... }
    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>,
    { ... }
    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>,
    { ... }
    fn content_type(&self) -> Option<Mime> { ... }
    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,
    { ... }
    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,
    { ... }

}
Expand description

A HTTP Entity.

This is either a request or a response. This represents common, shared functionality between the two, such as accessing headers and the body.

Required Methods§

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

Examples
let mut response = Response::text("hello");
let body = std::mem::replace(response.body_mut(), hyper::Body::empty());
let body = hyper::body::to_bytes(body).await?;
assert_eq!(&body[..], b"hello");

Returns a reference to the associated header field map.

Examples
let request = Request::get("/").unwrap();
assert!(request.headers().is_empty());

Returns a mutable reference to the associated header field map.

Examples
let mut request = Request::get("/").unwrap();
request.headers_mut().insert(HOST, HeaderValue::from_static("world"));
assert!(!request.headers().is_empty());

Provided Methods§

source

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.

Examples
let mut response = Response::default();
response.set_body("foo");
let body = hyper::body::to_bytes(response.take_body()).await?;
assert_eq!(&body[..], b"foo");
source

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.

Examples
let mut response = Response::default()
    .with_body("foo");
let body = hyper::body::to_bytes(response.take_body()).await?;
assert_eq!(&body[..], b"foo");
source

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.

Examples
let mut response = Response::default().with_body("foo");
let body = hyper::body::to_bytes(response.take_body()).await?;
assert_eq!(&body[..], b"foo");
let body = hyper::body::to_bytes(response.take_body()).await?;
assert_eq!(&body[..], b"");
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.

Errors

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

Examples
let mut response = Response::empty_404();
response.set_json(&serde_json::json!({ "error": 404 }))?;
assert_eq!(response.header(http::header::CONTENT_TYPE), None);
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.

Errors

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

Examples
let mut response = Response::empty_404();
let response = response.with_json(&serde_json::json!({ "error": 404 }))?;
assert_eq!(response.header(http::header::CONTENT_TYPE), None);

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.

Examples
let mut response = Response::text("hello, world");
let data = response.data(1_000_000)
    .into_text().await?;
assert_eq!(&data[..], "hello, world");
let mut response = Response::text("hello, world");
let data = response.data(1)
   .into_text().await;
assert!(data.is_err());

Retrieves the given header specified here.

Examples
let response = Response::text("hello, world");
let content_type = response.header("Content-Type").unwrap();
assert_eq!(content_type.as_bytes(), b"text/plain; charset=utf-8");

Retrieves all potential values for the given header specified here.

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

Errors

If the given value cannot be converted into a header value, this will return an error.

Examples
let mut response = Response::default();
response.set_header(LOCATION, "/").unwrap();
let location: Option<&[u8]> = response.header(LOCATION).map(|v| v.as_bytes());
assert_eq!(location, Some(b"/".as_ref()));

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.

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

Errors

If the given value cannot be converted into a header value, this will return an error.

Examples
let mut response = Response::default();
response.set_header(LOCATION, "/").unwrap();
response.add_header(LOCATION, "/hello").unwrap();
let location: Vec<&[u8]> = response.header_all(LOCATION)
    .into_iter()
    .map(|v| v.as_bytes())
    .collect::<Vec<_>>();
assert_eq!(location, vec![b"/".as_ref(), b"/hello".as_ref()]);

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.

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.

Examples
let mut request = Request::get("/").unwrap();
assert!(request.content_type().is_none());
let request = request.with_header(http::header::CONTENT_TYPE, "application/json")?;
let ctype = request.content_type();
assert_eq!(ctype.as_ref().map(|m| m.essence_str()), Some("application/json"));
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.

Examples
#[derive(Debug, serde::Deserialize, PartialEq, Eq)]
struct Form {
  hello: String,
}

let mut response = Response::text(r#"{"hello": "world"}"#);
response
 .set_header(http::header::CONTENT_TYPE, "application/json")?;
let body = response.as_sniff::<Form>(512).await?;
let expected = Form { hello: "world".to_string() };
assert_eq!(body, expected);

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.

This functions similarly to HttpEntity::as_sniff, but it also can parse x-www-form-urlencoded content types as well.

Implementors§