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

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

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.