nitr-std 0.0.0-beta.7

The built-in `nitr.*` standard library for Nitr: dbg, fetch, template, json, http, log, crypto, and the SQLite driver.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
// SPDX-License-Identifier: MIT OR Apache-2.0
// This file is part of Nitr.
// See https://nitrweb.com/ for more information
// Copyright (C) 2024-present Jose Quintana <joseluisq.net>

//! The built-in `nitr.*` standard library for Nitr and its registration.
//!
//! Every builtin mounts as a field of the global `nitr` namespace table
//! (`nitr.json`, `nitr.fetch`, `nitr.db`, …) — Nitr registers no other
//! globals, so scripts always read `nitr.*` and nothing is intermixed with
//! the Lua standard library.

// Lint policy comes from `[workspace.lints]` in the root Cargo.toml.
// `unwrap_used`/`expect_used` are denied here (not in the workspace table,
// which would also hit test and bench targets); unit tests are exempt, and
// the few documented-invariant `expect()`s carry targeted allows.
#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used))]
#![cfg_attr(docsrs, feature(doc_cfg))]

use std::path::PathBuf;

use nitr_core::Result;

pub(crate) mod base64;
pub(crate) mod bounded;
pub mod cache;
pub mod clock;
pub(crate) mod config;
#[cfg(feature = "crypto")]
pub(crate) mod crypto;
pub(crate) mod csrf;
#[cfg(feature = "db")]
pub(crate) mod db;
pub(crate) mod env;
#[cfg(feature = "fetch")]
pub(crate) mod fetch;
pub(crate) mod http;
pub(crate) mod json;
pub(crate) mod log;
pub(crate) mod path;
pub(crate) mod session;
#[cfg(feature = "template")]
pub(crate) mod template;
pub mod testing;
pub(crate) mod time;
pub(crate) mod url;
pub(crate) mod utils;
pub(crate) mod validate;

pub use cache::{Cache, CacheOptions};

/// The validation engine as the server uses it: compiled schemas for route
/// `input` declarations, text coercion, the error shape, and the
/// `nitr.File` handle for validated uploads.
pub mod validation {
    pub use crate::validate::format::{CustomFormatInfo, custom_formats};
    pub use crate::validate::media::{
        Detection, MEDIA_TYPES, MediaType, SNIFF_BYTES, detect, dimensions, executable_extension,
        is_active_content, is_text, lookup, text_subtype_matches,
    };
    pub use crate::validate::message::{fmt_size, rule_codes};
    pub use crate::validate::schema_json::{Components, regex_escape};
    pub use crate::validate::{
        CompiledSchema, DocSchema, ErrorEntry, FileInfo, LuaFile, SaveResolver, TextValue,
        ValidationError, compile_doc_schema, compile_file_rule, compile_schema,
        compile_text_schema, freeze_messages,
    };
}
// The configuration types are always available: `nitr.toml` has one shape
// regardless of which builtins this build compiled in.
pub use config::{EnvOptions, FetchOptions, MAX_PASSWORD_BYTES, RunMode, SqlitePragmas};
pub use env::set_run_mode;
pub use http::{
    RequestCookies, ResponseCookies, SetCookie, best_match, parse_set_cookie, response_table,
};
pub use utils::error_lua_value;

/// Internal functions exposed for the fuzz targets in `fuzz/` only.
/// Not part of the public API; no stability promise applies here.
#[doc(hidden)]
pub mod fuzzing {
    #[cfg(feature = "crypto")]
    pub use crate::crypto::{VERIFY_REASONS, create_auth_table, create_crypto_table};
    pub use crate::http::{sign, verify};
    pub use crate::json::create_json_fn;
    pub use crate::path::{
        basename, dirname, is_absolute, is_windows_style, join, normalize, split_root,
    };
    pub use crate::url::create_url_table;
    // Also driven by the `bounds_guard` benchmark, which measures the
    // guard's own walk against the serialization it precedes.
    pub use crate::utils::check_json_bounds;
    pub use crate::validate::coerce_for_fuzzing;
    pub use crate::validate::exemplars::FORMAT_EXEMPLARS;
    pub use crate::validate::format::{check_format, format_names};
    pub use crate::validate::media::{detect as sniff_file, dimensions as sniff_dimensions};
}

#[cfg(feature = "db")]
pub use db::migrate;
#[cfg(feature = "db")]
pub use db::pragmas::open as db_open;
/// Database fixtures for `nitr test`: snapshot/restore, truncate, seed.
#[cfg(feature = "db")]
pub use db::testing as db_fixtures;
#[cfg(feature = "fetch")]
pub use fetch::{reset_outbound_budget, set_trace_context};

/// Encodes a Lua value as JSON under the standard library's bounds (depth,
/// node count, UTF-8) — the encoder anything outside this crate uses for a
/// script's value, so deep nesting is an error rather than a stack
/// overflow.
///
/// # Errors
///
/// A value past the bounds, or one JSON cannot represent.
pub fn json_encode(value: &mlua::Value) -> mlua::Result<Vec<u8>> {
    bounded::to_json_vec(value).map_err(mlua::Error::external)
}

/// Resets the per-request outbound budget. A no-op without the `fetch`
/// feature, so the server can call it unconditionally.
#[cfg(not(feature = "fetch"))]
pub fn reset_outbound_budget(_lua: &mlua::Lua) {}

/// Records the inbound request id for `traceparent` propagation. A no-op
/// without the `fetch` feature.
#[cfg(not(feature = "fetch"))]
pub fn set_trace_context(_lua: &mlua::Lua, _request_id: &str) {}

bitflags::bitflags! {
    /// Built-in `nitr.*` standard library modules that can be exposed to
    /// Lua scripts.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct Builtins: u32 {
        /// `nitr.dbg(value)` debug-print function.
        const DEBUG = 1;
        /// `nitr.fetch(method, url, opts?)` HTTP client plus
        /// `nitr.await_all` for concurrent requests.
        const FETCH = 1 << 1;
        /// `nitr.template:render(name, data?)` template engine (minijinja).
        const TEMPLATE = 1 << 2;
        /// `nitr.json` JSON codec (`:encode`/`:decode`) and, called as a
        /// function, the JSON response helper.
        const JSON = 1 << 3;
        /// `nitr.db:execute/query/query_row/query_one/transaction` SQLite
        /// driver.
        const DATABASE = 1 << 4;
        /// HTTP ergonomics: the `nitr.text`/`html`/`redirect`/`status`/
        /// `negotiate`/`sse` response helpers and `nitr.error`.
        const HTTP = 1 << 5;
        /// `nitr.log.debug/info/warn/error(msg, fields?)` structured logging.
        const LOG = 1 << 6;
        /// `nitr.crypto` primitives (hashing, HMAC, passwords, AEAD, JWT)
        /// and the `nitr.auth` header parsers.
        const CRYPTO = 1 << 7;
        /// `nitr.cache`: the bounded cache shared by every pooled state.
        const CACHE = 1 << 8;
        /// `nitr.time`: safe clocks and time formatting/parsing, so
        /// scripts never need the `os` Lua standard library for a date.
        const TIME = 1 << 9;
        /// `nitr.validate`: declarative request validation, compiled once
        /// and checked in Rust.
        const VALIDATE = 1 << 10;
        /// `nitr.base64`: base64 encoding/decoding (standard and
        /// URL-safe alphabets).
        const BASE64 = 1 << 11;
        /// `nitr.path`: lexical `/`-path manipulation — pure text, no
        /// filesystem access.
        const PATH = 1 << 12;
        /// `nitr.url`: percent-encoding, query strings, and a lexical
        /// URL splitter.
        const URL = 1 << 13;
        /// `nitr.env`: read-only environment variable access
        /// (`get`/`has`/`number`/`bool`), filtered by `[env] allow` and
        /// never exposing `NITR_*` internals.
        const ENV = 1 << 14;
    }
}

impl Builtins {
    /// The minimal default feature set enabled when the configuration has
    /// no explicit `[std] features` list: the JSON codec, the HTTP response
    /// helpers, structured logging, safe time, validation, base64, path
    /// handling, and URL utilities. These need no external resources
    /// (templates directory, database file, outbound network) and keep the
    /// standard library lightweight; everything else is opt-in. `time` and
    /// `validate` are here because they replace the dangerous alternatives
    /// (`os.date`, hand-rolled input checks) — a default that omitted them
    /// would push scripts toward widening the sandbox instead; `base64`,
    /// `path` and `url` are pure string transforms with the same rationale.
    pub const fn minimal() -> Self {
        Self::JSON
            .union(Self::HTTP)
            .union(Self::LOG)
            .union(Self::TIME)
            .union(Self::VALIDATE)
            .union(Self::BASE64)
            .union(Self::PATH)
            .union(Self::URL)
    }

    /// The field name a builtin mounts under on the `nitr` namespace table.
    ///
    /// Returns `None` for combined flags and for builtins that register
    /// several fields ([`HTTP`](Self::HTTP) and [`CRYPTO`](Self::CRYPTO)).
    pub fn nitr_name(self) -> Option<&'static str> {
        match self {
            Builtins::DEBUG => Some("dbg"),
            Builtins::FETCH => Some("fetch"),
            Builtins::TEMPLATE => Some("template"),
            Builtins::JSON => Some("json"),
            Builtins::DATABASE => Some("db"),
            Builtins::LOG => Some("log"),
            Builtins::TIME => Some("time"),
            Builtins::VALIDATE => Some("validate"),
            Builtins::BASE64 => Some("base64"),
            Builtins::PATH => Some("path"),
            Builtins::URL => Some("url"),
            Builtins::ENV => Some("env"),
            _ => None,
        }
    }

    /// Resolves a configuration name (e.g. `"dbg"`, `"fetch"`, `"db"`) into
    /// its builtin flag.
    pub fn from_config_name(name: &str) -> Option<Self> {
        match name {
            "dbg" => Some(Builtins::DEBUG),
            "fetch" => Some(Builtins::FETCH),
            "template" => Some(Builtins::TEMPLATE),
            "json" => Some(Builtins::JSON),
            "db" => Some(Builtins::DATABASE),
            "http" => Some(Builtins::HTTP),
            "log" => Some(Builtins::LOG),
            "crypto" => Some(Builtins::CRYPTO),
            "cache" => Some(Builtins::CACHE),
            "time" => Some(Builtins::TIME),
            "validate" => Some(Builtins::VALIDATE),
            "base64" => Some(Builtins::BASE64),
            "path" => Some(Builtins::PATH),
            "url" => Some(Builtins::URL),
            "env" => Some(Builtins::ENV),
            _ => None,
        }
    }
}

/// External resources required by some builtins: `template` needs a
/// templates directory and `db` a SQLite database file.
#[derive(Debug, Clone, Default)]
pub struct BuiltinsEnv {
    /// Directory the `template` builtin loads templates from.
    pub templates_dir: Option<PathBuf>,
    /// SQLite database file the `db` builtin connects to.
    pub database: Option<PathBuf>,
    /// Connection pragmas applied to that database.
    pub sqlite: SqlitePragmas,
    /// The shared cache backing `nitr.cache`. Built once by the server and
    /// handed to every state, so it survives a pool rebuild — a cache that
    /// empties on every reload is a cache that never warms.
    pub cache: Option<Cache>,
    /// Outbound-request policy for the `fetch` builtin.
    pub fetch: FetchOptions,
    /// Read policy for the `nitr.env` builtin.
    pub env: EnvOptions,
    /// Whether cookies Nitr builds carry `Secure` when the caller's own
    /// options table does not say. Resolved by the server from
    /// `[cookies] secure` and `[tls] enabled`.
    ///
    /// `false` in `Default` deliberately: an embedder who never sets one,
    /// and `nitr hash-password`, keep exactly today's behaviour.
    pub cookie_secure: bool,
    /// Why a cookie built without `Secure` is worth a warning, logged once
    /// by the first such cookie; `None` when the server has nothing to say.
    pub cookie_insecure_warning: Option<String>,
}

/// Registers the selected builtins as fields of the global `nitr`
/// namespace table (`nitr.dbg`, `nitr.fetch`, `nitr.json`, `nitr.db`, …).
///
/// Builtins that need a setting from the [`BuiltinsEnv`] (`template` needs
/// `templates_dir`, `db` needs `database`) are skipped with a warning when
/// that setting is absent; callers that take an explicit builtins list
/// should reject such combinations upfront.
/// Only reachable when at least one gated builtin was left out.
#[cfg(not(all(
    feature = "crypto",
    feature = "db",
    feature = "fetch",
    feature = "template"
)))]
fn not_compiled_in(name: &str) -> nitr_core::Error {
    nitr_core::Error::Config(format!(
        "the `{name}` builtin is configured but was not compiled into this \
         binary: rebuild with the `{name}` Cargo feature (or `all`), or drop \
         it from `[std] features`"
    ))
}

/// Registers the selected builtins on the global `nitr` namespace table,
/// using the [`BuiltinsEnv`] for the resources some of them need.
pub fn register_builtins(lua: &mlua::Lua, builtins: Builtins, env: &BuiltinsEnv) -> Result {
    let nitr = nitr_core::nitr_table(lua)?;
    // The cookie policy is stashed per state rather than captured, because
    // the cookie serializer is reached from `UserData` methods whose
    // closures are registered once per type. Set unconditionally — not
    // only under `Builtins::HTTP` — so the value a state carries never
    // depends on which builtins happened to be enabled.
    lua.set_app_data(http::CookieDefaults {
        secure: env.cookie_secure,
        insecure_warning: env.cookie_insecure_warning.clone(),
    });
    for builtin in builtins.iter() {
        match builtin {
            Builtins::DEBUG => nitr.set("dbg", utils::create_debug_fn(lua)?)?,
            // Also registers `nitr.await_all` for concurrent requests.
            #[cfg(feature = "fetch")]
            Builtins::FETCH => {
                let opts = std::sync::Arc::new(env.fetch.clone());
                nitr.set("fetch", fetch::create_fetch_fn(lua, opts.clone())?)?;
                nitr.set("await_all", fetch::create_await_all_fn(lua, opts)?)?;
            }
            #[cfg(not(feature = "fetch"))]
            Builtins::FETCH => return Err(not_compiled_in("fetch")),

            #[cfg(feature = "template")]
            Builtins::TEMPLATE => match &env.templates_dir {
                Some(dir) => nitr.set("template", template::create_template_fn(lua, dir)?)?,
                None => {
                    tracing::warn!(
                        "skipping builtin `template`: `[templating] dir` is not configured"
                    );
                }
            },
            #[cfg(not(feature = "template"))]
            Builtins::TEMPLATE => return Err(not_compiled_in("template")),
            Builtins::JSON => nitr.set("json", json::create_json_fn(lua)?)?,
            // Registers the response helpers (`nitr.text`, `nitr.html`,
            // `nitr.redirect`, `nitr.status`, `nitr.negotiate`, `nitr.sse`),
            // `nitr.error`, and the signed-cookie ergonomics built on them:
            // `nitr.csrf` and `nitr.session`.
            Builtins::HTTP => {
                http::register(lua, &nitr)?;
                nitr.set("csrf", csrf::create_csrf_table(lua)?)?;
                nitr.set("session", session::create_session_fn(lua)?)?;
            }
            Builtins::LOG => nitr.set("log", log::create_log_table(lua)?)?,
            Builtins::TIME => nitr.set("time", time::create_time_table(lua)?)?,
            Builtins::VALIDATE => nitr.set("validate", validate::create_validate_table(lua)?)?,
            Builtins::BASE64 => nitr.set("base64", base64::create_base64_table(lua)?)?,
            Builtins::PATH => nitr.set("path", path::create_path_table(lua)?)?,
            Builtins::URL => nitr.set("url", url::create_url_table(lua)?)?,
            Builtins::ENV => nitr.set("env", env::create_env_table(lua, &env.env)?)?,
            // Registers both `nitr.crypto` and `nitr.auth`.
            #[cfg(feature = "crypto")]
            Builtins::CRYPTO => {
                nitr.set("crypto", crypto::create_crypto_table(lua)?)?;
                nitr.set("auth", crypto::create_auth_table(lua)?)?;
            }
            #[cfg(not(feature = "crypto"))]
            Builtins::CRYPTO => return Err(not_compiled_in("crypto")),

            #[cfg(feature = "db")]
            Builtins::DATABASE => match &env.database {
                Some(path) => nitr.set("db", db::create_database_fn(lua, path, &env.sqlite)?)?,
                None => {
                    tracing::warn!("skipping builtin `db`: `database` is not configured");
                }
            },
            #[cfg(not(feature = "db"))]
            Builtins::DATABASE => return Err(not_compiled_in("db")),
            Builtins::CACHE => match &env.cache {
                Some(cache) => nitr.set("cache", cache::create_cache(lua, cache.clone())?)?,
                None => {
                    tracing::warn!("skipping builtin `cache`: no shared cache was provided");
                }
            },
            _ => continue,
        };
    }
    // Always registered, independent of the configured builtins: turning a
    // caught error into its structured form is part of the error model,
    // not an optional capability.
    nitr.set("errinfo", utils::create_errinfo_fn(lua)?)?;
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::Builtins;

    #[test]
    fn config_names_round_trip() {
        for (name, flag) in [
            ("dbg", Builtins::DEBUG),
            ("fetch", Builtins::FETCH),
            ("template", Builtins::TEMPLATE),
            ("json", Builtins::JSON),
            ("db", Builtins::DATABASE),
            ("http", Builtins::HTTP),
            ("log", Builtins::LOG),
            ("crypto", Builtins::CRYPTO),
            ("time", Builtins::TIME),
            ("validate", Builtins::VALIDATE),
            ("base64", Builtins::BASE64),
            ("path", Builtins::PATH),
            ("url", Builtins::URL),
            ("env", Builtins::ENV),
        ] {
            assert_eq!(Builtins::from_config_name(name), Some(flag));
        }
        assert_eq!(Builtins::from_config_name("nope"), None);
        // Combined flags and multi-field builtins have no single name.
        assert_eq!((Builtins::DEBUG | Builtins::JSON).nitr_name(), None);
        assert_eq!(Builtins::HTTP.nitr_name(), None);
        assert_eq!(Builtins::DATABASE.nitr_name(), Some("db"));
    }
}