pub mod category;
pub mod render;
pub use category::{Category, ExitNumber};
use std::fmt;
#[derive(Debug, Clone)]
pub struct Failure {
category: Category,
code: &'static str,
message: String,
hint: Option<String>,
retryable_override: Option<bool>,
extras: Option<Box<Extras>>,
}
#[derive(Debug, Clone, Default)]
struct Extras {
causes: Vec<String>,
extra_conditions: Vec<String>,
details: Vec<(&'static str, String)>,
}
impl Failure {
#[must_use]
pub fn new(category: Category, code: &'static str, message: impl Into<String>) -> Self {
Self {
category,
code,
message: message.into(),
hint: None,
retryable_override: None,
extras: None,
}
}
#[must_use]
pub fn with_detail(mut self, name: &'static str, value: impl Into<String>) -> Self {
self.extras
.get_or_insert_with(Box::default)
.details
.push((name, value.into()));
self
}
#[must_use]
pub fn with_hint(mut self, hint: impl Into<String>) -> Self {
self.hint = Some(hint.into());
self
}
#[must_use]
pub const fn with_retryable(mut self, retryable: bool) -> Self {
self.retryable_override = Some(retryable);
self
}
#[must_use]
pub fn with_cause(mut self, cause: impl Into<String>) -> Self {
self.extras
.get_or_insert_with(Box::default)
.causes
.push(cause.into());
self
}
#[must_use]
pub fn with_extra_condition(mut self, condition: impl Into<String>) -> Self {
self.extras
.get_or_insert_with(Box::default)
.extra_conditions
.push(condition.into());
self
}
#[must_use]
pub const fn category(&self) -> Category {
self.category
}
#[must_use]
pub const fn code(&self) -> &'static str {
self.code
}
#[must_use]
pub fn message(&self) -> &str {
&self.message
}
#[must_use]
pub fn hint(&self) -> Option<&str> {
self.hint.as_deref()
}
#[must_use]
pub fn causes(&self) -> &[String] {
self.extras
.as_deref()
.map_or(&[], |extras| extras.causes.as_slice())
}
#[must_use]
pub fn extra_conditions(&self) -> &[String] {
self.extras
.as_deref()
.map_or(&[], |extras| extras.extra_conditions.as_slice())
}
#[must_use]
pub fn details(&self) -> &[(&'static str, String)] {
self.extras
.as_deref()
.map_or(&[], |extras| extras.details.as_slice())
}
#[must_use]
pub fn is_retryable(&self) -> bool {
self.retryable_override
.unwrap_or_else(|| self.category.is_retryable())
}
#[must_use]
pub const fn exit_number(&self) -> ExitNumber {
self.category.exit_number()
}
}
impl fmt::Display for Failure {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}: {}", self.code, self.message)
}
}
impl std::error::Error for Failure {}
pub type Result<T> = std::result::Result<T, Failure>;
impl Failure {
#[must_use]
pub fn usage(code: &'static str, message: impl Into<String>) -> Self {
Self::new(Category::Usage, code, message)
}
#[must_use]
pub fn validation(code: &'static str, message: impl Into<String>) -> Self {
Self::new(Category::Validation, code, message)
}
#[must_use]
pub fn config(code: &'static str, message: impl Into<String>) -> Self {
Self::new(Category::Config, code, message)
}
#[must_use]
pub fn network(code: &'static str, message: impl Into<String>) -> Self {
Self::new(Category::Network, code, message)
}
#[must_use]
pub fn authentication(code: &'static str, message: impl Into<String>) -> Self {
Self::new(Category::Authentication, code, message)
}
#[must_use]
pub fn permission(code: &'static str, message: impl Into<String>) -> Self {
Self::new(Category::Permission, code, message)
}
#[must_use]
pub fn absence(code: &'static str, message: impl Into<String>) -> Self {
Self::new(Category::Absence, code, message)
}
#[must_use]
pub fn conflict(code: &'static str, message: impl Into<String>) -> Self {
Self::new(Category::Conflict, code, message)
}
#[must_use]
pub fn timeout(code: &'static str, message: impl Into<String>) -> Self {
Self::new(Category::Timeout, code, message)
}
#[must_use]
pub fn server(code: &'static str, message: impl Into<String>) -> Self {
Self::new(Category::Server, code, message)
}
#[must_use]
pub fn limit(code: &'static str, message: impl Into<String>) -> Self {
Self::new(Category::Limit, code, message)
}
#[must_use]
pub fn interrupted(code: &'static str, message: impl Into<String>) -> Self {
Self::new(Category::Interrupted, code, message)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn retry_mark_follows_category_by_default() {
let transient = Failure::network("net.unreachable", "server not reached");
assert!(transient.is_retryable());
let permanent = Failure::usage("usage.bad_flag", "unknown value");
assert!(!permanent.is_retryable());
}
#[test]
fn server_condition_overrides_the_retry_mark() {
let retryable = Failure::server("server.1213", "deadlock found").with_retryable(true);
assert!(retryable.is_retryable());
assert_eq!(retryable.exit_number(), ExitNumber::Server);
let permanent = Failure::server("server.1064", "syntax error");
assert!(!permanent.is_retryable());
}
#[test]
fn every_server_condition_is_kept() {
let failure = Failure::server("server.1364", "field has no default")
.with_extra_condition("column `b` has no default")
.with_extra_condition("column `c` has no default");
assert_eq!(failure.extra_conditions().len(), 2);
}
}