Struct Error 

pub struct Error { /* private fields */ }

Rich application error preserving domain code, taxonomy and metadata.

Implementations

impl AppError

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

Build a NotFound error.

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

Build a Validation error.

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

Build an Unauthorized error.

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

Build a Forbidden error.

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

Build a Conflict error.

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

Build a BadRequest error.

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

Build a RateLimited error.

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

Build a TelegramAuth error.

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

Build an Internal error.

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

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

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.

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

Build a Turnkey error.

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

Build a Timeout error.

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

Build a Network error.

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

Build a DependencyUnavailable error.

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

Backward-compatible alias; routes to DependencyUnavailable.

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

Build a Serialization error.

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

Build a Deserialization error.

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

Build an ExternalApi error.

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

Build a Queue error.

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

Build a Cache error.

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.

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.

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

Override the machine-readable AppCode.

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.

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

Attach a WWW-Authenticate challenge string.

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

Attach additional metadata to the error.

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

Extend metadata from an iterator of fields.

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

Override the redaction policy for a stored metadata field.

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

Replace metadata entirely.

pub fn redactable(self) -> Self

Mark the message as redactable.

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.

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.

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

pub fn metadata(&self) -> &Metadata

Borrow the attached metadata.

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

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

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

Borrow the source if present.

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

Human-readable message or the kind fallback.

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.

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

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

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.