131 lines
4.0 KiB
Rust
131 lines
4.0 KiB
Rust
// file: crates/ksp-core-lib/src/error.rs
|
|
// version: 1
|
|
|
|
/// Stable structured identifier for a KSP error.
|
|
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
|
|
pub struct ErrorCode {
|
|
domain: &'static str,
|
|
code: &'static str,
|
|
}
|
|
|
|
impl ErrorCode {
|
|
/// Creates an error code from a stable domain and code identifier.
|
|
#[must_use]
|
|
pub const fn new(domain: &'static str, code: &'static str) -> Self {
|
|
return Self { domain, code };
|
|
}
|
|
|
|
/// Returns the stable error domain identifier.
|
|
#[must_use]
|
|
pub const fn domain(&self) -> &'static str {
|
|
return self.domain;
|
|
}
|
|
|
|
/// Returns the stable error code identifier within the domain.
|
|
#[must_use]
|
|
pub const fn code(&self) -> &'static str {
|
|
return self.code;
|
|
}
|
|
}
|
|
|
|
/// Structured contextual field attached to a KSP error.
|
|
#[derive(Clone, Debug, Eq, PartialEq)]
|
|
pub struct ErrorContext {
|
|
key: &'static str,
|
|
value: std::string::String,
|
|
}
|
|
|
|
impl ErrorContext {
|
|
/// Creates one contextual field from a stable key and an owned value.
|
|
#[must_use]
|
|
pub fn new(key: &'static str, value: impl std::convert::Into<std::string::String>) -> Self {
|
|
return Self { key, value: value.into() };
|
|
}
|
|
|
|
/// Returns the stable contextual key.
|
|
#[must_use]
|
|
pub fn key(&self) -> &'static str {
|
|
return self.key;
|
|
}
|
|
|
|
/// Returns the contextual value.
|
|
#[must_use]
|
|
pub fn value(&self) -> &str {
|
|
return self.value.as_str();
|
|
}
|
|
}
|
|
|
|
/// Common KSP error carrying a stable code, human-readable message, structured context and optional source.
|
|
#[derive(Debug)]
|
|
pub struct Error {
|
|
code: crate::ErrorCode,
|
|
message: std::string::String,
|
|
context: std::vec::Vec<crate::ErrorContext>,
|
|
source: std::option::Option<std::boxed::Box<dyn std::error::Error + std::marker::Send + std::marker::Sync + 'static>>,
|
|
}
|
|
|
|
impl Error {
|
|
/// Creates a KSP error without context or external source.
|
|
#[must_use]
|
|
pub fn new(code: crate::ErrorCode, message: impl std::convert::Into<std::string::String>) -> Self {
|
|
return Self { code, message: message.into(), context: std::vec::Vec::new(), source: std::option::Option::None };
|
|
}
|
|
|
|
/// Returns the stable structured error code.
|
|
#[must_use]
|
|
pub const fn code(&self) -> crate::ErrorCode {
|
|
return self.code;
|
|
}
|
|
|
|
/// Returns the human-readable diagnostic message.
|
|
#[must_use]
|
|
pub fn message(&self) -> &str {
|
|
return self.message.as_str();
|
|
}
|
|
|
|
/// Returns the contextual fields in insertion order.
|
|
#[must_use]
|
|
pub fn context(&self) -> &[crate::ErrorContext] {
|
|
return self.context.as_slice();
|
|
}
|
|
|
|
/// Appends one contextual field and returns the enriched error.
|
|
#[must_use]
|
|
pub fn with_context(mut self, key: &'static str, value: impl std::convert::Into<std::string::String>) -> Self {
|
|
self.context.push(crate::ErrorContext::new(key, value));
|
|
return self;
|
|
}
|
|
|
|
/// Attaches an external error as the standard source and returns the enriched error.
|
|
#[must_use]
|
|
pub fn with_source<E>(mut self, source: E) -> Self
|
|
where
|
|
E: std::error::Error + std::marker::Send + std::marker::Sync + 'static,
|
|
{
|
|
self.source = std::option::Option::Some(std::boxed::Box::new(source));
|
|
return self;
|
|
}
|
|
}
|
|
|
|
impl std::fmt::Display for Error {
|
|
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
|
return write!(formatter, "{}.{}: {}", self.code.domain(), self.code.code(), self.message);
|
|
}
|
|
}
|
|
|
|
impl std::error::Error for Error {
|
|
fn source(&self) -> std::option::Option<&(dyn std::error::Error + 'static)> {
|
|
return match self.source.as_deref() {
|
|
std::option::Option::Some(source) => std::option::Option::Some(source),
|
|
std::option::Option::None => std::option::Option::None,
|
|
};
|
|
}
|
|
}
|
|
|
|
/// Common result type returned by KSP APIs using [`crate::Error`].
|
|
pub type Result<T> = std::result::Result<T, crate::Error>;
|
|
|
|
#[cfg(test)]
|
|
#[path = "../unit_tests/error.rs"]
|
|
mod tests;
|