#![doc = include_str!("../ERRORS.md")]
use std::error::Error as StdError;
use std::fmt;
use std::io;
pub type Result<T> = std::result::Result<T, Error>;
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum ErrorKind {
InvalidInput,
Unsupported,
Busy,
Overloaded,
ResourceExhausted,
Unavailable,
CorruptData,
Io,
Internal,
}
impl ErrorKind {
pub const fn as_str(self) -> &'static str {
match self {
Self::InvalidInput => "invalid_input",
Self::Unsupported => "unsupported",
Self::Busy => "busy",
Self::Overloaded => "overloaded",
Self::ResourceExhausted => "resource_exhausted",
Self::Unavailable => "unavailable",
Self::CorruptData => "corrupt_data",
Self::Io => "io",
Self::Internal => "internal",
}
}
}
impl fmt::Display for ErrorKind {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(self.as_str())
}
}
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum ErrorOperation {
ValidateConfig,
PeakDiskBytes,
Open,
Put,
PutL2,
Delete,
Get,
Drain,
Snapshot,
DetailedSnapshot,
CloseFast,
CloseWarm,
}
impl ErrorOperation {
pub const fn as_str(self) -> &'static str {
match self {
Self::ValidateConfig => "validate_config",
Self::PeakDiskBytes => "peak_disk_bytes",
Self::Open => "open",
Self::Put => "put",
Self::PutL2 => "put_l2",
Self::Delete => "delete",
Self::Get => "get",
Self::Drain => "drain",
Self::Snapshot => "snapshot",
Self::DetailedSnapshot => "detailed_snapshot",
Self::CloseFast => "close_fast",
Self::CloseWarm => "close_warm",
}
}
}
impl fmt::Display for ErrorOperation {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(self.as_str())
}
}
#[derive(Debug)]
pub struct Error {
kind: ErrorKind,
operation: ErrorOperation,
source: io::Error,
}
impl Error {
pub(crate) fn from_io(operation: ErrorOperation, source: io::Error) -> Self {
Self {
kind: classify(operation, &source),
operation,
source,
}
}
pub const fn kind(&self) -> ErrorKind {
self.kind
}
pub const fn operation(&self) -> ErrorOperation {
self.operation
}
pub fn io_kind(&self) -> io::ErrorKind {
self.source.kind()
}
pub fn raw_os_error(&self) -> Option<i32> {
self.source.raw_os_error()
}
pub const fn as_io_error(&self) -> &io::Error {
&self.source
}
pub fn into_io_error(self) -> io::Error {
self.source
}
pub fn into_io_error_with_context(self) -> io::Error {
let kind = self.io_kind();
io::Error::new(kind, self)
}
}
impl fmt::Display for Error {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
formatter,
"{} failed [{}]: {}",
self.operation, self.kind, self.source
)
}
}
impl StdError for Error {
fn source(&self) -> Option<&(dyn StdError + 'static)> {
Some(&self.source)
}
}
impl From<Error> for io::Error {
fn from(error: Error) -> Self {
error.into_io_error()
}
}
fn classify(operation: ErrorOperation, source: &io::Error) -> ErrorKind {
use io::ErrorKind as IoKind;
match source.kind() {
IoKind::InvalidInput if source.raw_os_error().is_some() => ErrorKind::Io,
IoKind::InvalidInput if accepts_caller_input(operation) => ErrorKind::InvalidInput,
IoKind::InvalidInput => ErrorKind::Internal,
IoKind::Unsupported => ErrorKind::Unsupported,
IoKind::WouldBlock | IoKind::AlreadyExists if operation == ErrorOperation::Open => {
ErrorKind::Busy
}
IoKind::WouldBlock if source.raw_os_error().is_some() => ErrorKind::Io,
IoKind::WouldBlock if has_bounded_admission(operation) => ErrorKind::Overloaded,
IoKind::WouldBlock | IoKind::AlreadyExists => ErrorKind::Internal,
IoKind::TimedOut if operation == ErrorOperation::Get => ErrorKind::Overloaded,
IoKind::TimedOut => ErrorKind::Io,
IoKind::OutOfMemory if operation == ErrorOperation::Get => ErrorKind::Overloaded,
IoKind::OutOfMemory => ErrorKind::ResourceExhausted,
IoKind::BrokenPipe | IoKind::NotConnected | IoKind::Interrupted => ErrorKind::Unavailable,
IoKind::InvalidData | IoKind::UnexpectedEof => ErrorKind::CorruptData,
IoKind::Other if source.raw_os_error().is_none() => ErrorKind::Internal,
_ => ErrorKind::Io,
}
}
const fn accepts_caller_input(operation: ErrorOperation) -> bool {
matches!(
operation,
ErrorOperation::ValidateConfig
| ErrorOperation::PeakDiskBytes
| ErrorOperation::Open
| ErrorOperation::Put
| ErrorOperation::PutL2
| ErrorOperation::Delete
)
}
const fn has_bounded_admission(operation: ErrorOperation) -> bool {
matches!(
operation,
ErrorOperation::Put
| ErrorOperation::PutL2
| ErrorOperation::Delete
| ErrorOperation::Get
| ErrorOperation::Drain
)
}
#[cfg(test)]
mod tests {
use super::*;
fn error(operation: ErrorOperation, kind: io::ErrorKind) -> Error {
Error::from_io(operation, io::Error::new(kind, "injected failure"))
}
fn assert_send_sync<T: Send + Sync>() {}
#[test]
fn public_error_is_send_and_sync() {
assert_send_sync::<Error>();
}
#[test]
fn request_pressure_and_open_contention_are_distinct() {
assert_eq!(
error(ErrorOperation::Put, io::ErrorKind::WouldBlock).kind(),
ErrorKind::Overloaded
);
assert_eq!(
error(ErrorOperation::Open, io::ErrorKind::WouldBlock).kind(),
ErrorKind::Busy
);
assert_eq!(
error(ErrorOperation::Snapshot, io::ErrorKind::WouldBlock).kind(),
ErrorKind::Internal
);
}
#[test]
fn request_deadline_and_device_completion_timeout_are_distinct() {
assert_eq!(
error(ErrorOperation::Get, io::ErrorKind::TimedOut).kind(),
ErrorKind::Overloaded
);
assert_eq!(
error(ErrorOperation::Drain, io::ErrorKind::TimedOut).kind(),
ErrorKind::Io
);
}
#[test]
fn bounded_get_memory_pressure_is_overload() {
assert_eq!(
error(ErrorOperation::Get, io::ErrorKind::OutOfMemory).kind(),
ErrorKind::Overloaded
);
assert_eq!(
error(ErrorOperation::Open, io::ErrorKind::OutOfMemory).kind(),
ErrorKind::ResourceExhausted
);
}
#[test]
fn low_level_failures_map_to_actionable_categories() {
for (io_kind, expected) in [
(io::ErrorKind::InvalidInput, ErrorKind::Internal),
(io::ErrorKind::Unsupported, ErrorKind::Unsupported),
(io::ErrorKind::BrokenPipe, ErrorKind::Unavailable),
(io::ErrorKind::InvalidData, ErrorKind::CorruptData),
(io::ErrorKind::PermissionDenied, ErrorKind::Io),
(io::ErrorKind::Other, ErrorKind::Internal),
] {
assert_eq!(error(ErrorOperation::Drain, io_kind).kind(), expected);
}
assert_eq!(
error(ErrorOperation::Put, io::ErrorKind::InvalidInput).kind(),
ErrorKind::InvalidInput
);
}
#[test]
fn display_contains_structured_labels_and_cause() {
let error = error(ErrorOperation::Drain, io::ErrorKind::TimedOut);
assert_eq!(error.to_string(), "drain failed [io]: injected failure");
}
#[test]
fn default_io_conversion_preserves_raw_os_error() {
let error = Error::from_io(ErrorOperation::Open, io::Error::from_raw_os_error(13));
let error = io::Error::from(error);
assert_eq!(error.raw_os_error(), Some(13));
}
#[test]
fn contextual_io_conversion_retains_structured_error() {
let error = Error::from_io(ErrorOperation::Open, io::Error::from_raw_os_error(13))
.into_io_error_with_context();
assert_eq!(error.raw_os_error(), None);
let source = error
.get_ref()
.and_then(|source| source.downcast_ref::<Error>())
.expect("structured error remains in the source chain");
assert_eq!(source.operation(), ErrorOperation::Open);
assert_eq!(source.raw_os_error(), Some(13));
}
}