bedrock_world/
error.rs

1//! Error and result types for the public API.
2
3use thiserror::Error;
4
5/// Crate-wide result type returned by `bedrock-world` APIs.
6pub type Result<T> = std::result::Result<T, BedrockWorldError>;
7
8/// Stable high-level category for a [`BedrockWorldError`].
9///
10/// Prefer matching this enum in application code instead of parsing the
11/// human-readable [`std::fmt::Display`] output.
12#[derive(Debug, Clone, Copy, PartialEq, Eq)]
13#[non_exhaustive]
14pub enum BedrockWorldErrorKind {
15    /// Filesystem or operating-system I/O failed.
16    Io,
17    /// NBT bytes were malformed or could not be represented.
18    Nbt,
19    /// The configured `LevelDB` backend returned an error.
20    LevelDb,
21    /// A Bedrock `LevelDB` key could not be decoded as the requested key shape.
22    InvalidKey,
23    /// A chunk, subchunk, or palette format is not supported by this crate.
24    UnsupportedChunkFormat,
25    /// Caller-supplied input failed validation before touching storage.
26    Validation,
27    /// A mutating operation was rejected because the handle is read-only.
28    ReadOnly,
29    /// A cooperative cancellation flag interrupted a scan.
30    Cancelled,
31    /// A concurrent storage operation failed because a lock was poisoned.
32    ConcurrentWrite,
33    /// World data was truncated, internally inconsistent, or otherwise corrupt.
34    CorruptWorld,
35    /// An async wrapper failed to join its blocking task.
36    Join,
37}
38
39/// Errors returned while reading, parsing, scanning, or editing a Bedrock world.
40#[non_exhaustive]
41#[derive(Debug, Error)]
42pub enum BedrockWorldError {
43    /// Filesystem or OS I/O failure.
44    #[error("I/O error: {0}")]
45    Io(#[from] std::io::Error),
46    /// NBT parse, serialization, or validation failure.
47    #[error("NBT error: {0}")]
48    Nbt(String),
49    /// `LevelDB` backend failure.
50    #[error("LevelDB error: {0}")]
51    LevelDb(String),
52    /// Invalid Bedrock database key.
53    #[error("invalid Bedrock key: {0}")]
54    InvalidKey(String),
55    /// Unsupported chunk or subchunk payload.
56    #[error("unsupported chunk format: {0}")]
57    UnsupportedChunkFormat(String),
58    /// Invalid caller-supplied input.
59    #[error("validation failed: {0}")]
60    Validation(String),
61    /// Mutating operation attempted through a read-only world handle.
62    #[error("world is read-only")]
63    ReadOnly,
64    /// Long-running operation cancelled by the caller.
65    #[error("{operation} was cancelled")]
66    Cancelled {
67        /// Operation that observed the cancellation flag.
68        operation: &'static str,
69    },
70    /// Concurrent write or lock poisoning failure.
71    #[error("concurrent write rejected: {0}")]
72    ConcurrentWrite(String),
73    /// Corrupt or inconsistent world data.
74    #[error("corrupt world: {0}")]
75    CorruptWorld(String),
76    /// Async runtime join failure.
77    #[error("async runtime error: {0}")]
78    Join(String),
79}
80
81impl BedrockWorldError {
82    /// Returns the stable category for this error.
83    #[must_use]
84    pub const fn kind(&self) -> BedrockWorldErrorKind {
85        match self {
86            Self::Io(_) => BedrockWorldErrorKind::Io,
87            Self::Nbt(_) => BedrockWorldErrorKind::Nbt,
88            Self::LevelDb(_) => BedrockWorldErrorKind::LevelDb,
89            Self::InvalidKey(_) => BedrockWorldErrorKind::InvalidKey,
90            Self::UnsupportedChunkFormat(_) => BedrockWorldErrorKind::UnsupportedChunkFormat,
91            Self::Validation(_) => BedrockWorldErrorKind::Validation,
92            Self::ReadOnly => BedrockWorldErrorKind::ReadOnly,
93            Self::Cancelled { .. } => BedrockWorldErrorKind::Cancelled,
94            Self::ConcurrentWrite(_) => BedrockWorldErrorKind::ConcurrentWrite,
95            Self::CorruptWorld(_) => BedrockWorldErrorKind::CorruptWorld,
96            Self::Join(_) => BedrockWorldErrorKind::Join,
97        }
98    }
99}
100
101impl From<std::string::FromUtf8Error> for BedrockWorldError {
102    fn from(error: std::string::FromUtf8Error) -> Self {
103        Self::Nbt(error.to_string())
104    }
105}
106
107impl From<std::str::Utf8Error> for BedrockWorldError {
108    fn from(error: std::str::Utf8Error) -> Self {
109        Self::Nbt(error.to_string())
110    }
111}
bedrock_world/error.rs

bedrock_world/
error.rs
