Trait AttachmentHandler 

pub trait AttachmentHandler<A>: 'static {
    // Required methods
    fn display(value: &A, formatter: &mut Formatter<'_>) -> Result;
    fn debug(value: &A, formatter: &mut Formatter<'_>) -> Result;

    // Provided method
    fn preferred_formatting_style(
        value: &A,
        report_formatting_function: FormattingFunction,
    ) -> AttachmentFormattingStyle { ... }
}

Trait for implementing custom formatting behavior for report attachments.

This trait defines how an attachment type should be formatted when displayed or debugged as part of an error report. Unlike ContextHandler, this trait also allows specifying placement preferences (inline vs appendix).

When to Implement

You typically don’t need to implement this trait directly. The rootcause library provides built-in handlers that cover most use cases. Implement this trait when you need:

• Custom formatting for attachment types
• Special placement logic (e.g., large data in appendices)
• Dynamic formatting based on attachment content

Required Methods

• display: Formats the attachment for display output
• debug: Formats the attachment for debug output

Optional Methods

• preferred_formatting_style: Specifies formatting preferences including placement (inline/appendix) and whether to use display or debug formatting. The default implementation prefers inline display formatting.

Examples

use rootcause_internals::handlers::{
    AttachmentFormattingPlacement, AttachmentFormattingStyle, AttachmentHandler,
    FormattingFunction,
};

// Attachment type with potentially large data
struct LargeData {
    records: Vec<String>,
}

// Handler that moves large attachments to appendix
struct LargeDataHandler;

impl AttachmentHandler<LargeData> for LargeDataHandler {
    fn display(attachment: &LargeData, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{} records", attachment.records.len())
    }

    fn debug(attachment: &LargeData, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "LargeData {{ {} records }}", attachment.records.len())
    }

    fn preferred_formatting_style(
        attachment: &LargeData,
        _report_formatting: FormattingFunction,
    ) -> AttachmentFormattingStyle {
        if attachment.records.len() > 10 {
            // Large data goes to appendix
            AttachmentFormattingStyle {
                placement: AttachmentFormattingPlacement::Appendix {
                    appendix_name: "Large Data Records",
                },
                function: FormattingFunction::Display,
                priority: 0,
            }
        } else {
            // Small data shows inline
            AttachmentFormattingStyle::default()
        }
    }
}

Required Methods

fn display(value: &A, formatter: &mut Formatter<'_>) -> Result

Formats the attachment using display-style formatting.

This method is called when the attachment needs to be displayed as part of an error report. It should produce human-readable output suitable for end users.

Examples

use rootcause_internals::handlers::AttachmentHandler;

struct ConfigData {
    key: String,
    value: String,
}

struct ConfigHandler;

impl AttachmentHandler<ConfigData> for ConfigHandler {
    fn display(attachment: &ConfigData, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{} = {}", attachment.key, attachment.value)
    }
}

fn debug(value: &A, formatter: &mut Formatter<'_>) -> Result

Formats the attachment using debug-style formatting.

This method is called when the attachment needs to be debug-formatted. It should produce detailed output suitable for developers.

Provided Methods

fn preferred_formatting_style( value: &A, report_formatting_function: FormattingFunction, ) -> AttachmentFormattingStyle

Specifies the preferred formatting style and placement for this attachment.

This method allows the handler to control:

• Placement: Whether the attachment appears inline, in an appendix, or is hidden
• Formatting: Whether to use display or debug formatting
• Priority: The order in which attachments are displayed (higher = earlier)

The default implementation returns inline display formatting with priority 0.

Examples

Attachment that hides sensitive data:

use rootcause_internals::handlers::{
    AttachmentFormattingPlacement, AttachmentFormattingStyle, AttachmentHandler,
    FormattingFunction,
};

struct ApiKey(String);

struct SecureHandler;

impl AttachmentHandler<ApiKey> for SecureHandler {
    fn display(_attachment: &ApiKey, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "[REDACTED]")
    }

    fn debug(_attachment: &ApiKey, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "ApiKey([REDACTED])")
    }

    fn preferred_formatting_style(
        _attachment: &ApiKey,
        _report_formatting: FormattingFunction,
    ) -> AttachmentFormattingStyle {
        // Hide this attachment completely in production
        AttachmentFormattingStyle {
            placement: AttachmentFormattingPlacement::Hidden,
            function: FormattingFunction::Display,
            priority: 0,
        }
    }
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors