Skip to main content

rocket/request/
mod.rs

1//! Types and traits for request parsing and handling.
2
3mod request;
4mod from_param;
5mod from_request;
6mod atomic_method;
7
8#[cfg(test)]
9mod tests;
10
11#[cfg(doctest)]
12mod doctest {
13    /// ```compile_fail
14    /// use rocket::Request;
15    ///
16    /// fn covariant<'a, 'b: 'a>(req: &'a Request<'b>) -> &'a Request<'a> {
17    ///     req
18    /// }
19    /// ```
20    #[allow(dead_code)]
21    fn test_request_invariant() {}
22}
23
24pub use self::request::Request;
25pub use self::from_request::{FromRequest, Outcome};
26pub use self::from_param::{FromParam, FromSegments};
27
28#[doc(inline)]
29pub use crate::response::flash::FlashMessage;
30
31pub(crate) use self::request::ConnectionMeta;
32pub(crate) use self::atomic_method::AtomicMethod;
33
34crate::export! {
35    /// Store and immediately retrieve a vector-like value `$v` (`String` or
36    /// `Vec<T>`) in `$request`'s local cache using a locally generated
37    /// anonymous type to avoid type conflicts.
38    ///
39    /// Unlike `local_cache_once`, this macro's generated code _always_ returns
40    /// a unique reference to request-local cache.
41    ///
42    /// # Note
43    ///
44    /// The value `$v` must be of type `String` or `Vec<T>`, that is, a type
45    /// that implements the sealed trait [`Shareable`](crate::form::Shareable)bb).
46    ///
47    /// # Example
48    ///
49    /// ```rust
50    /// use rocket::request::{local_cache, local_cache_once};
51    /// # let c = rocket::local::blocking::Client::debug_with(vec![]).unwrap();
52    /// # let request = c.get("/");
53    ///
54    /// // The first store into local cache for a given type wins.
55    /// for i in 0..4 {
56    ///     assert_eq!(request.local_cache(|| i.to_string()), "0");
57    /// }
58    ///
59    /// // This shows that we cannot cache different values of the same type; we
60    /// // _must_ use a proxy type. To avoid the need to write these manually, use
61    /// // `local_cache!`, which generates one of the fly.
62    /// for i in 0..4 {
63    ///     assert_eq!(local_cache!(request, i.to_string()), i.to_string());
64    /// }
65    ///
66    /// // Note that while `local_cache_once!` generates a new type for the
67    /// // _macro_ invocation, that type is the same per run-time invocation, so
68    /// // all "calls" to `local_cache_once!` on the same line return the same
69    /// // reference for a given request.
70    /// for i in 1..4 {
71    ///     // Note that this is `1`, so _not_ the `String` from line 4.
72    ///     assert_eq!(local_cache_once!(request, i.to_string()), "1");
73    /// }
74    /// ```
75    macro_rules! local_cache {
76        ($request:expr, $v:expr $(,)?) => ({
77            struct Local<T: $crate::form::Shareable>($crate::form::SharedStack<T>);
78            let stack = $request.local_cache(|| Local($crate::form::SharedStack::new()));
79            stack.0.push_owned($v)
80        })
81    }
82}
83
84crate::export! {
85    /// Store and immediately retrieve a value `$v` in `$request`'s local cache
86    /// using a locally generated anonymous type to avoid type conflicts.
87    ///
88    /// The code generated by this macro is expected to be invoked at-most once
89    /// per-request. This is because while `local_cache_once!` generates a new
90    /// type for the _macro_ invocation, that type is the same per run-time
91    /// invocation. Thus, for a given request, a `local_cache_once!` invocation
92    /// always returns the same reference.
93    ///
94    /// To get a unique request-local reference to string-like values, use
95    /// [`local_cache!`] instead.
96    ///
97    /// # Example
98    ///
99    /// ```rust
100    /// use rocket::request::local_cache_once;
101    /// # let c = rocket::local::blocking::Client::debug_with(vec![]).unwrap();
102    /// # let request = c.get("/");
103    ///
104    /// // The first store into local cache for a given type wins.
105    /// assert_eq!(request.local_cache(|| String::from("hello")), "hello");
106    ///
107    /// // The following returns the cached, previously stored value for the type.
108    /// assert_eq!(request.local_cache(|| String::from("goodbye")), "hello");
109    ///
110    /// // This shows that we cannot cache different values of the same type;
111    /// // we _must_ use a proxy type. To avoid the need to write these manually,
112    /// // use `local_cache_once!`, which generates one of the fly.
113    /// assert_eq!(local_cache_once!(request, String::from("hello")), "hello");
114    /// assert_eq!(local_cache_once!(request, String::from("goodbye")), "goodbye");
115    ///
116    /// // But a macro invocation for the same request always resolves to the
117    /// // first reference as the unique type is generated at compile-time.
118    /// for i in 1..4 {
119    ///     assert_eq!(local_cache_once!(request, i.to_string()), "1");
120    /// }
121    /// ```
122    macro_rules! local_cache_once {
123        ($request:expr, $v:expr $(,)?) => ({
124            struct Local<T>(T);
125            &$request.local_cache(move || Local($v)).0
126        })
127    }
128}