nitr-core 0.0.0-beta.7

The resource-controlled Lua runtime at the heart of Nitr: sandboxed states, limits, and the runtime pool.
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
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
// 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>

use mlua::{
    FromLuaMulti, Function, HookTriggers, IntoLuaMulti, Lua, LuaOptions, LuaSerdeExt as _, StdLib,
    Table, Thread, Value, Variadic, VmState, chunk::ChunkMode,
};
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{Duration, Instant};

use crate::error::{Error, Result};

pub(crate) mod pool;
mod script;
pub use script::eval_script;
use script::load_error;
#[cfg(test)]
mod tests;

pub use pool::{RuntimeGuard, RuntimePool};

const MEMORY_LIMIT: usize = 8 * 1024 * 1024; // 8 MiB

/// Default wall-clock budget per handler invocation.
const EXEC_TIMEOUT: Duration = Duration::from_secs(30);

/// How often (in Lua VM instructions) the execution-deadline hook runs.
///
/// Not a throughput knob. While a count hook is set, Lua 5.4 keeps the
/// interpreter on its trap path for *every* instruction (`luaG_traceexec`
/// returns 1 whenever the counter has not reached zero — `ldebug.c`), so
/// the cost is per instruction whatever the interval; the interval only
/// decides how often the Rust closure runs. Measured with the `hook`
/// group in `crates/nitr/benches/runtime.rs` (2026-09-03, i7-6500U): a
/// 100 000-iteration arithmetic loop takes 0.99 ms without the hook and
/// 2.08 ms with it, and 2.06 ms at 4 000, 40 000 and 400 000 alike. That
/// factor of two on pure interpreter time is the price of stopping
/// `while true do end`, and raising this value would not recover any of
/// it — it would only coarsen the deadline's resolution.
const HOOK_INSTRUCTION_INTERVAL: u32 = 4000;

/// Extra wall-clock grace given to the outer async timeout so the
/// instruction hook (with its precise error message) fires first for
/// CPU-bound overruns.
const EXEC_TIMEOUT_GRACE: Duration = Duration::from_millis(100);

/// The base-library patches every state carries, applied once at
/// construction before any script loads.
///
/// **Text-only `load`.** Lua 5.4 performs no bytecode verification, so a
/// hand-patched binary chunk (out-of-range register or constant indices)
/// is type confusion inside the VM and, from there, arbitrary memory
/// access in the process — a complete escape from the sandbox the memory
/// limit and instruction hook enforce. The stock `load` defaults its mode
/// to `"bt"`; this wrapper pins it to `"t"` whatever the caller asked for,
/// and `string.dump` goes too, since producing bytecode is the other half
/// of that primitive. `loadfile` and `dofile`, present only with `io`,
/// are pinned the same way. The wrapper preserves the argument count: an
/// explicit `nil` environment is not the same as an absent one.
///
/// **An uncatchable budget error.** The instruction hook raises an
/// ordinary Lua error when the deadline passes, and the count restarts at
/// every fire, so `while true do pcall(function() while true do end end)
/// end` catches every trip inside the inner function and never lets the
/// outer loop accumulate enough instructions to trip on its own — one
/// request then holds a pooled state and a worker thread forever, past
/// every timeout, because nothing ever yields. `pcall`, `xpcall`,
/// `coroutine.resume` and a `load` reader function are the doors a caught
/// error can come back through; each is wrapped so a failure caught
/// *after* the deadline is re-raised as the budget error. The wrappers
/// are Lua functions rather than Rust callbacks so a body that yields (an
/// async builtin inside `pcall`) keeps working. The wrappers are inert
/// until a deadline is armed: a budgeted call, or the load of a script.
///
/// **No finalizers.** Lua runs `__gc` metamethods with hooks disabled, so
/// a finalizer is out of the budget's reach and a spinning one never
/// returns. `setmetatable` refuses a metatable carrying `__gc`; Lua only
/// registers a finalizer when the field is present at that call.
const PRELUDE: &str = r##"
local tripped, budget_msg = ...
local raw_load, raw_pcall, raw_xpcall = load, pcall, xpcall
local raw_setmetatable, rawget, type = setmetatable, rawget, type
local select, error = select, error

local function checked_load(chunk, ...)
    if chunk == nil and tripped() then error(budget_msg, 0) end
    return chunk, ...
end
load = function(chunk, name, _, ...)
    if select("#", ...) > 0 then
        return checked_load(raw_load(chunk, name, "t", (...)))
    end
    return checked_load(raw_load(chunk, name, "t"))
end
if string then string.dump = nil end

if loadfile then
    local raw_loadfile = loadfile
    loadfile = function(name, _, ...)
        if select("#", ...) > 0 then
            return raw_loadfile(name, "t", (...))
        end
        return raw_loadfile(name, "t")
    end
    dofile = function(name)
        local chunk, err = raw_loadfile(name, "t")
        if not chunk then error(err, 0) end
        return chunk()
    end
end

setmetatable = function(t, mt)
    if type(mt) == "table" and rawget(mt, "__gc") ~= nil then
        error("setmetatable: __gc finalizers are not allowed", 2)
    end
    return raw_setmetatable(t, mt)
end

-- Cost, measured with the `pcall` group in crates/nitr/benches/runtime.rs
-- (2026-09-03): the two extra frames and vararg round trips make a
-- successful pcall about 100 ns slower (10 000 calls: 1.12 ms stock,
-- 2.14 ms wrapped). Kept as is: the success path never crosses into
-- Rust, and the uncatchable budget error is what stops
-- `while true do pcall(...) end` from pinning a worker.
local function guard(ok, ...)
    if not ok and tripped() then error(budget_msg, 0) end
    return ok, ...
end
pcall = function(...) return guard(raw_pcall(...)) end
xpcall = function(...) return guard(raw_xpcall(...)) end
if coroutine then
    local raw_resume = coroutine.resume
    coroutine.resume = function(...) return guard(raw_resume(...)) end
end
"##;

/// The Lua runtime that provides an interface to execute Lua scripts and manage Lua state.
/// It allows for registering Rust extension modules on the `nitr` namespace,
/// running a configuration script, and calling Lua functions under the
/// state's execution budget.
#[derive(Debug)]
pub struct Runtime {
    lua: Lua,
    cfg: Option<Table>,
    /// Cached handler coroutine, reset and reused across requests to avoid
    /// per-request thread allocation and hook installation.
    thread: Option<Thread>,
    /// Execution deadline for the instruction hook, in nanoseconds since
    /// `epoch`. Stored atomically so the hook closure (installed once for
    /// the whole state) reads the current request's deadline without
    /// locking.
    deadline: Arc<AtomicU64>,
    epoch: Instant,
    /// Set when a failure leaves this state unfit for reuse (memory limit
    /// hit, panic). The pool rebuilds a poisoned state instead of handing
    /// it to the next request.
    poisoned: bool,
    opts: RuntimeOpts,
}

/// Grants additional execution budget to a runtime while it produces a
/// streaming response: each chunk handed to the client resets the
/// instruction-hook deadline, so the budget applies per chunk-production
/// slice instead of to the total stream lifetime.
#[derive(Debug, Clone)]
pub struct DeadlineHandle {
    deadline: Arc<AtomicU64>,
    epoch: Instant,
    budget: Option<Duration>,
}

impl DeadlineHandle {
    /// Grants another full execution budget from now. A no-op when the
    /// runtime has no execution timeout configured.
    pub fn extend(&self) {
        if let Some(budget) = self.budget {
            self.deadline.store(
                (self.epoch.elapsed() + budget).as_nanos() as u64,
                Ordering::Relaxed,
            );
        }
    }
}

/// A deadline armed by [`Runtime::arm`], lifted on drop.
struct Armed<'a>(&'a Runtime);

impl Drop for Armed<'_> {
    fn drop(&mut self) {
        self.0.clear_deadline();
    }
}

/// Options for configuring the Lua runtime.
#[derive(Debug)]
pub struct RuntimeOpts {
    /// Lua standard libraries to load.
    pub libs: mlua::StdLib,
    /// Lua memory limit in bytes.
    pub memory_limit: usize,
    /// Development mode: reload the HTTP handler script before each call and
    /// include error details (Lua tracebacks) in error responses.
    pub dev_mode: bool,
    /// Execution budget per handler invocation, enforced by an
    /// instruction-count hook (CPU-bound loops) and an outer async timeout
    /// (slow I/O). `None` disables both.
    pub exec_timeout: Option<Duration>,
    /// Directory `require` is confined to: `package.path` is pinned to it.
    /// `None` skips only the pinning — every `package`-bearing state has
    /// `package.loadlib` removed and `package.cpath` emptied regardless, so
    /// native modules can never load.
    pub package_dir: Option<PathBuf>,
    /// Further `require` roots, tried in order after
    /// [`package_dir`](Self::package_dir), each under the same rules (a
    /// dotted-identifier name, text-only chunks, no path from
    /// `package.path`). Ignored without a `package_dir`. `nitr test`
    /// puts its tests directory here, so shared helpers load in test
    /// states and never in the states that serve requests.
    pub extra_package_dirs: Vec<PathBuf>,
}

impl Runtime {
    /// It creates a new Lua runtime with default options.
    ///
    /// Such as some **built-in** libraries loaded and a default memory limit.
    ///
    /// `package` is not among them, so `require` is unavailable: confinement
    /// needs a directory to pin to, and this constructor takes no arguments to
    /// name one. Embedders that want module loading call [`Runtime::new_with`]
    /// with both [`StdLib::PACKAGE`] and a
    /// [`package_dir`](RuntimeOpts::package_dir).
    pub fn new() -> Result<Self> {
        // `io` and `os` are deliberately excluded from the defaults: they
        // give scripts ambient filesystem/process access. Opt in via
        // `RuntimeOpts::libs` when needed.
        //
        // `package` is excluded for a different reason: its confinement is
        // conditional on `package_dir`, which this constructor cannot supply,
        // so enabling it here would hand out a stock `package.path`. A default
        // that is safe but less capable is the right default for a library.
        Runtime::new_with(RuntimeOpts {
            libs: StdLib::NONE
                | StdLib::MATH
                | StdLib::TABLE
                | StdLib::STRING
                | StdLib::UTF8
                | StdLib::COROUTINE,
            memory_limit: MEMORY_LIMIT,
            dev_mode: false,
            exec_timeout: Some(EXEC_TIMEOUT),
            package_dir: None,
            extra_package_dirs: Vec::new(),
        })
    }

    /// It creates a new Lua runtime with specified options.
    ///
    /// For example, it allows for customizing the Lua standard libraries to load
    /// like `io`, `math`, `os`, etc as well as the memory limits.
    ///
    /// Some scrubbing applies to every state, whatever the options:
    /// `collectgarbage` is always removed (the memory limit is enforced by
    /// the allocator, not the collector), and `package`-bearing states can
    /// never load native modules — see
    /// [`package_dir`](RuntimeOpts::package_dir).
    pub fn new_with(opts: RuntimeOpts) -> Result<Self> {
        let lua = Lua::new_with(opts.libs, LuaOptions::default())?;
        lua.set_memory_limit(opts.memory_limit)?;

        // The base library is always loaded, and it carries `dofile` and
        // `loadfile` — reading and executing arbitrary files is the same
        // ambient authority the excluded-by-default `io` library gates.
        // They follow the same opt-in: absent unless IO was requested.
        if !opts.libs.contains(StdLib::IO) {
            let globals = lua.globals();
            globals.set("dofile", Value::Nil)?;
            globals.set("loadfile", Value::Nil)?;
        }

        // Not a confinement escape: the memory limit is enforced by the
        // allocator, not the collector, so `collectgarbage("stop")` only
        // reaches that limit sooner and poisons the state. It goes because no
        // Nitr script has business pacing the collector, and `("count")` is a
        // heap oracle.
        lua.globals().set("collectgarbage", Value::Nil)?;

        // Forbid loading native modules in every `package`-bearing state,
        // not only the confined ones. mlua's safe constructor already stubs
        // `package.loadlib` and the C-library searchers (`searchers[3]` is
        // replaced, `[4]` removed — see mlua's `disable_c_modules`), so this
        // is defense-in-depth over that guarantee, not the load-bearing
        // layer: it is the scrub Nitr owns and tests, and the one that would
        // survive if the state were ever built another way.
        if opts.libs.contains(StdLib::PACKAGE) {
            let package: Table = lua.globals().get("package")?;
            package.set("loadlib", Value::Nil)?;
            package.set("cpath", "")?;
            // `searchpath(name, template)` takes its template as an
            // argument, never from `package.path`, so no pinning reaches
            // it: `package.searchpath("passwd", "/etc/?")` answers whether
            // any file on the box exists and is readable. Nothing in Nitr
            // uses it (the confined searcher below does its own lookup).
            package.set("searchpath", Value::Nil)?;

            // Confine `require` to the configured directory. Only the
            // pinning is conditional: without a directory there is nothing
            // to pin to.
            //
            // `package.path` is set for anything that reads it, but it is
            // not what confines: the stock file searcher would honor a
            // script's later reassignment of `package.path`, and it loads
            // whatever it finds in whatever mode — bytecode included. The
            // searcher installed here owns the directory itself, maps the
            // module name to a path without ever consulting `package.path`,
            // and compiles text only.
            if let Some(dir) = &opts.package_dir {
                let roots: Vec<PathBuf> = std::iter::once(dir)
                    .chain(&opts.extra_package_dirs)
                    .cloned()
                    .collect();
                let shown = roots
                    .iter()
                    .map(|root| {
                        let shown = root.to_string_lossy();
                        format!("{shown}/?.lua;{shown}/?/init.lua")
                    })
                    .collect::<Vec<_>>()
                    .join(";");
                package.set("path", shown)?;
                let searchers: Table = package.get("searchers")?;
                let preload: Value = searchers.get(1)?;
                let confined = lua.create_table()?;
                confined.set(1, preload)?;
                confined.set(2, confined_searcher(&lua, roots)?)?;
                package.set("searchers", confined)?;
            }
        }

        let deadline = Arc::new(AtomicU64::new(u64::MAX));
        let epoch = Instant::now();

        // See `PRELUDE`. The tripped check reads the same deadline the hook
        // does, so the two cannot disagree about whether the budget is gone.
        let tripped = {
            let deadline = deadline.clone();
            lua.create_function(move |_, ()| {
                Ok(epoch.elapsed().as_nanos() as u64 > deadline.load(Ordering::Relaxed))
            })?
        };
        lua.load(PRELUDE)
            .set_name("=nitr-prelude")
            .call::<()>((tripped, crate::error::EXEC_BUDGET_MSG))?;

        // Instruction-count hook: the only mechanism that can stop a
        // CPU-bound loop (`while true do end` never reaches an await point,
        // blocking both the async timeout and the executor).
        //
        // It is installed *globally* rather than per coroutine: Lua 5.4
        // propagates a state's hook to threads created from it, so a
        // `coroutine.create` inside a handler inherits the budget instead of
        // escaping it.
        if opts.exec_timeout.is_some() {
            let deadline = deadline.clone();
            lua.set_global_hook(
                HookTriggers::new().every_nth_instruction(HOOK_INSTRUCTION_INTERVAL),
                move |_, _| {
                    if epoch.elapsed().as_nanos() as u64 > deadline.load(Ordering::Relaxed) {
                        return Err(mlua::Error::RuntimeError(
                            crate::error::EXEC_BUDGET_MSG.into(),
                        ));
                    }
                    Ok(VmState::Continue)
                },
            )?;
        }

        Ok(Self {
            lua,
            cfg: None,
            thread: None,
            deadline,
            epoch,
            poisoned: false,
            opts,
        })
    }

    /// Whether a failure has left this state unfit for reuse (a memory
    /// limit hit or a caught panic). The pool rebuilds a poisoned state
    /// rather than handing it to the next request.
    pub fn is_poisoned(&self) -> bool {
        self.poisoned
    }

    /// Marks this state unfit for reuse. Used by the HTTP layer when a
    /// panic is caught while the state is checked out.
    pub fn poison(&mut self) {
        self.poisoned = true;
    }

    /// Registers a Rust extension module: the closure runs now (and its
    /// result is a table by Lua module convention), mounted at
    /// `nitr.ext.<name>` — one level below the standard library, so a
    /// module can never collide with a builtin. Fails when the name is
    /// already taken, so two extensions cannot shadow each other.
    ///
    /// This is the embedding-side extension point; HTTP applications use
    /// `ServerBuilder::module()` in the `nitr-http` crate, which applies
    /// the closure to every pooled state.
    ///
    /// ## Error attribution
    ///
    /// An error a module raises should say which module failed. Wrap Rust
    /// errors with a `module <name>` context and [`ErrorInfo`] classifies
    /// them as `kind = "module"` with the module named; a module that
    /// returns an opaque string makes its failures everyone's problem:
    ///
    /// ```ignore
    /// t.set("query", lua.create_function(|_, sql: String| {
    ///     run(&sql).map_err(|err| mlua::Error::WithContext {
    ///         context: "module db".into(),
    ///         cause: std::sync::Arc::new(mlua::Error::external(err)),
    ///     })
    /// })?)?;
    /// ```
    ///
    /// [`ErrorInfo`]: crate::ErrorInfo
    pub fn register_module<F>(&self, name: &str, f: F) -> Result
    where
        F: Fn(&Lua) -> mlua::Result<Table>,
    {
        let value = f(&self.lua)?;
        crate::ns::mount(&self.lua, name, value)
    }

    /// It sets the Lua configuration script that runs once at server startup.
    ///
    /// The script is a plain Lua chunk in the same shape handler scripts
    /// use: statements at the top level ending in `return { ... }`, with
    /// the provided arguments available as its varargs (`local db = ...`).
    ///
    /// The Lua table containing the configuration fields can be accessed later
    /// using the [`cfg()`](Self::cfg) method.
    pub async fn register_cfg_fn(&mut self, cfg_src: &Path, args: impl IntoLuaMulti) -> Result {
        let data = std::fs::read(cfg_src).map_err(|err| {
            Error::Script(format!(
                "failed to read the Lua configuration file {}: {err}",
                cfg_src.display()
            ))
        })?;

        let chunk = self
            .load_chunk(data, cfg_src)
            .map_err(|err| load_error(cfg_src, err))?;
        // The chunk itself receives the arguments as its varargs, so the
        // script sees `db` via `local db = ...` at the top. A failure while
        // it runs (a misspelled `db:` method, a nil index) gets the same
        // in-context rendering as a parse error. The run is budgeted like
        // a call: a loop here would hang every boot and reload.
        let value = {
            let _armed = self.arm();
            let call = chunk.call_async::<Value>(args);
            match self.opts.exec_timeout {
                Some(timeout) => tokio::time::timeout(timeout + EXEC_TIMEOUT_GRACE, call)
                    .await
                    .map_err(|_| Error::Timeout)?,
                None => call.await,
            }
            .map_err(|err| load_error(cfg_src, err))?
        };
        let cfg = match value {
            Value::Table(cfg) => cfg,
            // The pre-1.0 wrapper form; point migrations at the new shape.
            Value::Function(_) => {
                return Err(Error::Script(format!(
                    "the configuration script {} returned a function; the \
                     `function(db) ... end` wrapper is no longer supported — \
                     take arguments via `local db = ...` at the top level and \
                     end the script with `return {{ ... }}`",
                    cfg_src.display()
                )));
            }
            other => {
                return Err(Error::Script(format!(
                    "the configuration script {} must return a table, got {}",
                    cfg_src.display(),
                    other.type_name()
                )));
            }
        };

        self.cfg = Some(cfg);
        Ok(())
    }

    /// The underlying Lua state, for advanced customization beyond
    /// [`register_module()`](Self::register_module).
    pub fn lua(&self) -> &Lua {
        &self.lua
    }

    /// The Lua configuration table that is returned after the script handler is invoked.
    pub fn cfg(&self) -> Option<&Table> {
        self.cfg.as_ref()
    }

    /// Serializes the configuration table into a plain-data snapshot that can
    /// be injected into other runtimes with
    /// [`set_cfg_snapshot()`](Self::set_cfg_snapshot).
    ///
    /// Returns `None` when no configuration script has been registered.
    pub fn cfg_snapshot(&self) -> Result<Option<serde_json::Value>> {
        let Some(cfg) = &self.cfg else {
            return Ok(None);
        };
        let snapshot = serde_json::to_value(cfg).map_err(|err| {
            Error::Config(format!(
                "the configuration script must return plain data \
                 (tables, strings, numbers, booleans): {err}"
            ))
        })?;
        Ok(Some(snapshot))
    }

    /// Injects a configuration snapshot produced by
    /// [`cfg_snapshot()`](Self::cfg_snapshot) as this runtime's
    /// configuration table.
    pub fn set_cfg_snapshot(&mut self, snapshot: &serde_json::Value) -> Result {
        match self.lua.to_value(snapshot)? {
            Value::Table(table) => {
                self.cfg = Some(table);
                Ok(())
            }
            _ => Err(Error::Config(
                "the configuration snapshot must be a table".into(),
            )),
        }
    }

    /// Returns the cached handler coroutine reset to the given function,
    /// creating it when necessary.
    ///
    /// The handler runs in its own coroutine; the execution-deadline hook is
    /// installed globally at construction and inherited by every thread,
    /// including coroutines the script creates itself.
    fn handler_thread(&mut self, http_fn: Function) -> Result<Thread> {
        if let Some(thread) = self.thread.take()
            && thread.reset(http_fn.clone()).is_ok()
        {
            return Ok(thread);
        }
        Ok(self.lua.create_thread(http_fn)?)
    }

    /// Calls a Lua function under the configured execution budget
    /// ([`RuntimeOpts::exec_timeout`]): an instruction-count hook stops
    /// CPU-bound overruns and an outer async timeout stops slow I/O
    /// ([`Error::Timeout`]). The function runs on this runtime's cached
    /// coroutine so the instruction-count hook applies.
    pub async fn call_function<R: FromLuaMulti>(
        &mut self,
        f: Function,
        args: impl IntoLuaMulti,
    ) -> Result<R> {
        let thread = self.handler_thread(f.clone())?;
        let result = match self.opts.exec_timeout {
            Some(timeout) => {
                self.deadline.store(
                    (self.epoch.elapsed() + timeout).as_nanos() as u64,
                    Ordering::Relaxed,
                );
                // The async timeout covers the disjoint failure mode: time
                // spent suspended in async I/O, where no Lua instructions
                // execute and the hook cannot fire.
                let timed = tokio::time::timeout(
                    timeout + EXEC_TIMEOUT_GRACE,
                    thread.clone().into_async::<R>(args)?,
                )
                .await;
                match timed {
                    Ok(result) => result,
                    Err(_) => {
                        // The coroutine is still suspended inside whatever
                        // builtin it was awaiting, and the pending Rust
                        // future — with everything it holds, an open SQLite
                        // transaction among them — lives on that coroutine's
                        // stack. Dropping the thread handle would leave both
                        // to a later collection cycle the script cannot
                        // force (`collectgarbage` is gone), so the state
                        // could serve its next request with the previous
                        // one's work still in flight. Close the stack now
                        // and collect, so the future is dropped here.
                        //
                        // Measured (`gc_collect_loaded_state` in
                        // crates/nitr/benches/runtime.rs): a full
                        // collection over ~3 MiB of live tables is ~1 ms,
                        // paid once per timed-out request on this worker
                        // — nothing next to the budget that request
                        // already spent, so it stays inline rather than
                        // hopping to the blocking pool.
                        let _ = thread.reset(f);
                        let _ = self.lua.gc_collect();
                        self.thread = Some(thread);
                        self.clear_deadline();
                        return Err(Error::Timeout);
                    }
                }
            }
            None => thread.clone().into_async::<R>(args)?.await,
        };
        // Keep the coroutine for the next request (reset() also recovers
        // errored threads on Lua 5.4).
        self.thread = Some(thread);
        self.clear_deadline();
        self.classify(result)
    }

    /// Arms the execution deadline for a stretch of work; the guard lifts
    /// it again. A no-op without an execution timeout.
    fn arm(&self) -> Armed<'_> {
        if let Some(timeout) = self.opts.exec_timeout {
            self.deadline.store(
                (self.epoch.elapsed() + timeout).as_nanos() as u64,
                Ordering::Relaxed,
            );
        }
        Armed(self)
    }

    /// Runs `f` on this state under the execution budget, as a call is:
    /// the load of a script has the same limits as the handlers in it.
    pub fn budgeted<R>(&self, f: impl FnOnce(&Lua) -> Result<R>) -> Result<R> {
        let _armed = self.arm();
        f(&self.lua)
    }

    /// Lifts the deadline once a budgeted call has returned. The state is
    /// idle between calls, and Lua that runs outside a call — a dev-mode
    /// reload, an embedder's own `eval` — must not inherit a deadline the
    /// last request already blew through: the hook would fire within 4000
    /// instructions and the `pcall` guard would re-raise on every caught
    /// error, so the "next" request would fail before it started.
    fn clear_deadline(&self) {
        self.deadline.store(u64::MAX, Ordering::Relaxed);
    }

    /// Calls a Lua function under the instruction-hook deadline only — no
    /// outer async timeout — for long-lived streaming calls. The caller is
    /// expected to keep granting budget via [`DeadlineHandle::extend()`] as
    /// chunks are delivered; time suspended in async I/O (e.g. waiting for a
    /// slow client) is deliberately unbounded.
    pub async fn call_function_streaming<R: FromLuaMulti>(
        &mut self,
        f: Function,
        args: impl IntoLuaMulti,
    ) -> Result<R> {
        let thread = self.handler_thread(f)?;
        if let Some(timeout) = self.opts.exec_timeout {
            self.deadline.store(
                (self.epoch.elapsed() + timeout).as_nanos() as u64,
                Ordering::Relaxed,
            );
        }
        let result = thread.clone().into_async::<R>(args)?.await;
        self.thread = Some(thread);
        self.clear_deadline();
        self.classify(result)
    }

    /// Converts a call outcome into a [`Result`], marking the state
    /// poisoned when the failure is one it cannot cleanly recover from.
    fn classify<R>(&mut self, result: mlua::Result<R>) -> Result<R> {
        match result {
            Ok(value) => Ok(value),
            Err(err) => {
                let err = Error::from(err);
                if err.poisons_state() {
                    self.poisoned = true;
                }
                Err(err)
            }
        }
    }

    /// A handle for extending this runtime's execution deadline from
    /// long-lived calls (see
    /// [`call_function_streaming()`](Self::call_function_streaming)).
    pub fn deadline_handle(&self) -> DeadlineHandle {
        DeadlineHandle {
            deadline: self.deadline.clone(),
            epoch: self.epoch,
            budget: self.opts.exec_timeout,
        }
    }

    /// Whether this runtime operates in development mode.
    pub fn dev_mode(&self) -> bool {
        self.opts.dev_mode
    }
}

/// The `require` searcher for a confined state: `a.b` resolves to
/// `<root>/a/b.lua` or `<root>/a/b/init.lua` for each root in order, and
/// nothing else.
///
/// The module name is restricted to a dotted identifier before it touches
/// a path, so no spelling of a name can name a parent directory or an
/// absolute location; the roots are captured at construction rather than
/// read back from `package.path`, so a script cannot widen the search by
/// reassigning that string. Chunks compile as text only, for the same
/// reason `load` does (see [`PRELUDE`]).
fn confined_searcher(lua: &Lua, roots: Vec<PathBuf>) -> mlua::Result<Function> {
    lua.create_function(move |lua, name: String| {
        let well_formed = !name.is_empty()
            && name
                .chars()
                .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '.')
            && name.split('.').all(|segment| !segment.is_empty());
        if !well_formed {
            let note = format!(
                "\n\tmodule name '{name}' is not a dotted identifier (letters, digits and '_' \
                 between dots)"
            );
            return Ok(Variadic::from_iter([Value::String(
                lua.create_string(note)?,
            )]));
        }
        let rel = name.replace('.', "/");
        let mut tried = String::new();
        let candidates = roots.iter().flat_map(|dir| {
            [
                dir.join(format!("{rel}.lua")),
                dir.join(&rel).join("init.lua"),
            ]
        });
        for candidate in candidates {
            match std::fs::read(&candidate) {
                Ok(data) => {
                    let loader = lua
                        .load(data)
                        .set_name(format!("@{}", candidate.display()))
                        .set_mode(ChunkMode::Text)
                        .into_function()?;
                    let path = lua.create_string(candidate.to_string_lossy().as_bytes())?;
                    return Ok(Variadic::from_iter([
                        Value::Function(loader),
                        Value::String(path),
                    ]));
                }
                Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
                    tried.push_str(&format!("\n\tno file '{}'", candidate.display()));
                }
                Err(err) => {
                    return Err(mlua::Error::RuntimeError(format!(
                        "failed to read module '{name}' at {}: {err}",
                        candidate.display()
                    )));
                }
            }
        }
        Ok(Variadic::from_iter([Value::String(
            lua.create_string(tried)?,
        )]))
    })
}