rocket/local/asynchronous/
client.rs

Help
1use std::fmt;
2
3use parking_lot::RwLock;
4
5use crate::{Rocket, Phase, Orbit, Ignite, Error};
6use crate::local::asynchronous::{LocalRequest, LocalResponse};
7use crate::http::{Method, uri::Origin};
8use crate::listener::Endpoint;
9
10/// An `async` client to construct and dispatch local requests.
11///
12/// For details, see [the top-level documentation](../index.html#client).
13/// For the `blocking` version, see
14/// [`blocking::Client`](crate::local::blocking::Client).
15///
16/// ## Multithreaded Tracking Synchronization Pitfalls
17///
18/// Unlike its [`blocking`](crate::local::blocking) variant, this `async`
19/// `Client` implements `Sync`. However, using it in a multithreaded environment
20/// while tracking cookies can result in surprising, non-deterministic behavior.
21/// This is because while cookie modifications are serialized, the ordering
22/// depends on the ordering of request dispatch.
23///
24/// If possible, refrain from sharing a single instance of a tracking `Client`
25/// across multiple threads. Instead, prefer to create a unique instance of
26/// `Client` per thread. If this is not possible, ensure that you are not
27/// depending on the ordering of cookie modifications or have arranged for
28/// request dispatch to occur in a deterministic manner.
29///
30/// Alternatively, use an untracked client, which does not suffer from these
31/// pitfalls.
32///
33/// ## Example
34///
35/// The following snippet creates a `Client` from a `Rocket` instance and
36/// dispatches a local `POST /` request with a body of `Hello, world!`.
37///
38/// ```rust,no_run
39/// use rocket::local::asynchronous::Client;
40///
41/// # rocket::async_test(async {
42/// let rocket = rocket::build();
43/// let client = Client::tracked(rocket).await.expect("valid rocket");
44/// let response = client.post("/")
45///     .body("Hello, world!")
46///     .dispatch()
47///     .await;
48/// # });
49/// ```
50pub struct Client {
51    rocket: Rocket<Orbit>,
52    cookies: RwLock<cookie::CookieJar>,
53    pub(in super) tracked: bool,
54}
55
56impl Client {
57    pub(crate) async fn _new<P: Phase>(
58        rocket: Rocket<P>,
59        tracked: bool,
60        secure: bool,
61    ) -> Result<Client, Error> {
62        let mut endpoint = Endpoint::new("local client");
63        if secure {
64            endpoint = endpoint.assume_tls();
65        }
66
67        let rocket = rocket.local_launch(endpoint).await?;
68        let cookies = RwLock::new(cookie::CookieJar::new());
69        Ok(Client { rocket, cookies, tracked })
70    }
71
72    // WARNING: This is unstable! Do not use this method outside of Rocket!
73    // This is used by the `Client` doctests.
74    #[doc(hidden)]
75    pub fn _test<T, F>(f: F) -> T
76        where F: FnOnce(&Self, LocalRequest<'_>, LocalResponse<'_>) -> T + Send
77    {
78        crate::async_test(async {
79            let client = Client::debug(crate::build()).await.unwrap();
80            let request = client.get("/");
81            let response = request.clone().dispatch().await;
82            f(&client, request, response)
83        })
84    }
85
86    #[inline(always)]
87    pub(crate) fn _rocket(&self) -> &Rocket<Orbit> {
88        &self.rocket
89    }
90
91    #[inline(always)]
92    pub(crate) fn _with_raw_cookies<F, T>(&self, f: F) -> T
93        where F: FnOnce(&cookie::CookieJar) -> T
94    {
95        f(&self.cookies.read())
96    }
97
98    #[inline(always)]
99    pub(crate) fn _with_raw_cookies_mut<F, T>(&self, f: F) -> T
100        where F: FnOnce(&mut cookie::CookieJar) -> T
101    {
102        f(&mut self.cookies.write())
103    }
104
105    #[inline(always)]
106    fn _req<'c, 'u: 'c, U>(&'c self, method: Method, uri: U) -> LocalRequest<'c>
107        where U: TryInto<Origin<'u>> + fmt::Display
108    {
109        LocalRequest::new(self, method, uri)
110    }
111
112    pub(crate) async fn _terminate(self) -> Rocket<Ignite> {
113        let rocket = self.rocket;
114        rocket.shutdown().notify();
115        rocket.fairings.handle_shutdown(&rocket).await;
116        rocket.deorbit()
117    }
118
119    // Generates the public API methods, which call the private methods above.
120    pub_client_impl!("use rocket::local::asynchronous::Client;" @async await);
121}
122
123impl std::fmt::Debug for Client {
124    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
125        self._rocket().fmt(f)
126    }
127}
128
129#[cfg(test)]
130mod test {
131    #[test]
132    fn test_local_client_impl_send_sync() {
133        fn assert_sync_send<T: Sync + Send>() {}
134        assert_sync_send::<super::Client>();
135    }
136}
rocket/local/asynchronous/client.rs

rocket/local/asynchronous/
client.rs
