Skip to main content

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}