Skip to main content

rocket/local/
request.rs

1macro_rules! pub_request_impl {
2    ($import:literal $($prefix:tt $suffix:tt)?) =>
3{
4    /// Borrows the inner `Request` as seen by Rocket.
5    ///
6    /// Note that no routing has occurred and that there is no remote
7    /// address unless one has been explicitly set with
8    /// [`set_remote()`](Request::set_remote()).
9    ///
10    /// # Example
11    ///
12    /// ```rust
13    #[doc = $import]
14    ///
15    /// # Client::_test(|_, request, _| {
16    /// let request: LocalRequest = request;
17    /// let inner: &rocket::Request = request.inner();
18    /// # });
19    /// ```
20    #[inline(always)]
21    pub fn inner(&self) -> &Request<'c> {
22        self._request()
23    }
24
25    /// Mutably borrows the inner `Request` as seen by Rocket.
26    ///
27    /// Note that no routing has occurred and that there is no remote
28    /// address unless one has been explicitly set with
29    /// [`set_remote()`](Request::set_remote()).
30    ///
31    /// # Example
32    ///
33    /// ```rust
34    #[doc = $import]
35    ///
36    /// # Client::_test(|_, request, _| {
37    /// let mut request: LocalRequest = request;
38    /// let inner: &mut rocket::Request = request.inner_mut();
39    /// # });
40    /// ```
41    #[inline(always)]
42    pub fn inner_mut(&mut self) -> &mut Request<'c> {
43        self._request_mut()
44    }
45
46    /// Add a header to this request.
47    ///
48    /// Any type that implements `Into<Header>` can be used here. Among
49    /// others, this includes [`ContentType`] and [`Accept`].
50    ///
51    /// [`ContentType`]: crate::http::ContentType
52    /// [`Accept`]: crate::http::Accept
53    ///
54    /// # Examples
55    ///
56    /// Add the Content-Type header:
57    ///
58    /// ```rust
59    #[doc = $import]
60    /// use rocket::http::Header;
61    /// use rocket::http::ContentType;
62    ///
63    /// # Client::_test(|_, request, _| {
64    /// let request: LocalRequest = request;
65    /// let req = request
66    ///     .header(ContentType::JSON)
67    ///     .header(Header::new("X-Custom", "custom-value"));
68    /// # });
69    /// ```
70    #[inline]
71    pub fn header<H>(mut self, header: H) -> Self
72        where H: Into<crate::http::Header<'static>>
73    {
74        self._request_mut().add_header(header.into());
75        self
76    }
77
78    /// Adds a header to this request without consuming `self`.
79    ///
80    /// # Examples
81    ///
82    /// Add the Content-Type header:
83    ///
84    /// ```rust
85    #[doc = $import]
86    /// use rocket::http::ContentType;
87    ///
88    /// # Client::_test(|_, mut request, _| {
89    /// let mut request: LocalRequest = request;
90    /// request.add_header(ContentType::JSON);
91    /// # });
92    /// ```
93    #[inline]
94    pub fn add_header<H>(&mut self, header: H)
95        where H: Into<crate::http::Header<'static>>
96    {
97        self._request_mut().add_header(header.into());
98    }
99
100    /// Set the remote address of this request.
101    ///
102    /// # Examples
103    ///
104    /// Set the remote address to "8.8.8.8:80":
105    ///
106    /// ```rust
107    #[doc = $import]
108    ///
109    /// # Client::_test(|_, request, _| {
110    /// let request: LocalRequest = request;
111    /// let address = "8.8.8.8:80".parse().unwrap();
112    /// let req = request.remote(address);
113    /// # });
114    /// ```
115    #[inline]
116    pub fn remote(mut self, address: std::net::SocketAddr) -> Self {
117        self.set_remote(address);
118        self
119    }
120
121    /// Add a cookie to this request.
122    ///
123    /// # Examples
124    ///
125    /// Add `user_id` cookie:
126    ///
127    /// ```rust
128    #[doc = $import]
129    /// use rocket::http::Cookie;
130    ///
131    /// # Client::_test(|_, request, _| {
132    /// let request: LocalRequest = request;
133    /// let req = request
134    ///     .cookie(("username", "sb"))
135    ///     .cookie(("user_id", "12"));
136    /// # });
137    /// ```
138    #[inline]
139    pub fn cookie<'a, C>(mut self, cookie: C) -> Self
140        where C: Into<crate::http::Cookie<'a>>
141    {
142        self._request_mut().cookies_mut().add_original(cookie.into().into_owned());
143        self
144    }
145
146    /// Add all of the cookies in `cookies` to this request.
147    ///
148    /// # Example
149    ///
150    /// ```rust
151    #[doc = $import]
152    /// use rocket::http::Cookie;
153    ///
154    /// # Client::_test(|_, request, _| {
155    /// let request: LocalRequest = request;
156    /// let cookies = vec![("a", "b"), ("c", "d")];
157    /// let req = request.cookies(cookies);
158    /// # });
159    /// ```
160    #[inline]
161    pub fn cookies<'a, C, I>(mut self, cookies: I) -> Self
162        where C: Into<crate::http::Cookie<'a>>,
163              I: IntoIterator<Item = C>
164    {
165        for cookie in cookies {
166            let cookie: crate::http::Cookie<'_> = cookie.into();
167            self._request_mut().cookies_mut().add_original(cookie.into_owned());
168        }
169
170        self
171    }
172
173    /// Add a [private cookie] to this request.
174    ///
175    /// [private cookie]: crate::http::CookieJar::add_private()
176    ///
177    /// # Examples
178    ///
179    /// Add `user_id` as a private cookie:
180    ///
181    /// ```rust
182    #[doc = $import]
183    /// use rocket::http::Cookie;
184    ///
185    /// # Client::_test(|_, request, _| {
186    /// let request: LocalRequest = request;
187    /// let req = request.private_cookie(("user_id", "sb"));
188    /// # });
189    /// ```
190    #[cfg(feature = "secrets")]
191    #[cfg_attr(nightly, doc(cfg(feature = "secrets")))]
192    #[inline]
193    pub fn private_cookie<C>(mut self, cookie: C) -> Self
194        where C: Into<crate::http::Cookie<'static>>
195    {
196        self._request_mut().cookies_mut().add_original_private(cookie.into());
197        self
198    }
199
200    /// Set mTLS client certificates to send along with the request.
201    ///
202    /// If the request already contained certificates, they are replaced with
203    /// those in `reader.`
204    ///
205    /// `reader` is expected to be PEM-formatted and contain X509 certificates.
206    /// If it contains more than one certificate, the entire chain is set on the
207    /// request. If it contains items other than certificates, the certificate
208    /// chain up to the first non-certificate item is set on the request. If
209    /// `reader` is syntactically invalid PEM, certificates are cleared on the
210    /// request.
211    ///
212    /// The type `C` can be anything that implements [`std::io::Read`]. This
213    /// includes: `&[u8]`, `File`, `&File`, `Stdin`, and so on. To read a file
214    /// in at compile-time, use [`include_bytes!()`].
215    ///
216    /// ```rust
217    /// use std::fs::File;
218    ///
219    #[doc = $import]
220    /// use rocket::fs::relative;
221    ///
222    /// # Client::_test(|_, request, _| {
223    /// let request: LocalRequest = request;
224    /// let path = relative!("../../examples/tls/private/ed25519_cert.pem");
225    /// let req = request.identity(File::open(path).unwrap());
226    /// # });
227    /// ```
228    #[cfg(feature = "mtls")]
229    #[cfg_attr(nightly, doc(cfg(feature = "mtls")))]
230    pub fn identity<C: std::io::Read>(mut self, reader: C) -> Self {
231        use crate::http::tls::util::load_certs;
232        use crate::http::private::{CertificateData, Certificates};
233
234        let mut reader = std::io::BufReader::new(reader);
235        let certs = load_certs(&mut reader).map(|certs| {
236            let certs = certs.into_iter().map(|c| CertificateData(c.to_vec()));
237            Certificates::from(certs.collect::<Vec<_>>())
238        });
239        self._request_mut().connection.client_certificates = certs.ok();
240        self
241    }
242
243    /// Sets the body data of the request.
244    ///core/lib/src/local/request.rs
245    /// # Examples
246    ///
247    /// ```rust
248    #[doc = $import]
249    /// use rocket::http::ContentType;
250    ///
251    /// # Client::_test(|_, request, _| {
252    /// let request: LocalRequest = request;
253    /// let req = request
254    ///     .header(ContentType::Text)
255    ///     .body("Hello, world!");
256    /// # });
257    /// ```
258    #[inline]
259    pub fn body<S: AsRef<[u8]>>(mut self, body: S) -> Self {
260        // TODO: For CGI, we want to be able to set the body to be stdin
261        // without actually reading everything into a vector. Can we allow
262        // that here while keeping the simplicity? Looks like it would
263        // require us to reintroduce a NetStream::Local(Box<Read>) or
264        // something like that.
265        *self._body_mut() = body.as_ref().into();
266        self
267    }
268
269    /// Sets the body to `value` serialized as JSON with `Content-Type`
270    /// [`ContentType::JSON`](crate::http::ContentType::JSON).
271    ///
272    /// If `value` fails to serialize, the body is set to empty. The
273    /// `Content-Type` header is _always_ set.
274    ///
275    /// # Examples
276    ///
277    /// ```rust
278    #[doc = $import]
279    /// use rocket::serde::Serialize;
280    /// use rocket::http::ContentType;
281    ///
282    /// #[derive(Serialize)]
283    /// struct Task {
284    ///     id: usize,
285    ///     complete: bool,
286    /// }
287    ///
288    /// # Client::_test(|_, request, _| {
289    /// let task = Task { id: 10, complete: false };
290    ///
291    /// let request: LocalRequest = request;
292    /// let req = request.json(&task);
293    /// assert_eq!(req.content_type(), Some(&ContentType::JSON));
294    /// # });
295    /// ```
296    #[cfg(feature = "json")]
297    #[cfg_attr(nightly, doc(cfg(feature = "json")))]
298    pub fn json<T: crate::serde::Serialize>(self, value: &T) -> Self {
299        let json = serde_json::to_vec(&value).unwrap_or_default();
300        self.header(crate::http::ContentType::JSON).body(json)
301    }
302
303    /// Sets the body to `value` serialized as MessagePack with `Content-Type`
304    /// [`ContentType::MsgPack`](crate::http::ContentType::MsgPack).
305    ///
306    /// If `value` fails to serialize, the body is set to empty. The
307    /// `Content-Type` header is _always_ set.
308    ///
309    /// # Examples
310    ///
311    /// ```rust
312    #[doc = $import]
313    /// use rocket::serde::Serialize;
314    /// use rocket::http::ContentType;
315    ///
316    /// #[derive(Serialize)]
317    /// struct Task {
318    ///     id: usize,
319    ///     complete: bool,
320    /// }
321    ///
322    /// # Client::_test(|_, request, _| {
323    /// let task = Task { id: 10, complete: false };
324    ///
325    /// let request: LocalRequest = request;
326    /// let req = request.msgpack(&task);
327    /// assert_eq!(req.content_type(), Some(&ContentType::MsgPack));
328    /// # });
329    /// ```
330    #[cfg(feature = "msgpack")]
331    #[cfg_attr(nightly, doc(cfg(feature = "msgpack")))]
332    pub fn msgpack<T: crate::serde::Serialize>(self, value: &T) -> Self {
333        let msgpack = rmp_serde::to_vec(value).unwrap_or_default();
334        self.header(crate::http::ContentType::MsgPack).body(msgpack)
335    }
336
337    /// Set the body (data) of the request without consuming `self`.
338    ///
339    /// # Examples
340    ///
341    /// Set the body to be a JSON structure; also sets the Content-Type.
342    ///
343    /// ```rust
344    #[doc = $import]
345    /// use rocket::http::ContentType;
346    ///
347    /// # Client::_test(|_, request, _| {
348    /// let request: LocalRequest = request;
349    /// let mut request = request.header(ContentType::JSON);
350    /// request.set_body(r#"{ "key": "value", "array": [1, 2, 3] }"#);
351    /// # });
352    /// ```
353    #[inline]
354    pub fn set_body<S: AsRef<[u8]>>(&mut self, body: S) {
355        *self._body_mut() = body.as_ref().into();
356    }
357
358    /// Dispatches the request, returning the response.
359    ///
360    /// This method consumes `self` and is the preferred mechanism for
361    /// dispatching.
362    ///
363    /// # Example
364    ///
365    /// ```rust
366    #[doc = $import]
367    ///
368    /// # Client::_test(|_, request, _| {
369    /// let request: LocalRequest = request;
370    /// let response = request.dispatch();
371    /// # });
372    /// ```
373    #[inline(always)]
374    pub $($prefix)? fn dispatch(self) -> LocalResponse<'c> {
375        self._dispatch()$(.$suffix)?
376    }
377
378    #[cfg(test)]
379    #[allow(dead_code)]
380    fn _ensure_impls_exist() {
381        fn is_clone_debug<T: Clone + std::fmt::Debug>() {}
382        is_clone_debug::<Self>();
383
384        fn is_deref_req<'a, T: std::ops::Deref<Target = Request<'a>>>() {}
385        is_deref_req::<Self>();
386
387        fn is_deref_mut_req<'a, T: std::ops::DerefMut<Target = Request<'a>>>() {}
388        is_deref_mut_req::<Self>();
389    }
390}}