Struct rocket::Request

pub struct Request<'r> { /* fields omitted */ }

The type of an incoming web request.

This should be used sparingly in Rocket applications. In particular, it should likely only be used when writing FromRequest implementations. It contains all of the information for a given web request except for the body data. This includes the HTTP method, URI, cookies, headers, and more.

Methods

impl<'r> Request<'r>

fn method(&self) -> Method

Retrieve the method from self.

Example

use rocket::http::Method;

request.set_method(Method::Get);
assert_eq!(request.method(), Method::Get);

fn set_method(&mut self, method: Method)

Set the method of self.

Example

use rocket::http::Method;

assert_eq!(request.method(), Method::Get);

request.set_method(Method::Post);
assert_eq!(request.method(), Method::Post);

fn uri(&self) -> &URI

Borrow the URI from self, which is guaranteed to be an absolute URI.

Example

assert_eq!(request.uri().as_str(), "/uri");

fn set_uri<'u: 'r, U: Into<URI<'u>>>(&mut self, uri: U)

Set the URI in self. The uri parameter can be of any type that implements Into<URI> including &str and String; it must be a valid, absolute URI.

Example

request.set_uri("/hello/Sergio?type=greeting");
assert_eq!(request.uri().as_str(), "/hello/Sergio?type=greeting");

fn remote(&self) -> Option<SocketAddr>

Returns the address of the remote connection that initiated this request if the address is known. If the address is not known, None is returned.

Example

assert!(request.remote().is_none());

fn set_remote(&mut self, address: SocketAddr)

Sets the remote address of self to address.

Example

Set the remote address to be 127.0.0.1:8000:

use std::net::{SocketAddr, IpAddr, Ipv4Addr};

let (ip, port) = (IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8000);
let localhost = SocketAddr::new(ip, port);
request.set_remote(localhost);

assert_eq!(request.remote(), Some(localhost));

fn headers(&self) -> &HeaderMap<'r>

Returns a HeaderMap of all of the headers in self.

Example

let header_map = request.headers();
assert!(header_map.is_empty());

fn add_header<'h: 'r, H: Into<Header<'h>>>(&mut self, header: H)

Add header to self's headers. The type of header can be any type that implements the Into<Header> trait. This includes common types such as ContentType and Accept.

Example

use rocket::http::ContentType;

assert!(request.headers().is_empty());

request.add_header(ContentType::HTML);
assert!(request.headers().contains("Content-Type"));
assert_eq!(request.headers().len(), 1);

fn replace_header<'h: 'r, H: Into<Header<'h>>>(&mut self, header: H)

Replaces the value of the header with name header.name with header.value. If no such header exists, header is added as a header to self.

Example

use rocket::http::ContentType;

assert!(request.headers().is_empty());

request.add_header(ContentType::Any);
assert_eq!(request.headers().get_one("Content-Type"), Some("*/*"));

request.replace_header(ContentType::PNG);
assert_eq!(request.headers().get_one("Content-Type"), Some("image/png"));

fn cookies(&self) -> Cookies

Returns a wrapped borrow to the cookies in self.

Cookies implements internal mutability, so this method allows you to get and add/remove cookies in self.

Example

Add a new cookie to a request's cookies:

use rocket::http::Cookie;

request.cookies().add(Cookie::new("key", "val"));
request.cookies().add(Cookie::new("ans", format!("life: {}", 38 + 4)));

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

Returns the Content-Type header of self. If the header is not present, returns None. The Content-Type header is cached after the first call to this function. As a result, subsequent calls will always return the same value.

Example

use rocket::http::ContentType;

request.add_header(ContentType::JSON);
assert_eq!(request.content_type(), Some(&ContentType::JSON));

// The header is cached; it cannot be replaced after first access.
request.replace_header(ContentType::HTML);
assert_eq!(request.content_type(), Some(&ContentType::JSON));

fn accept(&self) -> Option<&Accept>

Returns the Accept header of self. If the header is not present, returns None. The Accept header is cached after the first call to this function. As a result, subsequent calls will always return the same value.

Example

use rocket::http::Accept;

request.add_header(Accept::JSON);
assert_eq!(request.accept(), Some(&Accept::JSON));

// The header is cached; it cannot be replaced after first access.
request.replace_header(Accept::HTML);
assert_eq!(request.accept(), Some(&Accept::JSON));

fn format(&self) -> Option<&MediaType>

Returns the media type "format" of the request.

The "format" of a request is either the Content-Type, if the request methods indicates support for a payload, or the preferred media type in the Accept header otherwise. If the method indicates no payload and no Accept header is specified, a media type of Any is returned.

The media type returned from this method is used to match against the format route attribute.

Example

use rocket::http::{Method, Accept, ContentType, MediaType};

request.add_header(ContentType::JSON);
request.add_header(Accept::HTML);

request.set_method(Method::Get);
assert_eq!(request.format(), Some(&MediaType::HTML));

request.set_method(Method::Post);
assert_eq!(request.format(), Some(&MediaType::JSON));

fn limits(&self) -> &'r Limits

Returns the configured application receive limits.

Example

let json_limit = request.limits().get("json");

fn route(&self) -> Option<&'r Route>

Get the presently matched route, if any.

This method returns Some any time a handler or its guards are being invoked. This method returns None before routing has commenced; this includes during request fairing callbacks.

Example

let route = request.route();

fn guard<'a, T: FromRequest<'a, 'r>>(&'a self) -> Outcome<T, T::Error>

Invokes the request guard implemention for T, returning its outcome.

Example

Assuming a User request guard exists, invoke it:

let outcome = request.guard::<User>();

Retrieve managed state inside of a guard implementation:

use rocket::State;

let pool = request.guard::<State<Pool>>()?;

fn get_param<'a, T: FromParam<'a>>(&'a self, n: usize) -> Result<T, Error>

Retrieves and parses into T the 0-indexed nth dynamic parameter from the request. Returns Error::NoKey if n is greater than the number of params. Returns Error::BadParse if the parameter type T can't be parsed from the parameter.

This method exists only to be used by manual routing. To retrieve parameters from a request, use Rocket's code generation facilities.

Example

Retrieve parameter 0, which is expected to be a String, in a manual route:

use rocket::{Request, Data};
use rocket::handler::Outcome;

fn name<'a>(req: &'a Request, _: Data) -> Outcome<'a> {
    Outcome::from(req, req.get_param::<String>(0).unwrap_or("unnamed".into()))
}

fn get_segments<'a, T: FromSegments<'a>>(&'a self, n: usize) -> Result<T, Error>

Retrieves and parses into T all of the path segments in the request URI beginning at the 0-indexed nth dynamic parameter. T must implement FromSegments, which is used to parse the segments.

This method exists only to be used by manual routing. To retrieve segments from a request, use Rocket's code generation facilities.

Error

If there are less than n segments, returns an Err of NoKey. If parsing the segments failed, returns an Err of BadParse.

Example

If the request URI is "/hello/there/i/am/here", and the matched route path for this request is "/hello/<name>/i/<segs..>", then request.get_segments::<T>(1) will attempt to parse the segments "am/here" as type T.

Trait Implementations

impl<'r> Clone for Request<'r>

fn clone(&self) -> Request<'r>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'r> Debug for Request<'r>

fn fmt(&self, fmt: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'r> Display for Request<'r>

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

Pretty prints a Request. This is primarily used by Rocket's logging infrastructure.