nitr-http 0.0.0-beta.7

The Nitr HTTP server layer: hyper server, configuration, and the request/response Lua bridge.
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
// SPDX-License-Identifier: MIT OR Apache-2.0
// This file is part of Nitr.
// See https://nitrweb.com/ for more information
// Copyright (C) 2024-present Jose Quintana <joseluisq.net>

use std::net::SocketAddr;
use std::sync::Arc;

use http_body_util::BodyExt as _;
use http_body_util::combinators::BoxBody;
use hyper::Request;
use hyper::body::Bytes;

/// The request body type: boxed so both real (`hyper::body::Incoming`) and
/// synthetic (test client) bodies flow through the same dispatch.
pub(crate) type IncomingBody = BoxBody<Bytes, Box<dyn std::error::Error + Send + Sync>>;
use mlua::{ExternalResult, LuaSerdeExt, UserData, UserDataFields, UserDataMethods};
use serde_json::Value as SerdeValue;

mod body;
mod fresh;
#[cfg(test)]
mod tests;

pub(crate) use body::BodyGuards;
use body::{LimitedBody, StalledBody};
pub use fresh::is_fresh;

/// Wrapper around the incoming request that implements UserData.
pub(crate) struct LuaRequest {
    pub(crate) peer_addr: SocketAddr,
    /// Whether the connection is TLS: the scheme an HTTP/1.1 request
    /// target does not carry.
    pub(crate) tls: bool,
    pub(crate) req: Request<IncomingBody>,
    /// Path parameters captured by the router (empty for the catch-all).
    pub(crate) params: Vec<(String, String)>,
    /// The request id: generated per request (UUIDv7), or taken from a
    /// trusted inbound `X-Request-ID` header. Shared, so the response
    /// phase and the trace context clone a pointer, not the string.
    pub(crate) id: Arc<str>,
    /// Body-parsing bounds, copied from `[limits]` when the request is
    /// dispatched. Carried on the request because the Lua-facing parsers
    /// need them and Lua must not be able to raise them.
    pub(crate) limits: FormLimits,
    /// The parsed urlencoded form, kept after the first `req:form()` so a
    /// middleware (e.g. `nitr.csrf`) and the handler can both read it —
    /// the body itself can only be consumed once.
    pub(crate) cached_form: Option<Vec<(String, String)>>,
    /// The effective `[limits] max_body_bytes`, recorded by
    /// [`guard_body`](Self::guard_body) so the sized `req:read(n)` branch
    /// can clamp a Lua-supplied size *at the allocation* instead of
    /// relying on the limiter installed in another file. `u64::MAX` until
    /// the guard runs (nothing to clamp against yet).
    pub(crate) body_limit: u64,
    /// The whole body, once route validation or a handler read it, so
    /// `req:json()`/`req:text()`/`req:form()` still work afterwards: the
    /// read happens once, whoever asks first.
    pub(crate) cached_body: Option<Bytes>,
    /// Set when validation consumed the body as a stream (multipart or a
    /// raw upload): there is nothing left for `req:multipart` to parse.
    #[cfg_attr(not(feature = "multipart"), allow(dead_code))]
    pub(crate) body_consumed: bool,
    /// The validated input (`req.valid`), populated by route validation.
    pub(crate) valid: Option<mlua::Table>,
    /// Where this request's validated uploads spool; set by the handler
    /// when the route may receive files.
    #[cfg_attr(not(feature = "multipart"), allow(dead_code))]
    pub(crate) spool_dir: Option<std::path::PathBuf>,
}

/// Bounds applied while parsing a request body into Lua values.
///
/// Only multipart reads these today, so a build without that feature
/// carries the values without using them; keeping the struct whole means
/// `[limits]` parses identically either way.
#[derive(Debug, Clone)]
pub(crate) struct FormLimits {
    #[cfg_attr(not(feature = "multipart"), allow(dead_code))]
    pub(crate) max_parts: usize,
    #[cfg_attr(not(feature = "multipart"), allow(dead_code))]
    pub(crate) max_field_bytes: u64,
    #[cfg_attr(not(feature = "multipart"), allow(dead_code))]
    pub(crate) max_file_bytes: u64,
    /// `[multipart] upload_dir`: the root every `part:save` resolves
    /// inside. `None` leaves `save` unavailable. Shared rather than
    /// cloned per request — it is set once at startup and never changes.
    #[cfg_attr(not(feature = "multipart"), allow(dead_code))]
    pub(crate) upload_root: Option<std::sync::Arc<std::path::PathBuf>>,
}

impl Default for FormLimits {
    fn default() -> Self {
        let defaults = crate::config::LimitsConfig::default();
        Self {
            max_parts: defaults.max_form_parts,
            max_field_bytes: defaults.max_field_bytes,
            max_file_bytes: defaults.max_file_bytes,
            upload_root: None,
        }
    }
}

impl LuaRequest {
    /// The whole body, read once and kept, so `req:form()`, `req:text()`
    /// and `req:json()` all see it whichever runs first.
    async fn whole_body(&mut self) -> mlua::Result<Bytes> {
        if let Some(cached) = &self.cached_body {
            return Ok(cached.clone());
        }
        let body = self
            .req
            .body_mut()
            .collect()
            .await
            .into_lua_err()?
            .to_bytes();
        self.cached_body = Some(body.clone());
        Ok(body)
    }

    /// A request as the dispatch path receives it, before routing: every
    /// other field starts at its pre-dispatch default (the handler fills
    /// in the configured limits and the router's parameters). The one
    /// constructor the live service, [`TestClient`](crate::testing::TestClient)
    /// and `nitr test`'s fake request share, so they cannot drift apart.
    pub(crate) fn synthetic(
        req: Request<IncomingBody>,
        peer_addr: SocketAddr,
        id: Arc<str>,
    ) -> Self {
        Self {
            peer_addr,
            tls: false,
            req,
            params: Vec::new(),
            id,
            // Replaced with the configured bounds by the handler.
            limits: Default::default(),
            cached_form: None,
            body_limit: u64::MAX,
            cached_body: None,
            body_consumed: false,
            valid: None,
            spool_dir: None,
        }
    }

    /// Caps this request's body at `limit` bytes *as it arrives*.
    ///
    /// The `Content-Length` check in
    /// [`Protection`](crate::protect::Protection) only sees what the client
    /// declared; a chunked body declares nothing and a dishonest one declares
    /// the wrong thing. This counts what actually shows up and fails the
    /// stream the moment it passes the ceiling, so an oversized upload is cut
    /// mid-flight instead of being buffered in full.
    ///
    /// The violations are also recorded in the returned flags, because by
    /// the time either failure surfaces it has crossed into Lua and become
    /// an opaque error value. The flags let the handler answer `413` (too
    /// large) or `408` (stalled) instead of a generic `500`.
    pub(crate) fn guard_body(
        &mut self,
        limit: u64,
        stall: Option<std::time::Duration>,
    ) -> BodyGuards {
        let guards = BodyGuards(Arc::new(body::BodyFlags::default()));
        // Recorded for `req:read(n)`'s clamp, so the bound is readable at
        // the point that allocates.
        self.body_limit = limit;
        let inner = std::mem::take(self.req.body_mut());
        let limited = LimitedBody {
            inner,
            limit,
            read: 0,
            flags: guards.0.clone(),
        };
        // The stall timer wraps the byte counter so its budget covers the
        // whole read; when disabled the counter is installed alone.
        *self.req.body_mut() = match stall {
            Some(budget) => StalledBody {
                inner: limited.boxed(),
                budget,
                deadline: None,
                flags: guards.0.clone(),
            }
            .boxed(),
            None => limited.boxed(),
        };
        guards
    }

    /// Releases the unread remainder of the body.
    ///
    /// The request outlives the response as a Lua userdata — unreachable,
    /// but not collected until the state's next GC — and with it hyper's
    /// `Incoming`, which keeps the exchange open on the connection. A
    /// handler that never read the body, or stopped half-way (an oversized
    /// upload), would otherwise stall that connection until an unrelated
    /// collection happened to run.
    pub(crate) fn discard_body(&mut self) {
        *self.req.body_mut() = BoxBody::default();
    }
}

/// Clamps the sized `req:read(n)` argument — a Lua-supplied `usize` — to
/// the effective body limit **plus one**.
///
/// The `+ 1` is what keeps `LimitedBody` able to trip. The limiter flags
/// `oversized` only once *cumulative* `read > limit` (`body.rs`), and the
/// handler turns that flag into the `413`. Clamped to `limit` exactly, the
/// read loop would stop the moment `buf.len() >= limit`, so an over-limit
/// body whose frames happen to sum to the limit at a frame boundary would
/// never be pulled one frame further, never trip the limiter, and get the
/// application's `200` instead of a `413` — and 1 MiB is a multiple of
/// typical frame sizes, so "happen to" means "usually". The one extra
/// frame is the one that errors; its bytes are never appended, so the
/// buffer still never exceeds `limit`.
fn clamp_want(want: usize, limit: u64) -> usize {
    // Saturating twice: `limit + 1` must not wrap at `u64::MAX`, and the
    // cast must not wrap on a 32-bit `usize`.
    let ceiling = usize::try_from(limit.saturating_add(1)).unwrap_or(usize::MAX);
    want.min(ceiling)
}

impl UserData for LuaRequest {
    fn add_fields<'lua, F: UserDataFields<Self>>(fields: &mut F) {
        fields.add_field_method_get("remote_addr", |_, req| Ok(req.peer_addr.to_string()));
        fields.add_field_method_get("method", |_, req| Ok(req.req.method().to_string()));
        fields.add_field_method_get("path", |_, req| Ok(req.req.uri().path().to_string()));
        fields.add_field_method_get("query", |lua, req| {
            // Query string parsed (and percent-decoded) into a table; for
            // repeated keys the last value wins.
            let table = lua.create_table()?;
            if let Some(query) = req.req.uri().query() {
                for (k, v) in url::form_urlencoded::parse(query.as_bytes()) {
                    table.set(k.as_ref(), v.as_ref())?;
                }
            }
            Ok(table)
        });
        fields.add_field_method_get("id", |lua, req| lua.create_string(&*req.id));
        fields.add_field_method_get("params", |lua, req| {
            // Path parameters captured by the router, e.g. `id` for a route
            // registered as `/users/:id`.
            let table = lua.create_table()?;
            for (k, v) in &req.params {
                table.set(k.as_str(), v.as_str())?;
            }
            Ok(table)
        });
        // An HTTP/1.1 request target is the path alone: the authority is
        // the client-sent `Host` header, the scheme the listener's.
        fields.add_field_method_get("uri", |lua, req| {
            let table = lua.create_table()?;
            let uri = req.req.uri();
            let scheme = match uri.scheme_str() {
                Some(scheme) => scheme,
                None if req.tls => "https",
                None => "http",
            };
            let authority = uri.authority().cloned().or_else(|| {
                req.req
                    .headers()
                    .get(hyper::header::HOST)?
                    .to_str()
                    .ok()?
                    .parse::<hyper::http::uri::Authority>()
                    .ok()
            });
            let default_port = if scheme == "https" { 443 } else { 80 };
            table.set("scheme", scheme)?;
            table.set("host", authority.as_ref().map_or("", |a| a.host()))?;
            table.set(
                "port",
                authority
                    .as_ref()
                    .map_or(0, |a| a.port_u16().unwrap_or(default_port)),
            )?;
            table.set("path", uri.path())?;
            table.set("authority", authority.as_ref().map_or("", |a| a.as_str()))?;
            table.set("query", uri.query().unwrap_or_default())?;
            Ok(table)
        });
        fields.add_field_method_get("headers", |lua, req| {
            // One value per name: for a repeated header the last value
            // wins. That collapse is a written decision, not an
            // accident, and each security-relevant name has its own
            // answer: `Authorization` never gets here repeated (two or
            // more are refused with a 400 in `Protection::check`, since
            // a collapsed credential can desync from a proxy in front);
            // `Cookie` is joined below, because a joined cookie string
            // is still a valid cookie string; `X-Forwarded-For` is only
            // trusted when `[rate_limit] trust_forwarded_for` says so,
            // and the limiter parses the header itself rather than this
            // table; `Content-Length` and `Transfer-Encoding` are
            // enforced by hyper before a request exists. A non-UTF-8
            // value becomes `""` — fail-closed, indistinguishable from
            // absent, and kept that way because distinguishing the two
            // would change the type of every header value a script reads.
            let headers = req.req.headers();
            let table = lua.create_table()?;
            for (k, v) in headers.iter() {
                table.set(k.as_str(), v.to_str().unwrap_or_default())?;
            }
            Ok(table)
        });
        // req.valid — `{ body, query, params, headers }` as the route's
        // `input` declaration validated them; nil on routes without one.
        fields.add_field_method_get("valid", |_, req| Ok(req.valid.clone()));
        fields.add_field_method_get("cookies", |_, req| {
            // All `Cookie` headers, joined so multi-header clients work.
            let header = req
                .req
                .headers()
                .get_all(hyper::header::COOKIE)
                .iter()
                .filter_map(|v| v.to_str().ok())
                .collect::<Vec<_>>()
                .join("; ");
            Ok(nitr_std::RequestCookies::parse(&header))
        });
    }

    fn add_methods<'lua, M: UserDataMethods<Self>>(methods: &mut M) {
        // Returns the best match among the given media types for the
        // request's `Accept` header, or nil when none is acceptable.
        methods.add_method("accepts", |_, req, offers: mlua::Variadic<String>| {
            let accept = req
                .req
                .headers()
                .get(hyper::header::ACCEPT)
                .and_then(|v| v.to_str().ok())
                .unwrap_or("*/*");
            let refs: Vec<&str> = offers.iter().map(String::as_str).collect();
            Ok(nitr_std::best_match(accept, &refs).map(|i| offers[i].clone()))
        });

        // req:read()  — the next chunk as it arrives off the socket.
        // req:read(n) — at least n bytes, or fewer at the end of the body.
        //
        // The size argument is what lets a handler process an upload larger
        // than its own memory limit: the request-side mirror of a streaming
        // response. `nil` marks the end of the body.
        // `n` is taken as a full Lua integer, not `usize`: a Lua integer
        // is 64-bit on every platform while `usize` is not, and on a
        // 32-bit target a script asking for more than 4 GiB would fail
        // the conversion — an error on one platform for what is a plain
        // "read everything" on another. The saturation below (with the
        // clamp after it) keeps the pointer width invisible to scripts.
        methods.add_async_method_mut("read", |lua, mut req, n: Option<i64>| async move {
            let body_limit = req.body_limit;
            let reader = req.req.body_mut();
            let Some(want) = n else {
                while let Some(frame) = reader.frame().await {
                    // Trailer frames carry no data; keep reading.
                    if let Some(bytes) = frame.into_lua_err()?.data_ref() {
                        return Some(lua.create_string(bytes)).transpose();
                    }
                }
                return Ok(None);
            };

            if want < 0 {
                return Err(mlua::Error::RuntimeError(format!(
                    "req:read(n) requires a non-negative size, got {want}"
                )));
            }
            // The limiter installed by `guard_body` already bounds what the
            // body can deliver; the clamp makes that bound local and keeps
            // the loop's termination readable here, without trusting `want`.
            let want = clamp_want(usize::try_from(want).unwrap_or(usize::MAX), body_limit);
            let mut buf = Vec::new();
            while buf.len() < want {
                let Some(frame) = reader.frame().await else {
                    break;
                };
                if let Some(bytes) = frame.into_lua_err()?.data_ref() {
                    buf.extend_from_slice(bytes);
                }
            }
            if buf.is_empty() {
                return Ok(None);
            }
            Some(lua.create_string(buf)).transpose()
        });

        // req:form() — an `application/x-www-form-urlencoded` body as a
        // table. Percent-decoding and `+`-as-space are HTTP details worth
        // exactly one careful implementation, not one per application.
        // Repeated keys keep the last value, matching `req.query`.
        methods.add_async_method_mut("form", |lua, mut req, ()| async move {
            if req.cached_form.is_none() {
                let body = req.whole_body().await?;
                req.cached_form = Some(
                    url::form_urlencoded::parse(&body)
                        .map(|(k, v)| (k.into_owned(), v.into_owned()))
                        .collect(),
                );
            }
            let table = lua.create_table()?;
            for (k, v) in req.cached_form.as_deref().unwrap_or_default() {
                table.set(k.as_str(), v.as_str())?;
            }
            Ok(table)
        });

        // req:multipart(fn) — invokes `fn` once per part, in arrival order.
        // See `crate::multipart` for why parts stream instead of being
        // collected. Returns the number of parts seen.
        #[cfg(feature = "multipart")]
        methods.add_async_method_mut("multipart", |lua, mut req, cb: mlua::Function| async move {
            if req.body_consumed {
                return Err(mlua::Error::RuntimeError(
                    "req:multipart() cannot run on a route whose `input` already consumed the \
                     body: read the validated files from req.valid instead"
                        .into(),
                ));
            }
            let content_type = req
                .req
                .headers()
                .get(hyper::header::CONTENT_TYPE)
                .and_then(|v| v.to_str().ok())
                .map(str::to_string);
            let boundary = crate::multipart::boundary(content_type.as_deref())?;
            let limits = req.limits.clone();

            let body = std::mem::take(req.req.body_mut());
            let mut parser = multer::Multipart::new(body.into_data_stream(), boundary);

            let mut count = 0usize;
            loop {
                let Some(field) = parser.next_field().await.into_lua_err()? else {
                    break;
                };
                count += 1;
                if count > limits.max_parts {
                    return Err(crate::multipart::too_many_parts(limits.max_parts));
                }
                let part = lua.create_userdata(crate::multipart::LuaPart::new(
                    field,
                    limits.max_field_bytes,
                    limits.max_file_bytes,
                    limits.upload_root.clone(),
                ))?;
                let outcome = cb.call_async::<()>(&part).await;

                // The parser cannot advance while a field is alive, so the
                // part is reclaimed and drained whatever the callback did
                // with it — including nothing, and including failing.
                if let Ok(part) = part.borrow::<crate::multipart::LuaPart>()
                    && let Some(mut field) = part.reclaim()
                {
                    while field.chunk().await.into_lua_err()?.is_some() {}
                }
                outcome?;
            }
            Ok(count)
        });

        // req:fresh(etag, last_modified?) — whether the client's cached
        // copy is still current. Rust compares the validators; Lua decides
        // what identifies the resource, which is application knowledge.
        methods.add_method(
            "fresh",
            |_, req, (etag, last_modified): (Option<String>, Option<i64>)| {
                Ok(is_fresh(req.req.headers(), etag.as_deref(), last_modified))
            },
        );

        methods.add_async_method_mut("text", |lua, mut req, ()| async move {
            lua.create_string(req.whole_body().await?)
        });

        methods.add_async_method_mut("json", |lua, mut req, ()| async move {
            let buf = req.whole_body().await?;
            if buf.is_empty() {
                return Err(mlua::Error::external(
                    "Unexpected end of JSON input, probably request body is empty or already consumed",
                ));
            }
            let json = serde_json::from_slice::<SerdeValue>(&buf).into_lua_err()?;
            lua.to_value(&json)
        });
    }
}