Skip to main content

nitr_http/server/
mod.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 HTTP server and its builder: the main entrypoint for consuming Nitr.
7
8use std::sync::atomic::{AtomicBool, Ordering};
9use std::sync::{Arc, RwLock};
10
11use nitr_core::ModuleFn;
12use tokio::sync::Semaphore;
13
14use crate::config::Config;
15use crate::protect::Protection;
16use nitr_core::RuntimePool;
17use nitr_std::Builtins;
18
19/// A closure that customizes each pooled Lua state (advanced escape hatch;
20/// prefer [`ServerBuilder::module()`] for extensions).
21type SetupFn = Box<dyn Fn(&mlua::Lua) -> mlua::Result<()> + Send + Sync>;
22
23/// A named Rust extension module, mounted at `nitr.<name>` in every state.
24type Module = (String, Arc<ModuleFn>);
25
26/// The Nitr HTTP server: a pool of Lua runtimes behind a shared listener.
27///
28/// Built via [`Server::builder()`]; run via [`serve()`](Self::serve).
29pub struct Server {
30    cfg: Config,
31    builtins: Builtins,
32    setup_fns: Arc<Vec<SetupFn>>,
33    modules: Arc<Vec<Module>>,
34    /// The current pool, swappable as a whole for zero-downtime reloads.
35    pool: Arc<RwLock<Arc<RuntimePool>>>,
36    /// Streaming-response slots: one permit per live streaming body.
37    streams: Arc<Semaphore>,
38    /// The permit count `streams` was created with, so the drain can tell
39    /// whether any streaming body is still live.
40    max_streams: usize,
41    /// Pre-Lua protection: rate limiting, size limits, request ids.
42    protection: Arc<Protection>,
43    /// A caller-supplied, already-bound listener (see
44    /// [`ServerBuilder::listener`]); when absent, `serve` binds
45    /// `cfg.listen` itself.
46    listener: Option<std::net::TcpListener>,
47    /// A caller-supplied, already-bound listener for the health probes
48    /// (see [`ServerBuilder::health_listener`]); when absent and
49    /// `[health] bind` is set, `serve` binds that address itself.
50    health_listener: Option<std::net::TcpListener>,
51    /// Cleared as soon as a drain starts, so a load balancer can stop
52    /// routing before requests begin to fail. Read by
53    /// [`is_ready()`](Self::is_ready), which a readiness probe surfaces.
54    ready: Arc<AtomicBool>,
55    /// The `SIGHUP` stream, taken at build so the signal is owned before
56    /// a pidfile can name this process; `serve` forwards it to reloads.
57    #[cfg(unix)]
58    reload_signal: Option<tokio::signal::unix::Signal>,
59    /// The shared `nitr.cache`, held here so a reload hands the new pool
60    /// the same storage rather than starting cold.
61    cache: Option<nitr_std::Cache>,
62    /// The configuration script's result as built, for states outside the
63    /// pool (`nitr test` mounts it as `nitr.cfg` in its test states).
64    cfg_snapshot: Option<serde_json::Value>,
65    /// The pool rebuild's state: [`RELOAD_IDLE`], [`RELOAD_RUNNING`], or
66    /// [`RELOAD_PENDING`] (running, and another was asked for meanwhile —
67    /// the task runs once more when it finishes, so a save or a `SIGHUP`
68    /// that lands mid-rebuild is never lost).
69    reloading: Arc<std::sync::atomic::AtomicU8>,
70    /// The TLS acceptor built from `[tls] cert`/`key`, or `None` on a
71    /// plaintext listener. Built in [`ServerBuilder::build`] — so a
72    /// broken pair fails the build rather than every handshake on an
73    /// already-bound port — and held behind a lock so a `SIGHUP` can
74    /// swap in renewed material without a restart: the accept loop reads
75    /// the slot per accepted connection, never from the filesystem.
76    #[cfg(feature = "tls")]
77    tls: Arc<RwLock<Option<tokio_rustls::TlsAcceptor>>>,
78    /// The OpenAPI document and page, rebuilt with the pool on reload so
79    /// a document never describes routes that are no longer live. The
80    /// handler reads it through [`Protection`].
81    #[cfg(feature = "openapi")]
82    docs: crate::openapi::docs::DocsSlot,
83}
84
85mod builder;
86mod pool;
87mod serve;
88
89pub use builder::ServerBuilder;
90use pool::{build_runtimes, new_pool};
91pub(crate) use pool::{current_pool, input_env};
92pub(crate) use serve::accept_error_backoff;
93
94impl Server {
95    /// Creates a [`ServerBuilder`] with default configuration.
96    pub fn builder() -> ServerBuilder {
97        ServerBuilder::default()
98    }
99
100    /// The pool of Lua runtimes currently serving requests.
101    pub fn pool(&self) -> Arc<RuntimePool> {
102        current_pool(&self.pool)
103    }
104
105    /// Whether the server is accepting traffic. Cleared at the start of a
106    /// graceful shutdown, before in-flight requests are drained.
107    pub fn is_ready(&self) -> bool {
108        self.ready.load(Ordering::Relaxed)
109    }
110
111    /// The OpenAPI document as `nitr openapi` prints it: pretty JSON with
112    /// a trailing newline, describing the routes currently compiled.
113    /// Generated whether or not `[openapi] enabled` — that flag gates
114    /// serving, not generation.
115    #[cfg(feature = "openapi")]
116    pub fn openapi_json(&self) -> Option<bytes::Bytes> {
117        self.docs
118            .read()
119            .ok()
120            .and_then(|slot| slot.as_ref().map(|d| d.spec().clone()))
121    }
122
123    /// The Swagger UI page and its assets as a self-contained static site:
124    /// relative file names with their bytes (`index.html`, `openapi.json`,
125    /// `assets/<version>/…`), openable from `file://` or any static host.
126    #[cfg(feature = "swagger")]
127    pub fn openapi_site(&self) -> Option<Vec<(String, bytes::Bytes)>> {
128        let docs = self.docs.read().ok()?.clone()?;
129        docs.static_site(&self.cfg.swagger).ok()
130    }
131
132    /// The configuration script's snapshot (`nitr.cfg`) as of the build;
133    /// `None` without a configuration script.
134    pub fn cfg_snapshot(&self) -> Option<&serde_json::Value> {
135        self.cfg_snapshot.as_ref()
136    }
137
138    /// An in-process client that dispatches requests through the full
139    /// router/middleware/handler path without binding a socket — the
140    /// foundation for `nitr test` and Rust-level integration tests.
141    pub fn test_client(&self) -> crate::testing::TestClient {
142        crate::testing::TestClient::new(
143            self.pool.clone(),
144            self.streams.clone(),
145            self.protection.clone(),
146            self.cfg.tls.enabled,
147        )
148    }
149
150    /// Builds a complete replacement pool (re-running the configuration
151    /// script) and atomically swaps it in; in-flight requests finish on
152    /// the old pool, which is dropped when its last guard returns. On any
153    /// error the old pool stays. With `[tls]` enabled the certificate and
154    /// key are re-read too, each half independent: a failed TLS re-read
155    /// keeps the old acceptor while the pool still reloads, and vice
156    /// versa.
157    ///
158    /// What a reload deliberately does **not** refresh, so the boundary
159    /// is written down rather than discovered: `nitr.toml` itself is
160    /// never re-read (`self.cfg` is fixed at build), and with it every
161    /// compiled policy — `Protection` (limits, rate limit, request-id
162    /// trust), the CORS and compression policies, the cache and its
163    /// capacity, the listen address and worker count. A reload re-runs
164    /// the configuration *script* and re-reads the certificate *files*;
165    /// everything else needs a restart.
166    ///
167    /// The rebuild runs on its own task. It constructs `workers` Lua
168    /// states, compiles the handler into each and awaits the
169    /// configuration script — seconds, on a large pool with a script that
170    /// opens a database — and it used to run inline in the accept loop's
171    /// `select!`, during which no connection was accepted and a `SIGTERM`
172    /// went unanswered. A reload requested while one is running marks it
173    /// pending, and the task rebuilds once more when it finishes: the
174    /// running rebuild read the scripts before the second request came,
175    /// so dropping that request would lose the edit it carried.
176    fn reload(&self) {
177        #[cfg(feature = "tls")]
178        self.reload_tls();
179        if self
180            .reloading
181            .compare_exchange(
182                RELOAD_IDLE,
183                RELOAD_RUNNING,
184                Ordering::AcqRel,
185                Ordering::Acquire,
186            )
187            .is_err()
188        {
189            self.reloading.store(RELOAD_PENDING, Ordering::Release);
190            tracing::info!("reload requested while one is in progress; it will run again");
191            return;
192        }
193        tracing::info!("reload requested: rebuilding the runtime pool");
194        let cfg = self.cfg.clone();
195        let builtins = self.builtins;
196        let setup_fns = self.setup_fns.clone();
197        let modules = self.modules.clone();
198        let cache = self.cache.clone();
199        let pool = self.pool.clone();
200        #[cfg(feature = "openapi")]
201        let docs = self.docs.clone();
202        let state = self.reloading.clone();
203        tokio::spawn(async move {
204            // Whatever happens below — a panic in an embedder's setup
205            // function included — the state must return to idle, or no
206            // reload would ever run again for the life of the process.
207            let _reset = ReloadReset(state.clone());
208            loop {
209                let rebuild = std::panic::AssertUnwindSafe(rebuild_pool(
210                    &cfg,
211                    builtins,
212                    &setup_fns,
213                    &modules,
214                    &cache,
215                    &pool,
216                    #[cfg(feature = "openapi")]
217                    &docs,
218                ));
219                if let Err(payload) = futures_util::FutureExt::catch_unwind(rebuild).await {
220                    let message = payload
221                        .downcast_ref::<&str>()
222                        .map(|s| s.to_string())
223                        .or_else(|| payload.downcast_ref::<String>().cloned())
224                        .unwrap_or_else(|| "non-string panic payload".into());
225                    tracing::error!("reload failed: the rebuild panicked: {message}");
226                }
227                // Finished. If another request arrived meanwhile, go again.
228                if state
229                    .compare_exchange(
230                        RELOAD_RUNNING,
231                        RELOAD_IDLE,
232                        Ordering::AcqRel,
233                        Ordering::Acquire,
234                    )
235                    .is_ok()
236                {
237                    break;
238                }
239                state.store(RELOAD_RUNNING, Ordering::Release);
240                tracing::info!("running the reload requested during the last rebuild");
241            }
242        });
243    }
244
245    /// Re-reads `[tls] cert`/`key` from their configured paths and swaps
246    /// the acceptor — validate first, swap only on success: a server that
247    /// stops terminating TLS because certbot wrote a half-file is
248    /// strictly worse than a stale certificate. Connections already
249    /// established keep the acceptor they handshook with.
250    #[cfg(feature = "tls")]
251    fn reload_tls(&self) {
252        // `enabled` cannot change here: a reload re-reads the certificate
253        // files, not `nitr.toml`, so a plaintext listener has nothing to
254        // swap — and saying so beats silently doing nothing.
255        if !self.cfg.tls.enabled {
256            tracing::debug!("reload: [tls] is disabled, no certificate to re-read");
257            return;
258        }
259        match crate::tls::load(&self.cfg.tls) {
260            Ok(loaded) => {
261                let acceptor = tokio_rustls::TlsAcceptor::from(loaded.config);
262                match self.tls.write() {
263                    Ok(mut slot) => {
264                        *slot = Some(acceptor);
265                        tracing::info!(
266                            "reload complete: TLS material re-read ({} certificate(s))",
267                            loaded.certs
268                        );
269                    }
270                    // Unreachable in practice: the lock is only ever held
271                    // to clone or replace the acceptor.
272                    Err(_) => tracing::error!("TLS reload failed: the acceptor lock is poisoned"),
273                }
274            }
275            Err(err) => {
276                tracing::warn!("TLS reload failed, keeping the current certificate: {err}");
277            }
278        }
279    }
280}
281
282/// No rebuild in flight.
283const RELOAD_IDLE: u8 = 0;
284/// A rebuild is running.
285const RELOAD_RUNNING: u8 = 1;
286/// A rebuild is running and another was requested while it ran.
287const RELOAD_PENDING: u8 = 2;
288
289/// Returns the reload state to idle when dropped — the rebuild task's
290/// backstop against a panic that would otherwise leave it "running"
291/// forever.
292struct ReloadReset(Arc<std::sync::atomic::AtomicU8>);
293
294impl Drop for ReloadReset {
295    fn drop(&mut self) {
296        self.0.store(RELOAD_IDLE, Ordering::Release);
297    }
298}
299
300/// One rebuild: a complete replacement pool, swapped in on success.
301async fn rebuild_pool(
302    cfg: &Config,
303    builtins: Builtins,
304    setup_fns: &Arc<Vec<SetupFn>>,
305    modules: &Arc<Vec<Module>>,
306    cache: &Option<nitr_std::Cache>,
307    pool: &Arc<RwLock<Arc<RuntimePool>>>,
308    #[cfg(feature = "openapi")] docs: &crate::openapi::docs::DocsSlot,
309) {
310    match build_runtimes(cfg, builtins, setup_fns, modules, cache.as_ref()).await {
311        Ok(built) => {
312            // The document comes from the new bootstrap state; a document
313            // that fails its bound keeps the old pool *and* the old
314            // document, so the two never disagree.
315            #[cfg(feature = "openapi")]
316            let fresh_docs = match pool::build_docs(cfg, &built.runtimes) {
317                Ok(docs) => docs,
318                Err(err) => {
319                    tracing::error!("reload failed, keeping the current pool: {err}");
320                    return;
321                }
322            };
323            let fresh = Arc::new(new_pool(
324                built,
325                cfg,
326                builtins,
327                setup_fns,
328                modules,
329                cache.clone(),
330            ));
331            match pool.write() {
332                Ok(mut pool) => {
333                    *pool = fresh;
334                    // Swapped while the pool lock is held: no request can
335                    // see the new pool with the old document.
336                    #[cfg(feature = "openapi")]
337                    match docs.write() {
338                        Ok(mut slot) => *slot = Some(fresh_docs),
339                        Err(_) => tracing::error!("reload: the docs lock is poisoned"),
340                    }
341                    tracing::info!("reload complete: new runtime pool is live");
342                }
343                Err(_) => tracing::error!("reload failed: pool lock is poisoned"),
344            }
345        }
346        Err(err) => {
347            tracing::error!("reload failed, keeping the current pool: {err}");
348        }
349    }
350}
351
352impl std::fmt::Debug for Server {
353    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
354        f.debug_struct("Server")
355            .field("cfg", &self.cfg)
356            .field("builtins", &self.builtins)
357            .finish_non_exhaustive()
358    }
359}