Struct rocket::local::LocalRequest

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

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 three ways:

1. dispatch

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

2. cloned_dispatch

   This method should be used when one LocalRequest will be dispatched many times. This method clones the request and dispatches the clone, so the request is not consumed and can be reused.

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

Methods

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<'static>) -> 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 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 cloned_dispatch(&self) -> LocalResponse<'c>

Dispatches the request, returning the response.

This method does not consume self. Instead, it clones self and dispatches the clone. As such, self can be reused.

Example

use rocket::local::Client;

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

let req = client.get("/");
let response_a = req.cloned_dispatch();
let response_b = req.cloned_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 or cloned_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> Debug for LocalRequest<'c>

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

Formats the value using the given formatter.