Struct Client

pub struct Client { /* private fields */ }

A structure to construct requests for local dispatching.

Usage

A Client is constructed via the new() or untracked() methods from an already constructed Rocket instance. Once a value of Client has been constructed, the LocalRequest constructor methods (get(), put(), post(), and so on) can be used to create a LocalRequest for dispatching.

See the top-level documentation for more usage information.

Cookie Tracking

A Client constructed using new() propagates cookie changes made by responses to previously dispatched requests. In other words, if a previously dispatched request resulted in a response that adds a cookie, any future requests will contain that cookie. Similarly, cookies removed by a response won’t be propagated further.

This is typically the desired mode of operation for a Client as it removes the burden of manually tracking cookies. Under some circumstances, however, disabling this tracking may be desired. In these cases, use the untracked() constructor to create a Client that will not track cookies.

Synchronization

While Client implements Sync, using it in a multithreaded environment while tracking cookies can result in surprising, non-deterministic behavior. This is because while cookie modifications are serialized, the exact ordering depends on when requests are dispatched. Specifically, when cookie tracking is enabled, all request dispatches are serialized, which in-turn serializes modifications to the internally tracked cookies.

If possible, refrain from sharing a single instance of Client across multiple threads. Instead, prefer to create a unique instance of Client per thread. If it’s not possible, ensure that either you are not depending on cookies, the ordering of their modifications, or both, or have arranged for dispatches to occur in a deterministic ordering.

Example

The following snippet creates a Client from a Rocket instance and dispatches a local request to POST / with a body of Hello, world!.

use rocket::local::Client;

let rocket = rocket::ignite();
let client = Client::new(rocket).expect("valid rocket");
let response = client.post("/")
    .body("Hello, world!")
    .dispatch();

Implementations

impl Client

pub fn new(rocket: Rocket) -> Result<Client, LaunchError>

Construct a new Client from an instance of Rocket with cookie tracking.

Cookie Tracking

By default, a Client propagates cookie changes made by responses to previously dispatched requests. In other words, if a previously dispatched request resulted in a response that adds a cookie, any future requests will contain the new cookies. Similarly, cookies removed by a response won’t be propagated further.

This is typically the desired mode of operation for a Client as it removes the burden of manually tracking cookies. Under some circumstances, however, disabling this tracking may be desired. The untracked() method creates a Client that will not track cookies.

Errors

If launching the Rocket instance would fail, excepting network errors, the LaunchError is returned.

Example

use rocket::local::Client;

let client = Client::new(rocket::ignite()).expect("valid rocket");

pub fn untracked(rocket: Rocket) -> Result<Client, LaunchError>

Construct a new Client from an instance of Rocket without cookie tracking.

Cookie Tracking

Unlike the new() constructor, a Client returned from this method does not automatically propagate cookie changes.

Errors

If launching the Rocket instance would fail, excepting network errors, the LaunchError is returned.

Example

use rocket::local::Client;

let client = Client::untracked(rocket::ignite()).expect("valid rocket");

pub fn rocket(&self) -> &Rocket

Returns the instance of Rocket this client is creating requests for.

Example

use rocket::local::Client;

let my_rocket = rocket::ignite();
let client = Client::new(my_rocket).expect("valid rocket");

// get the instance of `my_rocket` within `client`
let my_rocket = client.rocket();

pub fn get<'c, 'u: 'c, U: Into<Cow<'u, str>>>( &'c self, uri: U, ) -> LocalRequest<'c>

Create a local GET request to the URI uri.

When dispatched, the request will be served by the instance of Rocket within self. The request is not dispatched automatically. To actually dispatch the request, call LocalRequest::dispatch() on the returned request.

Example

use rocket::local::Client;

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

pub fn put<'c, 'u: 'c, U: Into<Cow<'u, str>>>( &'c self, uri: U, ) -> LocalRequest<'c>

Create a local PUT request to the URI uri.

When dispatched, the request will be served by the instance of Rocket within self. The request is not dispatched automatically. To actually dispatch the request, call LocalRequest::dispatch() on the returned request.

Example

use rocket::local::Client;

let client = Client::new(rocket::ignite()).expect("valid rocket");
let req = client.put("/hello");

pub fn post<'c, 'u: 'c, U: Into<Cow<'u, str>>>( &'c self, uri: U, ) -> LocalRequest<'c>

Create a local POST request to the URI uri.

When dispatched, the request will be served by the instance of Rocket within self. The request is not dispatched automatically. To actually dispatch the request, call LocalRequest::dispatch() on the returned request.

Example

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

let client = Client::new(rocket::ignite()).expect("valid rocket");

let req = client.post("/hello")
    .body("field=value&otherField=123")
    .header(ContentType::Form);

pub fn delete<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c>

where U: Into<Cow<'u, str>>,

Create a local DELETE request to the URI uri.

When dispatched, the request will be served by the instance of Rocket within self. The request is not dispatched automatically. To actually dispatch the request, call LocalRequest::dispatch() on the returned request.

Example

use rocket::local::Client;

let client = Client::new(rocket::ignite()).expect("valid rocket");
let req = client.delete("/hello");

pub fn options<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c>

where U: Into<Cow<'u, str>>,

Create a local OPTIONS request to the URI uri.

When dispatched, the request will be served by the instance of Rocket within self. The request is not dispatched automatically. To actually dispatch the request, call LocalRequest::dispatch() on the returned request.

Example

use rocket::local::Client;

let client = Client::new(rocket::ignite()).expect("valid rocket");
let req = client.options("/hello");

pub fn head<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c>

where U: Into<Cow<'u, str>>,

Create a local HEAD request to the URI uri.

When dispatched, the request will be served by the instance of Rocket within self. The request is not dispatched automatically. To actually dispatch the request, call LocalRequest::dispatch() on the returned request.

Example

use rocket::local::Client;

let client = Client::new(rocket::ignite()).expect("valid rocket");
let req = client.head("/hello");

pub fn patch<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c>

where U: Into<Cow<'u, str>>,

Create a local PATCH request to the URI uri.

When dispatched, the request will be served by the instance of Rocket within self. The request is not dispatched automatically. To actually dispatch the request, call LocalRequest::dispatch() on the returned request.

Example

use rocket::local::Client;

let client = Client::new(rocket::ignite()).expect("valid rocket");
let req = client.patch("/hello");

pub fn req<'c, 'u: 'c, U>(&'c self, method: Method, uri: U) -> LocalRequest<'c>

where U: Into<Cow<'u, str>>,

Create a local request with method method to the URI uri.

When dispatched, the request will be served by the instance of Rocket within self. The request is not dispatched automatically. To actually dispatch the request, call LocalRequest::dispatch() on the returned request.

Example

use rocket::local::Client;
use rocket::http::Method;

let client = Client::new(rocket::ignite()).expect("valid rocket");
let req = client.req(Method::Get, "/hello");