[][src]Struct rocket::local::Client

pub struct Client { /* fields omitted */ }

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.

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

Methods

impl Client
[src]

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

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

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

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

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

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

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

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

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

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

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

Auto Trait Implementations

impl Send for Client

impl Sync for Client

Blanket Implementations

impl<T> From for T
[src]

impl<T, U> Into for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom for T where
    T: From<U>, 
[src]

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

impl<T> Borrow for T where
    T: ?Sized
[src]

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T, U> TryInto for T where
    U: TryFrom<T>, 
[src]

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

impl<T> BorrowMut for T where
    T: ?Sized
[src]

impl<T> Typeable for T where
    T: Any

Get the TypeId of this object.

impl<T> IntoCollection for T

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