ntex 4.9.2

Framework for composable network services
Documentation
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
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
//! Request extractors
use std::convert::Infallible;

use super::{HttpRequest, State, WebResponseError};
use crate::http::Payload;

/// Turns request data into a value that a handler can use.
///
/// Each argument accepted by a handler registered with
/// [`Route::to()`](super::Route::to) is an extractor. Before calling the
/// handler, ntex asks each argument type to create its value from the incoming
/// request.
///
/// An extractor can look at the application state, request headers, path, and
/// other request information. It can also read the request body through the
/// payload. Extractors run in the same order as the handler arguments and
/// share that payload, so an extractor that reads the body may leave nothing
/// for the next one. For that reason, a handler should normally have only one
/// body-reading extractor.
///
/// A failed body extractor may also have consumed the body, depending on where
/// it failed. For example, `Json<T>` rejects an unsupported content type before
/// reading anything, but it has already read the body when deserialization
/// fails. Wrapping it in `Option<T>` or `Result<T, E>` therefore does not make
/// `(Option<Json<T>>, Bytes)` a reliable "JSON or raw body" fallback. To fall
/// back to the raw body, extract `Bytes` once and parse the retained bytes, for
/// example with `serde_json::from_slice()`.
/// [`PayloadConfig`](super::types::PayloadConfig) limits that buffer.
///
/// When an extractor returns an error, ntex turns it into an HTTP response and
/// skips the handler. The error must implement [`WebResponseError`] for the
/// application. If the handler should still run, use `Option<T>` to receive
/// `None`, or `Result<T, T::Error>` to receive the original error. Both also
/// let malformed or oversized input through, so the handler must reject it
/// itself when that matters.
///
/// # Example
///
/// A custom extractor can turn a request header into a handler argument:
///
/// ```rust
/// use ntex::http::Payload;
/// use ntex::web::{self, FromRequest, HttpRequest, InternalError};
///
/// struct ClientName(String);
///
/// impl<St: web::State> FromRequest<St> for ClientName {
///     type Error = InternalError<&'static str>;
///
///     async fn from_request(_: &St, req: &HttpRequest, _: &mut Payload) -> Result<Self, Self::Error> {
///         req.headers()
///             .get("x-client-name")
///             .and_then(|value| value.to_str().ok())
///             .map(|value| ClientName(value.to_owned()))
///             .ok_or_else(|| web::error::ErrorBadRequest("Missing client name"))
///     }
/// }
///
/// async fn hello(client: ClientName) -> String {
///     format!("Hello, {}!", client.0)
/// }
///
/// let app = web::App::default().route("/", web::get().to(hello));
/// ```
#[diagnostic::on_unimplemented(
    message = "`{Self}` cannot be used as a handler argument",
    label = "not a request extractor",
    note = "handler arguments must implement `FromRequest`, for example `HttpRequest`, `web::types::Path<T>`, `Query<T>`, `Json<T>`, `Form<T>`, or `Payload`",
    note = "implement `FromRequest<St>` for `{Self}` to extract it from the request"
)]
pub trait FromRequest<St>: Sized {
    /// The error returned when extraction fails.
    ///
    /// For a route handler, ntex must be able to turn this error into an HTTP
    /// response through [`WebResponseError`].
    type Error;

    /// Creates the extractor value for this request.
    async fn from_request(
        st: &St,
        req: &HttpRequest,
        payload: &mut Payload,
    ) -> Result<Self, Self::Error>;
}

/// Optionally extract a field from the request
///
/// If the `FromRequest` for T fails, return None rather than returning an error response
///
/// `None` covers every extraction error, not only missing input. Input that is
/// present but invalid also becomes `None`, and the handler runs. For example,
/// `Option<Json<T>>` receives `None` for a missing body, a wrong content type,
/// malformed JSON, and a body over the [`JsonConfig`](super::types::JsonConfig)
/// limit, where `Json<T>` would reject the last two with 400 and 413. Use
/// `Option<T>` only when such input may be ignored. To accept missing input
/// but still reject invalid input, extract `Result<T, T::Error>` and return the
/// errors that should still fail the request.
///
/// The request body is not rewound. If `T` reads the body before failing, later
/// extractors see only what remains. See [`FromRequest`] for a single-read
/// fallback pattern.
///
/// ## Example
///
/// ```rust
/// use ntex::http;
/// use ntex::web::{self, error, App, HttpRequest, FromRequest, InternalError};
/// use rand;
///
/// #[derive(Debug, serde::Deserialize)]
/// struct Thing {
///     name: String
/// }
///
/// impl<St> FromRequest<St> for Thing {
///     type Error = InternalError<&'static str>;
///
///     async fn from_request(st: &St, req: &HttpRequest, payload: &mut http::Payload) -> Result<Self, Self::Error> {
///         if rand::random() {
///             Ok(Thing { name: "thingy".into() })
///         } else {
///             Err(error::ErrorBadRequest("no luck"))
///         }
///     }
/// }
///
/// /// extract `Thing` from request
/// async fn index(supplied_thing: Option<Thing>) -> String {
///     match supplied_thing {
///         // Puns not intended
///         Some(thing) => format!("Got something: {:?}", thing),
///         None => format!("No thing!")
///     }
/// }
///
/// fn main() {
///     let app = App::default().service(
///         web::resource("/users/{first}").route(
///             web::post().to(index))
///     );
/// }
/// ```
impl<St, T> FromRequest<St> for Option<T>
where
    St: State,
    T: FromRequest<St>,
    <T as FromRequest<St>>::Error: WebResponseError<St, St::Error>,
{
    type Error = Infallible;

    #[inline]
    async fn from_request(
        st: &St,
        req: &HttpRequest,
        payload: &mut Payload,
    ) -> Result<Option<T>, Self::Error> {
        match T::from_request(st, req, payload).await {
            Ok(v) => Ok(Some(v)),
            Err(e) => {
                log::debug!("Error for Option<T> extractor: {e}");
                Ok(None)
            }
        }
    }
}

/// Optionally extract a field from the request or extract the Error if unsuccessful
///
/// If the `FromRequest` for T fails, inject Err into handler rather than returning an error response
///
/// As with `Option<T>`, the request body is not rewound after a failure.
///
/// ## Example
///
/// ```rust
/// use ntex::http;
/// use ntex::web::{self, error, App, State, HttpRequest, FromRequest, InternalError};
/// use rand;
///
/// #[derive(Debug, serde::Deserialize)]
/// struct Thing {
///     name: String
/// }
///
/// impl<St: State> FromRequest<St> for Thing {
///     type Error = InternalError<&'static str>;
///
///     async fn from_request(st: &St, req: &HttpRequest, payload: &mut http::Payload) -> Result<Thing, Self::Error> {
///         if rand::random() {
///             Ok(Thing { name: "thingy".into() })
///         } else {
///             Err(error::ErrorBadRequest("no luck"))
///         }
///     }
/// }
///
/// /// extract `Thing` from request
/// async fn index(supplied_thing: Result<Thing, InternalError<&'static str>>) -> String {
///     match supplied_thing {
///         Ok(thing) => format!("Got thing: {:?}", thing),
///         Err(e) => format!("Error extracting thing: {}", e)
///     }
/// }
///
/// fn main() {
///     let app = App::default().service(
///         web::resource("/users/{first}").route(web::post().to(index))
///     );
/// }
/// ```
impl<St, T> FromRequest<St> for Result<T, T::Error>
where
    St: State,
    T: FromRequest<St>,
{
    type Error = T::Error;

    #[inline]
    async fn from_request(
        st: &St,
        req: &HttpRequest,
        payload: &mut Payload,
    ) -> Result<Self, Self::Error> {
        match T::from_request(st, req, payload).await {
            Ok(v) => Ok(Ok(v)),
            Err(e) => Ok(Err(e)),
        }
    }
}

#[doc(hidden)]
impl<St: State> FromRequest<St> for () {
    type Error = Infallible;

    #[inline]
    async fn from_request(_: &St, _: &HttpRequest, _: &mut Payload) -> Result<(), Self::Error> {
        Ok(())
    }
}

macro_rules! tuple_from_req {
    ($(#[$meta:meta])* $(($T:ident, $t:ident)),*) => {
        $(#[$meta])*
        impl<St, $($T,)+> FromRequest<St> for ($($T,)+)
        where
            St: State,
            $($T: FromRequest<St> + 'static,)+
            $(<$T as $crate::web::FromRequest<St>>::Error: WebResponseError<St, St::Error>),+
        {
            type Error = $crate::web::InternalError<&'static str>;

            async fn from_request(st: &St, req: &HttpRequest, payload: &mut Payload) -> Result<($($T,)+), Self::Error> {
                Ok((
                    $($T::from_request(st, req, payload).await.map_err(
                        |e|
                        $crate::web::InternalError::from_response("Error", e.error_response(st)))?,)+
                ))
            }
        }
    }
}

#[allow(non_snake_case, clippy::wildcard_imports)]
#[rustfmt::skip]
mod m {
    use super::*;
    use variadics_please::all_tuples;

    all_tuples!(#[doc(fake_variadic)] tuple_from_req, 1, 12, T, t);
}

#[cfg(test)]
mod tests {
    use crate::http::header;
    use crate::util::Bytes;
    use crate::web::error::{PayloadError, UrlencodedError};
    use crate::web::test::{TestRequest, from_request};
    use crate::web::types::{Form, FormConfig, Json, PayloadConfig};

    #[derive(serde::Deserialize, Debug, PartialEq)]
    struct Info {
        hello: String,
    }

    /// STATEMENT: Optional extractors turn extraction failures into `None` and retain valid values.
    ///
    /// HOW:
    /// - Extract `Option<Form<Info>>` from empty, valid, and missing-field URL-encoded bodies.
    /// - Assert `None`, the expected `hello` value, and `None`, respectively.
    #[crate::rt_test]
    async fn test_option() {
        let (req, mut pl, ()) =
            TestRequest::with_header(header::CONTENT_TYPE, "application/x-www-form-urlencoded")
                .app_value(FormConfig::default().limit(4096))
                .to_http_parts();

        let r = from_request::<_, Option<Form<Info>>>(&(), &req, &mut pl)
            .await
            .unwrap();
        assert_eq!(r, None);

        let (req, mut pl, ()) =
            TestRequest::with_header(header::CONTENT_TYPE, "application/x-www-form-urlencoded")
                .header(header::CONTENT_LENGTH, "9")
                .payload(Bytes::from_static(b"hello=world"))
                .to_http_parts();

        let r = from_request::<_, Option<Form<Info>>>(&(), &req, &mut pl)
            .await
            .unwrap();
        assert_eq!(
            r,
            Some(Form(Info {
                hello: "world".into()
            }))
        );

        let (req, mut pl, ()) =
            TestRequest::with_header(header::CONTENT_TYPE, "application/x-www-form-urlencoded")
                .header(header::CONTENT_LENGTH, "9")
                .payload(Bytes::from_static(b"bye=world"))
                .to_http_parts();

        let r = from_request::<_, Option<Form<Info>>>(&(), &req, &mut pl)
            .await
            .unwrap();
        assert_eq!(r, None);
    }

    /// STATEMENT: Result extractors expose inner extraction errors without failing outer extraction.
    ///
    /// HOW:
    /// - Extract `Result<Form<Info>, UrlencodedError>` from valid and missing-field bodies.
    /// - Assert outer success in both cases, with the expected form value or an inner error.
    #[crate::rt_test]
    async fn test_result() {
        let (req, mut pl, ()) =
            TestRequest::with_header(header::CONTENT_TYPE, "application/x-www-form-urlencoded")
                .header(header::CONTENT_LENGTH, "11")
                .payload(Bytes::from_static(b"hello=world"))
                .to_http_parts();

        let r = from_request::<_, Result<Form<Info>, UrlencodedError>>(&(), &req, &mut pl)
            .await
            .unwrap();
        assert_eq!(
            r.unwrap(),
            Form(Info {
                hello: "world".into()
            })
        );

        let (req, mut pl, ()) =
            TestRequest::with_header(header::CONTENT_TYPE, "application/x-www-form-urlencoded")
                .header(header::CONTENT_LENGTH, "9")
                .payload(Bytes::from_static(b"bye=world"))
                .to_http_parts();

        let r = from_request::<_, Result<Form<Info>, UrlencodedError>>(&(), &req, &mut pl)
            .await
            .unwrap();
        assert!(r.is_err());
    }

    /// STATEMENT: `Option<Json<T>>` turns malformed and oversized bodies into `None` and
    /// runs the handler, where `Json<T>` rejects them; `Result<Json<T>, _>` keeps the cause.
    ///
    /// HOW:
    /// - Serve `Json<Value>`, `Option<Json<Value>>` and `Result<Json<Value>, JsonPayloadError>`
    ///   routes with `JsonConfig::limit(8)`, counting handler invocations per route.
    /// - Send an absent body, valid JSON, malformed JSON and a 13-byte body to each route.
    /// - Assert `Json` returns 200, 400, 400 and 413 and runs only for valid input, while the
    ///   optional routes return 200 and run every time, receiving `None` or the matching
    ///   `ContentType`, `Deserialize` or `Overflow` error for every non-valid input.
    #[crate::rt_test]
    async fn test_optional_json_suppresses_validation() {
        use crate::http::{Method, StatusCode};
        use crate::web::error::JsonPayloadError;
        use crate::web::test::{call_service, init_service, read_body};
        use crate::web::types::JsonConfig;
        use crate::web::{self, App, WebAppConfig};
        use std::{cell::Cell, rc::Rc};

        type Value = Json<serde_json::Value>;

        let calls = Rc::new([Cell::new(0), Cell::new(0), Cell::new(0)]);
        let (c1, c2, c3) = (calls.clone(), calls.clone(), calls.clone());
        let srv = init_service(
            App::new()
                .with_config(WebAppConfig::new().set_value(JsonConfig::default().limit(8)))
                .route(
                    "/required",
                    web::post().to(async move |v: Value| {
                        c1[0].set(c1[0].get() + 1);
                        v.into_inner().to_string()
                    }),
                )
                .route(
                    "/option",
                    web::post().to(async move |v: Option<Value>| {
                        c2[1].set(c2[1].get() + 1);
                        v.map_or_else(|| "none".to_owned(), |v| v.into_inner().to_string())
                    }),
                )
                .route(
                    "/result",
                    web::post().to(async move |v: Result<Value, JsonPayloadError>| {
                        c3[2].set(c3[2].get() + 1);
                        match v {
                            Ok(v) => v.into_inner().to_string(),
                            Err(JsonPayloadError::ContentType) => "content-type".to_owned(),
                            Err(JsonPayloadError::Deserialize(_)) => "deserialize".to_owned(),
                            Err(JsonPayloadError::Overflow) => "overflow".to_owned(),
                            Err(JsonPayloadError::Payload(_)) => "payload".to_owned(),
                        }
                    }),
                ),
        )
        .await;

        // (input, body, required status, option body, result body)
        let cases: [(&str, Option<&'static [u8]>, StatusCode, &str, &str); 4] = [
            (
                "absent",
                None,
                StatusCode::BAD_REQUEST,
                "none",
                "content-type",
            ),
            (
                "valid",
                Some(b"{\"a\":1}"),
                StatusCode::OK,
                "{\"a\":1}",
                "{\"a\":1}",
            ),
            (
                "malformed",
                Some(b"{\"a\":"),
                StatusCode::BAD_REQUEST,
                "none",
                "deserialize",
            ),
            (
                "oversized",
                Some(b"{\"a\":1234567}"),
                StatusCode::PAYLOAD_TOO_LARGE,
                "none",
                "overflow",
            ),
        ];
        let request = |path: &str, body: Option<&'static [u8]>| {
            let req = TestRequest::with_uri(path).method(Method::POST);
            match body {
                None => req.to_request(),
                Some(body) => req
                    .header(header::CONTENT_TYPE, "application/json")
                    .header(header::CONTENT_LENGTH, body.len().to_string())
                    .payload(Bytes::from_static(body))
                    .to_request(),
            }
        };

        let mut required_calls = 0;
        for (n, (input, body, status, option, result)) in cases.into_iter().enumerate() {
            let resp = call_service(&srv, request("/required", body)).await;
            assert_eq!(resp.status(), status, "required {input}");
            required_calls += usize::from(status == StatusCode::OK);
            assert_eq!(calls[0].get(), required_calls, "required {input}");

            for (path, idx, expected) in [("/option", 1, option), ("/result", 2, result)] {
                let resp = call_service(&srv, request(path, body)).await;
                assert_eq!(resp.status(), StatusCode::OK, "{path} {input}");
                assert_eq!(read_body(resp).await, expected.as_bytes(), "{path} {input}");
                assert_eq!(calls[idx].get(), n + 1, "{path} {input}");
            }
        }
    }

    fn body_parts(
        ctype: &'static str,
        body: &'static [u8],
    ) -> (crate::web::HttpRequest, crate::http::Payload, ()) {
        TestRequest::with_header(header::CONTENT_TYPE, ctype)
            .header(header::CONTENT_LENGTH, body.len().to_string())
            .payload(Bytes::from_static(body))
            .to_http_parts()
    }

    /// STATEMENT: An optional body extractor followed by `Bytes` is not a reliable fallback;
    /// what `Bytes` receives depends on where the optional extractor stopped.
    ///
    /// HOW:
    /// - Extract `(Option<Json<Value>>, Bytes)` from a `text/plain` JSON body and assert
    ///   `None` with the whole body left for `Bytes`, because the media-type check fails
    ///   before reading.
    /// - Repeat with malformed `application/json` and assert `None` with an empty `Bytes`,
    ///   because deserialization fails after reading the body.
    /// - Repeat with valid `application/json` and assert the parsed value with an empty `Bytes`.
    #[crate::rt_test]
    async fn test_optional_body_fallback_depends_on_failure_phase() {
        type Args = (Option<Json<serde_json::Value>>, Bytes);

        let (req, mut pl, ()) = body_parts("text/plain", b"{\"a\":1}");
        let (json, rest) = from_request::<_, Args>(&(), &req, &mut pl).await.unwrap();
        assert!(json.is_none());
        assert_eq!(rest, Bytes::from_static(b"{\"a\":1}"));

        let (req, mut pl, ()) = body_parts("application/json", b"{\"a\":");
        let (json, rest) = from_request::<_, Args>(&(), &req, &mut pl).await.unwrap();
        assert!(json.is_none());
        assert!(rest.is_empty());

        let (req, mut pl, ()) = body_parts("application/json", b"{\"a\":1}");
        let (json, rest) = from_request::<_, Args>(&(), &req, &mut pl).await.unwrap();
        assert_eq!(json.unwrap().into_inner(), serde_json::json!({"a": 1}));
        assert!(rest.is_empty());
    }

    /// STATEMENT: Reading the body once as `Bytes` and parsing the retained bytes gives a
    /// fallback that keeps the whole body, within the `PayloadConfig` limit.
    ///
    /// HOW:
    /// - Extract `Bytes` from valid JSON, malformed JSON, and a non-JSON content type.
    /// - Assert `serde_json::from_slice()` parses the valid body, fails on the malformed one,
    ///   and the retained `Bytes` equals the full request body in every case.
    /// - Set `PayloadConfig::new(4)` and assert a 7-byte body fails with
    ///   `PayloadError::Overflow` instead of being buffered.
    #[crate::rt_test]
    async fn test_single_read_body_fallback() {
        for (ctype, body, parsed) in [
            ("application/json", &b"{\"a\":1}"[..], true),
            ("application/json", &b"{\"a\":"[..], false),
            ("text/plain", &b"{\"a\":1}"[..], true),
        ] {
            let (req, mut pl, ()) = body_parts(ctype, body);
            let raw = from_request::<_, Bytes>(&(), &req, &mut pl).await.unwrap();
            assert_eq!(raw, Bytes::copy_from_slice(body));
            assert_eq!(
                serde_json::from_slice::<serde_json::Value>(&raw).is_ok(),
                parsed,
                "{ctype} {body:?}"
            );
        }

        let (req, mut pl, ()) = TestRequest::with_header(header::CONTENT_TYPE, "application/json")
            .header(header::CONTENT_LENGTH, "7")
            .payload(Bytes::from_static(b"{\"a\":1}"))
            .app_value(PayloadConfig::new(4))
            .to_http_parts();
        let err = from_request::<_, Bytes>(&(), &req, &mut pl)
            .await
            .unwrap_err();
        assert!(
            matches!(
                err,
                PayloadError::Payload(crate::http::error::PayloadError::Overflow)
            ),
            "{err:?}"
        );
    }
}