Skip to main content

nitr_http/server/
serve.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2// This file is part of Nitr.
3// See https://nitrweb.com/ for more information
4// Copyright (C) 2024-present Jose Quintana <joseluisq.net>
5
6//! The serving half of [`Server`]: the accept loop with its connection
7//! cap and TLS handshake, zero-downtime reloads, and the graceful drain.
8
9use std::future::Future;
10use std::sync::Arc;
11use std::sync::atomic::Ordering;
12use std::time::Duration;
13
14use hyper::server::conn::http1;
15use hyper_util::rt::{TokioIo, TokioTimer};
16use hyper_util::server::graceful::GracefulShutdown;
17use tokio::net::TcpListener;
18use tokio::sync::Semaphore;
19
20use crate::service::Svc;
21use nitr_core::{Error, Result};
22
23use super::Server;
24use super::pool::current_pool;
25
26impl Server {
27    /// Serves until a shutdown signal arrives, then drains gracefully.
28    ///
29    /// The signal contract:
30    ///
31    /// | Signal | Meaning |
32    /// | ------ | ------- |
33    /// | `SIGTERM` | Graceful shutdown (what containers and systemd send) |
34    /// | `SIGINT` | Graceful shutdown (ctrl-c) |
35    /// | `SIGHUP` | Reload the runtime pool, keeping connections alive |
36    ///
37    /// On Windows only ctrl-c is available; the others are not wired.
38    pub async fn serve(self) -> Result {
39        self.serve_with_shutdown(shutdown_signal()).await
40    }
41
42    /// Serves until the given future resolves, then shuts down gracefully:
43    /// the listener stops accepting and in-flight requests get a grace
44    /// period to complete.
45    pub async fn serve_with_shutdown(mut self, shutdown: impl Future<Output = ()>) -> Result {
46        // The *slot*, not the acceptor: a `SIGHUP` swaps renewed TLS
47        // material into `self.tls`, and snapshotting the acceptor here
48        // would keep handing out the stale one — a hot reload that logs
49        // success and does nothing. Each accepted connection loads the
50        // current acceptor from this handle instead.
51        #[cfg(feature = "tls")]
52        let tls_slot = self.tls.clone();
53        let listener = match self.listener.take() {
54            // A pre-bound listener arrives blocking; tokio requires
55            // non-blocking before it will adopt it.
56            Some(std_listener) => std_listener
57                .set_nonblocking(true)
58                .and_then(|()| TcpListener::from_std(std_listener))
59                .map_err(|err| {
60                    Error::Config(format!("unable to adopt the given listener: {err}"))
61                })?,
62            None => TcpListener::bind(self.cfg.listen).await.map_err(|err| {
63                Error::Config(format!("unable to listen on {}: {err}", self.cfg.listen))
64            })?,
65        };
66        let graceful = GracefulShutdown::new();
67        let mut shutdown = std::pin::pin!(shutdown);
68
69        // SIGHUP triggers a zero-downtime pool swap (Unix only; the
70        // channel simply stays silent elsewhere). The stream was taken at
71        // build, so the signal has been owned since before a pidfile could
72        // name this process.
73        let (reload_tx, mut reload_rx) = tokio::sync::mpsc::channel::<()>(1);
74        #[cfg(unix)]
75        if let Some(mut hangup) = self.reload_signal.take() {
76            let tx = reload_tx.clone();
77            tokio::spawn(async move {
78                while hangup.recv().await.is_some() {
79                    let _ = tx.try_send(());
80                }
81            });
82        }
83        // Dev mode: a notify-based watcher feeds the same reload channel a
84        // SIGHUP does, so a save rebuilds the pool immediately instead of
85        // being discovered by the next request.
86        let _watcher = self
87            .cfg
88            .dev_mode
89            .then(|| crate::watch::spawn(&self.cfg, &[], reload_tx.clone()))
90            .flatten();
91        let _reload_tx = reload_tx;
92
93        // The listener's own address, not `cfg.listen`: with a pre-bound
94        // listener (or port 0) the config value is not where we serve.
95        let bound = listener.local_addr().unwrap_or(self.cfg.listen);
96        // The scheme is part of what an operator checks this line for:
97        // saying `http://` on a TLS listener would send the first curl of
98        // every deployment to the wrong URL.
99        let scheme = if self.cfg.tls.enabled {
100            "https"
101        } else {
102            "http"
103        };
104        tracing::info!(
105            "listening on {scheme}://{} with {} Lua state(s)",
106            bound,
107            current_pool(&self.pool).size()
108        );
109        if let Some(warning) = self.cfg.streams_warning() {
110            tracing::warn!("{warning}");
111        }
112
113        // hyper enforces a floor of 8 KiB on its read buffer.
114        let max_buf_size = self.cfg.limits.max_header_bytes.max(8 * 1024);
115        // Complete-headers deadline (`[limits] header_read_ms`); `None`
116        // disables it. Enforced by hyper per connection: an expired one
117        // is simply closed — no request exists yet to answer. Under TLS it
118        // also bounds the handshake: the same question ("how long may a
119        // client take to say what it wants?"), asked one layer down.
120        let header_read = match self.cfg.limits.header_read_ms {
121            0 => None,
122            ms => Some(Duration::from_millis(ms)),
123        };
124        // The handshake deadline is never `None`: `[tls] handshake_ms`,
125        // or `min(header_read_ms, 10s)` when unset — including when
126        // `header_read_ms` is `0`, the spelling that disables hyper's
127        // header deadline but must not unbound the handshake (a stalled
128        // `ClientHello` holds a connection slot nothing else reclaims).
129        #[cfg(feature = "tls")]
130        let handshake_deadline = handshake_deadline(&self.cfg.tls, header_read);
131
132        // Health endpoints: on the main listener by default, or on their
133        // own address so the probes stay off the public port.
134        let health_state = self.cfg.health.enabled.then(|| {
135            Arc::new(crate::health::HealthState {
136                cfg: self.cfg.health.clone(),
137                ready: self.ready.clone(),
138            })
139        });
140        // The probe listener carries the main listener's guards — its own
141        // (smaller) connection cap, and the same header deadline and read
142        // buffer, because "how long may a client take to say what it
143        // wants?" has one answer per process.
144        let probe_guards = crate::health::ProbeGuards {
145            max_connections: self.cfg.health.max_connections,
146            header_read,
147            max_buf_size,
148        };
149        // The probe transport is a decision, not an accident: the probe
150        // port stays plaintext even under `[tls]`, because a prober that
151        // must complete a TLS handshake fails exactly when liveness must
152        // still answer — during certificate trouble. The startup line says
153        // so instead of implying it with a bare `http://`. One closure
154        // serves both listener branches, so their wording cannot drift
155        // apart.
156        let tls_enabled = self.cfg.tls.enabled;
157        let log_probe_endpoint = move |addr: &str| {
158            if tls_enabled {
159                tracing::info!(
160                    "health endpoints on http://{addr} (plaintext; TLS terminates on the \
161                     main listener only)"
162                );
163            } else {
164                tracing::info!("health endpoints on http://{addr}");
165            }
166        };
167        let mut probe_task = None;
168        let mut probe_stop = None;
169        let main_health = match (&health_state, self.health_listener.take()) {
170            // An adopted probe listener wins over binding `[health] bind`
171            // ourselves — the same rule the main listener follows — so the
172            // port was never released between choosing it and serving.
173            (Some(state), Some(std_listener)) => {
174                let probe_listener = std_listener
175                    .set_nonblocking(true)
176                    .and_then(|()| TcpListener::from_std(std_listener))
177                    .map_err(|err| {
178                        Error::Config(format!("unable to adopt the given health listener: {err}"))
179                    })?;
180                let addr = probe_listener
181                    .local_addr()
182                    .map(|a| a.to_string())
183                    .unwrap_or_else(|_| "<unknown>".into());
184                log_probe_endpoint(&addr);
185                let (stop_tx, stop_rx) = tokio::sync::oneshot::channel();
186                probe_stop = Some(stop_tx);
187                probe_task = Some(tokio::spawn(crate::health::serve_probes(
188                    probe_listener,
189                    state.clone(),
190                    probe_guards,
191                    stop_rx,
192                )));
193                None
194            }
195            (Some(state), None) => match self.cfg.health.bind {
196                Some(addr) => {
197                    let probe_listener = TcpListener::bind(addr).await.map_err(|err| {
198                        Error::Config(format!("unable to bind [health] bind = {addr}: {err}"))
199                    })?;
200                    // The bound address, not the configured one: with a
201                    // port-0 bind the config value is not where we serve —
202                    // the same rule the main listener's line follows.
203                    let bound = probe_listener
204                        .local_addr()
205                        .map(|a| a.to_string())
206                        .unwrap_or_else(|_| addr.to_string());
207                    log_probe_endpoint(&bound);
208                    let (stop_tx, stop_rx) = tokio::sync::oneshot::channel();
209                    probe_stop = Some(stop_tx);
210                    probe_task = Some(tokio::spawn(crate::health::serve_probes(
211                        probe_listener,
212                        state.clone(),
213                        probe_guards,
214                        stop_rx,
215                    )));
216                    None
217                }
218                None => Some(state.clone()),
219            },
220            (None, _) => None,
221        };
222
223        // Connection cap: the listener stops accepting while at the limit
224        // instead of queueing unbounded connections.
225        let conn_slots = Arc::new(Semaphore::new(self.cfg.limits.max_connections.max(1)));
226        // Identical for every connection, so it is built once and cloned
227        // into each task rather than rebuilt per accept.
228        let http = {
229            let mut builder = http1::Builder::new();
230            builder
231                .timer(TokioTimer::new())
232                .header_read_timeout(header_read)
233                .max_buf_size(max_buf_size);
234            builder
235        };
236
237        // Set by the shutdown signal: the listener keeps serving until it
238        // fires, with readiness already answering 503.
239        let mut draining: Option<std::pin::Pin<Box<tokio::time::Sleep>>> = None;
240        loop {
241            tokio::select! {
242                accepted = async {
243                    // Wait for a free connection slot before accepting; the
244                    // whole future is dropped (releasing nothing) on
245                    // shutdown. The semaphore is never closed.
246                    // Invariant: acquire fails only on a closed
247                    // semaphore, and nothing ever closes this one.
248                    #[allow(clippy::expect_used)]
249                    let permit = conn_slots
250                        .clone()
251                        .acquire_owned()
252                        .await
253                        .expect("connection semaphore is never closed");
254                    (permit, listener.accept().await)
255                } => {
256                    let (permit, accepted) = accepted;
257                    let (stream, peer_addr) = match accepted {
258                        Ok(x) => x,
259                        Err(err) => {
260                            accept_error_backoff("listener", &err).await;
261                            continue;
262                        }
263                    };
264
265                    // Small responses must not wait on Nagle's algorithm.
266                    let _ = stream.set_nodelay(true);
267
268                    let svc = Svc::new(
269                        self.pool.clone(),
270                        self.streams.clone(),
271                        self.protection.clone(),
272                        main_health.clone(),
273                        peer_addr,
274                        tls_enabled,
275                    );
276                    let http = http.clone();
277                    // Subscribed here rather than inside the task:
278                    // `watcher()` takes its version at accept time, so a
279                    // drain that starts while a handshake is still running
280                    // is seen by this connection instead of arriving one
281                    // version late.
282                    let watcher = graceful.watcher();
283                    // Loaded per accept, so a reload's swap is visible to
284                    // the next connection; the clone is an `Arc` handle.
285                    #[cfg(feature = "tls")]
286                    let acceptor = current_acceptor(&tls_slot);
287                    tokio::spawn(async move {
288                        // Held until the connection closes.
289                        let _permit = permit;
290                        // The TLS handshake happens HERE, in the
291                        // connection's own task — never in the accept loop
292                        // above. A `ClientHello` that arrives one byte a
293                        // minute then costs this connection and nothing
294                        // else; handshaking before the spawn would let one
295                        // hostile client stall every other.
296                        #[cfg(feature = "tls")]
297                        if let Some(acceptor) = acceptor {
298                            let Some(stream) =
299                                tls_handshake(&acceptor, stream, handshake_deadline, peer_addr)
300                                    .await
301                            else {
302                                return;
303                            };
304                            let conn = http.serve_connection(TokioIo::new(stream), svc);
305                            if let Err(err) = watcher.watch(conn).await {
306                                // `debug`, not `error`, and the plaintext
307                                // arm below stays at `error` on purpose.
308                                // TLS adds a shutdown handshake that a
309                                // client is free to skip: curl and every
310                                // browser routinely close the socket
311                                // without a `close_notify`, which arrives
312                                // here as "error shutting down
313                                // connection". At `error` that is one log
314                                // line per request on a healthy server —
315                                // noise that buries the failures an
316                                // operator is actually looking for.
317                                tracing::debug!(
318                                    "TLS connection from {peer_addr} ended with: {err}"
319                                );
320                            }
321                            return;
322                        }
323                        let conn = http.serve_connection(TokioIo::new(stream), svc);
324                        if let Err(err) = watcher.watch(conn).await {
325                            tracing::error!("error serving connection: {err}");
326                        }
327                    });
328                }
329                Some(()) = reload_rx.recv() => self.reload(),
330                () = &mut shutdown, if draining.is_none() => {
331                    // Step 1: stop advertising readiness *before* requests
332                    // can fail, so a load balancer drains us on its own
333                    // terms. On the main listener that is only observable
334                    // while it still accepts, hence the delay.
335                    self.ready.store(false, Ordering::Relaxed);
336                    let delay = self.cfg.readiness_delay();
337                    if delay.is_zero() {
338                        break;
339                    }
340                    tracing::info!("draining: readiness answers 503, still serving for {delay:?}");
341                    draining = Some(Box::pin(tokio::time::sleep(delay)));
342                }
343                () = async {
344                    match draining.as_mut() {
345                        Some(delay) => delay.await,
346                        None => std::future::pending().await,
347                    }
348                }, if draining.is_some() => break,
349            }
350        }
351
352        // Step 2: the listener is dropped and no new connection is taken.
353        // A separate probe listener stays up through the drain, readiness
354        // observable as "draining" while it happens, and dies with the
355        // process. Responses issued from here on carry `Connection: close`.
356        drop(listener);
357
358        let grace = self.cfg.shutdown.grace();
359        let total = self.cfg.shutdown.total_grace();
360        tracing::info!(
361            "draining: waiting up to {grace:?} for in-flight requests \
362             ({stream_grace:?} more for streaming bodies)",
363            stream_grace = total.saturating_sub(grace),
364        );
365
366        // Steps 3-5: in-flight requests finish, idle keep-alive connections
367        // close (hyper marks them `Connection: close` as it drains), and the
368        // pool states they hold come back with them. Streaming bodies get
369        // the extra budget before anything is cut.
370        // Step 6 follows from the drain: dropping the watcher (and with it
371        // the last connection tasks) closes every Lua state, which
372        // checkpoints the SQLite WAL of each connection.
373        let deadline = drain_deadline(&self.streams, self.max_streams, grace, total);
374        let drained = tokio::select! {
375            _ = graceful.shutdown() => true,
376            _ = deadline => false,
377        };
378
379        // The probe listener stayed up through the drain — readiness had
380        // to be observable as "draining" while it happened — and drains
381        // now: `serve_probes` watches every in-flight probe connection
382        // with its own `GracefulShutdown`, so stopping it finishes open
383        // probe answers instead of severing them. The deadline is tight
384        // because a probe response is one fixed-body round trip.
385        if let Some(mut task) = probe_task {
386            if let Some(stop) = probe_stop.take() {
387                let _ = stop.send(());
388            }
389            if tokio::time::timeout(Duration::from_secs(1), &mut task)
390                .await
391                .is_err()
392            {
393                // Aborting kills the accept/drain task only; the
394                // per-connection tasks are independent spawns and simply
395                // run to completion on their own (in the binary, until
396                // process exit moments later).
397                tracing::warn!("probe listener did not drain within 1s, abandoning the drain");
398                task.abort();
399            }
400        }
401
402        if drained {
403            tracing::info!("drained cleanly, shutting down");
404            Ok(())
405        } else {
406            // A truncated shutdown means somebody's request was cut. Report
407            // it as an error so a supervisor can surface it, rather than
408            // exiting 0 and hiding it.
409            tracing::warn!("drain deadline of {total:?} expired, aborting remaining connections");
410            Err(Error::ShutdownTimeout)
411        }
412    }
413}
414
415/// How long an accept loop pauses after a non-client accept failure.
416///
417/// Fixed rather than exponential on purpose: the failure this exists for
418/// is descriptor exhaustion (`EMFILE`/`ENFILE`), which clears when a
419/// descriptor frees, not on a schedule — and exponential backoff adds
420/// state to a loop whose whole virtue is having none.
421const ACCEPT_ERROR_BACKOFF: Duration = Duration::from_millis(50);
422
423/// Classifies, logs, and (for one class) backs off one `accept()` failure.
424/// Both accept loops — the main listener's and the probe listener's — go
425/// through here, so the level split and the delay cannot drift apart.
426///
427/// Exactly two classes, deliberately. `ConnectionAborted`,
428/// `ConnectionReset` and `Interrupted` are client-caused and self-clearing
429/// (the peer gave up between the kernel completing the handshake and this
430/// process accepting it): `debug`, retry at once. *Everything else* is
431/// treated as resource trouble and paced: Rust has no stable `ErrorKind`
432/// for `EMFILE`/`ENFILE` — they surface as an uncategorized kind plus a
433/// raw OS error — so they cannot be named directly, and without the sleep
434/// a persistent one busy-spins the accept loop at 100% CPU. If this match
435/// ever grows a third case, it has stopped being insurance.
436pub(crate) async fn accept_error_backoff(listener: &str, err: &std::io::Error) {
437    use std::io::ErrorKind;
438    match err.kind() {
439        ErrorKind::ConnectionAborted | ErrorKind::ConnectionReset | ErrorKind::Interrupted => {
440            tracing::debug!("{listener}: client gone before accept: {err}");
441        }
442        _ => {
443            tracing::warn!("{listener}: failed to accept connection: {err}");
444            tokio::time::sleep(ACCEPT_ERROR_BACKOFF).await;
445        }
446    }
447}
448
449/// One connection's TLS handshake, run inside that connection's own task.
450///
451/// Returns `None` when the connection is finished with — the stream is
452/// dropped, closing it, and nothing else is affected. Failures are logged
453/// at `debug`, not `error`: on a public port a failed handshake is
454/// ordinary traffic (a plaintext client, a scanner, a client with no
455/// cipher suite in common), and an `error` per probe would drown the log
456/// an operator actually needs.
457///
458/// `deadline` is `[tls] handshake_ms` (or its `min(header_read_ms, 10s)`
459/// default) — a plain `Duration`, not an `Option`, so the bound cannot be
460/// switched off by any spelling: without one a client can hold a
461/// connection slot — and, during a drain, the graceful watcher — open
462/// forever by never finishing its `ClientHello`.
463#[cfg(feature = "tls")]
464async fn tls_handshake(
465    acceptor: &tokio_rustls::TlsAcceptor,
466    stream: tokio::net::TcpStream,
467    deadline: Duration,
468    peer: std::net::SocketAddr,
469) -> Option<tokio_rustls::server::TlsStream<tokio::net::TcpStream>> {
470    let handshake = match tokio::time::timeout(deadline, acceptor.accept(stream)).await {
471        Ok(handshake) => handshake,
472        Err(_) => {
473            tracing::debug!("TLS handshake from {peer} did not finish within {deadline:?}");
474            return None;
475        }
476    };
477    match handshake {
478        Ok(stream) => Some(stream),
479        Err(err) => {
480            tracing::debug!("TLS handshake from {peer} failed: {err}");
481            None
482        }
483    }
484}
485
486/// The effective handshake deadline. Validation refuses `handshake_ms =
487/// 0`, but an embedder can hand a config over by value — a zero here
488/// falls back to the default rather than meaning "unbounded".
489#[cfg(feature = "tls")]
490fn handshake_deadline(tls: &crate::config::TlsConfig, header_read: Option<Duration>) -> Duration {
491    /// Long enough for any honest client on any honest network; far
492    /// short of forever.
493    const DEFAULT_HANDSHAKE: Duration = Duration::from_secs(10);
494    match tls.handshake_ms {
495        Some(ms) if ms > 0 => Duration::from_millis(ms),
496        _ => header_read.map_or(DEFAULT_HANDSHAKE, |d| d.min(DEFAULT_HANDSHAKE)),
497    }
498}
499
500/// The acceptor currently in the slot (poisoning is unreachable: the lock
501/// is only ever held to clone or replace the acceptor).
502#[cfg(feature = "tls")]
503fn current_acceptor(
504    slot: &Arc<std::sync::RwLock<Option<tokio_rustls::TlsAcceptor>>>,
505) -> Option<tokio_rustls::TlsAcceptor> {
506    slot.read()
507        .map(|s| s.clone())
508        .unwrap_or_else(|e| e.into_inner().clone())
509}
510
511/// Resolves when the drain has run out of time.
512///
513/// Ordinary requests get `grace`. A streaming body legitimately outlives any
514/// request-shaped budget, so when one is still live at that point the drain
515/// waits until `total` instead — the extra budget is spent only on the case
516/// it exists for, rather than delaying every shutdown by it.
517async fn drain_deadline(streams: &Semaphore, max_streams: usize, grace: Duration, total: Duration) {
518    tokio::time::sleep(grace).await;
519    if streams.available_permits() < max_streams {
520        tracing::info!("streaming bodies still live, extending the drain to {total:?}");
521        tokio::time::sleep(total.saturating_sub(grace)).await;
522    }
523}
524
525/// Resolves when the process is asked to stop: `SIGTERM` (containers and
526/// systemd) or `SIGINT` (ctrl-c). On non-Unix targets only ctrl-c exists.
527async fn shutdown_signal() {
528    #[cfg(unix)]
529    {
530        use tokio::signal::unix::{SignalKind, signal};
531        let mut term = match signal(SignalKind::terminate()) {
532            Ok(sig) => sig,
533            Err(err) => {
534                tracing::warn!("failed to install the SIGTERM handler: {err}");
535                let _ = tokio::signal::ctrl_c().await;
536                return;
537            }
538        };
539        tokio::select! {
540            _ = term.recv() => tracing::info!("received SIGTERM"),
541            _ = tokio::signal::ctrl_c() => tracing::info!("received SIGINT"),
542        }
543    }
544    #[cfg(not(unix))]
545    {
546        let _ = tokio::signal::ctrl_c().await;
547        tracing::info!("received ctrl-c");
548    }
549}