Struct TaskFailure 

pub struct TaskFailure { /* private fields */ }

Represents a failed task execution with comprehensive error information and context.

TaskFailure captures detailed information about why a task failed, including the underlying error, failure classification, retry hints, and any warnings or messages collected during execution before the failure occurred. This structure provides rich context for error handling, logging, and determining whether a failed task should be retried.

The failure information includes timing data, structured details about the error, and the ability to downcast to specific error types for specialized error handling.

Fields

• error - The underlying error that caused the task to fail. This is a thread-safe, reference-counted error that can be downcast to specific error types. Not serialized.

• kind - The classification of the failure (e.g., Connection, Authentication, Timeout). This helps categorize errors for reporting and handling purposes.

• error_type - A string representation of the error’s type name, useful for debugging and logging when the actual error type information is needed.

• message - A human-readable error message describing what went wrong. This is typically derived from the error’s Display implementation.

• retryable - Indicates whether this failure is potentially transient and the task could succeed if retried. This helps automation systems decide retry strategies.

• details - Optional structured data providing additional context about the failure, such as error codes, affected resources, or diagnostic information.

• warnings - A list of warning messages that were generated during execution before the failure occurred. These can provide context about what led to the failure.

• messages - Structured messages with levels (Info, Warning, Error, Debug) that were collected during execution, providing a detailed execution trace up to the point of failure.

• started_at - The timestamp when the task execution started, if available.

• finished_at - The timestamp when the task execution failed, if available.

• duration_ms - The duration of the task execution in milliseconds before it failed, if available.

Example

use genja_core::task::{TaskFailure, TaskFailureKind, TaskMessage, MessageLevel};
use serde_json::json;
use std::io;

let failure = TaskFailure::new(io::Error::new(io::ErrorKind::TimedOut, "connection timeout"))
    .with_kind(TaskFailureKind::Timeout)
    .with_retryable(true)
    .with_details(json!({"timeout_seconds": 30}))
    .with_warning("Slow network detected")
    .with_message(TaskMessage::new(MessageLevel::Error, "Failed to connect to host"));

assert!(failure.retryable());
assert!(matches!(failure.kind(), TaskFailureKind::Timeout));
assert_eq!(failure.warnings().len(), 1);

Implementations

impl TaskFailure

pub fn new<E>(error: E) -> Self

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

Creates a new TaskFailure instance from an error.

This constructor wraps any error type that implements the standard Error trait in a TaskFailure, capturing the error message and type information. The failure is initialized with default values: classified as Internal, not retryable, with no additional details, warnings, or messages, and no timing information.

The error is stored as a thread-safe, reference-counted pointer (Arc<dyn Error>), allowing it to be cloned and shared across threads while preserving the ability to downcast to the original error type for specialized error handling.

Parameters

• error - The error that caused the task to fail. Must implement Error + Send + Sync + 'static, ensuring it can be safely shared across threads and stored for the lifetime of the program.

Returns

A new TaskFailure instance with the error wrapped and default values for all other fields. The failure kind is set to Internal, retryable is false, and all optional fields are None.

pub fn capture<E>(error: E) -> Self

where E: Debug + Display + Send + Sync + 'static,

Creates a new TaskFailure from any thread-safe 'static payload.

This is useful when the failure value does not implement Error but still carries meaningful type and display information that should be stored with the task result.

pub fn from_task_error(error: TaskError) -> Self

Creates a new TaskFailure from an already-erased task error.

Failures captured through the task execution boundary default to TaskFailureKind::External, because the error originated outside the Genja framework itself.

pub fn with_kind(self, kind: TaskFailureKind) -> Self

Sets the failure classification kind.

This is a builder method that consumes self and returns the modified instance, allowing for method chaining. The kind categorizes the failure type (e.g., Connection, Authentication, Timeout) to help with error handling and reporting.

Parameters

• kind - The TaskFailureKind classification for this failure.

Returns

The modified TaskFailure instance with the failure kind set.

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

Sets whether this failure is retryable.

This is a builder method that consumes self and returns the modified instance, allowing for method chaining. The retryable flag indicates whether the failure is potentially transient and the task could succeed if retried.

Parameters

• retryable - true if the task should be retried after this failure, false if the failure is permanent and retrying would not help.

Returns

The modified TaskFailure instance with the retryable flag set.

pub fn with_details(self, details: Value) -> Self

Sets additional structured details about the failure.

This is a builder method that consumes self and returns the modified instance, allowing for method chaining. The details can contain arbitrary JSON data providing additional context about the failure, such as error codes, affected resources, or diagnostic information.

Parameters

• details - A serde_json::Value containing the structured failure details.

Returns

The modified TaskFailure instance with the details set.

pub fn with_warning(self, warning: impl Into<String>) -> Self

Adds a warning message to the list of warnings generated before the failure.

This is a builder method that consumes self and returns the modified instance, allowing for method chaining. Warnings provide context about what occurred during execution before the failure happened. Multiple warnings can be added by calling this method multiple times.

Parameters

• warning - A warning message. Can be any type that implements Into<String>, such as &str, String, or other string-like types.

Returns

The modified TaskFailure instance with the warning added to the warnings list.

pub fn with_message(self, message: TaskMessage) -> Self

Adds a structured message to the list of messages generated before the failure.

This is a builder method that consumes self and returns the modified instance, allowing for method chaining. Messages provide detailed execution information with associated severity levels that were collected before the failure occurred. Multiple messages can be added by calling this method multiple times.

Parameters

• message - A TaskMessage containing the message text, severity level, and optional code and timestamp.

Returns

The modified TaskFailure instance with the message added to the messages list.

pub fn with_started_at(self, started_at: SystemTime) -> Self

Sets the task execution start timestamp.

This is a builder method that consumes self and returns the modified instance, allowing for method chaining.

Parameters

• started_at - The timestamp when the task execution started.

Returns

The modified TaskFailure instance with the start timestamp set.

pub fn with_finished_at(self, finished_at: SystemTime) -> Self

Sets the task execution finish timestamp.

This is a builder method that consumes self and returns the modified instance, allowing for method chaining.

Parameters

• finished_at - The timestamp when the task execution failed.

Returns

The modified TaskFailure instance with the finish timestamp set.

pub fn with_duration_ms(self, duration_ms: u128) -> Self

Sets the task execution duration in milliseconds.

This is a builder method that consumes self and returns the modified instance, allowing for method chaining.

Parameters

• duration_ms - The duration of the task execution in milliseconds before it failed.

Returns

The modified TaskFailure instance with the duration set.

pub fn with_duration_ns(self, duration_ns: u128) -> Self

Sets the task execution duration in nanoseconds.

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

where E: 'static,

Attempts to downcast the underlying error to a specific error type.

This method provides type-safe access to the original error type, allowing specialized error handling based on the concrete error type. If the underlying error is of type E, this returns a reference to it; otherwise, it returns None.

Type Parameters

• E - The concrete error type to downcast to. Must implement Error + 'static.

Returns

Some(&E) if the underlying error is of type E, None otherwise.

pub fn error(&self) -> &(dyn Error + Send + Sync + 'static)

Returns a reference to the underlying error as a trait object.

This method provides access to the error through the Error trait interface, allowing generic error handling without knowing the concrete error type.

Returns

A reference to the underlying error as a trait object implementing Error + Send + Sync + 'static.

pub fn error_type(&self) -> &str

Returns the type name of the underlying error.

This method provides the fully qualified type name of the error as a string, which is useful for debugging and logging when you need to know the concrete error type without downcasting.

Returns

A string slice containing the fully qualified type name of the error.

pub fn message(&self) -> &str

Returns the human-readable error message.

This message is derived from the error’s Display implementation and provides a description of what went wrong during task execution.

Returns

A string slice containing the error message.

pub fn kind(&self) -> &TaskFailureKind

Returns the failure classification kind.

Returns

A reference to the TaskFailureKind indicating the category of this failure.

pub fn retryable(&self) -> bool

Returns whether this failure is retryable.

Returns

true if the task should be retried after this failure, false if the failure is permanent and retrying would not help.

pub fn details(&self) -> Option<&Value>

Returns the additional structured details about the failure, if available.

Returns

Some(&Value) if failure details were set, None otherwise.

pub fn warnings(&self) -> &[String]

Returns a slice of all warning messages generated before the failure.

Returns

A slice containing all warning messages. Returns an empty slice if no warnings were generated.

pub fn messages(&self) -> &[TaskMessage]

Returns a slice of all structured messages generated before the failure.

Returns

A slice containing all TaskMessage instances. Returns an empty slice if no messages were generated.

pub fn started_at(&self) -> Option<SystemTime>

Returns the task execution start timestamp, if available.

Returns

Some(SystemTime) if the start timestamp was set, None otherwise.

pub fn finished_at(&self) -> Option<SystemTime>

Returns the task execution finish timestamp, if available.

Returns

Some(SystemTime) if the finish timestamp was set, None otherwise.

pub fn duration_ms(&self) -> Option<u128>

Returns the task execution duration in milliseconds, if available.

Returns

Some(u128) if the duration was set, None otherwise.

pub fn duration_ns(&self) -> Option<u128>

Returns the task execution duration in nanoseconds, if available.

pub fn started_at_display(&self) -> Option<String>

Returns the task execution start timestamp in RFC 3339 format, if available.

pub fn finished_at_display(&self) -> Option<String>

Returns the task execution finish timestamp in RFC 3339 format, if available.

pub fn duration_display(&self) -> Option<String>

Returns the task execution duration in a human-readable format, if available.

Trait Implementations

impl Clone for TaskFailure

fn clone(&self) -> TaskFailure

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TaskFailure

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

Formats the value using the given formatter.

impl Serialize for TaskFailure

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

where __S: Serializer,

Serialize this value into the given Serde serializer.