Struct Error 

pub struct Error { /* 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 AppError

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

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

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>>) -> Self

Build a Cache error.

use masterror::AppError;

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

impl Error

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

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>>) -> Self

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) -> Self

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) -> Self

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) -> Self

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>) -> Self

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) -> Self

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>) -> Self

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) -> Self

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) -> Self

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) -> Self

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>) -> Self

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 CoreError + Send + Sync + 'static) -> Self

Attach a source error for diagnostics.

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 CoreError + Send + Sync + 'static>, ) -> Self

Attach a shared source error without cloning the underlying Arc.

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) -> Self

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>) -> Self

Available on non-crate feature serde_json only.

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 CoreError + 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 CoreError + '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: CoreError + 'static,

Attempts to downcast the error source to a concrete type.

Returns true if the error source is of type E, false otherwise. This only checks the immediate source, not the entire chain.

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>, Self>

where E: CoreError + 'static,

Attempt to downcast the error source to a concrete type by value.

Note: This method is currently a stub and always returns Err(Self).

Use downcast_ref for inspecting error sources.

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);

assert!(err.downcast::<IoError>().is_err());

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

where E: CoreError + 'static,

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

Returns Some(&E) if this error is of type E, None otherwise.

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: CoreError + 'static,

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

Returns Some(&mut E) if this error is of type E, None otherwise.

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);

if let Some(_io) = err.downcast_mut::<IoError>() {
    // Can modify the IoError if needed
}

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Deref for Error

type Target = ErrorInner

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Error

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn CoreError + '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<&Error> for ErrorResponse

Convert borrowed AppError to ErrorResponse.

Clones the error’s message and metadata, leaving the original error intact. Respects MessageEditPolicy for message visibility.

Examples

use masterror::{AppError, ErrorResponse};

let err = AppError::conflict("resource exists");
let resp: ErrorResponse = (&err).into();

assert_eq!(resp.message, "resource exists");
// Original error remains intact
assert_eq!(err.message.as_deref(), Some("resource exists"));

fn from(err: &AppError) -> Self

Converts to this type from the input type.

impl From<Error> for AppError

Available on crate feature std only.

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

Rationale: I/O failures are infrastructure-level and should not leak driver-specific details to clients. The message is preserved for observability, but the public-facing kind is always Internal.

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: IoError) -> Self

Converts to this type from the input type.

impl From<Error> for ErrorResponse

Convert owned AppError to ErrorResponse.

Consumes the error, transferring ownership of message and metadata. Respects MessageEditPolicy for message visibility.

Examples

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

let err = AppError::validation("invalid email");
let resp: ErrorResponse = err.into();

assert_eq!(resp.status, AppErrorKind::Validation.http_status());
assert_eq!(resp.message, "invalid email");

fn from(err: AppError) -> Self

Converts to this type from the input type.

impl From<String> for AppError

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) -> Self

Converts to this type from the input type.