Struct rocket::local::LocalRequest

source ·
pub struct LocalRequest<'c> { /* private fields */ }
Expand description

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§

source§

impl<'c> LocalRequest<'c>

source

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

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

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

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

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

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

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

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], }"#);
source

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], }"#);
source

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

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§

source§

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

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'c> Freeze for LocalRequest<'c>

§

impl<'c> !RefUnwindSafe for LocalRequest<'c>

§

impl<'c> !Send for LocalRequest<'c>

§

impl<'c> !Sync for LocalRequest<'c>

§

impl<'c> Unpin for LocalRequest<'c>

§

impl<'c> !UnwindSafe for LocalRequest<'c>

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
source§

impl<T, I> AsResult<T, I> for T
where I: Input,

source§

fn as_result(self) -> Result<T, ParseErr<I>>

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.

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.

§

impl<T> IntoCollection<T> for T

§

fn into_collection<A>(self) -> SmallVec<A>
where A: Array<Item = T>,

Converts self into a collection.
§

fn mapped<U, F, A>(self, f: F) -> SmallVec<A>
where F: FnMut(T) -> U, A: Array<Item = U>,

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
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.
source§

impl<T> Typeable for T
where T: Any,

source§

fn get_type(&self) -> TypeId

Get the TypeId of this object.
source§

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

source§

fn vzip(self) -> V