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}