pub struct Client { /* private fields */ }
Expand description
An async
client to construct and dispatch local requests.
For details, see the top-level documentation.
For the blocking
version, see
blocking::Client
.
Multithreaded Tracking Synchronization Pitfalls
Unlike its blocking
variant, this async
Client
implements Sync
. However, 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 ordering
depends on the ordering of request dispatch.
If possible, refrain from sharing a single instance of a tracking Client
across multiple threads. Instead, prefer to create a unique instance of
Client
per thread. If this is not possible, ensure that you are not
depending on the ordering of cookie modifications or have arranged for
request dispatch to occur in a deterministic manner.
Alternatively, use an untracked client, which does not suffer from these pitfalls.
Example
The following snippet creates a Client
from a Rocket
instance and
dispatches a local POST /
request with a body of Hello, world!
.
use rocket::local::asynchronous::Client;
let rocket = rocket::build();
let client = Client::tracked(rocket).await.expect("valid rocket");
let response = client.post("/")
.body("Hello, world!")
.dispatch()
.await;
Implementations
sourceimpl Client
impl Client
sourcepub async fn tracked<P: Phase>(rocket: Rocket<P>) -> Result<Self, Error>
pub async fn tracked<P: Phase>(rocket: Rocket<P>) -> Result<Self, Error>
Construct a new Client
from an instance of Rocket
with cookie
tracking. This is typically the desired mode of operation for testing.
Cookie Tracking
With cookie tracking enabled, a Client
propagates cookie changes made
by responses to previously dispatched requests. In other words,
succeeding requests reflect changes (additions and removals) made by any
prior responses.
Cookie tracking requires synchronization between dispatches. As such, cookie tracking should not be enabled if a local client is being used to serve requests on multiple threads.
Errors
If launching the Rocket
instance would fail, excepting network errors,
the Error
is returned.
use rocket::local::asynchronous::Client;
let rocket = rocket::build();
let client = Client::tracked(rocket);
sourcepub async fn untracked<P: Phase>(rocket: Rocket<P>) -> Result<Self, Error>
pub async fn untracked<P: Phase>(rocket: Rocket<P>) -> Result<Self, Error>
Construct a new Client
from an instance of Rocket
without
cookie tracking.
Cookie Tracking
Unlike the tracked()
constructor, a Client
returned from this method does not automatically propagate cookie
changes and thus requires no synchronization between dispatches.
Errors
If launching the Rocket
instance would fail, excepting network
errors, the Error
is returned.
use rocket::local::asynchronous::Client;
let rocket = rocket::build();
let client = Client::untracked(rocket);
sourcepub async fn terminate(self) -> Rocket<Ignite>
pub async fn terminate(self) -> Rocket<Ignite>
Terminates Client
by initiating a graceful shutdown via
Shutdown::notify()
and running shutdown fairings.
This method must be called on a Client
if graceful shutdown is
required for testing as Drop
does not signal Shutdown
nor run
shutdown fairings. Returns the instance of Rocket
being managed by
this client after all shutdown fairings run to completion.
use rocket::local::asynchronous::Client;
let client: Client = client;
let rocket = client.terminate();
sourcepub async fn new<P: Phase>(rocket: Rocket<P>) -> Result<Self, Error>
👎 Deprecated since 0.5.0: choose between Client::untracked()
and Client::tracked()
pub async fn new<P: Phase>(rocket: Rocket<P>) -> Result<Self, Error>
choose between Client::untracked()
and Client::tracked()
Deprecated alias to Client::tracked()
.
sourcepub fn rocket(&self) -> &Rocket<Orbit>
pub fn rocket(&self) -> &Rocket<Orbit>
Returns a reference to the Rocket
this client is creating requests
for.
Example
use rocket::local::asynchronous::Client;
let client: &Client = client;
let rocket = client.rocket();
Returns a cookie jar containing all of the cookies this client is currently tracking.
If cookie tracking is disabled, the returned jar will always be empty. Otherwise, it will contains all of the cookies collected from responses to requests dispatched by this client that have not expired.
Example
use rocket::local::asynchronous::Client;
let client: &Client = client;
let cookie = client.cookies();
sourcepub fn get<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
pub fn get<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
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::asynchronous::Client;
let client: &Client = client;
let req = client.get("/hello");
sourcepub fn put<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
pub fn put<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
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::asynchronous::Client;
let client: &Client = client;
let req = client.put("/hello");
sourcepub fn post<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
pub fn post<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
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::asynchronous::Client;
let client: &Client = client;
let req = client.post("/hello");
sourcepub fn delete<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
pub fn delete<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
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::asynchronous::Client;
let client: &Client = client;
let req = client.delete("/hello");
sourcepub fn options<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
pub fn options<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
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::asynchronous::Client;
let client: &Client = client;
let req = client.options("/hello");
sourcepub fn head<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
pub fn head<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
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::asynchronous::Client;
let client: &Client = client;
let req = client.head("/hello");
sourcepub fn patch<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
pub fn patch<'c, 'u: 'c, U>(&'c self, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
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::asynchronous::Client;
let client: &Client = client;
let req = client.patch("/hello");
sourcepub fn req<'c, 'u: 'c, U>(&'c self, method: Method, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
pub fn req<'c, 'u: 'c, U>(&'c self, method: Method, uri: U) -> LocalRequest<'c> where
U: TryInto<Origin<'u>> + Display,
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::asynchronous::Client;
use rocket::http::Method;
let client: &Client = client;
client.req(Method::Get, "/hello");
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for Client
impl Send for Client
impl Sync for Client
impl Unpin for Client
impl !UnwindSafe for Client
Blanket Implementations
impl<'a, T> AsTaggedExplicit<'a> for T where
T: 'a,
impl<'a, T> AsTaggedExplicit<'a> for T where
T: 'a,
fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self>
impl<'a, T> AsTaggedImplicit<'a> for T where
T: 'a,
impl<'a, T> AsTaggedImplicit<'a> for T where
T: 'a,
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
impl<T> IntoCollection<T> for T
impl<T> IntoCollection<T> for T
fn into_collection<A>(self) -> SmallVec<A> where
A: Array<Item = 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>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more