Trait AsyncForgeError 

pub trait AsyncForgeError:
    StdError
    + Send
    + Sync
    + 'static {
    // Required methods
    fn kind(&self) -> &'static str;
    fn caption(&self) -> &'static str;

    // Provided methods
    fn is_retryable(&self) -> bool { ... }
    fn is_fatal(&self) -> bool { ... }
    fn status_code(&self) -> u16 { ... }
    fn exit_code(&self) -> i32 { ... }
    fn user_message(&self) -> String { ... }
    fn dev_message(&self) -> String { ... }
    fn backtrace(&self) -> Option<&Backtrace> { ... }
    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 { ... }
    fn register(&self) { ... }
}

Async-aware companion trait to ForgeError.

Carries the same sync metadata methods as ForgeError plus a single async hook, async_handle, that callers can override to run an await step (logging, telemetry, cleanup) when an error surfaces in an async context. The default implementation is a no-op — implementors who do not need an async hook can ignore the method entirely.

Example

Requires the async cargo feature (which pulls in async-trait). The hidden #[cfg(feature = "async")] gate means this doctest is only compiled when the feature is enabled — under cargo test --all-features it runs; otherwise it is silently skipped.

use error_forge::async_error::AsyncForgeError;
use async_trait::async_trait;
use std::error::Error as StdError;

#[derive(Debug)]
struct MyAsyncError { message: String }

impl std::fmt::Display for MyAsyncError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.message)
    }
}

impl std::error::Error for MyAsyncError {}

#[async_trait]
impl AsyncForgeError for MyAsyncError {
    fn kind(&self) -> &'static str { "AsyncExample" }
    fn caption(&self) -> &'static str { "Async Example Error" }

    // Override the no-op default if you want async behaviour:
    async fn async_handle(&self) -> Result<(), Box<dyn StdError + Send + Sync>> {
        // Telemetry, cleanup, etc. would go here.
        Ok(())
    }
}

Breaking change from 0.9.x

In 0.9.x, async_handle was a required method with no default body, and the AppError implementation provided a stub that did nothing. In 1.0, async_handle gains a default no-op body and the stub AppError implementation is removed. Implementors who actually want async behaviour override the default; everyone else can derive the trait without writing the method.

Required Methods

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.

Provided Methods

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

Implementors

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.