Struct LocalRequest

pub struct LocalRequest<'c> { /* private fields */ }

A structure representing a local request as created by Client.

Usage

A LocalRequest value is constructed via method constructors on Client. Headers can be added via the header builder method and the add_header method. Cookies can be added via the cookie builder method. The remote IP address can be set via the remote builder method. The body of the request can be set via the body builder method or set_body method.

Example

The following snippet uses the available builder methods to construct a POST request to / with a JSON body:

use rocket::local::Client;
use rocket::http::{ContentType, Cookie};

let client = Client::new(rocket::ignite()).expect("valid rocket");
let req = client.post("/")
    .header(ContentType::JSON)
    .remote("127.0.0.1:8000".parse().unwrap())
    .cookie(Cookie::new("name", "value"))
    .body(r#"{ "value": 42 }"#);

Dispatching

A LocalRequest can be dispatched in one of two ways:

1. dispatch

   This method should always be preferred. The LocalRequest is consumed and a response is returned.

2. mut_dispatch

   This method should only be used when either it is known that the application will not modify the request, or it is desired to see modifications to the request. No cloning occurs, and the request is not consumed.

Additionally, note that LocalRequest implements Clone. As such, if the same request needs to be dispatched multiple times, the request can first be cloned and then dispatched: request.clone().dispatch().

Implementations

impl<'c> LocalRequest<'c>

pub fn inner(&self) -> &Request<'c>

Retrieves the inner Request as seen by Rocket.

Example

use rocket::local::Client;

let client = Client::new(rocket::ignite()).expect("valid rocket");
let req = client.get("/");
let inner_req = req.inner();

pub fn header<H: Into<Header<'static>>>(self, header: H) -> Self

Add a header to this request.

Any type that implements Into<Header> can be used here. Among others, this includes ContentType and Accept.

Examples

Add the Content-Type header:

use rocket::local::Client;
use rocket::http::ContentType;

let client = Client::new(rocket::ignite()).unwrap();
let req = client.get("/").header(ContentType::JSON);

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

Adds a header to this request without consuming self.

Examples

Add the Content-Type header:

use rocket::local::Client;
use rocket::http::ContentType;

let client = Client::new(rocket::ignite()).unwrap();
let mut req = client.get("/");
req.add_header(ContentType::JSON);

pub fn remote(self, address: SocketAddr) -> Self

Set the remote address of this request.

Examples

Set the remote address to “8.8.8.8:80”:

use rocket::local::Client;

let client = Client::new(rocket::ignite()).unwrap();
let address = "8.8.8.8:80".parse().unwrap();
let req = client.get("/").remote(address);

pub fn cookie(self, cookie: Cookie<'_>) -> Self

Add a cookie to this request.

Examples

Add user_id cookie:

use rocket::local::Client;
use rocket::http::Cookie;

let client = Client::new(rocket::ignite()).unwrap();
let req = client.get("/")
    .cookie(Cookie::new("username", "sb"))
    .cookie(Cookie::new("user_id", "12"));

pub fn cookies(self, cookies: Vec<Cookie<'_>>) -> Self

Add all of the cookies in cookies to this request.

Examples

Add user_id cookie:

use rocket::local::Client;
use rocket::http::Cookie;

let client = Client::new(rocket::ignite()).unwrap();
let cookies = vec![Cookie::new("a", "b"), Cookie::new("c", "d")];
let req = client.get("/").cookies(cookies);

pub fn private_cookie(self, cookie: Cookie<'static>) -> Self

Add a private cookie to this request.

This method is only available when the private-cookies feature is enabled.

Examples

Add user_id as a private cookie:

use rocket::local::Client;
use rocket::http::Cookie;

let client = Client::new(rocket::ignite()).unwrap();
let req = client.get("/").private_cookie(Cookie::new("user_id", "sb"));

pub fn body<S: AsRef<[u8]>>(self, body: S) -> Self

Set the body (data) of the request.

Examples

Set the body to be a JSON structure; also sets the Content-Type.

use rocket::local::Client;
use rocket::http::ContentType;

let client = Client::new(rocket::ignite()).unwrap();
let req = client.post("/")
    .header(ContentType::JSON)
    .body(r#"{ "key": "value", "array": [1, 2, 3], }"#);

pub fn set_body<S: AsRef<[u8]>>(&mut self, body: S)

Set the body (data) of the request without consuming self.

Examples

Set the body to be a JSON structure; also sets the Content-Type.

use rocket::local::Client;
use rocket::http::ContentType;

let client = Client::new(rocket::ignite()).unwrap();
let mut req = client.post("/").header(ContentType::JSON);
req.set_body(r#"{ "key": "value", "array": [1, 2, 3], }"#);

pub fn dispatch(self) -> LocalResponse<'c>

Dispatches the request, returning the response.

This method consumes self and is the preferred mechanism for dispatching.

Example

use rocket::local::Client;

let client = Client::new(rocket::ignite()).unwrap();
let response = client.get("/").dispatch();

pub fn mut_dispatch(&mut self) -> LocalResponse<'c>

Dispatches the request, returning the response.

This method does not consume or clone self. Any changes to the request that occur during handling will be visible after this method is called. For instance, body data is always consumed after a request is dispatched. As such, only the first call to mut_dispatch for a given LocalRequest will contains the original body data.

This method should only be used when either it is known that the application will not modify the request, or it is desired to see modifications to the request. Prefer to use dispatch instead.

Example

use rocket::local::Client;

let client = Client::new(rocket::ignite()).unwrap();

let mut req = client.get("/");
let response_a = req.mut_dispatch();
let response_b = req.mut_dispatch();

Trait Implementations

impl<'c> Clone for LocalRequest<'c>

fn clone(&self) -> LocalRequest<'c>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'c> Debug for LocalRequest<'c>

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

Formats the value using the given formatter.