chore: initial sanitized public snapshot

2026-07-18 14:04:26 +08:00
commit 7b3816441c
320 changed files with 76813 additions and 0 deletions
@@ -0,0 +1,66 @@
+//! Error codes and error values emitted by the core crate.
+
+use std::fmt::{Display, Formatter};
+
+use crate::request::DownloadId;
+
+/// Standard result type returned by core APIs.
+pub type Result<T> = std::result::Result<T, CoreError>;
+
+/// Stable error categories for mapping runtime failures to RPC-facing codes.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ErrorCode {
+    /// The requested operation is not supported by the current implementation.
+    Unsupported,
+    /// The supplied download id does not resolve to a tracked request group.
+    UnknownDownload,
+    /// The requested state transition is not valid for the current runtime state.
+    InvalidState,
+    /// The runtime is shutting down and cannot accept the requested operation.
+    ShutdownInProgress,
+    /// A required persistence or storage action failed.
+    StorageUnavailable,
+}
+
+/// Concrete errors returned by the core engine and state surfaces.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum CoreError {
+    /// The referenced download id is not present in the registry.
+    UnknownDownloadId(DownloadId),
+    /// The caller requested a feature that is not yet implemented.
+    UnsupportedOperation(&'static str),
+    /// The caller requested an invalid state transition or runtime action.
+    InvalidState(&'static str),
+    /// Shutdown has started and the runtime is no longer accepting work.
+    ShutdownInProgress,
+    /// Session or control-file storage was unavailable.
+    StorageUnavailable(&'static str),
+}
+
+impl CoreError {
+    /// Returns the stable error code associated with this error value.
+    #[must_use]
+    pub const fn code(&self) -> ErrorCode {
+        match self {
+            Self::UnknownDownloadId(_) => ErrorCode::UnknownDownload,
+            Self::UnsupportedOperation(_) => ErrorCode::Unsupported,
+            Self::InvalidState(_) => ErrorCode::InvalidState,
+            Self::ShutdownInProgress => ErrorCode::ShutdownInProgress,
+            Self::StorageUnavailable(_) => ErrorCode::StorageUnavailable,
+        }
+    }
+}
+
+impl Display for CoreError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::UnknownDownloadId(gid) => write!(f, "unknown download id: {gid}"),
+            Self::UnsupportedOperation(msg) => write!(f, "unsupported operation: {msg}"),
+            Self::InvalidState(msg) => write!(f, "invalid runtime state: {msg}"),
+            Self::ShutdownInProgress => write!(f, "engine shutdown is in progress"),
+            Self::StorageUnavailable(msg) => write!(f, "storage unavailable: {msg}"),
+        }
+    }
+}
+
+impl std::error::Error for CoreError {}