rootcause 0.12.1

//! Context formatting hooks for customizing how error messages are displayed.
//!
//! Control how the main error type in each report appears:
//! - Custom error descriptions for your types
//! - Better Display output for Debug-only types
//! - Simplify noisy or complex error messages
//! - Hide sensitive details while keeping useful information
//!
//! By installing hooks for specific error types, you can customize how they
//! appear in reports without changing the error type itself.
//!
//! > **Note:** Hooks format a type globally across ALL errors. To control
//! > formatting for a single context, use [`context_custom()`] with a handler
//! > instead (see [`examples/custom_handler.rs`]).
//!
//! [`context_custom()`]: crate::Report::context_custom
//! [`examples/custom_handler.rs`]: https://github.com/rootcause-rs/rootcause/blob/main/examples/custom_handler.rs
//!
//! # Key Components
//!
//! - [`ContextFormatterHook`] - Trait for implementing custom context
//!   formatting
//!
//! # Examples
//!
//! ## Custom formatting for your own types
//!
//! ```
//! use core::fmt;
//!
//! use rootcause::{
//!     ReportRef,
//!     hooks::{Hooks, context_formatter::ContextFormatterHook},
//!     markers::{Local, Uncloneable},
//! };
//!
//! struct DatabaseError {
//!     table: String,
//!     operation: String,
//!     details: String,
//! }
//!
//! struct DatabaseErrorFormatter;
//!
//! impl ContextFormatterHook<DatabaseError> for DatabaseErrorFormatter {
//!     fn display(
//!         &self,
//!         report: ReportRef<'_, DatabaseError, Uncloneable, Local>,
//!         f: &mut fmt::Formatter<'_>,
//!     ) -> fmt::Result {
//!         let err = report.current_context();
//!         write!(
//!             f,
//!             "Database {} failed on table '{}': {}",
//!             err.operation, err.table, err.details
//!         )
//!     }
//! }
//!
//! // Install the custom formatter globally
//! Hooks::new()
//!     .context_formatter::<DatabaseError, _>(DatabaseErrorFormatter)
//!     .install()
//!     .expect("failed to install hooks");
//! ```
//!
//! ## Simplifying complex or Debug-only types
//!
//! When using types that only implement [`Debug`](core::fmt::Debug) (not
//! [`Display`](core::fmt::Display)), reports show "Context of type `TypeName`"
//! by default (see [`crate::handlers::Debug`]). Use a context formatter to
//! provide simplified, user-friendly output:
//!
//! ```
//! use core::fmt;
//!
//! use rootcause::{
//!     ReportRef,
//!     hooks::{Hooks, context_formatter::ContextFormatterHook},
//!     markers::{Local, Uncloneable},
//!     prelude::*,
//! };
//!
//! // External type you can't modify (only has Debug, not Display)
//! #[derive(Debug)]
//! struct InternalState {
//!     connection_count: usize,
//!     pending_requests: usize,
//! }
//!
//! struct InternalStateFormatter;
//!
//! impl ContextFormatterHook<InternalState> for InternalStateFormatter {
//!     fn display(
//!         &self,
//!         report: ReportRef<'_, InternalState, Uncloneable, Local>,
//!         f: &mut fmt::Formatter<'_>,
//!     ) -> fmt::Result {
//!         let state = report.current_context();
//!         write!(
//!             f,
//!             "System overloaded: {} connections, {} pending",
//!             state.connection_count, state.pending_requests
//!         )
//!     }
//! }
//!
//! // Without this hook, would show "Context of type `InternalState`"
//! Hooks::new()
//!     .context_formatter::<InternalState, _>(InternalStateFormatter)
//!     .install()
//!     .expect("failed to install hooks");
//! ```

use alloc::{boxed::Box, fmt};
use core::{any::TypeId, marker::PhantomData};

use hashbrown::HashMap;
use rootcause_internals::handlers::{ContextFormattingStyle, FormattingFunction};

use crate::{
    ReportRef,
    hooks::{HookData, use_hooks},
    markers::{Dynamic, Local, Uncloneable},
    preformatted::PreformattedContext,
};

#[derive(Default)]
pub(crate) struct HookMap {
    /// # Safety Invariant
    ///
    /// The hook stored under `TypeId::of::<C>()` is guaranteed to be an
    /// instance of the type `Hook<C, H>`.
    map: HashMap<TypeId, Box<dyn StoredHook>, rustc_hash::FxBuildHasher>,
}

impl core::fmt::Debug for HookMap {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.map.values().fmt(f)
    }
}

impl HookMap {
    /// Retrieves the formatter hook for the specified context
    /// type.
    ///
    /// The returned hook is guaranteed to be an instance of type `Hook<C, H>`,
    /// where `TypeId::of::<C>() == type_id`.
    fn get(&self, type_id: TypeId) -> Option<&dyn StoredHook> {
        Some(&**self.map.get(&type_id)?)
    }

    pub(crate) fn insert<C, H>(&mut self, hook: H)
    where
        C: 'static,
        H: ContextFormatterHook<C>,
    {
        let hook: Hook<C, H> = Hook {
            hook,
            _hooked_type: PhantomData,
        };
        let hook: Box<Hook<C, H>> = Box::new(hook);
        // We must uphold the safety invariant of HookMap.
        //
        // The safety invariant requires that the hook stored under
        // `TypeId::of::<C>()` is always of type `Hook<C, H>`.
        //
        // However this is exactly what we are doing here,
        // so the invariant is upheld.
        self.map.insert(TypeId::of::<C>(), hook);
    }
}

struct Hook<C, H>
where
    C: 'static,
{
    hook: H,
    _hooked_type: PhantomData<fn(C) -> C>,
}

impl<C, H> core::fmt::Debug for Hook<C, H>
where
    C: 'static,
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "ContextFormattingHook<{}, {}>",
            core::any::type_name::<C>(),
            core::any::type_name::<H>(),
        )
    }
}

/// Trait for untyped context formatter hooks.
///
/// This trait is guaranteed to only be implemented for [`Hook<C, H>`].
trait StoredHook: 'static + Send + Sync + core::fmt::Debug {
    /// Formats the context using Display formatting.
    ///
    /// # Safety
    ///
    /// The caller must ensure:
    ///
    /// 1. The type `C` stored in the context matches the `C` from type `Hook<C,
    ///    H>` this is implemented for.
    unsafe fn display(
        &self,
        report: ReportRef<'_, Dynamic, Uncloneable, Local>,
        formatter: &mut fmt::Formatter<'_>,
    ) -> fmt::Result;

    /// Formats the context using Debug formatting.
    ///
    /// # Safety
    ///
    /// The caller must ensure:
    ///
    /// 1. The type `C` stored in the context matches the `C` from type `Hook<C,
    ///    H>` this is implemented for.
    unsafe fn debug(
        &self,
        report: ReportRef<'_, Dynamic, Uncloneable, Local>,
        formatter: &mut fmt::Formatter<'_>,
    ) -> fmt::Result;

    fn display_preformatted(
        &self,
        report: ReportRef<'_, PreformattedContext, Uncloneable, Local>,
        formatter: &mut fmt::Formatter<'_>,
    ) -> fmt::Result;

    fn debug_preformatted(
        &self,
        report: ReportRef<'_, PreformattedContext, Uncloneable, Local>,
        formatter: &mut fmt::Formatter<'_>,
    ) -> fmt::Result;

    fn preferred_context_formatting_style(
        &self,
        report: ReportRef<'_, Dynamic, Uncloneable, Local>,
        report_formatting_function: FormattingFunction,
    ) -> ContextFormattingStyle;
}

/// Trait for customizing how contexts of a specific type are formatted in error
/// reports.
///
/// This trait allows you to override the default formatting behavior for
/// contexts (the main error types) of type `C`. You can customize both Display
/// and Debug formatting, handle preformatted contexts, and specify preferred
/// formatting styles.
///
/// # Type Parameters
///
/// * `C` - The context type that this formatter handles
///
/// # Default Implementations
///
/// All methods have default implementations that delegate to the unhooked
/// formatting, so you only need to implement the methods for the formatting you
/// want to customize.
///
/// # Examples
///
/// Custom Display formatting for a business logic error:
/// ```
/// use core::fmt;
///
/// use rootcause::{
///     ReportRef,
///     hooks::context_formatter::ContextFormatterHook,
///     markers::{Local, Uncloneable},
/// };
///
/// struct ValidationError {
///     field: String,
///     rule: String,
///     value: String,
/// }
///
/// struct ValidationErrorFormatter;
///
/// impl ContextFormatterHook<ValidationError> for ValidationErrorFormatter {
///     fn display(
///         &self,
///         report: ReportRef<'_, ValidationError, Uncloneable, Local>,
///         f: &mut fmt::Formatter<'_>,
///     ) -> fmt::Result {
///         let err = report.current_context();
///         write!(
///             f,
///             "Validation failed for field '{}': value '{}' violates rule '{}'",
///             err.field, err.value, err.rule
///         )
///     }
/// }
/// ```
pub trait ContextFormatterHook<C>: 'static + Send + Sync {
    /// Formats the context using Display formatting.
    ///
    /// This method is called when the context needs to be displayed in a
    /// user-friendly format. The default implementation delegates to the
    /// context's unhooked Display formatting.
    ///
    /// # Arguments
    ///
    /// * `report` - Reference to the report containing the context to format
    /// * `formatter` - The formatter to write output to
    ///
    /// # Examples
    ///
    /// ```
    /// use core::fmt;
    ///
    /// use rootcause::{
    ///     ReportRef,
    ///     hooks::context_formatter::ContextFormatterHook,
    ///     markers::{Local, Uncloneable},
    /// };
    ///
    /// struct HttpError {
    ///     status: u16,
    ///     message: String,
    /// }
    ///
    /// struct HttpErrorFormatter;
    ///
    /// impl ContextFormatterHook<HttpError> for HttpErrorFormatter {
    ///     fn display(
    ///         &self,
    ///         report: ReportRef<'_, HttpError, Uncloneable, Local>,
    ///         f: &mut fmt::Formatter<'_>,
    ///     ) -> fmt::Result {
    ///         let err = report.current_context();
    ///         write!(f, "HTTP {} - {}", err.status, err.message)
    ///     }
    /// }
    /// ```
    fn display(
        &self,
        report: ReportRef<'_, C, Uncloneable, Local>,
        formatter: &mut fmt::Formatter<'_>,
    ) -> fmt::Result {
        fmt::Display::fmt(&report.format_current_context_unhooked(), formatter)
    }

    /// Formats a preformatted context using Display formatting.
    ///
    /// This method handles contexts that have been preformatted (typically done
    /// using [`ReportRef::preformat`] for performance or consistency reasons).
    /// The default implementation delegates to the context's unhooked
    /// Display formatting.
    ///
    /// # Arguments
    ///
    /// * `report` - Reference to the report containing the preformatted context
    /// * `formatter` - The formatter to write output to
    ///
    /// # Examples
    ///
    /// ```
    /// use rootcause::{
    ///     ReportRef,
    ///     hooks::context_formatter::ContextFormatterHook,
    ///     markers::{Local, Uncloneable},
    ///     preformatted::PreformattedContext,
    /// };
    ///
    /// struct MyFormatter;
    /// impl ContextFormatterHook<String> for MyFormatter {
    ///     fn display_preformatted(
    ///         &self,
    ///         report: ReportRef<'_, PreformattedContext, Uncloneable, Local>,
    ///         f: &mut core::fmt::Formatter<'_>,
    ///     ) -> core::fmt::Result {
    ///         write!(
    ///             f,
    ///             "[Preformatted] {}",
    ///             report.format_current_context_unhooked()
    ///         )
    ///     }
    /// }
    /// ```
    fn display_preformatted(
        &self,
        report: ReportRef<'_, PreformattedContext, Uncloneable, Local>,
        formatter: &mut fmt::Formatter<'_>,
    ) -> fmt::Result {
        fmt::Display::fmt(&report.format_current_context_unhooked(), formatter)
    }

    /// Formats the context using Debug formatting.
    ///
    /// This method is called when the context needs to be displayed in a
    /// debug-friendly format (typically more verbose and detailed). The default
    /// implementation delegates to the context's unhooked Debug formatting.
    ///
    /// # Arguments
    ///
    /// * `report` - Reference to the report containing the context to format
    /// * `formatter` - The formatter to write output to
    ///
    /// # Examples
    ///
    /// ```
    /// use rootcause::{
    ///     ReportRef,
    ///     hooks::context_formatter::ContextFormatterHook,
    ///     markers::{Local, Uncloneable},
    /// };
    ///
    /// struct MyFormatter;
    /// impl ContextFormatterHook<String> for MyFormatter {
    ///     fn debug(
    ///         &self,
    ///         report: ReportRef<'_, String, Uncloneable, Local>,
    ///         f: &mut core::fmt::Formatter<'_>,
    ///     ) -> core::fmt::Result {
    ///         write!(f, "Debug: {:?}", report.current_context())
    ///     }
    /// }
    /// ```
    fn debug(
        &self,
        report: ReportRef<'_, C, Uncloneable, Local>,
        formatter: &mut fmt::Formatter<'_>,
    ) -> fmt::Result {
        fmt::Debug::fmt(&report.format_current_context_unhooked(), formatter)
    }

    /// Formats a preformatted context using Debug formatting.
    ///
    /// This method handles preformatted contexts when debug formatting is
    /// requested. The default implementation delegates to the context's
    /// unhooked Debug formatting.
    ///
    /// # Arguments
    ///
    /// * `report` - Reference to the report containing the preformatted context
    /// * `formatter` - The formatter to write output to
    ///
    /// # Examples
    ///
    /// ```
    /// use rootcause::{
    ///     ReportRef,
    ///     hooks::context_formatter::ContextFormatterHook,
    ///     markers::{Local, Uncloneable},
    ///     preformatted::PreformattedContext,
    /// };
    ///
    /// struct MyFormatter;
    /// impl ContextFormatterHook<String> for MyFormatter {
    ///     fn debug_preformatted(
    ///         &self,
    ///         report: ReportRef<'_, PreformattedContext, Uncloneable, Local>,
    ///         f: &mut core::fmt::Formatter<'_>,
    ///     ) -> core::fmt::Result {
    ///         write!(
    ///             f,
    ///             "[Preformatted Debug] {:?}",
    ///             report.format_current_context_unhooked()
    ///         )
    ///     }
    /// }
    /// ```
    fn debug_preformatted(
        &self,
        report: ReportRef<'_, PreformattedContext, Uncloneable, Local>,
        formatter: &mut fmt::Formatter<'_>,
    ) -> fmt::Result {
        fmt::Debug::fmt(&report.format_current_context_unhooked(), formatter)
    }

    /// Determines the preferred formatting style for this context.
    ///
    /// This method allows the formatter to specify how the context should be
    /// presented, including which formatting function should be used. The
    /// default implementation delegates to the context's unhooked
    /// preference.
    ///
    /// # Arguments
    ///
    /// * `report` - Reference to the report (as [`Dynamic`] as it can be either
    ///   a `C` or a [`PreformattedContext`])
    /// * `report_formatting_function` - Whether the overall report uses Display
    ///   or Debug formatting
    ///
    /// # Examples
    ///
    /// ```
    /// use rootcause::{
    ///     ReportRef,
    ///     handlers::{ContextFormattingStyle, FormattingFunction},
    ///     hooks::context_formatter::ContextFormatterHook,
    ///     markers::{Dynamic, Local, Uncloneable},
    /// };
    ///
    /// struct MyFormatter;
    /// impl ContextFormatterHook<String> for MyFormatter {
    ///     fn preferred_context_formatting_style(
    ///         &self,
    ///         _report: ReportRef<'_, Dynamic, Uncloneable, Local>,
    ///         _function: FormattingFunction,
    ///     ) -> ContextFormattingStyle {
    ///         ContextFormattingStyle {
    ///             function: FormattingFunction::Display,
    ///             follow_source: false,
    ///             follow_source_depth: None,
    ///         }
    ///     }
    /// }
    /// ```
    fn preferred_context_formatting_style(
        &self,
        report: ReportRef<'_, Dynamic, Uncloneable, Local>,
        report_formatting_function: FormattingFunction,
    ) -> ContextFormattingStyle {
        report.preferred_context_formatting_style_unhooked(report_formatting_function)
    }
}

impl<C, H> StoredHook for Hook<C, H>
where
    C: 'static,
    H: ContextFormatterHook<C>,
{
    unsafe fn display(
        &self,
        report: ReportRef<'_, Dynamic, Uncloneable, Local>,
        formatter: &mut fmt::Formatter<'_>,
    ) -> fmt::Result {
        // SAFETY:
        // 1. Guaranteed by the caller
        let report = unsafe { report.downcast_report_unchecked::<C>() };
        self.hook.display(report, formatter)
    }

    unsafe fn debug(
        &self,
        report: ReportRef<'_, Dynamic, Uncloneable, Local>,
        formatter: &mut fmt::Formatter<'_>,
    ) -> fmt::Result {
        // SAFETY:
        // 1. Guaranteed by the caller
        let report = unsafe { report.downcast_report_unchecked::<C>() };
        self.hook.debug(report, formatter)
    }

    fn display_preformatted(
        &self,
        report: ReportRef<'_, PreformattedContext, Uncloneable, Local>,
        formatter: &mut fmt::Formatter<'_>,
    ) -> fmt::Result {
        self.hook.display_preformatted(report, formatter)
    }

    fn debug_preformatted(
        &self,
        report: ReportRef<'_, PreformattedContext, Uncloneable, Local>,
        formatter: &mut fmt::Formatter<'_>,
    ) -> fmt::Result {
        self.hook.debug_preformatted(report, formatter)
    }

    fn preferred_context_formatting_style(
        &self,
        report: ReportRef<'_, Dynamic, Uncloneable, Local>,
        report_formatting_function: FormattingFunction,
    ) -> ContextFormattingStyle {
        self.hook
            .preferred_context_formatting_style(report, report_formatting_function)
    }
}

pub(crate) fn display_context(
    report: ReportRef<'_, Dynamic, Uncloneable, Local>,
    formatter: &mut fmt::Formatter<'_>,
) -> fmt::Result {
    use_hooks(|hook_data: Option<&HookData>| {
        if let Some(hook_data) = hook_data {
            let context_formatters: &HookMap = &hook_data.context_formatters;
            if let Some(report) = report.downcast_report::<PreformattedContext>()
                && let Some(hook) =
                    context_formatters.get(report.current_context().original_type_id())
            {
                return hook.display_preformatted(report, formatter);
            }

            if let Some(hook) = context_formatters.get(report.current_context_type_id()) {
                // SAFETY:
                // 1. The call to `get` guarantees that the returned hook is of type `Hook<C,
                //    H>`, and `TypeId::of<C>() == report.current_context_type_id()`. Therefore
                //    the type `C` stored in the context matches the `C` from type `Hook<C, H>`.
                unsafe {
                    // @add-unsafe-context: StoredHook
                    return hook.display(report, formatter);
                }
            }
        }
        fmt::Display::fmt(&report.format_current_context_unhooked(), formatter)
    })
}

pub(crate) fn debug_context(
    report: ReportRef<'_, Dynamic, Uncloneable, Local>,
    formatter: &mut fmt::Formatter<'_>,
) -> fmt::Result {
    use_hooks(|hook_data: Option<&HookData>| {
        if let Some(hook_data) = hook_data {
            let context_formatters: &HookMap = &hook_data.context_formatters;
            if let Some(report) = report.downcast_report::<PreformattedContext>()
                && let Some(hook) =
                    context_formatters.get(report.current_context().original_type_id())
            {
                return hook.debug_preformatted(report, formatter);
            }

            if let Some(hook) = context_formatters.get(report.current_context_type_id()) {
                // SAFETY:
                // 1. The call to `get` guarantees that the returned hook is of type `Hook<C,
                //    H>`, and `TypeId::of<C>() == report.current_context_type_id()`. Therefore
                //    the type `C` stored in the context matches the `C` from type `Hook<C, H>`.
                unsafe {
                    // @add-unsafe-context: StoredHook
                    return hook.debug(report, formatter);
                }
            }
        }
        fmt::Debug::fmt(&report.format_current_context_unhooked(), formatter)
    })
}

/// # Arguments
///
/// - `report_formatting_function`: Whether the report in which this context
///   will be embedded is being formatted using [`Display`] formatting or
///   [`Debug`]
///
/// [`Display`]: core::fmt::Display
/// [`Debug`]: core::fmt::Debug
pub(crate) fn get_preferred_context_formatting_style(
    report: ReportRef<'_, Dynamic, Uncloneable, Local>,
    report_formatting_function: FormattingFunction,
) -> ContextFormattingStyle {
    use_hooks(|hook_data: Option<&HookData>| {
        if let Some(hook_data) = hook_data {
            let context_formatters: &HookMap = &hook_data.context_formatters;

            if let Some(current_context) = report.downcast_current_context::<PreformattedContext>()
                && let Some(hook) = context_formatters.get(current_context.original_type_id())
            {
                return hook.preferred_context_formatting_style(report, report_formatting_function);
            }

            if let Some(hook) = context_formatters.get(report.current_context_type_id()) {
                return hook.preferred_context_formatting_style(report, report_formatting_function);
            }
        }
        report.preferred_context_formatting_style_unhooked(report_formatting_function)
    })
}