Skip to main content

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};