rocket/request/
query.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
use request::{FormItems, FormItem, Form, LenientForm, FromForm};

/// Iterator over form items in a query string.
///
/// The `Query` type exists to separate, at the type level, _form_ form items
/// ([`FormItems`]) from _query_ form items (`Query`). A value of type `Query`
/// is passed in to implementations of the [`FromQuery`] trait by Rocket's code
/// generation for every trailing query parameter, `<params..>` below:
///
/// ```rust
/// # #![feature(proc_macro_hygiene, decl_macro)]
/// # #[macro_use] extern crate rocket;
/// #
/// # use rocket::request::Form;
/// # #[derive(FromForm)] struct Q { foo: usize }
/// # type T = Form<Q>;
/// #
/// #[get("/user?<params..>")]
/// fn user(params: T) { /* ... */ }
/// # fn main() { }
/// ```
///
/// # Usage
///
/// A value of type `Query` can only be used as an iterator over values of type
/// [`FormItem`]. As such, its usage is equivalent to that of [`FormItems`], and
/// we refer you to its documentation for further details.
///
/// ## Example
///
/// ```rust
/// use rocket::request::Query;
///
/// # use rocket::request::FromQuery;
/// #
/// # struct MyType;
/// # type Result = ::std::result::Result<MyType, ()>;
/// #
/// # impl<'q> FromQuery<'q> for MyType {
/// #    type Error = ();
/// #
/// fn from_query(query: Query) -> Result {
///     for item in query {
///         println!("query key/value: ({}, {})", item.key, item.value);
///     }
///
///     // ...
/// #   Ok(MyType)
/// }
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct Query<'q>(#[doc(hidden)] pub &'q [FormItem<'q>]);

impl<'q> Iterator for Query<'q> {
    type Item = FormItem<'q>;

    #[inline(always)]
    fn next(&mut self) -> Option<Self::Item> {
        if self.0.is_empty() {
            return None;
        }

        let next = self.0[0];
        self.0 = &self.0[1..];
        Some(next)
    }
}

/// Trait implemented by query guards to derive a value from a query string.
///
/// # Query Guards
///
/// A query guard operates on multiple items of a request's query string. It
/// validates and optionally converts a query string into another value.
/// Validation and parsing/conversion is implemented through `FromQuery`. In
/// other words, every type that implements `FromQuery` is a query guard.
///
/// Query guards are used as the target of trailing query parameters, which
/// syntactically take the form `<param..>` after a `?` in a route's path. For
/// example, the parameter `user` is a trailing query parameter in the following
/// route:
///
/// ```rust
/// # #![feature(proc_macro_hygiene, decl_macro)]
/// # #[macro_use] extern crate rocket;
/// use rocket::request::Form;
///
/// #[derive(FromForm)]
/// struct User {
///     name: String,
///     account: usize,
/// }
///
/// #[get("/item?<id>&<user..>")]
/// fn item(id: usize, user: Form<User>) { /* ... */ }
/// # fn main() { }
/// ```
///
/// The `FromQuery` implementation of `Form<User>` will be passed in a [`Query`]
/// that iterates over all of the query items that don't have the key `id`
/// (because of the `<id>` dynamic query parameter). For posterity, note that
/// the `value` of an `id=value` item in a query string will be parsed as a
/// `usize` and passed in to `item` as `id`.
///
/// # Forwarding
///
/// If the conversion fails, signaled by returning an `Err` from a `FromQuery`
/// implementation, the incoming request will be forwarded to the next matching
/// route, if any. For instance, in the `item` route above, if a query string is
/// missing either a `name` or `account` key/value pair, or there is a query
/// item with a key that is not `id`, `name`, or `account`, the request will be
/// forwarded. Note that this strictness is imposed by the [`Form`] type. As an
/// example, using the [`LenientForm`] type instead would allow extra form items
/// to be ignored without forwarding. Alternatively, _not_ having a trailing
/// parameter at all would result in the same.
///
/// # Provided Implementations
///
/// Rocket implements `FromQuery` for several standard types. Their behavior is
/// documented here.
///
///   * **Form&lt;T>** _where_ **T: FromForm**
///
///     Parses the query as a strict form, where each key is mapped to a field
///     in `T`. See [`Form`] for more information.
///
///   * **LenientForm&lt;T>** _where_ **T: FromForm**
///
///     Parses the query as a lenient form, where each key is mapped to a field
///     in `T`. See [`LenientForm`] for more information.
///
///   * **Option&lt;T>** _where_ **T: FromQuery**
///
///     _This implementation always returns successfully._
///
///     The query is parsed by `T`'s `FromQuery` implementation. If the parse
///     succeeds, a `Some(parsed_value)` is returned. Otherwise, a `None` is
///     returned.
///
///   * **Result&lt;T, T::Error>** _where_ **T: FromQuery**
///
///     _This implementation always returns successfully._
///
///     The path segment is parsed by `T`'s `FromQuery` implementation. The
///     returned `Result` value is returned.
///
/// # Example
///
/// Explicitly implementing `FromQuery` should be rare. For most use-cases, a
/// query guard of `Form<T>` or `LenientForm<T>`, coupled with deriving
/// `FromForm` (as in the previous example) will suffice. For special cases
/// however, an implementation of `FromQuery` may be warranted.
///
/// Consider a contrived scheme where we expect to recieve one query key, `key`,
/// three times and wish to take the middle value. For instance, consider the
/// query:
///
/// ```text
/// key=first_value&key=second_value&key=third_value
/// ```
///
/// We wish to extract `second_value` from this query into a `Contrived` struct.
/// Because `Form` and `LenientForm` will take the _last_ value (`third_value`
/// here) and don't check that there are exactly three keys named `key`, we
/// cannot make use of them and must implement `FromQuery` manually. Such an
/// implementation might look like:
///
/// ```rust
/// use rocket::http::RawStr;
/// use rocket::request::{Query, FromQuery};
///
/// /// Our custom query guard.
/// struct Contrived<'q>(&'q RawStr);
///
/// impl<'q> FromQuery<'q> for Contrived<'q> {
///     /// The number of `key`s we actually saw.
///     type Error = usize;
///
///     fn from_query(query: Query<'q>) -> Result<Self, Self::Error> {
///         let mut key_items = query.filter(|i| i.key == "key");
///
///         // This is cloning an iterator, which is cheap.
///         let count = key_items.clone().count();
///         if count != 3 {
///             return Err(count);
///         }
///
///         // The `ok_or` gets us a `Result`. We will never see `Err(0)`.
///         key_items.map(|i| Contrived(i.value)).nth(1).ok_or(0)
///     }
/// }
/// ```
pub trait FromQuery<'q>: Sized {
    /// The associated error to be returned if parsing/validation fails.
    type Error;

    /// Parses and validates an instance of `Self` from a query or returns an
    /// `Error` if parsing or validation fails.
    fn from_query(query: Query<'q>) -> Result<Self, Self::Error>;
}

impl<'q, T: FromForm<'q>> FromQuery<'q> for Form<T> {
    type Error = T::Error;

    #[inline]
    fn from_query(q: Query<'q>) -> Result<Self, Self::Error> {
        T::from_form(&mut FormItems::from(q.0), true).map(Form)
    }
}

impl<'q, T: FromForm<'q>> FromQuery<'q> for LenientForm<T> {
    type Error = <T as FromForm<'q>>::Error;

    #[inline]
    fn from_query(q: Query<'q>) -> Result<Self, Self::Error> {
        T::from_form(&mut FormItems::from(q.0), false).map(LenientForm)
    }
}

impl<'q, T: FromQuery<'q>> FromQuery<'q> for Option<T> {
    type Error = !;

    #[inline]
    fn from_query(q: Query<'q>) -> Result<Self, Self::Error> {
        Ok(T::from_query(q).ok())
    }
}

impl<'q, T: FromQuery<'q>> FromQuery<'q> for Result<T, T::Error> {
    type Error = !;

    #[inline]
    fn from_query(q: Query<'q>) -> Result<Self, Self::Error> {
        Ok(T::from_query(q))
    }
}