pub struct Request<T> { /* private fields */ }
Expand description

Represents an HTTP request.

An HTTP request consists of a head and a potentially optional body. The body component is generic, enabling arbitrary types to represent the HTTP body. For example, the body could be Vec<u8>, a Stream of byte chunks, or a value that has been deserialized.

Examples

Creating a Request to send

use http::{Request, Response};

let mut request = Request::builder()
    .uri("https://www.rust-lang.org/")
    .header("User-Agent", "my-awesome-agent/1.0");

if needs_awesome_header() {
    request = request.header("Awesome", "yes");
}

let response = send(request.body(()).unwrap());

fn send(req: Request<()>) -> Response<()> {
    // ...
}

Inspecting a request to see what was sent.

use http::{Request, Response, StatusCode};

fn respond_to(req: Request<()>) -> http::Result<Response<()>> {
    if req.uri() != "/awesome-url" {
        return Response::builder()
            .status(StatusCode::NOT_FOUND)
            .body(())
    }

    let has_awesome_header = req.headers().contains_key("Awesome");
    let body = req.body();

    // ...
}

Deserialize a request of bytes via json:

use http::Request;
use serde::de;

fn deserialize<T>(req: Request<Vec<u8>>) -> serde_json::Result<Request<T>>
    where for<'de> T: de::Deserialize<'de>,
{
    let (parts, body) = req.into_parts();
    let body = serde_json::from_slice(&body)?;
    Ok(Request::from_parts(parts, body))
}

Or alternatively, serialize the body of a request to json

use http::Request;
use serde::ser;

fn serialize<T>(req: Request<T>) -> serde_json::Result<Request<Vec<u8>>>
    where T: ser::Serialize,
{
    let (parts, body) = req.into_parts();
    let body = serde_json::to_vec(&body)?;
    Ok(Request::from_parts(parts, body))
}

Implementations§

source§

impl Request<()>

source

pub fn builder() -> Builder

Creates a new builder-style object to manufacture a Request

This method returns an instance of Builder which can be used to create a Request.

Examples
let request = Request::builder()
    .method("GET")
    .uri("https://www.rust-lang.org/")
    .header("X-Custom-Foo", "Bar")
    .body(())
    .unwrap();
source

pub fn get<T>(uri: T) -> Builder
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Creates a new Builder initialized with a GET method and the given URI.

This method returns an instance of Builder which can be used to create a Request.

Example

let request = Request::get("https://www.rust-lang.org/")
    .body(())
    .unwrap();
source

pub fn put<T>(uri: T) -> Builder
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Creates a new Builder initialized with a PUT method and the given URI.

This method returns an instance of Builder which can be used to create a Request.

Example

let request = Request::put("https://www.rust-lang.org/")
    .body(())
    .unwrap();
source

pub fn post<T>(uri: T) -> Builder
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Creates a new Builder initialized with a POST method and the given URI.

This method returns an instance of Builder which can be used to create a Request.

Example

let request = Request::post("https://www.rust-lang.org/")
    .body(())
    .unwrap();
source

pub fn delete<T>(uri: T) -> Builder
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Creates a new Builder initialized with a DELETE method and the given URI.

This method returns an instance of Builder which can be used to create a Request.

Example

let request = Request::delete("https://www.rust-lang.org/")
    .body(())
    .unwrap();
source

pub fn options<T>(uri: T) -> Builder
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Creates a new Builder initialized with an OPTIONS method and the given URI.

This method returns an instance of Builder which can be used to create a Request.

Example

let request = Request::options("https://www.rust-lang.org/")
    .body(())
    .unwrap();
source

pub fn head<T>(uri: T) -> Builder
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Creates a new Builder initialized with a HEAD method and the given URI.

This method returns an instance of Builder which can be used to create a Request.

Example

let request = Request::head("https://www.rust-lang.org/")
    .body(())
    .unwrap();
source

pub fn connect<T>(uri: T) -> Builder
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Creates a new Builder initialized with a CONNECT method and the given URI.

This method returns an instance of Builder which can be used to create a Request.

Example

let request = Request::connect("https://www.rust-lang.org/")
    .body(())
    .unwrap();
source

pub fn patch<T>(uri: T) -> Builder
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Creates a new Builder initialized with a PATCH method and the given URI.

This method returns an instance of Builder which can be used to create a Request.

Example

let request = Request::patch("https://www.rust-lang.org/")
    .body(())
    .unwrap();
source

pub fn trace<T>(uri: T) -> Builder
where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Creates a new Builder initialized with a TRACE method and the given URI.

This method returns an instance of Builder which can be used to create a Request.

Example

let request = Request::trace("https://www.rust-lang.org/")
    .body(())
    .unwrap();
source§

impl<T> Request<T>

source

pub fn new(body: T) -> Request<T>

Creates a new blank Request with the body

The component parts of this request will be set to their default, e.g. the GET method, no headers, etc.

Examples
let request = Request::new("hello world");

assert_eq!(*request.method(), Method::GET);
assert_eq!(*request.body(), "hello world");
source

pub fn from_parts(parts: Parts, body: T) -> Request<T>

Creates a new Request with the given components parts and body.

Examples
let request = Request::new("hello world");
let (mut parts, body) = request.into_parts();
parts.method = Method::POST;

let request = Request::from_parts(parts, body);
source

pub fn method(&self) -> &Method

Returns a reference to the associated HTTP method.

Examples
let request: Request<()> = Request::default();
assert_eq!(*request.method(), Method::GET);
source

pub fn method_mut(&mut self) -> &mut Method

Returns a mutable reference to the associated HTTP method.

Examples
let mut request: Request<()> = Request::default();
*request.method_mut() = Method::PUT;
assert_eq!(*request.method(), Method::PUT);
source

pub fn uri(&self) -> &Uri

Returns a reference to the associated URI.

Examples
let request: Request<()> = Request::default();
assert_eq!(*request.uri(), *"/");
source

pub fn uri_mut(&mut self) -> &mut Uri

Returns a mutable reference to the associated URI.

Examples
let mut request: Request<()> = Request::default();
*request.uri_mut() = "/hello".parse().unwrap();
assert_eq!(*request.uri(), *"/hello");
source

pub fn version(&self) -> Version

Returns the associated version.

Examples
let request: Request<()> = Request::default();
assert_eq!(request.version(), Version::HTTP_11);
source

pub fn version_mut(&mut self) -> &mut Version

Returns a mutable reference to the associated version.

Examples
let mut request: Request<()> = Request::default();
*request.version_mut() = Version::HTTP_2;
assert_eq!(request.version(), Version::HTTP_2);
source

pub fn headers(&self) -> &HeaderMap

Returns a reference to the associated header field map.

Examples
let request: Request<()> = Request::default();
assert!(request.headers().is_empty());
source

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

Returns a mutable reference to the associated header field map.

Examples
let mut request: Request<()> = Request::default();
request.headers_mut().insert(HOST, HeaderValue::from_static("world"));
assert!(!request.headers().is_empty());
source

pub fn extensions(&self) -> &Extensions

Returns a reference to the associated extensions.

Examples
let request: Request<()> = Request::default();
assert!(request.extensions().get::<i32>().is_none());
source

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

Returns a mutable reference to the associated extensions.

Examples
let mut request: Request<()> = Request::default();
request.extensions_mut().insert("hello");
assert_eq!(request.extensions().get(), Some(&"hello"));
source

pub fn body(&self) -> &T

Returns a reference to the associated HTTP body.

Examples
let request: Request<String> = Request::default();
assert!(request.body().is_empty());
source

pub fn body_mut(&mut self) -> &mut T

Returns a mutable reference to the associated HTTP body.

Examples
let mut request: Request<String> = Request::default();
request.body_mut().push_str("hello world");
assert!(!request.body().is_empty());
source

pub fn into_body(self) -> T

Consumes the request, returning just the body.

Examples
let request = Request::new(10);
let body = request.into_body();
assert_eq!(body, 10);
source

pub fn into_parts(self) -> (Parts, T)

Consumes the request returning the head and body parts.

Examples
let request = Request::new(());
let (parts, body) = request.into_parts();
assert_eq!(parts.method, Method::GET);
source

pub fn map<F, U>(self, f: F) -> Request<U>
where F: FnOnce(T) -> U,

Consumes the request returning a new request with body mapped to the return type of the passed in function.

Examples
let request = Request::builder().body("some string").unwrap();
let mapped_request: Request<&[u8]> = request.map(|b| {
  assert_eq!(b, "some string");
  b.as_bytes()
});
assert_eq!(mapped_request.body(), &"some string".as_bytes());

Trait Implementations§

source§

impl<B> Body for Request<B>
where B: Body,

§

type Data = <B as Body>::Data

Values yielded by the Body.
§

type Error = <B as Body>::Error

The error type this Body might generate.
source§

fn poll_data( self: Pin<&mut Request<B>>, cx: &mut Context<'_> ) -> Poll<Option<Result<<Request<B> as Body>::Data, <Request<B> as Body>::Error>>>

Attempt to pull out the next data buffer of this stream.
source§

fn poll_trailers( self: Pin<&mut Request<B>>, cx: &mut Context<'_> ) -> Poll<Result<Option<HeaderMap>, <Request<B> as Body>::Error>>

Poll for an optional single HeaderMap of trailers. Read more
source§

fn is_end_stream(&self) -> bool

Returns true when the end of stream has been reached. Read more
source§

fn size_hint(&self) -> SizeHint

Returns the bounds on the remaining length of the stream. Read more
source§

fn map_data<F, B>(self, f: F) -> MapData<Self, F>
where Self: Sized, F: FnMut(Self::Data) -> B, B: Buf,

Maps this body’s data value to a different value.
source§

fn map_err<F, E>(self, f: F) -> MapErr<Self, F>
where Self: Sized, F: FnMut(Self::Error) -> E,

Maps this body’s error value to a different value.
source§

fn collect(self) -> Collect<Self>
where Self: Sized,

Turn this body into Collected body which will collect all the DATA frames and trailers.
source§

impl<T> Debug for Request<T>
where T: Debug,

source§

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

Formats the value using the given formatter. Read more
source§

impl<T> Default for Request<T>
where T: Default,

source§

fn default() -> Request<T>

Returns the “default value” for a type. Read more
§

impl IntoClientRequest for Request<()>

§

fn into_client_request(self) -> Result<Request<()>, Error>

Convert into a Request that can be used for a client connection.
§

impl TryParse for Request<()>

§

fn try_parse(buf: &[u8]) -> Result<Option<(usize, Request<()>)>, Error>

Return Ok(None) if incomplete, Err on syntax error.

Auto Trait Implementations§

§

impl<T> !RefUnwindSafe for Request<T>

§

impl<T> Send for Request<T>
where T: Send,

§

impl<T> Sync for Request<T>
where T: Sync,

§

impl<T> Unpin for Request<T>
where T: Unpin,

§

impl<T> !UnwindSafe for Request<T>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<'a, T, E> AsTaggedExplicit<'a, E> for T
where T: 'a,

§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

§

impl<'a, T, E> AsTaggedImplicit<'a, E> for T
where T: 'a,

§

fn implicit( self, class: Class, constructed: bool, tag: u32 ) -> TaggedParser<'a, Implicit, Self, E>

source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more