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}