HttpEntity

under

Trait HttpEntity 

Source 
pub trait HttpEntity: Sized {

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

    // Provided methods
    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§

Source

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 HttpEntity.

§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");
Source

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

Returns a reference to the associated header field map. This is used for all other methods in HttpEntity.

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

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

Returns a mutable reference to the associated header field map. This is used for all other methods in HttpEntity.

§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"");
Source

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.

§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);
Source

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.

§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);
Source

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.

§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());
Source

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

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");
Source

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

Retrieves all potential values for the given header specified here.

Source

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.

§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()));
Source

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.

Source

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.

§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()]);
Source

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.

Source

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.

§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"));
Source

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.

§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);
Source

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,

Available on crate features serde and from_form 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), 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.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§