Enum AppError 

pub enum AppError {
    Config {
        message: String,
        retryable: bool,
        fatal: bool,
        status: u16,
    },
    Filesystem {
        path: Option<PathBuf>,
        source: Error,
        retryable: bool,
        fatal: bool,
        status: u16,
    },
    Network {
        endpoint: String,
        source: Option<Box<dyn StdError + Send + Sync>>,
        retryable: bool,
        fatal: bool,
        status: u16,
    },
    Other {
        message: String,
        retryable: bool,
        fatal: bool,
        status: u16,
    },
}

Example error enum that can be replaced by the define_errors! macro.

Variants

Config

Configuration-related errors

Fields

message: String

retryable: bool

fatal: bool

status: u16

Filesystem

Filesystem-related errors with optional path and source error

Fields

path: Option<PathBuf>

source: Error

retryable: bool

fatal: bool

status: u16

Network

Network-related errors

Fields

endpoint: String

source: Option<Box<dyn StdError + Send + Sync>>

retryable: bool

fatal: bool

status: u16

Other

Generic errors for anything not covered by specific variants

Fields

message: String

retryable: bool

fatal: bool

status: u16

Implementations

impl AppError

Constructor methods for AppError

pub fn config(message: impl Into<String>) -> Self

Create a new Config error

pub fn filesystem( path: impl Into<String>, source: impl Into<Option<Error>>, ) -> Self

Create a new Filesystem error

pub fn filesystem_with_source(path: impl Into<PathBuf>, source: Error) -> Self

Create a filesystem error with specific source error

pub fn network( endpoint: impl Into<String>, source: impl Into<Option<Box<dyn StdError + Send + Sync>>>, ) -> Self

Create a new Network error

pub fn network_with_source( endpoint: impl Into<String>, source: Option<Box<dyn StdError + Send + Sync>>, ) -> Self

Create a network error with specific source error

pub fn other(message: impl Into<String>) -> Self

Create a new generic error

pub fn with_retryable(self, retryable: bool) -> Self

Set whether this error is retryable

pub fn with_fatal(self, fatal: bool) -> Self

Set whether this error is fatal

pub fn with_status(self, status: u16) -> Self

Set the HTTP status code for this error

pub fn with_code(self, code: impl Into<String>) -> CodedError<Self>

Add a code to this error

pub fn context<C: Display + Debug + Send + Sync + 'static>( self, context: C, ) -> ContextError<Self, C>

Add context to this error

impl AppError

pub async fn from_async_result<T, E>(result: Result<T, E>) -> Result<T, Self>

where E: StdError + Send + Sync + 'static,

Convert an async operation’s Result<T, E> (where E: std::error::Error + Send + Sync + 'static) into a Result<T, AppError> by wrapping the error in AppError::other(...), marked retryable and non-fatal.

Convenience for the common async fn -> Result<T, AppError> pattern where the caller wants to flatten any std::error::Error into an AppError shape.

pub async fn handle_async(&self) -> Result<(), Box<dyn StdError + Send + Sync>>

Run the async hook on this error.

Equivalent to calling <AppError as AsyncForgeError>::async_handle(&self).await; AppError does not override the trait default, so this is a no-op Ok(()). Exists for symmetry with the other *_async builders on AppError.

Trait Implementations

impl AsyncForgeError for AppError

AppError participates in the AsyncForgeError surface so it can be used wherever async-aware error metadata is required.

All sync metadata methods (kind, caption, is_retryable, is_fatal, status_code, exit_code, user_message, dev_message) delegate to the existing ForgeError implementation. The async async_handle method uses the trait’s default no-op implementation — AppError has no default async behaviour beyond carrying its metadata.

Breaking change from 0.9.x

0.9.x shipped a stub async_handle implementation here that returned Ok(()) regardless of input but matched on AppError variants as if it were doing something. The stub is removed in 1.0; the trait now provides a no-op default and AppError inherits it.

fn kind(&self) -> &'static str

Returns the kind of error, typically matching the enum variant.

fn caption(&self) -> &'static str

Returns a human-readable caption for the error.

fn is_retryable(&self) -> bool

Returns true if the operation can be retried.

fn is_fatal(&self) -> bool

Returns true if the error is fatal and should terminate the program.

fn status_code(&self) -> u16

Returns an appropriate HTTP status code for the error.

fn exit_code(&self) -> i32

Returns an appropriate process exit code for the error.

fn user_message(&self) -> String

Returns a user-facing message that can be shown to end users.

fn dev_message(&self) -> String

Returns a detailed technical message for developers/logs.

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

Returns a backtrace if available.

fn async_handle<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), Box<dyn StdError + Send + Sync>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Async hook called when the implementor wants to run an await step (logging, cleanup, telemetry) on error surfacing. The default is a no-op; override if you need behaviour.

fn register(&self)

Registers the error with the central error hook (if any).

impl Debug for AppError

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

Formats the value using the given formatter.

impl Display for AppError

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

Formats the value using the given formatter.

impl Error for AppError

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 ForgeError for AppError

fn kind(&self) -> &'static str

Returns the kind of error, typically matching the enum variant

fn caption(&self) -> &'static str

Returns a human-readable caption for the error

fn is_retryable(&self) -> bool

Returns true if the operation can be retried

fn is_fatal(&self) -> bool

Returns true if the error is fatal and should terminate the program

fn status_code(&self) -> u16

Returns an appropriate HTTP status code for the error

fn exit_code(&self) -> i32

Returns an appropriate process exit code for the error

fn user_message(&self) -> String

Returns a user-facing message that can be shown to end users

fn dev_message(&self) -> String

Returns a detailed technical message for developers/logs

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

Returns a backtrace if available

fn register(&self)

Registers the error with the central error registry

impl From<Error> for AppError

fn from(e: Error) -> Self

Converts to this type from the input type.

impl Serialize for AppError

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.