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
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
// 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>

//! The serving half of [`Server`]: the accept loop with its connection
//! cap and TLS handshake, zero-downtime reloads, and the graceful drain.

use std::future::Future;
use std::sync::Arc;
use std::sync::atomic::Ordering;
use std::time::Duration;

use hyper::server::conn::http1;
use hyper_util::rt::{TokioIo, TokioTimer};
use hyper_util::server::graceful::GracefulShutdown;
use tokio::net::TcpListener;
use tokio::sync::Semaphore;

use crate::service::Svc;
use nitr_core::{Error, Result};

use super::Server;
use super::pool::current_pool;

impl Server {
    /// Serves until a shutdown signal arrives, then drains gracefully.
    ///
    /// The signal contract:
    ///
    /// | Signal | Meaning |
    /// | ------ | ------- |
    /// | `SIGTERM` | Graceful shutdown (what containers and systemd send) |
    /// | `SIGINT` | Graceful shutdown (ctrl-c) |
    /// | `SIGHUP` | Reload the runtime pool, keeping connections alive |
    ///
    /// On Windows only ctrl-c is available; the others are not wired.
    pub async fn serve(self) -> Result {
        self.serve_with_shutdown(shutdown_signal()).await
    }

    /// Serves until the given future resolves, then shuts down gracefully:
    /// the listener stops accepting and in-flight requests get a grace
    /// period to complete.
    pub async fn serve_with_shutdown(mut self, shutdown: impl Future<Output = ()>) -> Result {
        // The *slot*, not the acceptor: a `SIGHUP` swaps renewed TLS
        // material into `self.tls`, and snapshotting the acceptor here
        // would keep handing out the stale one — a hot reload that logs
        // success and does nothing. Each accepted connection loads the
        // current acceptor from this handle instead.
        #[cfg(feature = "tls")]
        let tls_slot = self.tls.clone();
        let listener = match self.listener.take() {
            // A pre-bound listener arrives blocking; tokio requires
            // non-blocking before it will adopt it.
            Some(std_listener) => std_listener
                .set_nonblocking(true)
                .and_then(|()| TcpListener::from_std(std_listener))
                .map_err(|err| {
                    Error::Config(format!("unable to adopt the given listener: {err}"))
                })?,
            None => TcpListener::bind(self.cfg.listen).await.map_err(|err| {
                Error::Config(format!("unable to listen on {}: {err}", self.cfg.listen))
            })?,
        };
        let graceful = GracefulShutdown::new();
        let mut shutdown = std::pin::pin!(shutdown);

        // SIGHUP triggers a zero-downtime pool swap (Unix only; the
        // channel simply stays silent elsewhere). The stream was taken at
        // build, so the signal has been owned since before a pidfile could
        // name this process.
        let (reload_tx, mut reload_rx) = tokio::sync::mpsc::channel::<()>(1);
        #[cfg(unix)]
        if let Some(mut hangup) = self.reload_signal.take() {
            let tx = reload_tx.clone();
            tokio::spawn(async move {
                while hangup.recv().await.is_some() {
                    let _ = tx.try_send(());
                }
            });
        }
        // Dev mode: a notify-based watcher feeds the same reload channel a
        // SIGHUP does, so a save rebuilds the pool immediately instead of
        // being discovered by the next request.
        let _watcher = self
            .cfg
            .dev_mode
            .then(|| crate::watch::spawn(&self.cfg, &[], reload_tx.clone()))
            .flatten();
        let _reload_tx = reload_tx;

        // The listener's own address, not `cfg.listen`: with a pre-bound
        // listener (or port 0) the config value is not where we serve.
        let bound = listener.local_addr().unwrap_or(self.cfg.listen);
        // The scheme is part of what an operator checks this line for:
        // saying `http://` on a TLS listener would send the first curl of
        // every deployment to the wrong URL.
        let scheme = if self.cfg.tls.enabled {
            "https"
        } else {
            "http"
        };
        tracing::info!(
            "listening on {scheme}://{} with {} Lua state(s)",
            bound,
            current_pool(&self.pool).size()
        );
        if let Some(warning) = self.cfg.streams_warning() {
            tracing::warn!("{warning}");
        }

        // hyper enforces a floor of 8 KiB on its read buffer.
        let max_buf_size = self.cfg.limits.max_header_bytes.max(8 * 1024);
        // Complete-headers deadline (`[limits] header_read_ms`); `None`
        // disables it. Enforced by hyper per connection: an expired one
        // is simply closed — no request exists yet to answer. Under TLS it
        // also bounds the handshake: the same question ("how long may a
        // client take to say what it wants?"), asked one layer down.
        let header_read = match self.cfg.limits.header_read_ms {
            0 => None,
            ms => Some(Duration::from_millis(ms)),
        };
        // The handshake deadline is never `None`: `[tls] handshake_ms`,
        // or `min(header_read_ms, 10s)` when unset — including when
        // `header_read_ms` is `0`, the spelling that disables hyper's
        // header deadline but must not unbound the handshake (a stalled
        // `ClientHello` holds a connection slot nothing else reclaims).
        #[cfg(feature = "tls")]
        let handshake_deadline = handshake_deadline(&self.cfg.tls, header_read);

        // Health endpoints: on the main listener by default, or on their
        // own address so the probes stay off the public port.
        let health_state = self.cfg.health.enabled.then(|| {
            Arc::new(crate::health::HealthState {
                cfg: self.cfg.health.clone(),
                ready: self.ready.clone(),
            })
        });
        // The probe listener carries the main listener's guards — its own
        // (smaller) connection cap, and the same header deadline and read
        // buffer, because "how long may a client take to say what it
        // wants?" has one answer per process.
        let probe_guards = crate::health::ProbeGuards {
            max_connections: self.cfg.health.max_connections,
            header_read,
            max_buf_size,
        };
        // The probe transport is a decision, not an accident: the probe
        // port stays plaintext even under `[tls]`, because a prober that
        // must complete a TLS handshake fails exactly when liveness must
        // still answer — during certificate trouble. The startup line says
        // so instead of implying it with a bare `http://`. One closure
        // serves both listener branches, so their wording cannot drift
        // apart.
        let tls_enabled = self.cfg.tls.enabled;
        let log_probe_endpoint = move |addr: &str| {
            if tls_enabled {
                tracing::info!(
                    "health endpoints on http://{addr} (plaintext; TLS terminates on the \
                     main listener only)"
                );
            } else {
                tracing::info!("health endpoints on http://{addr}");
            }
        };
        let mut probe_task = None;
        let mut probe_stop = None;
        let main_health = match (&health_state, self.health_listener.take()) {
            // An adopted probe listener wins over binding `[health] bind`
            // ourselves — the same rule the main listener follows — so the
            // port was never released between choosing it and serving.
            (Some(state), Some(std_listener)) => {
                let probe_listener = std_listener
                    .set_nonblocking(true)
                    .and_then(|()| TcpListener::from_std(std_listener))
                    .map_err(|err| {
                        Error::Config(format!("unable to adopt the given health listener: {err}"))
                    })?;
                let addr = probe_listener
                    .local_addr()
                    .map(|a| a.to_string())
                    .unwrap_or_else(|_| "<unknown>".into());
                log_probe_endpoint(&addr);
                let (stop_tx, stop_rx) = tokio::sync::oneshot::channel();
                probe_stop = Some(stop_tx);
                probe_task = Some(tokio::spawn(crate::health::serve_probes(
                    probe_listener,
                    state.clone(),
                    probe_guards,
                    stop_rx,
                )));
                None
            }
            (Some(state), None) => match self.cfg.health.bind {
                Some(addr) => {
                    let probe_listener = TcpListener::bind(addr).await.map_err(|err| {
                        Error::Config(format!("unable to bind [health] bind = {addr}: {err}"))
                    })?;
                    // The bound address, not the configured one: with a
                    // port-0 bind the config value is not where we serve —
                    // the same rule the main listener's line follows.
                    let bound = probe_listener
                        .local_addr()
                        .map(|a| a.to_string())
                        .unwrap_or_else(|_| addr.to_string());
                    log_probe_endpoint(&bound);
                    let (stop_tx, stop_rx) = tokio::sync::oneshot::channel();
                    probe_stop = Some(stop_tx);
                    probe_task = Some(tokio::spawn(crate::health::serve_probes(
                        probe_listener,
                        state.clone(),
                        probe_guards,
                        stop_rx,
                    )));
                    None
                }
                None => Some(state.clone()),
            },
            (None, _) => None,
        };

        // Connection cap: the listener stops accepting while at the limit
        // instead of queueing unbounded connections.
        let conn_slots = Arc::new(Semaphore::new(self.cfg.limits.max_connections.max(1)));
        // Identical for every connection, so it is built once and cloned
        // into each task rather than rebuilt per accept.
        let http = {
            let mut builder = http1::Builder::new();
            builder
                .timer(TokioTimer::new())
                .header_read_timeout(header_read)
                .max_buf_size(max_buf_size);
            builder
        };

        // Set by the shutdown signal: the listener keeps serving until it
        // fires, with readiness already answering 503.
        let mut draining: Option<std::pin::Pin<Box<tokio::time::Sleep>>> = None;
        loop {
            tokio::select! {
                accepted = async {
                    // Wait for a free connection slot before accepting; the
                    // whole future is dropped (releasing nothing) on
                    // shutdown. The semaphore is never closed.
                    // Invariant: acquire fails only on a closed
                    // semaphore, and nothing ever closes this one.
                    #[allow(clippy::expect_used)]
                    let permit = conn_slots
                        .clone()
                        .acquire_owned()
                        .await
                        .expect("connection semaphore is never closed");
                    (permit, listener.accept().await)
                } => {
                    let (permit, accepted) = accepted;
                    let (stream, peer_addr) = match accepted {
                        Ok(x) => x,
                        Err(err) => {
                            accept_error_backoff("listener", &err).await;
                            continue;
                        }
                    };

                    // Small responses must not wait on Nagle's algorithm.
                    let _ = stream.set_nodelay(true);

                    let svc = Svc::new(
                        self.pool.clone(),
                        self.streams.clone(),
                        self.protection.clone(),
                        main_health.clone(),
                        peer_addr,
                        tls_enabled,
                    );
                    let http = http.clone();
                    // Subscribed here rather than inside the task:
                    // `watcher()` takes its version at accept time, so a
                    // drain that starts while a handshake is still running
                    // is seen by this connection instead of arriving one
                    // version late.
                    let watcher = graceful.watcher();
                    // Loaded per accept, so a reload's swap is visible to
                    // the next connection; the clone is an `Arc` handle.
                    #[cfg(feature = "tls")]
                    let acceptor = current_acceptor(&tls_slot);
                    tokio::spawn(async move {
                        // Held until the connection closes.
                        let _permit = permit;
                        // The TLS handshake happens HERE, in the
                        // connection's own task — never in the accept loop
                        // above. A `ClientHello` that arrives one byte a
                        // minute then costs this connection and nothing
                        // else; handshaking before the spawn would let one
                        // hostile client stall every other.
                        #[cfg(feature = "tls")]
                        if let Some(acceptor) = acceptor {
                            let Some(stream) =
                                tls_handshake(&acceptor, stream, handshake_deadline, peer_addr)
                                    .await
                            else {
                                return;
                            };
                            let conn = http.serve_connection(TokioIo::new(stream), svc);
                            if let Err(err) = watcher.watch(conn).await {
                                // `debug`, not `error`, and the plaintext
                                // arm below stays at `error` on purpose.
                                // TLS adds a shutdown handshake that a
                                // client is free to skip: curl and every
                                // browser routinely close the socket
                                // without a `close_notify`, which arrives
                                // here as "error shutting down
                                // connection". At `error` that is one log
                                // line per request on a healthy server —
                                // noise that buries the failures an
                                // operator is actually looking for.
                                tracing::debug!(
                                    "TLS connection from {peer_addr} ended with: {err}"
                                );
                            }
                            return;
                        }
                        let conn = http.serve_connection(TokioIo::new(stream), svc);
                        if let Err(err) = watcher.watch(conn).await {
                            tracing::error!("error serving connection: {err}");
                        }
                    });
                }
                Some(()) = reload_rx.recv() => self.reload(),
                () = &mut shutdown, if draining.is_none() => {
                    // Step 1: stop advertising readiness *before* requests
                    // can fail, so a load balancer drains us on its own
                    // terms. On the main listener that is only observable
                    // while it still accepts, hence the delay.
                    self.ready.store(false, Ordering::Relaxed);
                    let delay = self.cfg.readiness_delay();
                    if delay.is_zero() {
                        break;
                    }
                    tracing::info!("draining: readiness answers 503, still serving for {delay:?}");
                    draining = Some(Box::pin(tokio::time::sleep(delay)));
                }
                () = async {
                    match draining.as_mut() {
                        Some(delay) => delay.await,
                        None => std::future::pending().await,
                    }
                }, if draining.is_some() => break,
            }
        }

        // Step 2: the listener is dropped and no new connection is taken.
        // A separate probe listener stays up through the drain, readiness
        // observable as "draining" while it happens, and dies with the
        // process. Responses issued from here on carry `Connection: close`.
        drop(listener);

        let grace = self.cfg.shutdown.grace();
        let total = self.cfg.shutdown.total_grace();
        tracing::info!(
            "draining: waiting up to {grace:?} for in-flight requests \
             ({stream_grace:?} more for streaming bodies)",
            stream_grace = total.saturating_sub(grace),
        );

        // Steps 3-5: in-flight requests finish, idle keep-alive connections
        // close (hyper marks them `Connection: close` as it drains), and the
        // pool states they hold come back with them. Streaming bodies get
        // the extra budget before anything is cut.
        // Step 6 follows from the drain: dropping the watcher (and with it
        // the last connection tasks) closes every Lua state, which
        // checkpoints the SQLite WAL of each connection.
        let deadline = drain_deadline(&self.streams, self.max_streams, grace, total);
        let drained = tokio::select! {
            _ = graceful.shutdown() => true,
            _ = deadline => false,
        };

        // The probe listener stayed up through the drain — readiness had
        // to be observable as "draining" while it happened — and drains
        // now: `serve_probes` watches every in-flight probe connection
        // with its own `GracefulShutdown`, so stopping it finishes open
        // probe answers instead of severing them. The deadline is tight
        // because a probe response is one fixed-body round trip.
        if let Some(mut task) = probe_task {
            if let Some(stop) = probe_stop.take() {
                let _ = stop.send(());
            }
            if tokio::time::timeout(Duration::from_secs(1), &mut task)
                .await
                .is_err()
            {
                // Aborting kills the accept/drain task only; the
                // per-connection tasks are independent spawns and simply
                // run to completion on their own (in the binary, until
                // process exit moments later).
                tracing::warn!("probe listener did not drain within 1s, abandoning the drain");
                task.abort();
            }
        }

        if drained {
            tracing::info!("drained cleanly, shutting down");
            Ok(())
        } else {
            // A truncated shutdown means somebody's request was cut. Report
            // it as an error so a supervisor can surface it, rather than
            // exiting 0 and hiding it.
            tracing::warn!("drain deadline of {total:?} expired, aborting remaining connections");
            Err(Error::ShutdownTimeout)
        }
    }
}

/// How long an accept loop pauses after a non-client accept failure.
///
/// Fixed rather than exponential on purpose: the failure this exists for
/// is descriptor exhaustion (`EMFILE`/`ENFILE`), which clears when a
/// descriptor frees, not on a schedule — and exponential backoff adds
/// state to a loop whose whole virtue is having none.
const ACCEPT_ERROR_BACKOFF: Duration = Duration::from_millis(50);

/// Classifies, logs, and (for one class) backs off one `accept()` failure.
/// Both accept loops — the main listener's and the probe listener's — go
/// through here, so the level split and the delay cannot drift apart.
///
/// Exactly two classes, deliberately. `ConnectionAborted`,
/// `ConnectionReset` and `Interrupted` are client-caused and self-clearing
/// (the peer gave up between the kernel completing the handshake and this
/// process accepting it): `debug`, retry at once. *Everything else* is
/// treated as resource trouble and paced: Rust has no stable `ErrorKind`
/// for `EMFILE`/`ENFILE` — they surface as an uncategorized kind plus a
/// raw OS error — so they cannot be named directly, and without the sleep
/// a persistent one busy-spins the accept loop at 100% CPU. If this match
/// ever grows a third case, it has stopped being insurance.
pub(crate) async fn accept_error_backoff(listener: &str, err: &std::io::Error) {
    use std::io::ErrorKind;
    match err.kind() {
        ErrorKind::ConnectionAborted | ErrorKind::ConnectionReset | ErrorKind::Interrupted => {
            tracing::debug!("{listener}: client gone before accept: {err}");
        }
        _ => {
            tracing::warn!("{listener}: failed to accept connection: {err}");
            tokio::time::sleep(ACCEPT_ERROR_BACKOFF).await;
        }
    }
}

/// One connection's TLS handshake, run inside that connection's own task.
///
/// Returns `None` when the connection is finished with — the stream is
/// dropped, closing it, and nothing else is affected. Failures are logged
/// at `debug`, not `error`: on a public port a failed handshake is
/// ordinary traffic (a plaintext client, a scanner, a client with no
/// cipher suite in common), and an `error` per probe would drown the log
/// an operator actually needs.
///
/// `deadline` is `[tls] handshake_ms` (or its `min(header_read_ms, 10s)`
/// default) — a plain `Duration`, not an `Option`, so the bound cannot be
/// switched off by any spelling: without one a client can hold a
/// connection slot — and, during a drain, the graceful watcher — open
/// forever by never finishing its `ClientHello`.
#[cfg(feature = "tls")]
async fn tls_handshake(
    acceptor: &tokio_rustls::TlsAcceptor,
    stream: tokio::net::TcpStream,
    deadline: Duration,
    peer: std::net::SocketAddr,
) -> Option<tokio_rustls::server::TlsStream<tokio::net::TcpStream>> {
    let handshake = match tokio::time::timeout(deadline, acceptor.accept(stream)).await {
        Ok(handshake) => handshake,
        Err(_) => {
            tracing::debug!("TLS handshake from {peer} did not finish within {deadline:?}");
            return None;
        }
    };
    match handshake {
        Ok(stream) => Some(stream),
        Err(err) => {
            tracing::debug!("TLS handshake from {peer} failed: {err}");
            None
        }
    }
}

/// The effective handshake deadline. Validation refuses `handshake_ms =
/// 0`, but an embedder can hand a config over by value — a zero here
/// falls back to the default rather than meaning "unbounded".
#[cfg(feature = "tls")]
fn handshake_deadline(tls: &crate::config::TlsConfig, header_read: Option<Duration>) -> Duration {
    /// Long enough for any honest client on any honest network; far
    /// short of forever.
    const DEFAULT_HANDSHAKE: Duration = Duration::from_secs(10);
    match tls.handshake_ms {
        Some(ms) if ms > 0 => Duration::from_millis(ms),
        _ => header_read.map_or(DEFAULT_HANDSHAKE, |d| d.min(DEFAULT_HANDSHAKE)),
    }
}

/// The acceptor currently in the slot (poisoning is unreachable: the lock
/// is only ever held to clone or replace the acceptor).
#[cfg(feature = "tls")]
fn current_acceptor(
    slot: &Arc<std::sync::RwLock<Option<tokio_rustls::TlsAcceptor>>>,
) -> Option<tokio_rustls::TlsAcceptor> {
    slot.read()
        .map(|s| s.clone())
        .unwrap_or_else(|e| e.into_inner().clone())
}

/// Resolves when the drain has run out of time.
///
/// Ordinary requests get `grace`. A streaming body legitimately outlives any
/// request-shaped budget, so when one is still live at that point the drain
/// waits until `total` instead — the extra budget is spent only on the case
/// it exists for, rather than delaying every shutdown by it.
async fn drain_deadline(streams: &Semaphore, max_streams: usize, grace: Duration, total: Duration) {
    tokio::time::sleep(grace).await;
    if streams.available_permits() < max_streams {
        tracing::info!("streaming bodies still live, extending the drain to {total:?}");
        tokio::time::sleep(total.saturating_sub(grace)).await;
    }
}

/// Resolves when the process is asked to stop: `SIGTERM` (containers and
/// systemd) or `SIGINT` (ctrl-c). On non-Unix targets only ctrl-c exists.
async fn shutdown_signal() {
    #[cfg(unix)]
    {
        use tokio::signal::unix::{SignalKind, signal};
        let mut term = match signal(SignalKind::terminate()) {
            Ok(sig) => sig,
            Err(err) => {
                tracing::warn!("failed to install the SIGTERM handler: {err}");
                let _ = tokio::signal::ctrl_c().await;
                return;
            }
        };
        tokio::select! {
            _ = term.recv() => tracing::info!("received SIGTERM"),
            _ = tokio::signal::ctrl_c() => tracing::info!("received SIGINT"),
        }
    }
    #[cfg(not(unix))]
    {
        let _ = tokio::signal::ctrl_c().await;
        tracing::info!("received ctrl-c");
    }
}