Struct AppError 

pub struct AppError { /* private fields */ }

Rich application error preserving domain code, taxonomy and metadata.

This is the main error type for application-level errors. It provides structured error information, telemetry integration, and diagnostic capabilities.

Examples

use masterror::{AppError, AppErrorKind};

let err = AppError::new(AppErrorKind::BadRequest, "invalid payload");
assert_eq!(err.kind, AppErrorKind::BadRequest);

Implementations

impl Error

pub fn not_found(msg: impl Into<Cow<'static, str>>) -> Error

Build a NotFound error.

use masterror::AppError;

let err = AppError::not_found("user not found");
assert_eq!(err.message.as_deref(), Some("user not found"));

pub fn validation(msg: impl Into<Cow<'static, str>>) -> Error

Build a Validation error.

use masterror::AppError;

let err = AppError::validation("invalid email format");
assert_eq!(err.message.as_deref(), Some("invalid email format"));

pub fn unauthorized(msg: impl Into<Cow<'static, str>>) -> Error

Build an Unauthorized error.

use masterror::AppError;

let err = AppError::unauthorized("missing authentication token");
assert_eq!(err.message.as_deref(), Some("missing authentication token"));

pub fn forbidden(msg: impl Into<Cow<'static, str>>) -> Error

Build a Forbidden error.

use masterror::AppError;

let err = AppError::forbidden("insufficient permissions");
assert_eq!(err.message.as_deref(), Some("insufficient permissions"));

pub fn conflict(msg: impl Into<Cow<'static, str>>) -> Error

Build a Conflict error.

use masterror::AppError;

let err = AppError::conflict("resource already exists");
assert_eq!(err.message.as_deref(), Some("resource already exists"));

pub fn bad_request(msg: impl Into<Cow<'static, str>>) -> Error

Build a BadRequest error.

use masterror::AppError;

let err = AppError::bad_request("malformed JSON payload");
assert_eq!(err.message.as_deref(), Some("malformed JSON payload"));

pub fn rate_limited(msg: impl Into<Cow<'static, str>>) -> Error

Build a RateLimited error.

use masterror::AppError;

let err = AppError::rate_limited("rate limit exceeded");
assert_eq!(err.message.as_deref(), Some("rate limit exceeded"));

pub fn telegram_auth(msg: impl Into<Cow<'static, str>>) -> Error

Build a TelegramAuth error.

use masterror::AppError;

let err = AppError::telegram_auth("invalid telegram signature");
assert_eq!(err.message.as_deref(), Some("invalid telegram signature"));

pub fn internal(msg: impl Into<Cow<'static, str>>) -> Error

Build an Internal error.

use masterror::AppError;

let err = AppError::internal("unexpected server error");
assert_eq!(err.message.as_deref(), Some("unexpected server error"));

pub fn service(msg: impl Into<Cow<'static, str>>) -> Error

Build a Service error (generic server-side service failure).

use masterror::AppError;

let err = AppError::service("service processing failed");
assert_eq!(err.message.as_deref(), Some("service processing failed"));

pub fn database(msg: Option<Cow<'static, str>>) -> Error

Build a Database error with an optional message.

This constructor accepts a pre-built Cow so callers that already manage ownership can pass either borrowed or owned strings. When you have plain string data, prefer AppError::database_with_message.

use masterror::AppError;

let err = AppError::database(None);
assert!(err.message.is_none());

pub fn database_with_message(msg: impl Into<Cow<'static, str>>) -> Error

Build a Database error with a message.

Convenience wrapper around AppError::database for the common case where you start from a plain string-like value.

use masterror::AppError;

let err = AppError::database_with_message("db down");
assert_eq!(err.message.as_deref(), Some("db down"));

pub fn config(msg: impl Into<Cow<'static, str>>) -> Error

Build a Config error.

use masterror::AppError;

let err = AppError::config("missing required configuration key");
assert_eq!(
    err.message.as_deref(),
    Some("missing required configuration key")
);

pub fn turnkey(msg: impl Into<Cow<'static, str>>) -> Error

Build a Turnkey error.

use masterror::AppError;

let err = AppError::turnkey("turnkey operation failed");
assert_eq!(err.message.as_deref(), Some("turnkey operation failed"));

pub fn timeout(msg: impl Into<Cow<'static, str>>) -> Error

Build a Timeout error.

use masterror::AppError;

let err = AppError::timeout("request timed out after 30s");
assert_eq!(err.message.as_deref(), Some("request timed out after 30s"));

pub fn network(msg: impl Into<Cow<'static, str>>) -> Error

Build a Network error.

use masterror::AppError;

let err = AppError::network("connection refused");
assert_eq!(err.message.as_deref(), Some("connection refused"));

pub fn dependency_unavailable(msg: impl Into<Cow<'static, str>>) -> Error

Build a DependencyUnavailable error.

use masterror::AppError;

let err = AppError::dependency_unavailable("payment service unavailable");
assert_eq!(err.message.as_deref(), Some("payment service unavailable"));

pub fn service_unavailable(msg: impl Into<Cow<'static, str>>) -> Error

Backward-compatible alias; routes to DependencyUnavailable.

use masterror::AppError;

let err = AppError::service_unavailable("service temporarily unavailable");
assert_eq!(
    err.message.as_deref(),
    Some("service temporarily unavailable")
);

pub fn serialization(msg: impl Into<Cow<'static, str>>) -> Error

Build a Serialization error.

use masterror::AppError;

let err = AppError::serialization("failed to serialize response");
assert_eq!(err.message.as_deref(), Some("failed to serialize response"));

pub fn deserialization(msg: impl Into<Cow<'static, str>>) -> Error

Build a Deserialization error.

use masterror::AppError;

let err = AppError::deserialization("failed to parse JSON");
assert_eq!(err.message.as_deref(), Some("failed to parse JSON"));

pub fn external_api(msg: impl Into<Cow<'static, str>>) -> Error

Build an ExternalApi error.

use masterror::AppError;

let err = AppError::external_api("third-party API returned error");
assert_eq!(
    err.message.as_deref(),
    Some("third-party API returned error")
);

pub fn queue(msg: impl Into<Cow<'static, str>>) -> Error

Build a Queue error.

use masterror::AppError;

let err = AppError::queue("queue is full");
assert_eq!(err.message.as_deref(), Some("queue is full"));

pub fn cache(msg: impl Into<Cow<'static, str>>) -> Error

Build a Cache error.

use masterror::AppError;

let err = AppError::cache("cache lookup failed");
assert_eq!(err.message.as_deref(), Some("cache lookup failed"));

pub fn from_boxed( kind: AppErrorKind, source: Box<dyn Error + Send + Sync>, ) -> Error

Build a message-less error with the given kind from an already boxed source error, without re-boxing the allocation.

The source is stored as an owned attachment, so it stays recoverable by value via downcast and borrowable via downcast_ref. This mirrors anyhow::Error::from_boxed (available since anyhow 1.0.95) and forms a round-trip with into_boxed_dyn_error.

use core::error::Error;

use masterror::{AppError, AppErrorKind};

let source: Box<dyn Error + Send + Sync> = "disk offline".into();
let err = AppError::from_boxed(AppErrorKind::Internal, source);
assert!(err.message.is_none());
assert_eq!(
    err.source_ref().expect("source").to_string(),
    "disk offline"
);

impl Error

pub fn new(kind: AppErrorKind, msg: impl Into<Cow<'static, str>>) -> Error

Create a new Error with a kind and message.

This is equivalent to Error::with, provided for API symmetry and to keep doctests readable.

Examples

use masterror::{AppError, AppErrorKind};
let err = AppError::new(AppErrorKind::BadRequest, "invalid payload");
assert!(err.message.is_some());

pub fn with(kind: AppErrorKind, msg: impl Into<Cow<'static, str>>) -> Error

Create an error with the given kind and message.

Prefer named helpers (e.g. Error::not_found) where it clarifies intent.

Examples

use masterror::{AppError, AppErrorKind};
let err = AppError::with(AppErrorKind::Validation, "bad input");
assert_eq!(err.kind, AppErrorKind::Validation);

pub fn bare(kind: AppErrorKind) -> Error

Create a message-less error with the given kind.

Useful when the kind alone conveys sufficient information to the client.

Examples

use masterror::{AppError, AppErrorKind};
let err = AppError::bare(AppErrorKind::NotFound);
assert!(err.message.is_none());

pub fn with_code(self, code: AppCode) -> Error

Override the machine-readable AppCode.

Examples

use masterror::{AppCode, AppError, AppErrorKind};
let err = AppError::new(AppErrorKind::BadRequest, "test").with_code(AppCode::NotFound);
assert_eq!(err.code, AppCode::NotFound);

pub fn with_retry_after_secs(self, secs: u64) -> Error

Attach retry advice to the error.

When mapped to HTTP, this becomes the Retry-After header.

Examples

use masterror::{AppError, AppErrorKind};
let err = AppError::new(AppErrorKind::RateLimited, "slow down").with_retry_after_secs(60);
assert_eq!(err.retry.map(|r| r.after_seconds), Some(60));

pub fn with_www_authenticate(self, value: impl Into<String>) -> Error

Attach a WWW-Authenticate challenge string.

Examples

use masterror::{AppError, AppErrorKind};
let err = AppError::new(AppErrorKind::Unauthorized, "auth required")
    .with_www_authenticate("Bearer realm=\"api\"");
assert!(err.www_authenticate.is_some());

pub fn with_field(self, field: Field) -> Error

Attach additional metadata to the error.

Examples

use masterror::{AppError, AppErrorKind, field};
let err = AppError::new(AppErrorKind::Validation, "bad field")
    .with_field(field::str("field_name", "email"));
assert!(err.metadata().get("field_name").is_some());

pub fn with_fields(self, fields: impl IntoIterator<Item = Field>) -> Error

Extend metadata from an iterator of fields.

Examples

use masterror::{AppError, AppErrorKind, field};
let fields = vec![field::str("key1", "value1"), field::str("key2", "value2")];
let err = AppError::new(AppErrorKind::BadRequest, "test").with_fields(fields);
assert!(err.metadata().get("key1").is_some());

pub fn redact_field( self, name: &'static str, redaction: FieldRedaction, ) -> Error

Override the redaction policy for a stored metadata field.

Examples

use masterror::{AppError, AppErrorKind, FieldRedaction, field};

let err = AppError::new(AppErrorKind::Internal, "test")
    .with_field(field::str("password", "secret"))
    .redact_field("password", FieldRedaction::Redact);

pub fn with_metadata(self, metadata: Metadata) -> Error

Replace metadata entirely.

Examples

use masterror::{AppError, AppErrorKind, Metadata};

let metadata = Metadata::new();
let err = AppError::new(AppErrorKind::Internal, "test").with_metadata(metadata);

pub fn redactable(self) -> Error

Mark the message as redactable.

Examples

use masterror::{AppError, AppErrorKind, MessageEditPolicy};

let err = AppError::new(AppErrorKind::Internal, "secret").redactable();
assert_eq!(err.edit_policy, MessageEditPolicy::Redact);

pub fn with_context(self, context: impl Into<ContextAttachment>) -> Error

Attach upstream diagnostics using with_source or an existing Arc.

This is the preferred alias for capturing upstream errors. It accepts either an owned error implementing core::error::Error or a shared Arc produced by other APIs, reusing the allocation when possible.

Examples

use masterror::AppError;

let err = AppError::service("downstream degraded")
    .with_context(std::io::Error::new(std::io::ErrorKind::Other, "boom"));
assert!(err.source_ref().is_some());

pub fn with_source(self, source: impl Error + Send + Sync + 'static) -> Error

Attach an owned source error for diagnostics.

The source stays exclusively owned by this error, so it can later be recovered by value via downcast or mutated via downcast_mut.

Prefer with_context when capturing upstream diagnostics without additional Arc allocations.

Examples

use masterror::{AppError, AppErrorKind};

let io_err = std::io::Error::new(std::io::ErrorKind::Other, "boom");
let err = AppError::internal("boom").with_source(io_err);
assert!(err.source_ref().is_some());

pub fn with_source_arc(self, source: Arc<dyn Error + Send + Sync>) -> Error

Attach a shared source error without cloning the underlying Arc.

A shared source can be borrowed via downcast_ref but never extracted by value: downcast returns Err(self) for shared sources and downcast_mut succeeds only while the Arc is uniquely referenced. Use with_source when the caller owns the source and may want it back.

Examples

use std::sync::Arc;

use masterror::{AppError, AppErrorKind};

let source = Arc::new(std::io::Error::new(std::io::ErrorKind::Other, "boom"));
let err = AppError::internal("boom").with_source_arc(source.clone());
assert!(err.source_ref().is_some());
assert_eq!(Arc::strong_count(&source), 2);

pub fn with_backtrace(self, backtrace: Backtrace) -> Error

Attach a captured backtrace.

Examples

use std::backtrace::Backtrace;

use masterror::AppError;

let bt = Backtrace::capture();
let err = AppError::internal("test").with_backtrace(bt);

pub fn with_details_text(self, details: impl Into<String>) -> Error

Attach plain-text details for client payloads.

The text is omitted from responses when the error is redactable.

Examples

use masterror::{AppError, AppErrorKind};

let err = AppError::new(AppErrorKind::Internal, "boom").with_details_text("retry later");
assert!(err.details.is_some());

impl Error

pub fn metadata(&self) -> &Metadata

Borrow the attached metadata.

Examples

use masterror::{AppError, field};

let err = AppError::internal("test").with_field(field::str("key", "value"));
let metadata = err.metadata();
assert!(!metadata.is_empty());

pub fn backtrace(&self) -> Option<&Backtrace>

Borrow the backtrace, capturing it lazily when the backtrace feature is enabled.

If a backtrace was previously attached via with_backtrace(), returns that. Otherwise, lazily captures a new backtrace based on RUST_BACKTRACE configuration.

Examples

use masterror::AppError;

let err = AppError::internal("test");
let bt = err.backtrace();

pub fn source_ref(&self) -> Option<&(dyn Error + Send + Sync + 'static)>

Borrow the source if present.

Examples

use masterror::AppError;

let io_err = std::io::Error::new(std::io::ErrorKind::Other, "boom");
let err = AppError::internal("failed").with_context(io_err);
assert!(err.source_ref().is_some());

pub fn render_message(&self) -> Cow<'_, str>

Human-readable message or the kind fallback.

Returns the error message if set, otherwise returns the error kind’s default label.

Examples

use masterror::{AppError, AppErrorKind};

let err = AppError::new(AppErrorKind::BadRequest, "custom message");
assert_eq!(err.render_message(), "custom message");

let bare_err = AppError::bare(AppErrorKind::NotFound);
assert!(!bare_err.render_message().is_empty());

pub fn log(&self)

Emit telemetry (tracing event, metrics counter, backtrace capture).

Downstream code can call this to guarantee telemetry after mutating the error. It is automatically invoked by constructors and conversions.

Examples

use masterror::AppError;

let err = AppError::internal("test");
err.log();

pub fn chain(&self) -> ErrorChain<'_>

Returns an iterator over the error chain, starting with this error.

The iterator yields references to each error in the source chain, walking through source() until reaching the root cause.

Examples

use std::io::Error as IoError;

use masterror::AppError;

let io_err = IoError::other("disk offline");
let app_err = AppError::internal("db down").with_context(io_err);

let chain: Vec<_> = app_err.chain().collect();
assert_eq!(chain.len(), 2);

pub fn root_cause(&self) -> &(dyn Error + 'static)

Returns the lowest-level source error in the chain.

This traverses the error source chain until it finds an error with no further source, then returns a reference to it. If this error has no source, it returns a reference to itself.

Examples

use std::io::Error as IoError;

use masterror::AppError;

let io_err = IoError::other("disk offline");
let app_err = AppError::internal("db down").with_context(io_err);

let root = app_err.root_cause();
assert_eq!(root.to_string(), "disk offline");

pub fn is<E>(&self) -> bool

where E: Error + 'static,

Check whether the attached source error is of a concrete type.

Returns true if the immediate source (not this error itself, and not the entire chain) is of type E, false otherwise.

Examples

use std::io::Error as IoError;

use masterror::AppError;

let io_err = IoError::other("disk offline");
let app_err = AppError::internal("db down").with_context(io_err);

assert!(app_err.is::<IoError>());

let err_without_source = AppError::not_found("missing");
assert!(!err_without_source.is::<IoError>());

pub fn downcast<E>(self) -> Result<Box<E>, Error>

where E: Error + 'static,

Attempt to take ownership of the source error as a concrete type.

Succeeds when the immediate source (not this error itself, and not the entire chain) is of type E and the error owns it exclusively, i.e. the source was attached from an owned value via with_source or with_context.

Sources attached as a shared Arc via with_source_arc are never extracted by value, even when the Arc is uniquely referenced, because exclusive ownership of an unsized Arc cannot be reclaimed without unsafe code. Use downcast_ref to borrow such sources.

Errors

Returns Err(self) with the error (including its source) intact when no source is attached, the source is not of type E, or the source is shared.

Examples

use std::io::Error as IoError;

use masterror::AppError;

let io_err = IoError::other("disk offline");
let err = AppError::internal("boom").with_context(io_err);

let io = err.downcast::<IoError>().expect("owned io source");
assert_eq!(io.to_string(), "disk offline");

A failed downcast returns the original error unchanged:

use std::{fmt::Error as FmtError, io::Error as IoError};

use masterror::AppError;

let err = AppError::internal("boom").with_context(IoError::other("disk offline"));

let err = err
    .downcast::<FmtError>()
    .expect_err("source is not FmtError");
assert!(err.is::<IoError>());

pub fn downcast_ref<E>(&self) -> Option<&E>

where E: Error + 'static,

Attempt to downcast the attached source error to a concrete type by immutable reference.

Returns Some(&E) if the immediate source is of type E, None otherwise (including when no source is attached).

Examples

use std::io::Error as IoError;

use masterror::AppError;

let io_err = IoError::other("disk offline");
let err = AppError::internal("boom").with_context(io_err);

if let Some(io) = err.downcast_ref::<IoError>() {
    assert_eq!(io.to_string(), "disk offline");
}

pub fn downcast_mut<E>(&mut self) -> Option<&mut E>

where E: Error + 'static,

Attempt to downcast the attached source error to a concrete type by mutable reference.

Returns Some(&mut E) when the immediate source (not this error itself, and not the entire chain) is of type E and mutable access is possible: the source was attached from an owned value, or it was attached as a shared Arc that is currently uniquely referenced.

Returns None when no source is attached, the source is not of type E, or the source is a shared Arc with other strong or weak references, since handing out &mut E would alias the other holders.

Examples

use std::io::Error as IoError;

use masterror::AppError;

let io_err = IoError::other("disk offline");
let mut err = AppError::internal("boom").with_context(io_err);

let io = err.downcast_mut::<IoError>().expect("owned io source");
*io = IoError::other("disk replaced");
assert_eq!(
    err.downcast_ref::<IoError>()
        .expect("io source")
        .to_string(),
    "disk replaced"
);

pub fn into_boxed_dyn_error(self) -> Box<dyn Error + Send + Sync>

Convert the error into a boxed trait object.

The error is always boxed as-is, never unwrapped to its source, so the returned trait object keeps the full Display output, the kind, the metadata and the entire source() chain of this error. This mirrors anyhow::Error::into_boxed_dyn_error (available since anyhow 1.0.98) and forms a round-trip with from_boxed.

use masterror::AppError;

let err = AppError::internal("db down");
let display = err.to_string();
let boxed = err.into_boxed_dyn_error();
assert_eq!(boxed.to_string(), display);

Round-trip through from_boxed keeps the chain:

use core::error::Error;

use masterror::{AppError, AppErrorKind};

let source: Box<dyn Error + Send + Sync> = "root cause".into();
let err = AppError::from_boxed(AppErrorKind::Internal, source);
let restored = AppError::from_boxed(AppErrorKind::Internal, err.into_boxed_dyn_error());
assert_eq!(restored.chain().count(), 3);
assert_eq!(restored.root_cause().to_string(), "root cause");

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Deref for Error

type Target = ErrorInner

The resulting type after dereferencing.

fn deref(&self) -> &<Error as Deref>::Target

Dereferences the value.

impl DerefMut for Error

fn deref_mut(&mut self) -> &mut <Error as Deref>::Target

Mutably dereferences the value.

impl Display for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Box<dyn Error + Send + Sync>> for Error

Map an already boxed error to an internal application error.

The box is stored as the owned source without re-boxing, so the concrete error stays recoverable via AppError::downcast and AppError::downcast_ref. Equivalent to AppError::from_boxed with AppErrorKind::Internal.

use core::error::Error;

use masterror::{AppError, AppErrorKind};

let source: Box<dyn Error + Send + Sync> = "boom".into();
let err: AppError = source.into();
assert!(matches!(err.kind, AppErrorKind::Internal));
assert_eq!(err.source_ref().expect("source").to_string(), "boom");

fn from(source: Box<dyn Error + Send + Sync>) -> Error

Converts to this type from the input type.

impl From<ConfigError> for AppError

where ConfigError: Error + Send + Sync + 'static,

fn from(value: ConfigError) -> Self

Converts to this type from the input type.

impl From<ConfigValidationError> for AppError

where ConfigValidationError: Error + Send + Sync + 'static,

fn from(value: ConfigValidationError) -> Self

Converts to this type from the input type.

impl From<DiffParseError> for AppError

where DiffParseError: Error + Send + Sync + 'static,

fn from(value: DiffParseError) -> Self

Converts to this type from the input type.

impl From<Error> for Error

Available on crate feature std only.

Map std::io::Error to an internal application error.

Rationale: I/O failures are infrastructure-level, so the public-facing kind is always Internal. The error text becomes the public message, so avoid embedding sensitive details in I/O error messages that cross this boundary.

use std::io::{self, ErrorKind};

use masterror::{AppError, AppErrorKind};

let io_err = io::Error::from(ErrorKind::Other);
let app_err: AppError = io_err.into();
assert!(matches!(app_err.kind, AppErrorKind::Internal));

fn from(err: Error) -> Error

Converts to this type from the input type.

impl From<FileReadError> for AppError

where FileReadError: Error + Send + Sync + 'static,

fn from(value: FileReadError) -> Self

Converts to this type from the input type.

impl From<IoError> for AppError

where IoError: Error + Send + Sync + 'static,

fn from(value: IoError) -> Self

Converts to this type from the input type.

impl From<LimitExceededError> for AppError

where LimitExceededError: Error + Send + Sync + 'static,

fn from(value: LimitExceededError) -> Self

Converts to this type from the input type.

impl From<OutputError> for AppError

where OutputError: Error + Send + Sync + 'static,

fn from(value: OutputError) -> Self

Converts to this type from the input type.

impl From<ParseError> for AppError

where ParseError: Error + Send + Sync + 'static,

fn from(value: ParseError) -> Self

Converts to this type from the input type.

impl From<String> for Error

Map a plain String to a client error (BadRequest).

Handy for quick validation paths without the validator feature. Prefer structured validation for complex DTOs, but this covers simple cases.

use masterror::{AppError, AppErrorKind, AppResult};

fn check(name: &str) -> AppResult<()> {
    if name.is_empty() {
        return Err(String::from("name must not be empty").into());
    }
    Ok(())
}

let err = check("").unwrap_err();
assert!(matches!(err.kind, AppErrorKind::BadRequest));

fn from(value: String) -> Error

Converts to this type from the input type.