v0.1.1-pre.002

crates/ksp-core-lib/src/error.rs

@@ -0,0 +1,130 @@
+// 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;