rustrails_support/

callbacks.rs

use std::any::Any;
use std::fmt;

/// Result of executing a callback or wrapped action.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CallbackResult {
    /// Continue running the callback chain.
    Continue,
    /// Stop running the callback chain.
    Halt,
}

/// When in the lifecycle a callback runs.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CallbackKind {
    /// Runs before the wrapped action.
    Before,
    /// Runs after the wrapped action.
    After,
    /// Wraps the wrapped action and any inner around callbacks.
    Around,
}

/// A predicate used to decide whether a callback should fire.
pub type ConditionPredicate = Box<dyn Fn(&dyn Any) -> bool + Send + Sync + 'static>;

/// The continuation passed to around callbacks.
pub type AroundContinuation<'a, T> = Box<dyn FnOnce(&mut T) -> CallbackResult + 'a>;

/// The function signature for around callbacks.
pub type AroundFilter<T> = Box<
    dyn for<'a> Fn(&mut T, AroundContinuation<'a, T>) -> CallbackResult + Send + Sync + 'static,
>;

/// Conditions that control when a callback is eligible to run.
#[derive(Default)]
pub struct CallbackConditions {
    /// Optional allow-list of action names. When present, only listed actions match.
    pub only: Option<Vec<String>>,
    /// Optional deny-list of action names. When present, listed actions do not match.
    pub except: Option<Vec<String>>,
    /// Predicate that must return `true` for the callback to run.
    pub if_cond: Option<ConditionPredicate>,
    /// Predicate that must return `false` for the callback to run.
    pub unless_cond: Option<ConditionPredicate>,
}

impl fmt::Debug for CallbackConditions {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CallbackConditions")
            .field("only", &self.only)
            .field("except", &self.except)
            .field("if_cond", &self.if_cond.as_ref().map(|_| "<predicate>"))
            .field(
                "unless_cond",
                &self.unless_cond.as_ref().map(|_| "<predicate>"),
            )
            .finish()
    }
}

impl CallbackConditions {
    /// Creates an empty set of callback conditions.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Restricts the callback to the provided action names.
    #[must_use]
    pub fn only<I, S>(mut self, actions: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.only = Some(actions.into_iter().map(Into::into).collect());
        self
    }

    /// Prevents the callback from running for the provided action names.
    #[must_use]
    pub fn except<I, S>(mut self, actions: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.except = Some(actions.into_iter().map(Into::into).collect());
        self
    }

    /// Adds a predicate that must return `true` for the callback to run.
    #[must_use]
    pub fn if_cond<F>(mut self, predicate: F) -> Self
    where
        F: Fn(&dyn Any) -> bool + Send + Sync + 'static,
    {
        self.if_cond = Some(Box::new(predicate));
        self
    }

    /// Adds a predicate that must return `false` for the callback to run.
    #[must_use]
    pub fn unless_cond<F>(mut self, predicate: F) -> Self
    where
        F: Fn(&dyn Any) -> bool + Send + Sync + 'static,
    {
        self.unless_cond = Some(Box::new(predicate));
        self
    }

    fn matches(&self, target: &dyn Any, action_name: &str) -> bool {
        if let Some(only) = &self.only
            && !only.iter().any(|candidate| candidate == action_name)
        {
            return false;
        }

        if let Some(except) = &self.except
            && except.iter().any(|candidate| candidate == action_name)
        {
            return false;
        }

        if let Some(predicate) = &self.if_cond
            && !predicate(target)
        {
            return false;
        }

        if let Some(predicate) = &self.unless_cond
            && predicate(target)
        {
            return false;
        }

        true
    }
}

/// The executable body of a callback.
pub enum CallbackFilter<T: Send + Sync + 'static> {
    /// A standard before or after callback.
    Standard(Box<dyn Fn(&mut T) -> CallbackResult + Send + Sync + 'static>),
    /// An around callback that decides whether and when to call the continuation.
    Around(AroundFilter<T>),
}

impl<T: Send + Sync + 'static> fmt::Debug for CallbackFilter<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Standard(_) => f.write_str("Standard(<callback>)"),
            Self::Around(_) => f.write_str("Around(<callback>)"),
        }
    }
}

/// A single callback entry in a callback chain.
pub struct Callback<T: Send + Sync + 'static> {
    /// Stable callback name used for replacement and skipping.
    pub name: String,
    /// The lifecycle phase where this callback runs.
    pub kind: CallbackKind,
    /// The executable body for the callback.
    pub filter: CallbackFilter<T>,
    /// Conditions that control whether this callback runs.
    pub conditions: CallbackConditions,
}

impl<T: Send + Sync + 'static> fmt::Debug for Callback<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Callback")
            .field("name", &self.name)
            .field("kind", &self.kind)
            .field("filter", &self.filter)
            .field("conditions", &self.conditions)
            .finish()
    }
}

impl<T: Send + Sync + 'static> Callback<T> {
    /// Creates a before callback.
    #[must_use]
    pub fn before<N, F>(name: N, filter: F) -> Self
    where
        N: Into<String>,
        F: Fn(&mut T) -> CallbackResult + Send + Sync + 'static,
    {
        Self {
            name: name.into(),
            kind: CallbackKind::Before,
            filter: CallbackFilter::Standard(Box::new(filter)),
            conditions: CallbackConditions::default(),
        }
    }

    /// Creates an after callback.
    #[must_use]
    pub fn after<N, F>(name: N, filter: F) -> Self
    where
        N: Into<String>,
        F: Fn(&mut T) -> CallbackResult + Send + Sync + 'static,
    {
        Self {
            name: name.into(),
            kind: CallbackKind::After,
            filter: CallbackFilter::Standard(Box::new(filter)),
            conditions: CallbackConditions::default(),
        }
    }

    /// Creates an around callback.
    #[must_use]
    pub fn around<N, F>(name: N, filter: F) -> Self
    where
        N: Into<String>,
        F: for<'a> Fn(&mut T, AroundContinuation<'a, T>) -> CallbackResult + Send + Sync + 'static,
    {
        Self {
            name: name.into(),
            kind: CallbackKind::Around,
            filter: CallbackFilter::Around(Box::new(filter)),
            conditions: CallbackConditions::default(),
        }
    }

    /// Replaces the callback conditions.
    #[must_use]
    pub fn with_conditions(mut self, conditions: CallbackConditions) -> Self {
        self.conditions = conditions;
        self
    }
}

/// A named chain of callbacks for a lifecycle event.
pub struct CallbackChain<T: Send + Sync + 'static> {
    name: String,
    callbacks: Vec<Callback<T>>,
    run_after_on_halt: bool,
}

impl<T: Send + Sync + 'static> fmt::Debug for CallbackChain<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CallbackChain")
            .field("name", &self.name)
            .field("callbacks", &self.callbacks)
            .field("run_after_on_halt", &self.run_after_on_halt)
            .finish()
    }
}

impl<T: Send + Sync + 'static> CallbackChain<T> {
    /// Creates an empty callback chain for the given lifecycle name.
    #[must_use]
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            callbacks: Vec::new(),
            run_after_on_halt: true,
        }
    }

    /// Returns the chain name.
    #[must_use]
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Returns the number of registered callbacks.
    #[must_use]
    pub fn len(&self) -> usize {
        self.callbacks.len()
    }

    /// Returns `true` when the chain has no callbacks.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.callbacks.is_empty()
    }

    /// Controls whether after callbacks still run when the chain halts.
    pub fn set_run_after_on_halt(&mut self, run_after_on_halt: bool) {
        self.run_after_on_halt = run_after_on_halt;
    }

    /// Adds a callback to the chain, replacing any existing callback with the same name.
    pub fn add(&mut self, callback: Callback<T>) {
        self.callbacks
            .retain(|existing| existing.name != callback.name);
        self.callbacks.push(callback);
    }

    /// Removes every callback with the provided name.
    pub fn skip(&mut self, name: &str) {
        self.callbacks.retain(|callback| callback.name != name);
    }

    /// Clears the callback chain.
    pub fn reset(&mut self) {
        self.callbacks.clear();
    }

    /// Runs the callback chain without a custom action.
    pub fn run(&self, target: &mut T, action_name: &str) -> CallbackResult {
        self.run_with(target, action_name, |_| CallbackResult::Continue)
    }

    /// Runs the callback chain around the provided action.
    pub fn run_with<F>(&self, target: &mut T, action_name: &str, action: F) -> CallbackResult
    where
        F: FnOnce(&mut T) -> CallbackResult,
    {
        if self.callbacks.is_empty() {
            return action(target);
        }

        let target_any = &*target as &dyn Any;
        let applicable = self
            .callbacks
            .iter()
            .filter(|callback| callback.conditions.matches(target_any, action_name))
            .collect::<Vec<_>>();

        let mut result = CallbackResult::Continue;

        for callback in applicable
            .iter()
            .copied()
            .filter(|callback| callback.kind == CallbackKind::Before)
        {
            result = match &callback.filter {
                CallbackFilter::Standard(filter) => filter(target),
                CallbackFilter::Around(_) => CallbackResult::Continue,
            };

            if result == CallbackResult::Halt {
                break;
            }
        }

        if result != CallbackResult::Halt {
            let around = applicable
                .iter()
                .copied()
                .filter(|callback| callback.kind == CallbackKind::Around)
                .collect::<Vec<_>>();
            result = invoke_around(&around, target, Box::new(action));
        }

        if self.run_after_on_halt || result != CallbackResult::Halt {
            for callback in applicable
                .iter()
                .rev()
                .copied()
                .filter(|callback| callback.kind == CallbackKind::After)
            {
                if let CallbackFilter::Standard(filter) = &callback.filter {
                    let _ = filter(target);
                }
            }
        }

        result
    }
}

fn invoke_around<'a, T: Send + Sync + 'static>(
    around_callbacks: &'a [&'a Callback<T>],
    target: &mut T,
    action: AroundContinuation<'a, T>,
) -> CallbackResult {
    match around_callbacks.split_first() {
        Some((callback, rest)) => match &callback.filter {
            CallbackFilter::Around(filter) => filter(
                target,
                Box::new(move |target| invoke_around(rest, target, action)),
            ),
            CallbackFilter::Standard(_) => invoke_around(rest, target, action),
        },
        None => action(target),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::any::Any;

    #[derive(Default)]
    struct Recorder {
        log: Vec<&'static str>,
        allow: bool,
        block: bool,
        action_ran: bool,
    }

    impl Recorder {
        fn push(&mut self, entry: &'static str) {
            self.log.push(entry);
        }
    }

    fn allow_predicate(target: &dyn Any) -> bool {
        target
            .downcast_ref::<Recorder>()
            .map(|recorder| recorder.allow)
            .unwrap_or(false)
    }

    fn block_predicate(target: &dyn Any) -> bool {
        target
            .downcast_ref::<Recorder>()
            .map(|recorder| recorder.block)
            .unwrap_or(false)
    }

    #[test]
    fn test_empty_chain_returns_continue() {
        let chain = CallbackChain::<Recorder>::new("save");
        let mut recorder = Recorder::default();

        let result = chain.run(&mut recorder, "save");

        assert_eq!(result, CallbackResult::Continue);
        assert!(recorder.log.is_empty());
    }

    #[test]
    fn test_before_callback_runs() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("audit", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        let result = chain.run(&mut recorder, "save");

        assert_eq!(result, CallbackResult::Continue);
        assert_eq!(recorder.log, vec!["before"]);
    }

    #[test]
    fn test_before_callback_halts_chain() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("halt", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Halt
        }));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            record.action_ran = true;
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Halt);
        assert_eq!(recorder.log, vec!["before"]);
        assert!(!recorder.action_ran);
    }

    #[test]
    fn test_halting_before_prevents_subsequent_before_callbacks() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("first", |record: &mut Recorder| {
            record.push("first");
            CallbackResult::Halt
        }));
        chain.add(Callback::before("second", |record: &mut Recorder| {
            record.push("second");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        let result = chain.run(&mut recorder, "save");

        assert_eq!(result, CallbackResult::Halt);
        assert_eq!(recorder.log, vec!["first"]);
    }

    #[test]
    fn test_after_callbacks_run_in_reverse_order() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::after("first", |record: &mut Recorder| {
            record.push("after-first");
            CallbackResult::Continue
        }));
        chain.add(Callback::after("second", |record: &mut Recorder| {
            record.push("after-second");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            record.action_ran = true;
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Continue);
        assert_eq!(recorder.log, vec!["action", "after-second", "after-first"]);
    }

    #[test]
    fn test_after_callbacks_ignore_their_own_halt_result() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::after("first", |record: &mut Recorder| {
            record.push("after-first");
            CallbackResult::Halt
        }));
        chain.add(Callback::after("second", |record: &mut Recorder| {
            record.push("after-second");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        let result = chain.run(&mut recorder, "save");

        assert_eq!(result, CallbackResult::Continue);
        assert_eq!(recorder.log, vec!["after-second", "after-first"]);
    }

    #[test]
    fn test_around_callback_wraps_action() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::around(
            "wrapper",
            |record: &mut Recorder, next| {
                record.push("around-before");
                let result = next(record);
                record.push("around-after");
                result
            },
        ));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            record.action_ran = true;
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Continue);
        assert_eq!(
            recorder.log,
            vec!["around-before", "action", "around-after"]
        );
        assert!(recorder.action_ran);
    }

    #[test]
    fn test_multiple_around_callbacks_nest_in_order() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::around("outer", |record: &mut Recorder, next| {
            record.push("outer-before");
            let result = next(record);
            record.push("outer-after");
            result
        }));
        chain.add(Callback::around("inner", |record: &mut Recorder, next| {
            record.push("inner-before");
            let result = next(record);
            record.push("inner-after");
            result
        }));
        let mut recorder = Recorder::default();

        chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Continue
        });

        assert_eq!(
            recorder.log,
            vec![
                "outer-before",
                "inner-before",
                "action",
                "inner-after",
                "outer-after"
            ]
        );
    }

    #[test]
    fn test_around_callback_can_prevent_inner_execution() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::around(
            "stopper",
            |record: &mut Recorder, _next| {
                record.push("around-before");
                CallbackResult::Halt
            },
        ));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            record.action_ran = true;
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Halt);
        assert_eq!(recorder.log, vec!["around-before"]);
        assert!(!recorder.action_ran);
    }

    #[test]
    fn test_multiple_callbacks_execute_in_order() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("one", |record: &mut Recorder| {
            record.push("before-one");
            CallbackResult::Continue
        }));
        chain.add(Callback::before("two", |record: &mut Recorder| {
            record.push("before-two");
            CallbackResult::Continue
        }));
        chain.add(Callback::after("three", |record: &mut Recorder| {
            record.push("after-one");
            CallbackResult::Continue
        }));
        chain.add(Callback::after("four", |record: &mut Recorder| {
            record.push("after-two");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Continue
        });

        assert_eq!(
            recorder.log,
            vec![
                "before-one",
                "before-two",
                "action",
                "after-two",
                "after-one"
            ]
        );
    }

    #[test]
    fn test_mixed_kinds_execute_in_expected_order() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("before", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Continue
        }));
        chain.add(Callback::around("around", |record: &mut Recorder, next| {
            record.push("around-before");
            let result = next(record);
            record.push("around-after");
            result
        }));
        chain.add(Callback::after("after", |record: &mut Recorder| {
            record.push("after");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Continue);
        assert_eq!(
            recorder.log,
            vec!["before", "around-before", "action", "around-after", "after"]
        );
    }

    #[test]
    fn test_only_condition_matches_listed_action() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::default().only(["save"])),
        );
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert_eq!(recorder.log, vec!["before"]);
    }

    #[test]
    fn test_only_condition_skips_unlisted_action() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::default().only(["create"])),
        );
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert!(recorder.log.is_empty());
    }

    #[test]
    fn test_only_empty_list_skips_callback() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::default().only(Vec::<&str>::new())),
        );
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert!(recorder.log.is_empty());
    }

    #[test]
    fn test_except_condition_skips_listed_action() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::default().except(["save"])),
        );
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert!(recorder.log.is_empty());
    }

    #[test]
    fn test_except_condition_allows_unlisted_action() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::default().except(["destroy"])),
        );
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert_eq!(recorder.log, vec!["before"]);
    }

    #[test]
    fn test_except_empty_list_allows_callback() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::default().except(Vec::<&str>::new())),
        );
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert_eq!(recorder.log, vec!["before"]);
    }

    #[test]
    fn test_if_condition_true_runs_callback() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::default().if_cond(allow_predicate)),
        );
        let mut recorder = Recorder {
            allow: true,
            ..Recorder::default()
        };

        chain.run(&mut recorder, "save");

        assert_eq!(recorder.log, vec!["before"]);
    }

    #[test]
    fn test_if_condition_false_skips_callback() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::default().if_cond(allow_predicate)),
        );
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert!(recorder.log.is_empty());
    }

    #[test]
    fn test_unless_condition_true_skips_callback() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::default().unless_cond(block_predicate)),
        );
        let mut recorder = Recorder {
            block: true,
            ..Recorder::default()
        };

        chain.run(&mut recorder, "save");

        assert!(recorder.log.is_empty());
    }

    #[test]
    fn test_unless_condition_false_runs_callback() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::default().unless_cond(block_predicate)),
        );
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert_eq!(recorder.log, vec!["before"]);
    }

    #[test]
    fn test_combined_conditions_require_all_checks_to_pass() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(
                CallbackConditions::default()
                    .only(["save"])
                    .if_cond(allow_predicate)
                    .unless_cond(block_predicate),
            ),
        );
        let mut allowed = Recorder {
            allow: true,
            block: false,
            ..Recorder::default()
        };
        let mut blocked = Recorder {
            allow: true,
            block: true,
            ..Recorder::default()
        };

        chain.run(&mut allowed, "save");
        chain.run(&mut blocked, "save");

        assert_eq!(allowed.log, vec!["before"]);
        assert!(blocked.log.is_empty());
    }

    #[test]
    fn test_skip_callback_removes_named_callback() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("audit", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Continue
        }));
        chain.skip("audit");
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert!(recorder.log.is_empty());
    }

    #[test]
    fn test_skip_missing_callback_is_a_noop() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("audit", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Continue
        }));
        chain.skip("missing");
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert_eq!(recorder.log, vec!["before"]);
    }

    #[test]
    fn test_reset_callbacks_clears_chain() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("audit", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Continue
        }));
        chain.reset();
        let mut recorder = Recorder::default();

        let result = chain.run(&mut recorder, "save");

        assert_eq!(result, CallbackResult::Continue);
        assert!(recorder.log.is_empty());
    }

    #[test]
    fn test_callbacks_with_same_name_replace_existing_callback() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("audit", |record: &mut Recorder| {
            record.push("first");
            CallbackResult::Continue
        }));
        chain.add(Callback::before("audit", |record: &mut Recorder| {
            record.push("second");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert_eq!(recorder.log, vec!["second"]);
    }

    #[test]
    fn test_after_callbacks_run_when_before_halts_by_default() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("halt", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Halt
        }));
        chain.add(Callback::after("cleanup", |record: &mut Recorder| {
            record.push("after");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Halt);
        assert_eq!(recorder.log, vec!["before", "after"]);
    }

    #[test]
    fn test_configured_chain_can_skip_after_callbacks_when_halted() {
        let mut chain = CallbackChain::new("save");
        chain.set_run_after_on_halt(false);
        chain.add(Callback::before("halt", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Halt
        }));
        chain.add(Callback::after("cleanup", |record: &mut Recorder| {
            record.push("after");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Halt);
        assert_eq!(recorder.log, vec!["before"]);
    }

    #[test]
    fn test_run_with_propagates_action_result() {
        let chain = CallbackChain::<Recorder>::new("save");
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Halt
        });

        assert_eq!(result, CallbackResult::Halt);
        assert_eq!(recorder.log, vec!["action"]);
    }

    #[test]
    fn test_around_callback_can_return_continue_without_running_inner_action() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::around("skip", |record: &mut Recorder, _next| {
            record.push("around-only");
            CallbackResult::Continue
        }));
        chain.add(Callback::after("cleanup", |record: &mut Recorder| {
            record.push("after");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            record.action_ran = true;
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Continue);
        assert_eq!(recorder.log, vec!["around-only", "after"]);
        assert!(!recorder.action_ran);
    }
    use std::sync::{
        Arc,
        atomic::{AtomicUsize, Ordering},
    };

    #[test]
    fn test_chain_metadata_reports_name_and_empty_state() {
        let chain = CallbackChain::<Recorder>::new("save");

        assert_eq!(chain.name(), "save");
        assert_eq!(chain.len(), 0);
        assert!(chain.is_empty());
    }

    #[test]
    fn test_adding_callback_updates_length_and_empty_state() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("audit", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Continue
        }));

        assert_eq!(chain.len(), 1);
        assert!(!chain.is_empty());
    }

    #[test]
    fn test_skip_removes_named_around_callback() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::around(
            "wrapper",
            |record: &mut Recorder, next| {
                record.push("around-before");
                let result = next(record);
                record.push("around-after");
                result
            },
        ));
        chain.skip("wrapper");
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Continue);
        assert_eq!(recorder.log, vec!["action"]);
    }

    #[test]
    fn test_skip_preserves_order_of_remaining_callbacks() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("first", |record: &mut Recorder| {
            record.push("first");
            CallbackResult::Continue
        }));
        chain.add(Callback::before("skip", |record: &mut Recorder| {
            record.push("skip");
            CallbackResult::Continue
        }));
        chain.add(Callback::before("third", |record: &mut Recorder| {
            record.push("third");
            CallbackResult::Continue
        }));
        chain.skip("skip");
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert_eq!(recorder.log, vec!["first", "third"]);
    }

    #[test]
    fn test_reset_clears_all_callback_kinds_and_length() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("before", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Continue
        }));
        chain.add(Callback::around("around", |record: &mut Recorder, next| {
            record.push("around-before");
            let result = next(record);
            record.push("around-after");
            result
        }));
        chain.add(Callback::after("after", |record: &mut Recorder| {
            record.push("after");
            CallbackResult::Continue
        }));

        assert_eq!(chain.len(), 3);
        chain.reset();

        let mut recorder = Recorder::default();
        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Continue);
        assert_eq!(chain.len(), 0);
        assert!(chain.is_empty());
        assert_eq!(recorder.log, vec!["action"]);
    }

    #[test]
    fn test_only_condition_matches_any_listed_action() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::new().only(["create", "save"])),
        );

        let mut save_recorder = Recorder::default();
        let mut create_recorder = Recorder::default();

        chain.run(&mut save_recorder, "save");
        chain.run(&mut create_recorder, "create");

        assert_eq!(save_recorder.log, vec!["before"]);
        assert_eq!(create_recorder.log, vec!["before"]);
    }

    #[test]
    fn test_except_condition_skips_each_listed_action() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::new().except(["create", "destroy"])),
        );

        let mut create_recorder = Recorder::default();
        let mut destroy_recorder = Recorder::default();
        let mut save_recorder = Recorder::default();

        chain.run(&mut create_recorder, "create");
        chain.run(&mut destroy_recorder, "destroy");
        chain.run(&mut save_recorder, "save");

        assert!(create_recorder.log.is_empty());
        assert!(destroy_recorder.log.is_empty());
        assert_eq!(save_recorder.log, vec!["before"]);
    }

    #[test]
    fn test_if_and_unless_conditions_must_both_allow_execution() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(
                CallbackConditions::new()
                    .if_cond(allow_predicate)
                    .unless_cond(block_predicate),
            ),
        );

        let mut allowed = Recorder {
            allow: true,
            block: false,
            ..Recorder::default()
        };
        let mut blocked = Recorder {
            allow: true,
            block: true,
            ..Recorder::default()
        };
        let mut disallowed = Recorder {
            allow: false,
            block: false,
            ..Recorder::default()
        };

        chain.run(&mut allowed, "save");
        chain.run(&mut blocked, "save");
        chain.run(&mut disallowed, "save");

        assert_eq!(allowed.log, vec!["before"]);
        assert!(blocked.log.is_empty());
        assert!(disallowed.log.is_empty());
    }

    #[test]
    fn test_before_halt_skips_around_callbacks_and_action() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("halt", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Halt
        }));
        chain.add(Callback::around(
            "wrapper",
            |record: &mut Recorder, next| {
                record.push("around-before");
                let result = next(record);
                record.push("around-after");
                result
            },
        ));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            record.action_ran = true;
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Halt);
        assert_eq!(recorder.log, vec!["before"]);
        assert!(!recorder.action_ran);
    }

    #[test]
    fn test_around_halt_runs_after_callbacks_by_default() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::around("halt", |record: &mut Recorder, _next| {
            record.push("around-before");
            CallbackResult::Halt
        }));
        chain.add(Callback::after("cleanup", |record: &mut Recorder| {
            record.push("after");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Halt);
        assert_eq!(recorder.log, vec!["around-before", "after"]);
    }

    #[test]
    fn test_around_halt_can_skip_after_callbacks_when_configured() {
        let mut chain = CallbackChain::new("save");
        chain.set_run_after_on_halt(false);
        chain.add(Callback::around("halt", |record: &mut Recorder, _next| {
            record.push("around-before");
            CallbackResult::Halt
        }));
        chain.add(Callback::after("cleanup", |record: &mut Recorder| {
            record.push("after");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Halt);
        assert_eq!(recorder.log, vec!["around-before"]);
    }

    #[test]
    fn test_replacing_callback_with_different_kind_moves_execution_phase() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("audit", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Continue
        }));
        chain.add(Callback::after("audit", |record: &mut Recorder| {
            record.push("after");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Continue);
        assert_eq!(chain.len(), 1);
        assert_eq!(recorder.log, vec!["action", "after"]);
    }

    #[test]
    fn test_callback_closure_can_capture_environment() {
        let counter = Arc::new(AtomicUsize::new(0));
        let captured = Arc::clone(&counter);
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("audit", move |record: &mut Recorder| {
            captured.fetch_add(1, Ordering::SeqCst);
            record.push("before");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        chain.run(&mut recorder, "save");

        assert_eq!(counter.load(Ordering::SeqCst), 1);
        assert_eq!(recorder.log, vec!["before"]);
    }

    #[test]
    fn test_nested_around_callbacks_propagate_halt_outward() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::around("outer", |record: &mut Recorder, next| {
            record.push("outer-before");
            let result = next(record);
            record.push("outer-after");
            result
        }));
        chain.add(Callback::around("inner", |record: &mut Recorder, _next| {
            record.push("inner-before");
            CallbackResult::Halt
        }));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Halt);
        assert_eq!(
            recorder.log,
            vec!["outer-before", "inner-before", "outer-after"]
        );
    }

    #[test]
    fn test_filtered_callbacks_still_run_action() {
        let mut chain = CallbackChain::new("save");
        chain.add(
            Callback::before("audit", |record: &mut Recorder| {
                record.push("before");
                CallbackResult::Continue
            })
            .with_conditions(CallbackConditions::new().only(["create"])),
        );
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            record.action_ran = true;
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Continue);
        assert_eq!(recorder.log, vec!["action"]);
        assert!(recorder.action_ran);
    }

    #[test]
    fn test_reset_then_readd_callback_uses_new_chain_contents() {
        let mut chain = CallbackChain::new("save");
        chain.add(Callback::before("before", |record: &mut Recorder| {
            record.push("before");
            CallbackResult::Continue
        }));
        chain.reset();
        chain.add(Callback::after("after", |record: &mut Recorder| {
            record.push("after");
            CallbackResult::Continue
        }));
        let mut recorder = Recorder::default();

        let result = chain.run_with(&mut recorder, "save", |record| {
            record.push("action");
            CallbackResult::Continue
        });

        assert_eq!(result, CallbackResult::Continue);
        assert_eq!(chain.len(), 1);
        assert_eq!(recorder.log, vec!["action", "after"]);
    }
}