nitr_core/error/mod.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//! Typed error and result types for the Nitr library.
7
8/// Errors returned by the Nitr library.
9#[derive(Debug, thiserror::Error)]
10pub enum Error {
11 /// An error raised by the Lua runtime or a script.
12 #[error("lua error: {0}")]
13 Lua(#[from] mlua::Error),
14
15 /// An invalid or missing configuration value.
16 #[error("configuration error: {0}")]
17 Config(String),
18
19 /// A script file could not be loaded or evaluated.
20 #[error("script error: {0}")]
21 Script(String),
22
23 /// An I/O error.
24 #[error("i/o error: {0}")]
25 Io(#[from] std::io::Error),
26
27 /// An HTTP protocol error.
28 #[error("http error: {0}")]
29 Http(#[from] http::Error),
30
31 /// The handler exceeded its execution budget.
32 #[error("handler execution timed out")]
33 Timeout,
34
35 /// No Lua state became available within the pool wait budget; the
36 /// request is shed rather than queued indefinitely.
37 #[error("no Lua state available within the pool wait budget")]
38 PoolBusy,
39
40 /// A panic was caught while running a request. The state that was in
41 /// use is recycled; this is always a bug in Rust code (Nitr's or an
42 /// extension module's), never in a Lua script.
43 #[error("panic while handling the request: {0}")]
44 Panic(String),
45
46 /// The graceful-shutdown drain deadline expired with connections still
47 /// in flight, so they were aborted. Surfaced rather than swallowed: a
48 /// truncated shutdown means a client's request was cut.
49 #[error("shutdown drain deadline expired with requests still in flight")]
50 ShutdownTimeout,
51}
52
53impl Error {
54 /// Whether this error leaves the Lua state unfit for reuse.
55 ///
56 /// A memory-limit hit is the clear case: the allocator refused, the
57 /// state's heap sits at its ceiling, and the next request would inherit
58 /// the problem. Ordinary script errors are *not* damage — Lua unwinds
59 /// cleanly and the state is fine.
60 pub fn poisons_state(&self) -> bool {
61 match self {
62 Error::Panic(_) => true,
63 Error::Lua(err) => is_memory_error(err),
64 _ => false,
65 }
66 }
67}
68
69/// Walks an mlua error chain looking for a memory error, which can be
70/// wrapped in `CallbackError`/`WithContext` layers by the time it surfaces.
71fn is_memory_error(err: &mlua::Error) -> bool {
72 match err {
73 mlua::Error::MemoryError(_) => true,
74 mlua::Error::CallbackError { cause, .. } => is_memory_error(cause),
75 mlua::Error::WithContext { cause, .. } => is_memory_error(cause),
76 _ => false,
77 }
78}
79
80/// Result type alias used across the Nitr library.
81pub type Result<T = (), E = Error> = std::result::Result<T, E>;
82
83mod info;
84mod render;
85#[cfg(test)]
86mod tests;
87
88pub(crate) use info::EXEC_BUDGET_MSG;
89pub use info::ErrorInfo;
90pub use render::{message_token, source_snippet};