Struct Request 

pub struct Request<T = Body> { /* private fields */ }

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 rama_http_types::{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 rama_http_types::{Request, Response, Result, StatusCode};

fn respond_to(req: Request<()>) -> Result<Response<()>> {
    if req.uri().as_str() != "/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 rama_http_types::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 rama_http_types::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

impl Request<()>

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

pub fn builder_with_extensions(ext: Extensions) -> Builder

Same as Request::builder but with the given Extensions to start from.

pub fn get<T>(uri: T) -> Builder

where T: TryInto<Uri>, <T as TryInto<Uri>>::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();

pub fn put<T>(uri: T) -> Builder

where T: TryInto<Uri>, <T as TryInto<Uri>>::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();

pub fn post<T>(uri: T) -> Builder

where T: TryInto<Uri>, <T as TryInto<Uri>>::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();

pub fn delete<T>(uri: T) -> Builder

where T: TryInto<Uri>, <T as TryInto<Uri>>::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();

pub fn options<T>(uri: T) -> Builder

where T: TryInto<Uri>, <T as TryInto<Uri>>::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();

pub fn head<T>(uri: T) -> Builder

where T: TryInto<Uri>, <T as TryInto<Uri>>::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();

pub fn connect<T>(uri: T) -> Builder

where T: TryInto<Uri>, <T as TryInto<Uri>>::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();

pub fn patch<T>(uri: T) -> Builder

where T: TryInto<Uri>, <T as TryInto<Uri>>::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();

pub fn trace<T>(uri: T) -> Builder

where T: TryInto<Uri>, <T as TryInto<Uri>>::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();

pub fn query<T>(uri: T) -> Builder

where T: TryInto<Uri>, <T as TryInto<Uri>>::Error: Into<Error>,

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

QUERY (RFC 10008) is a safe, idempotent method whose request content defines the query; remember to set a Content-Type for the body.

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

Example

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

impl<T> Request<T>

pub fn new(body: T) -> Self

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

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

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

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

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

pub fn uri(&self) -> &Uri

Returns a reference to the associated URI.

Examples

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

pub fn request_uri(&self) -> Uri

Get the URI as complete as possible for this request.

Where uri returns the URI exactly as received (often origin-form /path for HTTP/1.1), this fills in the scheme and authority from the request’s effective protocol and authority (URI → TLS SNI → Forwarded → Host header) — a derivation callers can treat as a technical detail.

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().as_str(), "/hello");

pub fn version(&self) -> Version

Returns the associated version.

Examples

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

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

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

Returns a reference to the associated header field map.

Examples

let request: Request<()> = Request::default();
assert!(request.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 request: Request<()> = Request::default();
request.headers_mut().insert(HOST, HeaderValue::from_static("world"));
assert!(!request.headers().is_empty());

pub fn clone_parts(&self) -> Parts

Returned a cloned of the associated HTTP header.

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

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

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

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

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

pub fn with_extensions(self, extensions: Extensions) -> Self

pub fn set_extensions(&mut self, extensions: Extensions) -> &mut Self

Trait Implementations

impl<Body> AuthorityInputExt for Request<Body>

fn authority(&self) -> Option<HostWithOptPort>

The routing authority (host[:port]), or None if none is resolvable.

fn host(&self) -> Option<Host>

The authority Host, dropping any port.

fn host_as_domain(&self) -> Option<Domain>

The authority host as a Domain, or None if absent or not a domain (e.g. an IP literal).

fn port(&self) -> Option<u16>

The authority port, if one is set explicitly.

impl<B: StreamingBody> Body for Request<B>

type Data = <B as Body>::Data

Values yielded by the Body.

type Error = <B as Body>::Error

The error type this Body might generate.

fn poll_frame( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Result<Frame<Self::Data>, Self::Error>>>

Attempt to pull out the next frame of this stream.

fn is_end_stream(&self) -> bool

A hint that may return true when the end of stream has been reached.

fn size_hint(&self) -> SizeHint

A hint that returns the bounds on the remaining length of the stream.

impl<Body> BodyExtractExt for Request<Body>

where Body: StreamingBody<Data = Bytes, Error: Into<BoxError>> + Send + Sync + 'static,

async fn try_into_json<T: DeserializeOwned + Send + 'static>( self, ) -> Result<T, BoxError>

Try to deserialize the (contained) body as a JSON object.

async fn try_into_json_streaming<T: DeserializeOwned + Send + 'static>( self, ) -> Result<T, BoxError>

Try to deserialize the (contained) body as a JSON object, streaming bytes from the body directly into the JSON parser instead of buffering the whole body first.

async fn try_into_string(self) -> Result<String, BoxError>

Try to turn the (contained) body in an utf-8 string.

async fn try_capture_json( self, selectors: impl IntoIterator<Item = JsonPath> + Send, max_capture_bytes: usize, ) -> Result<Vec<OwnedCapturedValue>, BoxError>

Capture JSON values matching selectors while streaming over the body.

async fn try_into_json_with<T: DeserializeOwned + Send + 'static>( self, opts: CollectOptions, ) -> Result<T, CollectError>

Like try_into_json, but bounded by opts (a size cap and/or timeout).

async fn try_into_string_with( self, opts: CollectOptions, ) -> Result<String, CollectError>

Like try_into_string, but bounded by opts. See try_into_json_with for the error semantics.

impl<B> ClientIp for Request<B>

fn client_ip(&self) -> Option<IpAddr>

Best-effort client IP — see client_ip for the common resolution.

impl<T: Clone> Clone for Request<T>

fn clone(&self) -> Request<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.

impl<B> ExtensionsRef for Request<B>

fn extensions(&self) -> &Extensions

Get reference to the underlying Extensions store

impl<Body> HttpRequestParts for Request<Body>

fn method(&self) -> &Method

fn uri(&self) -> &Uri

fn version(&self) -> Version

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

impl<Body> HttpRequestPartsMut for Request<Body>

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

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

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

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

impl<Body> HttpVersionInputExt for Request<Body>

fn http_version(&self) -> Option<Version>

The HTTP version, or None for non-HTTP inputs.

impl<Body> Matcher<Request<Body>> for SocketAddressMatcher

fn matches(&self, _ext: Option<&Extensions>, req: &Request<Body>) -> bool

returns true on a match, false otherwise

fn or<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Provide an alternative matcher to match if the current one does not match.

fn and<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Add another condition to match on top of the current one.

fn not(self) -> impl Matcher<Input>

where Self: Sized,

Negate the current condition.

impl<Body> Matcher<Request<Body>> for IpNetMatcher

fn matches(&self, _ext: Option<&Extensions>, req: &Request<Body>) -> bool

returns true on a match, false otherwise

fn or<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Provide an alternative matcher to match if the current one does not match.

fn and<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Add another condition to match on top of the current one.

fn not(self) -> impl Matcher<Input>

where Self: Sized,

Negate the current condition.

impl<Body> Matcher<Request<Body>> for LoopbackMatcher

fn matches(&self, _ext: Option<&Extensions>, req: &Request<Body>) -> bool

returns true on a match, false otherwise

fn or<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Provide an alternative matcher to match if the current one does not match.

fn and<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Add another condition to match on top of the current one.

fn not(self) -> impl Matcher<Input>

where Self: Sized,

Negate the current condition.

impl<Body> Matcher<Request<Body>> for PortMatcher

fn matches(&self, _ext: Option<&Extensions>, req: &Request<Body>) -> bool

returns true on a match, false otherwise

fn or<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Provide an alternative matcher to match if the current one does not match.

fn and<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Add another condition to match on top of the current one.

fn not(self) -> impl Matcher<Input>

where Self: Sized,

Negate the current condition.

impl<Body> Matcher<Request<Body>> for PrivateIpNetMatcher

fn matches(&self, _ext: Option<&Extensions>, req: &Request<Body>) -> bool

returns true on a match, false otherwise

fn or<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Provide an alternative matcher to match if the current one does not match.

fn and<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Add another condition to match on top of the current one.

fn not(self) -> impl Matcher<Input>

where Self: Sized,

Negate the current condition.

impl<Body: 'static> Matcher<Request<Body>> for SocketMatcher<Request<Body>>

The composite SocketMatcher delegates to the leaf impls above (and any custom/nested matchers) through its public matches_input helper, so its All/Any/Custom/negation logic applies to an HTTP Request too.

fn matches(&self, ext: Option<&Extensions>, req: &Request<Body>) -> bool

returns true on a match, false otherwise

fn or<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Provide an alternative matcher to match if the current one does not match.

fn and<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Add another condition to match on top of the current one.

fn not(self) -> impl Matcher<Input>

where Self: Sized,

Negate the current condition.

impl<Body> Matcher<Request<Body>> for HttpProxyConnectMatcher

fn matches(&self, _ext: Option<&Extensions>, req: &Request<Body>) -> bool

returns true on a match, false otherwise

fn or<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Provide an alternative matcher to match if the current one does not match.

fn and<M>(self, other: M) -> impl Matcher<Input>

where Self: Sized, M: Matcher<Input>,

Add another condition to match on top of the current one.

fn not(self) -> impl Matcher<Input>

where Self: Sized,

Negate the current condition.

impl<Body> PathInputExt for Request<Body>

fn path_ref(&self) -> PathRef<'_>

The path to route against.

impl<Body> ProtocolInputExt for Request<Body>

fn protocol(&self) -> Option<&Protocol>

The application protocol, or None if it can’t be determined.

fn protocol_default_port(&self) -> Option<u16>

The default port of the resolved Protocol (e.g. 443 for HTTPS), or None if the protocol is unknown or portless.

impl<Body> TransportProtocolInputExt for Request<Body>

fn transport_protocol(&self) -> Option<TransportProtocol>

The transport protocol (TCP or UDP).

impl<Body> UriInputExt for Request<Body>

fn uri(&self) -> &Uri

The Uri this input carries.