nitr_std/lib.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 built-in `nitr.*` standard library for Nitr and its registration.
7//!
8//! Every builtin mounts as a field of the global `nitr` namespace table
9//! (`nitr.json`, `nitr.fetch`, `nitr.db`, …) — Nitr registers no other
10//! globals, so scripts always read `nitr.*` and nothing is intermixed with
11//! the Lua standard library.
12
13// Lint policy comes from `[workspace.lints]` in the root Cargo.toml.
14// `unwrap_used`/`expect_used` are denied here (not in the workspace table,
15// which would also hit test and bench targets); unit tests are exempt, and
16// the few documented-invariant `expect()`s carry targeted allows.
17#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used))]
18#![cfg_attr(docsrs, feature(doc_cfg))]
19
20use std::path::PathBuf;
21
22use nitr_core::Result;
23
24pub(crate) mod base64;
25pub(crate) mod bounded;
26pub mod cache;
27pub mod clock;
28pub(crate) mod config;
29#[cfg(feature = "crypto")]
30pub(crate) mod crypto;
31pub(crate) mod csrf;
32#[cfg(feature = "db")]
33pub(crate) mod db;
34pub(crate) mod env;
35#[cfg(feature = "fetch")]
36pub(crate) mod fetch;
37pub(crate) mod http;
38pub(crate) mod json;
39pub(crate) mod log;
40pub(crate) mod path;
41pub(crate) mod session;
42#[cfg(feature = "template")]
43pub(crate) mod template;
44pub mod testing;
45pub(crate) mod time;
46pub(crate) mod url;
47pub(crate) mod utils;
48pub(crate) mod validate;
49
50pub use cache::{Cache, CacheOptions};
51
52/// The validation engine as the server uses it: compiled schemas for route
53/// `input` declarations, text coercion, the error shape, and the
54/// `nitr.File` handle for validated uploads.
55pub mod validation {
56 pub use crate::validate::format::{CustomFormatInfo, custom_formats};
57 pub use crate::validate::media::{
58 Detection, MEDIA_TYPES, MediaType, SNIFF_BYTES, detect, dimensions, executable_extension,
59 is_active_content, is_text, lookup, text_subtype_matches,
60 };
61 pub use crate::validate::message::{fmt_size, rule_codes};
62 pub use crate::validate::schema_json::{Components, regex_escape};
63 pub use crate::validate::{
64 CompiledSchema, DocSchema, ErrorEntry, FileInfo, LuaFile, SaveResolver, TextValue,
65 ValidationError, compile_doc_schema, compile_file_rule, compile_schema,
66 compile_text_schema, freeze_messages,
67 };
68}
69// The configuration types are always available: `nitr.toml` has one shape
70// regardless of which builtins this build compiled in.
71pub use config::{EnvOptions, FetchOptions, MAX_PASSWORD_BYTES, RunMode, SqlitePragmas};
72pub use env::set_run_mode;
73pub use http::{
74 RequestCookies, ResponseCookies, SetCookie, best_match, parse_set_cookie, response_table,
75};
76pub use utils::error_lua_value;
77
78/// Internal functions exposed for the fuzz targets in `fuzz/` only.
79/// Not part of the public API; no stability promise applies here.
80#[doc(hidden)]
81pub mod fuzzing {
82 #[cfg(feature = "crypto")]
83 pub use crate::crypto::{VERIFY_REASONS, create_auth_table, create_crypto_table};
84 pub use crate::http::{sign, verify};
85 pub use crate::json::create_json_fn;
86 pub use crate::path::{
87 basename, dirname, is_absolute, is_windows_style, join, normalize, split_root,
88 };
89 pub use crate::url::create_url_table;
90 // Also driven by the `bounds_guard` benchmark, which measures the
91 // guard's own walk against the serialization it precedes.
92 pub use crate::utils::check_json_bounds;
93 pub use crate::validate::coerce_for_fuzzing;
94 pub use crate::validate::exemplars::FORMAT_EXEMPLARS;
95 pub use crate::validate::format::{check_format, format_names};
96 pub use crate::validate::media::{detect as sniff_file, dimensions as sniff_dimensions};
97}
98
99#[cfg(feature = "db")]
100pub use db::migrate;
101#[cfg(feature = "db")]
102pub use db::pragmas::open as db_open;
103/// Database fixtures for `nitr test`: snapshot/restore, truncate, seed.
104#[cfg(feature = "db")]
105pub use db::testing as db_fixtures;
106#[cfg(feature = "fetch")]
107pub use fetch::{reset_outbound_budget, set_trace_context};
108
109/// Encodes a Lua value as JSON under the standard library's bounds (depth,
110/// node count, UTF-8) — the encoder anything outside this crate uses for a
111/// script's value, so deep nesting is an error rather than a stack
112/// overflow.
113///
114/// # Errors
115///
116/// A value past the bounds, or one JSON cannot represent.
117pub fn json_encode(value: &mlua::Value) -> mlua::Result<Vec<u8>> {
118 bounded::to_json_vec(value).map_err(mlua::Error::external)
119}
120
121/// Resets the per-request outbound budget. A no-op without the `fetch`
122/// feature, so the server can call it unconditionally.
123#[cfg(not(feature = "fetch"))]
124pub fn reset_outbound_budget(_lua: &mlua::Lua) {}
125
126/// Records the inbound request id for `traceparent` propagation. A no-op
127/// without the `fetch` feature.
128#[cfg(not(feature = "fetch"))]
129pub fn set_trace_context(_lua: &mlua::Lua, _request_id: &str) {}
130
131bitflags::bitflags! {
132 /// Built-in `nitr.*` standard library modules that can be exposed to
133 /// Lua scripts.
134 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
135 pub struct Builtins: u32 {
136 /// `nitr.dbg(value)` debug-print function.
137 const DEBUG = 1;
138 /// `nitr.fetch(method, url, opts?)` HTTP client plus
139 /// `nitr.await_all` for concurrent requests.
140 const FETCH = 1 << 1;
141 /// `nitr.template:render(name, data?)` template engine (minijinja).
142 const TEMPLATE = 1 << 2;
143 /// `nitr.json` JSON codec (`:encode`/`:decode`) and, called as a
144 /// function, the JSON response helper.
145 const JSON = 1 << 3;
146 /// `nitr.db:execute/query/query_row/query_one/transaction` SQLite
147 /// driver.
148 const DATABASE = 1 << 4;
149 /// HTTP ergonomics: the `nitr.text`/`html`/`redirect`/`status`/
150 /// `negotiate`/`sse` response helpers and `nitr.error`.
151 const HTTP = 1 << 5;
152 /// `nitr.log.debug/info/warn/error(msg, fields?)` structured logging.
153 const LOG = 1 << 6;
154 /// `nitr.crypto` primitives (hashing, HMAC, passwords, AEAD, JWT)
155 /// and the `nitr.auth` header parsers.
156 const CRYPTO = 1 << 7;
157 /// `nitr.cache`: the bounded cache shared by every pooled state.
158 const CACHE = 1 << 8;
159 /// `nitr.time`: safe clocks and time formatting/parsing, so
160 /// scripts never need the `os` Lua standard library for a date.
161 const TIME = 1 << 9;
162 /// `nitr.validate`: declarative request validation, compiled once
163 /// and checked in Rust.
164 const VALIDATE = 1 << 10;
165 /// `nitr.base64`: base64 encoding/decoding (standard and
166 /// URL-safe alphabets).
167 const BASE64 = 1 << 11;
168 /// `nitr.path`: lexical `/`-path manipulation — pure text, no
169 /// filesystem access.
170 const PATH = 1 << 12;
171 /// `nitr.url`: percent-encoding, query strings, and a lexical
172 /// URL splitter.
173 const URL = 1 << 13;
174 /// `nitr.env`: read-only environment variable access
175 /// (`get`/`has`/`number`/`bool`), filtered by `[env] allow` and
176 /// never exposing `NITR_*` internals.
177 const ENV = 1 << 14;
178 }
179}
180
181impl Builtins {
182 /// The minimal default feature set enabled when the configuration has
183 /// no explicit `[std] features` list: the JSON codec, the HTTP response
184 /// helpers, structured logging, safe time, validation, base64, path
185 /// handling, and URL utilities. These need no external resources
186 /// (templates directory, database file, outbound network) and keep the
187 /// standard library lightweight; everything else is opt-in. `time` and
188 /// `validate` are here because they replace the dangerous alternatives
189 /// (`os.date`, hand-rolled input checks) — a default that omitted them
190 /// would push scripts toward widening the sandbox instead; `base64`,
191 /// `path` and `url` are pure string transforms with the same rationale.
192 pub const fn minimal() -> Self {
193 Self::JSON
194 .union(Self::HTTP)
195 .union(Self::LOG)
196 .union(Self::TIME)
197 .union(Self::VALIDATE)
198 .union(Self::BASE64)
199 .union(Self::PATH)
200 .union(Self::URL)
201 }
202
203 /// The field name a builtin mounts under on the `nitr` namespace table.
204 ///
205 /// Returns `None` for combined flags and for builtins that register
206 /// several fields ([`HTTP`](Self::HTTP) and [`CRYPTO`](Self::CRYPTO)).
207 pub fn nitr_name(self) -> Option<&'static str> {
208 match self {
209 Builtins::DEBUG => Some("dbg"),
210 Builtins::FETCH => Some("fetch"),
211 Builtins::TEMPLATE => Some("template"),
212 Builtins::JSON => Some("json"),
213 Builtins::DATABASE => Some("db"),
214 Builtins::LOG => Some("log"),
215 Builtins::TIME => Some("time"),
216 Builtins::VALIDATE => Some("validate"),
217 Builtins::BASE64 => Some("base64"),
218 Builtins::PATH => Some("path"),
219 Builtins::URL => Some("url"),
220 Builtins::ENV => Some("env"),
221 _ => None,
222 }
223 }
224
225 /// Resolves a configuration name (e.g. `"dbg"`, `"fetch"`, `"db"`) into
226 /// its builtin flag.
227 pub fn from_config_name(name: &str) -> Option<Self> {
228 match name {
229 "dbg" => Some(Builtins::DEBUG),
230 "fetch" => Some(Builtins::FETCH),
231 "template" => Some(Builtins::TEMPLATE),
232 "json" => Some(Builtins::JSON),
233 "db" => Some(Builtins::DATABASE),
234 "http" => Some(Builtins::HTTP),
235 "log" => Some(Builtins::LOG),
236 "crypto" => Some(Builtins::CRYPTO),
237 "cache" => Some(Builtins::CACHE),
238 "time" => Some(Builtins::TIME),
239 "validate" => Some(Builtins::VALIDATE),
240 "base64" => Some(Builtins::BASE64),
241 "path" => Some(Builtins::PATH),
242 "url" => Some(Builtins::URL),
243 "env" => Some(Builtins::ENV),
244 _ => None,
245 }
246 }
247}
248
249/// External resources required by some builtins: `template` needs a
250/// templates directory and `db` a SQLite database file.
251#[derive(Debug, Clone, Default)]
252pub struct BuiltinsEnv {
253 /// Directory the `template` builtin loads templates from.
254 pub templates_dir: Option<PathBuf>,
255 /// SQLite database file the `db` builtin connects to.
256 pub database: Option<PathBuf>,
257 /// Connection pragmas applied to that database.
258 pub sqlite: SqlitePragmas,
259 /// The shared cache backing `nitr.cache`. Built once by the server and
260 /// handed to every state, so it survives a pool rebuild — a cache that
261 /// empties on every reload is a cache that never warms.
262 pub cache: Option<Cache>,
263 /// Outbound-request policy for the `fetch` builtin.
264 pub fetch: FetchOptions,
265 /// Read policy for the `nitr.env` builtin.
266 pub env: EnvOptions,
267 /// Whether cookies Nitr builds carry `Secure` when the caller's own
268 /// options table does not say. Resolved by the server from
269 /// `[cookies] secure` and `[tls] enabled`.
270 ///
271 /// `false` in `Default` deliberately: an embedder who never sets one,
272 /// and `nitr hash-password`, keep exactly today's behaviour.
273 pub cookie_secure: bool,
274 /// Why a cookie built without `Secure` is worth a warning, logged once
275 /// by the first such cookie; `None` when the server has nothing to say.
276 pub cookie_insecure_warning: Option<String>,
277}
278
279/// Registers the selected builtins as fields of the global `nitr`
280/// namespace table (`nitr.dbg`, `nitr.fetch`, `nitr.json`, `nitr.db`, …).
281///
282/// Builtins that need a setting from the [`BuiltinsEnv`] (`template` needs
283/// `templates_dir`, `db` needs `database`) are skipped with a warning when
284/// that setting is absent; callers that take an explicit builtins list
285/// should reject such combinations upfront.
286/// Only reachable when at least one gated builtin was left out.
287#[cfg(not(all(
288 feature = "crypto",
289 feature = "db",
290 feature = "fetch",
291 feature = "template"
292)))]
293fn not_compiled_in(name: &str) -> nitr_core::Error {
294 nitr_core::Error::Config(format!(
295 "the `{name}` builtin is configured but was not compiled into this \
296 binary: rebuild with the `{name}` Cargo feature (or `all`), or drop \
297 it from `[std] features`"
298 ))
299}
300
301/// Registers the selected builtins on the global `nitr` namespace table,
302/// using the [`BuiltinsEnv`] for the resources some of them need.
303pub fn register_builtins(lua: &mlua::Lua, builtins: Builtins, env: &BuiltinsEnv) -> Result {
304 let nitr = nitr_core::nitr_table(lua)?;
305 // The cookie policy is stashed per state rather than captured, because
306 // the cookie serializer is reached from `UserData` methods whose
307 // closures are registered once per type. Set unconditionally — not
308 // only under `Builtins::HTTP` — so the value a state carries never
309 // depends on which builtins happened to be enabled.
310 lua.set_app_data(http::CookieDefaults {
311 secure: env.cookie_secure,
312 insecure_warning: env.cookie_insecure_warning.clone(),
313 });
314 for builtin in builtins.iter() {
315 match builtin {
316 Builtins::DEBUG => nitr.set("dbg", utils::create_debug_fn(lua)?)?,
317 // Also registers `nitr.await_all` for concurrent requests.
318 #[cfg(feature = "fetch")]
319 Builtins::FETCH => {
320 let opts = std::sync::Arc::new(env.fetch.clone());
321 nitr.set("fetch", fetch::create_fetch_fn(lua, opts.clone())?)?;
322 nitr.set("await_all", fetch::create_await_all_fn(lua, opts)?)?;
323 }
324 #[cfg(not(feature = "fetch"))]
325 Builtins::FETCH => return Err(not_compiled_in("fetch")),
326
327 #[cfg(feature = "template")]
328 Builtins::TEMPLATE => match &env.templates_dir {
329 Some(dir) => nitr.set("template", template::create_template_fn(lua, dir)?)?,
330 None => {
331 tracing::warn!(
332 "skipping builtin `template`: `[templating] dir` is not configured"
333 );
334 }
335 },
336 #[cfg(not(feature = "template"))]
337 Builtins::TEMPLATE => return Err(not_compiled_in("template")),
338 Builtins::JSON => nitr.set("json", json::create_json_fn(lua)?)?,
339 // Registers the response helpers (`nitr.text`, `nitr.html`,
340 // `nitr.redirect`, `nitr.status`, `nitr.negotiate`, `nitr.sse`),
341 // `nitr.error`, and the signed-cookie ergonomics built on them:
342 // `nitr.csrf` and `nitr.session`.
343 Builtins::HTTP => {
344 http::register(lua, &nitr)?;
345 nitr.set("csrf", csrf::create_csrf_table(lua)?)?;
346 nitr.set("session", session::create_session_fn(lua)?)?;
347 }
348 Builtins::LOG => nitr.set("log", log::create_log_table(lua)?)?,
349 Builtins::TIME => nitr.set("time", time::create_time_table(lua)?)?,
350 Builtins::VALIDATE => nitr.set("validate", validate::create_validate_table(lua)?)?,
351 Builtins::BASE64 => nitr.set("base64", base64::create_base64_table(lua)?)?,
352 Builtins::PATH => nitr.set("path", path::create_path_table(lua)?)?,
353 Builtins::URL => nitr.set("url", url::create_url_table(lua)?)?,
354 Builtins::ENV => nitr.set("env", env::create_env_table(lua, &env.env)?)?,
355 // Registers both `nitr.crypto` and `nitr.auth`.
356 #[cfg(feature = "crypto")]
357 Builtins::CRYPTO => {
358 nitr.set("crypto", crypto::create_crypto_table(lua)?)?;
359 nitr.set("auth", crypto::create_auth_table(lua)?)?;
360 }
361 #[cfg(not(feature = "crypto"))]
362 Builtins::CRYPTO => return Err(not_compiled_in("crypto")),
363
364 #[cfg(feature = "db")]
365 Builtins::DATABASE => match &env.database {
366 Some(path) => nitr.set("db", db::create_database_fn(lua, path, &env.sqlite)?)?,
367 None => {
368 tracing::warn!("skipping builtin `db`: `database` is not configured");
369 }
370 },
371 #[cfg(not(feature = "db"))]
372 Builtins::DATABASE => return Err(not_compiled_in("db")),
373 Builtins::CACHE => match &env.cache {
374 Some(cache) => nitr.set("cache", cache::create_cache(lua, cache.clone())?)?,
375 None => {
376 tracing::warn!("skipping builtin `cache`: no shared cache was provided");
377 }
378 },
379 _ => continue,
380 };
381 }
382 // Always registered, independent of the configured builtins: turning a
383 // caught error into its structured form is part of the error model,
384 // not an optional capability.
385 nitr.set("errinfo", utils::create_errinfo_fn(lua)?)?;
386 Ok(())
387}
388
389#[cfg(test)]
390mod tests {
391 use super::Builtins;
392
393 #[test]
394 fn config_names_round_trip() {
395 for (name, flag) in [
396 ("dbg", Builtins::DEBUG),
397 ("fetch", Builtins::FETCH),
398 ("template", Builtins::TEMPLATE),
399 ("json", Builtins::JSON),
400 ("db", Builtins::DATABASE),
401 ("http", Builtins::HTTP),
402 ("log", Builtins::LOG),
403 ("crypto", Builtins::CRYPTO),
404 ("time", Builtins::TIME),
405 ("validate", Builtins::VALIDATE),
406 ("base64", Builtins::BASE64),
407 ("path", Builtins::PATH),
408 ("url", Builtins::URL),
409 ("env", Builtins::ENV),
410 ] {
411 assert_eq!(Builtins::from_config_name(name), Some(flag));
412 }
413 assert_eq!(Builtins::from_config_name("nope"), None);
414 // Combined flags and multi-field builtins have no single name.
415 assert_eq!((Builtins::DEBUG | Builtins::JSON).nitr_name(), None);
416 assert_eq!(Builtins::HTTP.nitr_name(), None);
417 assert_eq!(Builtins::DATABASE.nitr_name(), Some("db"));
418 }
419}