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
770
771
772
773
// 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 super::*;

fn write_temp_script(name: &str, content: &str) -> PathBuf {
    // `fs::write` truncates before writing, so a path two tests share is
    // a race; the counter keeps every call on its own file.
    static NEXT: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(0);
    let id = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    let path =
        std::env::temp_dir().join(format!("nitr-rt-test-{}-{id}-{name}", std::process::id()));
    std::fs::write(&path, content).expect("write temp script");
    path
}

fn test_runtime(exec_timeout: Option<Duration>) -> Runtime {
    Runtime::new_with(RuntimeOpts {
        libs: StdLib::MATH | StdLib::TABLE | StdLib::STRING,
        memory_limit: MEMORY_LIMIT,
        dev_mode: false,
        exec_timeout,
        package_dir: None,
        extra_package_dirs: Vec::new(),
    })
    .expect("runtime")
}

/// A `package`-bearing state, confined when a directory is given — the
/// single home for the options both `package` tests build on, so they
/// cannot drift apart in which libraries they enable.
fn package_runtime(package_dir: Option<PathBuf>) -> Runtime {
    Runtime::new_with(RuntimeOpts {
        libs: StdLib::MATH | StdLib::TABLE | StdLib::STRING | StdLib::PACKAGE,
        memory_limit: MEMORY_LIMIT,
        dev_mode: false,
        exec_timeout: None,
        package_dir,
        extra_package_dirs: Vec::new(),
    })
    .expect("runtime")
}

fn eval_function(rt: &Runtime, src: &str) -> Function {
    rt.lua().load(src).eval().expect("eval handler function")
}

#[test]
fn expression_form_typos_report_the_real_line() {
    // An expression-form script (`function(...) ... end`, no `return`)
    // with a typo mid-body. mlua's own `eval` would report its block
    // fallback — "<name> expected" at the `function(` line — masking
    // the actual position; the dual-parse must surface line 4.
    let rt = Runtime::new().expect("runtime");
    let path = write_temp_script(
        "expr-typo.lua",
        "-- comment\nfunction(db)\n    local ok = 1\n    lodcal users = 2\n    return {}\nend",
    );
    let err = rt.eval_script(&path).expect_err("typo must fail the load");
    let message = err.to_string();
    assert!(message.contains("expr-typo.lua:4"), "{message}");
    assert!(message.contains("near 'users'"), "{message}");
    // The caret spans the token the parser stopped at (`users`, five
    // wide); exact column alignment is covered by the snippet unit test.
    assert!(message.contains("^^^^^"), "{message}");
    std::fs::remove_file(&path).ok();
}

#[test]
fn both_script_forms_still_evaluate() {
    let rt = Runtime::new().expect("runtime");
    // Expression form.
    let path = write_temp_script("expr-ok.lua", "function(x)\n    return x\nend");
    assert!(matches!(
        rt.eval_script(&path).expect("expression form"),
        Value::Function(_)
    ));
    std::fs::remove_file(&path).ok();
    // Statement-block form (handler scripts).
    let path = write_temp_script("block-ok.lua", "local t = { ok = true }\nreturn t");
    assert!(matches!(
        rt.eval_script(&path).expect("block form"),
        Value::Table(_)
    ));
    std::fs::remove_file(&path).ok();
}

#[test]
fn a_bare_call_script_evaluates_as_an_expression() {
    // `f()` is valid as an expression *and* as a call statement. The
    // expression parse must stay first for this shape: as a block the
    // chunk would compile fine and evaluate to nothing.
    let rt = Runtime::new().expect("runtime");
    let path = write_temp_script("call-expr.lua", "-- comment\nstring.rep('ab', 2)");
    let value = rt.eval_script(&path).expect("call expression");
    std::fs::remove_file(&path).ok();
    match value {
        Value::String(s) => assert_eq!(s.to_str().expect("utf-8").as_ref(), "abab"),
        other => panic!("expected the call's result, got {}", other.type_name()),
    }
}

#[test]
fn block_form_typos_report_the_real_line() {
    // A handler-shaped script (leading comment, then `local`): the
    // expression parse is skipped for it, and the diagnostic must still be
    // the block parse's own — line 3, the typo — exactly as when both
    // parses ran and the furthest error won.
    let rt = Runtime::new().expect("runtime");
    let path = write_temp_script(
        "block-typo.lua",
        "-- comment\nlocal ok = 1\nlodcal users = 2\nreturn {}",
    );
    let err = rt.eval_script(&path).expect_err("typo must fail the load");
    std::fs::remove_file(&path).ok();
    let message = err.to_string();
    assert!(message.contains("block-typo.lua:3"), "{message}");
    assert!(message.contains("near 'users'"), "{message}");
}

#[tokio::test]
async fn function_calls_round_trip() {
    let mut rt = test_runtime(Some(Duration::from_secs(5)));
    let f = eval_function(
        &rt,
        "return function(req) return { status = 200, body = req } end",
    );

    // The cached coroutine must keep working across calls.
    for _ in 0..3 {
        let resp = rt
            .call_function::<Table>(f.clone(), "ping")
            .await
            .expect("call function");
        assert_eq!(resp.get::<String>("body").expect("body"), "ping");
    }
}

#[tokio::test]
async fn cpu_bound_loops_hit_the_instruction_hook() {
    let mut rt = test_runtime(Some(Duration::from_millis(100)));
    let looping = eval_function(&rt, "return function() while true do end end");

    let err = rt
        .call_function::<Table>(looping, Value::Nil)
        .await
        .expect_err("must time out");
    assert!(err.to_string().contains("time budget"), "got: {err}");

    // The state must survive and serve the next call after a reset.
    let ok = eval_function(&rt, "return function() return { body = 'alive' } end");
    let resp = rt
        .call_function::<Table>(ok, Value::Nil)
        .await
        .expect("recovered");
    assert_eq!(resp.get::<String>("body").expect("body"), "alive");
}

/// The default library set is the sandbox: nothing that reaches the
/// filesystem, the process, or the VM internals may exist as a global.
/// This is the test that makes flipping a bit in the default `StdLib`
/// set a visible failure instead of an invisible policy change.
#[test]
fn the_default_library_set_carries_no_ambient_authority() {
    let rt = Runtime::new().expect("runtime");
    let globals = rt.lua().globals();

    // Filesystem, process, and debug-introspection entry points, the
    // base-library functions that read arbitrary files, and the collector
    // control. `package` is absent from the default set entirely, so
    // `require` cannot reach a search path nothing pinned.
    for name in [
        "io",
        "os",
        "debug",
        "dofile",
        "loadfile",
        "collectgarbage",
        "package",
        "require",
    ] {
        let value: Value = globals.get(name).expect("read global");
        assert!(
            value.is_nil(),
            "`{name}` must not be exposed by the default sandbox, got a {}",
            value.type_name()
        );
    }

    // The safe computational set is present — the sandbox is a policy,
    // not an accident of loading nothing.
    for name in ["math", "table", "string", "utf8", "coroutine", "pcall"] {
        let value: Value = globals.get(name).expect("read global");
        assert!(!value.is_nil(), "`{name}` must be available by default");
    }

    // `load` is a deliberate keep, not an oversight: a *text* chunk runs
    // under the same instruction hook and memory limit as the code that
    // compiled it, so it grants no authority the caller lacks. Asserted
    // positively so a later tidy-up cannot quietly remove it.
    let compiled: i64 = rt
        .lua()
        .load("return load('return 41 + 1')()")
        .eval()
        .expect("load compiles and runs a chunk");
    assert_eq!(compiled, 42, "`load` must remain available");

    // Bytecode is the exception: Lua 5.4 does not verify it, so a binary
    // chunk is a VM escape. The mode is pinned to text whatever the caller
    // passes, and `string.dump` — the way to produce bytecode — is gone.
    let (ok, err): (bool, String) = rt
        .lua()
        .load(
            r#"local f, err = load("\27LuaT\0\25\147\r\n\26\n", "bc", "b")
               return f ~= nil, tostring(err)"#,
        )
        .eval()
        .expect("eval");
    assert!(!ok, "a binary chunk must not load: {err}");
    assert!(err.contains("binary"), "the refusal must say why: {err}");
    let dump: Value = rt.lua().load("return string.dump").eval().expect("eval");
    assert!(dump.is_nil(), "`string.dump` must not be exposed");

    // The wrapper keeps `load`'s argument shape: an explicit environment
    // still applies, and an explicit `nil` environment still means "no
    // globals" rather than "the default globals".
    let (with_env, no_env): (i64, bool) = rt
        .lua()
        .load(
            r#"local f = load("return x", "chunk", "t", { x = 7 })
               local g = load("return math.pi", "chunk", "t", nil)
               local ok = pcall(g)
               return f(), not ok"#,
        )
        .eval()
        .expect("eval");
    assert_eq!(with_env, 7, "an explicit environment must be honored");
    assert!(
        no_env,
        "an explicit nil environment must not become the globals"
    );
}

/// The budget error must not be catchable: the hook's count restarts at
/// every fire, so a loop that `pcall`s a spinning closure catches every
/// trip inside the closure and never trips on its own. Without the
/// `pcall`/`xpcall`/`coroutine.resume` wrappers this test never returns.
#[tokio::test]
async fn the_execution_budget_cannot_be_caught_and_ignored() {
    for body in [
        "while true do pcall(function() while true do end end) end",
        "while true do xpcall(function() while true do end end, function(e) return e end) end",
        "while true do coroutine.resume(coroutine.create(function() while true do end end)) end",
        // `load` runs a reader function inside its own protected parser
        // and returns the reader's error as `nil, msg` (lbaselib.c
        // `generic_reader`, `luaB_load`).
        "while true do load(function() while true do end end) end",
        // The honest variant: a retry loop that can never succeed once
        // the budget is gone.
        "repeat local ok = pcall(function() while true do end end) until ok",
    ] {
        let mut rt = Runtime::new_with(RuntimeOpts {
            libs: StdLib::MATH | StdLib::TABLE | StdLib::STRING | StdLib::COROUTINE,
            memory_limit: MEMORY_LIMIT,
            dev_mode: false,
            exec_timeout: Some(Duration::from_millis(100)),
            package_dir: None,
            extra_package_dirs: Vec::new(),
        })
        .expect("runtime");
        let looping = eval_function(&rt, &format!("return function() {body} end"));
        let started = Instant::now();
        let err = tokio::time::timeout(
            Duration::from_secs(10),
            rt.call_function::<Value>(looping, Value::Nil),
        )
        .await
        .unwrap_or_else(|_| panic!("`{body}` escaped the budget and never returned"))
        .expect_err("must trip the budget");
        assert!(err.to_string().contains("time budget"), "`{body}`: {err}");
        assert!(
            started.elapsed() < Duration::from_secs(5),
            "`{body}` took {:?} to trip a 100 ms budget",
            started.elapsed()
        );

        // A caught error *before* the deadline is still an ordinary
        // caught error: the wrappers only bite once the budget is gone.
        let caught: String = rt
            .lua()
            .load("local ok, e = pcall(error, 'plain') return tostring(ok) .. ':' .. e")
            .eval()
            .expect("eval");
        assert_eq!(caught, "false:plain");
    }
}

/// The load of a script is budgeted like a call: a loop at file scope
/// fails the load instead of hanging the boot, `nitr check` or a reload.
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn script_loads_run_under_the_execution_budget() {
    let mut rt = test_runtime(Some(Duration::from_millis(100)));
    let path = write_temp_script("spin.lua", "while true do end");

    let started = Instant::now();
    let err = tokio::time::timeout(Duration::from_secs(10), rt.register_cfg_fn(&path, ()))
        .await
        .unwrap_or_else(|_| panic!("the configuration script escaped the budget"))
        .expect_err("must trip the budget");
    assert!(err.to_string().contains("time budget"), "{err}");
    assert!(
        started.elapsed() < Duration::from_secs(5),
        "{:?}",
        started.elapsed()
    );

    // `eval_script` is synchronous: a hang would hang the test, so it runs
    // on a thread the test can give up on.
    let spun = tokio::task::spawn_blocking(move || {
        let err = rt.eval_script(&path).expect_err("must trip the budget");
        (rt, err.to_string())
    });
    let (rt, err) = tokio::time::timeout(Duration::from_secs(10), spun)
        .await
        .unwrap_or_else(|_| panic!("the handler script escaped the budget"))
        .expect("join");
    assert!(err.contains("time budget"), "{err}");

    // The deadline is gone once the load returns: the state is usable.
    let plain: i64 = rt.lua().load("return 1 + 1").eval().expect("eval");
    assert_eq!(plain, 2);
}

/// With `io` enabled, `dofile` and `loadfile` load text only, as `load`
/// does: bytecode is the sandbox escape they would otherwise reopen.
#[test]
fn dofile_and_loadfile_load_text_only() {
    let rt = Runtime::new_with(RuntimeOpts {
        libs: StdLib::MATH | StdLib::TABLE | StdLib::STRING | StdLib::IO,
        memory_limit: MEMORY_LIMIT,
        dev_mode: false,
        exec_timeout: None,
        package_dir: None,
        extra_package_dirs: Vec::new(),
    })
    .expect("runtime");
    let lua = rt.lua();
    let text = write_temp_script("chunk.lua", "return 42");
    let bytecode = lua
        .load("return 42")
        .into_function()
        .expect("compile")
        .dump(false);
    let binary = write_temp_script("chunk.luac", "");
    std::fs::write(&binary, bytecode).expect("write bytecode");
    lua.globals()
        .set("text", text.to_string_lossy().to_string())
        .expect("set");
    lua.globals()
        .set("binary", binary.to_string_lossy().to_string())
        .expect("set");
    let (loaded, reason, ran, ran_reason, via_text, via_dofile): (
        bool,
        String,
        bool,
        String,
        i64,
        i64,
    ) = lua
        .load(
            r#"local f, err = loadfile(binary)
               local ok, why = pcall(dofile, binary)
               return f ~= nil, tostring(err), ok, tostring(why), loadfile(text)(), dofile(text)"#,
        )
        .eval()
        .expect("eval");
    assert!(!loaded, "loadfile must refuse bytecode");
    assert!(reason.contains("binary chunk"), "{reason}");
    assert!(!ran, "dofile must refuse bytecode");
    assert!(ran_reason.contains("binary chunk"), "{ran_reason}");
    assert_eq!((via_text, via_dofile), (42, 42));
    let _ = std::fs::remove_file(text);
    let _ = std::fs::remove_file(binary);
}

/// Lua runs `__gc` finalizers with hooks off (lgc.c `GCTM` sets
/// `allowhook = 0`), so no budget reaches a spinning finalizer and the
/// state never returns. A metatable carrying `__gc` is refused instead.
#[tokio::test]
async fn a_finalizer_cannot_escape_the_execution_budget() {
    for body in [
        "setmetatable({}, {__gc = function() while true do end end})",
        // Lua registers a finalizer when `__gc` is present at
        // `setmetatable` time and calls whatever the field holds later.
        "local mt = {__gc = true} setmetatable({}, mt) mt.__gc = function() while true do end end",
    ] {
        let mut rt = test_runtime(Some(Duration::from_millis(100)));
        let src = format!(
            "return function() {body} local t = {{}} while true do t[#t % 64 + 1] = {{}} end end"
        );
        let looping = eval_function(&rt, &src);
        let started = Instant::now();
        let err = tokio::time::timeout(
            Duration::from_secs(10),
            rt.call_function::<Value>(looping, Value::Nil),
        )
        .await
        .unwrap_or_else(|_| panic!("`{body}` escaped the budget and never returned"))
        .expect_err("must fail");
        assert!(err.to_string().contains("__gc"), "`{body}`: {err}");
        assert!(
            started.elapsed() < Duration::from_secs(5),
            "`{body}` took {:?}",
            started.elapsed()
        );
    }

    let rt = test_runtime(None);
    let plain: bool = rt
        .lua()
        .load("local t = setmetatable({}, {__index = {x = true}}) return t.x")
        .eval()
        .expect("a metatable without __gc is still accepted");
    assert!(plain);
}

/// A handler that stalls in an async builtin past the budget: the outer
/// timeout fires, and the state must come back clean — the suspended
/// coroutine reset and its pending future dropped *now*, not at some
/// later collection — so the next request on the same state does not
/// inherit the previous one's in-flight work.
#[tokio::test]
async fn an_async_stall_times_out_and_the_state_recovers() {
    let mut rt = test_runtime(Some(Duration::from_millis(100)));
    // A future whose drop is observable, standing in for a fetch or a
    // database transaction left mid-flight.
    let dropped = Arc::new(std::sync::atomic::AtomicBool::new(false));
    struct Flag(Arc<std::sync::atomic::AtomicBool>);
    impl Drop for Flag {
        fn drop(&mut self) {
            self.0.store(true, std::sync::atomic::Ordering::SeqCst);
        }
    }
    let flag = dropped.clone();
    let stall = rt
        .lua()
        .create_async_function(move |_, ()| {
            let flag = Flag(flag.clone());
            async move {
                let _held = flag;
                tokio::time::sleep(Duration::from_secs(60)).await;
                Ok(())
            }
        })
        .expect("stall fn");
    rt.lua().globals().set("stall", stall).expect("set");

    let handler = eval_function(&rt, "return function() stall() return 'unreachable' end");
    let err = rt
        .call_function::<Value>(handler, Value::Nil)
        .await
        .expect_err("must time out");
    assert!(matches!(err, Error::Timeout), "got: {err}");
    assert!(
        dropped.load(std::sync::atomic::Ordering::SeqCst),
        "the stalled future must be dropped when the call times out"
    );
    assert!(!rt.is_poisoned(), "a timeout is recoverable, not poison");

    let ok = eval_function(&rt, "return function() return 'alive' end");
    let alive: String = rt
        .call_function(ok, Value::Nil)
        .await
        .expect("the state serves the next call");
    assert_eq!(alive, "alive");
}

/// `package.loadlib` is a confinement escape that ignores `package.cpath`:
/// it takes an absolute path and calls straight into arbitrary native code.
/// It must be gone from *every* `package`-bearing state — including the
/// unconfined `package_dir: None` shape, which is the one a
/// `package_dir`-conditional scrub would leave open.
#[test]
fn package_states_cannot_load_native_modules() {
    for package_dir in [None, Some(std::env::temp_dir())] {
        let confined = package_dir.is_some();
        let rt = package_runtime(package_dir);
        let lua = rt.lua();

        let package: Table = lua.globals().get("package").expect("package table");

        let loadlib: Value = package.get("loadlib").expect("read loadlib");
        assert!(
            loadlib.is_nil(),
            "`package.loadlib` must be nil (confined: {confined}), got a {}",
            loadlib.type_name()
        );

        let cpath: String = package.get("cpath").expect("read cpath");
        assert_eq!(
            cpath, "",
            "`package.cpath` must be empty (confined: {confined})"
        );

        // `searchpath` is a filesystem existence oracle with its own
        // template argument; confinement of `package.path` never reached
        // it.
        let searchpath: Value = package.get("searchpath").expect("read searchpath");
        assert!(
            searchpath.is_nil(),
            "`package.searchpath` must be nil (confined: {confined})"
        );
    }
}

/// `require` confinement (`RuntimeOpts::package_dir`): `package.path` is
/// pinned to the configured directory, `package.cpath` is emptied (no
/// native modules), modules inside load, and every escape shape misses.
#[tokio::test]
async fn require_is_confined_to_the_package_dir() {
    // A package dir with one module, and a would-be target right above it.
    static NEXT: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(0);
    let id = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    let root = std::env::temp_dir().join(format!("nitr-rt-confine-{}-{id}", std::process::id()));
    let pkg = root.join("pkg");
    std::fs::create_dir_all(&pkg).expect("mkdir pkg");
    std::fs::write(pkg.join("inside.lua"), "return { where = 'inside' }").expect("write inside");
    std::fs::write(root.join("outside.lua"), "return { where = 'outside' }")
        .expect("write outside");

    let rt = package_runtime(Some(pkg.clone()));
    let lua = rt.lua();

    // The pinned search path and the emptied native-module path.
    let dir = pkg.to_string_lossy();
    let path: String = lua
        .load("return package.path")
        .eval()
        .expect("package.path");
    assert_eq!(path, format!("{dir}/?.lua;{dir}/?/init.lua"));
    let cpath: String = lua
        .load("return package.cpath")
        .eval()
        .expect("package.cpath");
    assert_eq!(cpath, "", "native module loading must be disabled");

    // A module inside the directory loads.
    let inside: String = lua
        .load("return require('inside').where")
        .eval()
        .expect("require inside");
    assert_eq!(inside, "inside");

    // Escape shapes: the sibling exists on disk, so a hole in the
    // confinement would *succeed* here rather than 404 into a false pass.
    for escape in ["outside", "../outside", "..outside", "pkg/../../outside"] {
        let result = lua
            .load(format!("return require('{escape}').where"))
            .eval::<String>();
        assert!(
            result.is_err(),
            "require({escape:?}) must not reach outside the package dir"
        );
    }

    // Reassigning `package.path` must not widen the search: the searcher
    // owns the directory, the string is informational.
    let widened = lua
        .load(format!(
            "package.path = '{}/?.lua' return require('outside').where",
            root.to_string_lossy()
        ))
        .eval::<String>();
    assert!(
        widened.is_err(),
        "a script must not be able to point `require` elsewhere"
    );

    // A module that is bytecode is refused: `require` compiles text only,
    // like `load` and the script loader.
    std::fs::write(pkg.join("compiled.lua"), b"\x1bLuaT\0\x19\x93\r\n\x1a\n")
        .expect("write bytecode");
    let err = lua
        .load("return require('compiled')")
        .eval::<Value>()
        .expect_err("bytecode module");
    assert!(err.to_string().contains("binary"), "got: {err}");

    // Dotted names map to directories, and `init.lua` resolves.
    std::fs::create_dir_all(pkg.join("nested/deep")).expect("mkdir nested");
    std::fs::write(
        pkg.join("nested/deep/init.lua"),
        "return { where = 'init' }",
    )
    .expect("write init");
    let init: String = lua
        .load("return require('nested.deep').where")
        .eval()
        .expect("require init");
    assert_eq!(init, "init");

    std::fs::remove_dir_all(&root).ok();
}

/// A second `require` root (`RuntimeOpts::extra_package_dirs`, the tests
/// directory under `nitr test`) resolves modules after the first, under
/// the same confinement: no escape shape reaches a file beside either
/// root, and the first root wins a name both define.
#[tokio::test]
async fn extra_require_roots_keep_the_confinement() {
    static NEXT: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(0);
    let id = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    let root = std::env::temp_dir().join(format!("nitr-rt-roots-{}-{id}", std::process::id()));
    let app = root.join("app");
    let tests = root.join("tests");
    std::fs::create_dir_all(tests.join("helpers")).expect("mkdir tests");
    std::fs::create_dir_all(&app).expect("mkdir app");
    std::fs::write(app.join("shared.lua"), "return 'app'").expect("write shared");
    std::fs::write(tests.join("shared.lua"), "return 'tests'").expect("write shadow");
    std::fs::write(tests.join("helpers/auth.lua"), "return 'helper'").expect("write helper");
    std::fs::write(root.join("secret.lua"), "return 'secret'").expect("write secret");

    let rt = Runtime::new_with(RuntimeOpts {
        libs: StdLib::MATH | StdLib::TABLE | StdLib::STRING | StdLib::PACKAGE,
        memory_limit: MEMORY_LIMIT,
        dev_mode: false,
        exec_timeout: None,
        package_dir: Some(app.clone()),
        extra_package_dirs: vec![tests.clone()],
    })
    .expect("runtime");
    let lua = rt.lua();

    let helper: String = lua
        .load("return require('helpers.auth')")
        .eval()
        .expect("helper from the second root");
    assert_eq!(helper, "helper");
    let shared: String = lua.load("return require('shared')").eval().expect("shared");
    assert_eq!(shared, "app", "the application root is searched first");

    // `secret.lua` exists beside both roots, so a hole in either root's
    // confinement would load it rather than fail.
    for escape in ["secret", "..secret", "../secret", "helpers/../../secret"] {
        lua.load(format!("return require('{escape}')"))
            .eval::<Value>()
            .expect_err(escape);
    }
    let err = lua
        .load("return require('..secret')")
        .eval::<Value>()
        .expect_err("dotted escape");
    assert!(
        err.to_string().contains("is not a dotted identifier"),
        "got: {err}"
    );
    let err = lua
        .load("return require('/etc/passwd')")
        .eval::<Value>()
        .expect_err("absolute path");
    assert!(
        err.to_string().contains("is not a dotted identifier"),
        "got: {err}"
    );

    std::fs::remove_dir_all(&root).ok();
}

#[test]
fn modules_mount_under_nitr_ext_and_reject_collisions() {
    let rt = test_runtime(None);
    rt.register_module("greet", |lua| {
        let t = lua.create_table()?;
        t.set(
            "hello",
            lua.create_function(|_, name: String| Ok(format!("hi {name}")))?,
        )?;
        Ok(t)
    })
    .expect("register module");

    let out: String = rt
        .lua()
        .load("return nitr.ext.greet.hello('nitr')")
        .eval()
        .expect("call module");
    assert_eq!(out, "hi nitr");

    // A second mount under the same name must fail loudly.
    let err = rt
        .register_module("greet", |lua| lua.create_table())
        .expect_err("collision");
    assert!(err.to_string().contains("already exists"), "got: {err}");
}

#[tokio::test]
async fn config_accepts_plain_script() {
    // Handler-style shape: top-level statements, args via `...`,
    // trailing `return { ... }` — no `function(...)` wrapper.
    let cfg_script = write_temp_script(
        "cfg_plain.lua",
        "local greeting = ...\n\
             local upper = greeting:upper()\n\
             return { greeting = greeting, upper = upper }",
    );
    let mut rt = test_runtime(None);
    rt.register_cfg_fn(&cfg_script, "hi")
        .await
        .expect("run plain config script");
    std::fs::remove_file(&cfg_script).ok();

    let cfg = rt.cfg().expect("cfg table");
    assert_eq!(cfg.get::<String>("greeting").expect("greeting"), "hi");
    assert_eq!(cfg.get::<String>("upper").expect("upper"), "HI");
}

#[tokio::test]
async fn config_rejects_non_table_result() {
    let cfg_script = write_temp_script("cfg_bad.lua", "return 42");
    let mut rt = test_runtime(None);
    let err = rt
        .register_cfg_fn(&cfg_script, Value::Nil)
        .await
        .expect_err("number is not a valid configuration");
    std::fs::remove_file(&cfg_script).ok();
    assert!(
        err.to_string().contains("must return a table"),
        "got: {err}"
    );
}

#[tokio::test]
async fn config_rejects_the_dropped_wrapper_form() {
    // The old `function(db) ... end` shape must fail with a message
    // that points migrations at the plain-script form.
    let cfg_script = write_temp_script(
        "cfg_wrapped.lua",
        "function(db)\n    return { ok = true }\nend",
    );
    let mut rt = test_runtime(None);
    let err = rt
        .register_cfg_fn(&cfg_script, Value::Nil)
        .await
        .expect_err("wrapper form is no longer supported");
    std::fs::remove_file(&cfg_script).ok();
    let message = err.to_string();
    assert!(message.contains("no longer supported"), "got: {message}");
    assert!(message.contains("local db = ..."), "got: {message}");
}

#[tokio::test]
async fn config_snapshot_round_trips() {
    let cfg_script = write_temp_script("cfg.lua", "return { greeting = 'hi', nested = { n = 7 } }");
    let mut source = test_runtime(None);
    source
        .register_cfg_fn(&cfg_script, Value::Nil)
        .await
        .expect("run config script");
    std::fs::remove_file(&cfg_script).ok();

    let snapshot = source
        .cfg_snapshot()
        .expect("snapshot")
        .expect("config present");
    let mut target = test_runtime(None);
    target.set_cfg_snapshot(&snapshot).expect("inject snapshot");
    let cfg = target.cfg().expect("cfg table");
    assert_eq!(cfg.get::<String>("greeting").expect("greeting"), "hi");
    let nested: Table = cfg.get("nested").expect("nested");
    assert_eq!(nested.get::<i64>("n").expect("n"), 7);
}