glitcher_api/

hooks.rs

//! Action System Hook Interface
//!
//! Provides extensible hook points for action execution events.
//!
//! ## Use Cases
//!
//! - **Recording/Replay**: Capture action events for session recording
//! - **MIDI Learning**: Map hardware controls to actions
//! - **Analytics**: Track action usage patterns
//! - **Debug Logging**: Trace action execution for debugging
//! - **Network Sync**: Synchronize actions across multiple instances (OSC/Artnet)
//! - **UI State**: Update undo/redo buffers, highlight active controls
//!
//! ## Usage
//!
//! ```rust,ignore
//! use glitcher_api::hooks::{ActionHook, BeforeActionEvent, AfterActionEvent};
//!
//! struct MyRecordingHook {
//!     events: Vec<RecordedEvent>,
//! }
//!
//! impl ActionHook for MyRecordingHook {
//!     fn before_action(&mut self, event: &BeforeActionEvent) {
//!         println!("About to execute: {}", event.action_name);
//!     }
//!
//!     fn after_action(&mut self, event: &AfterActionEvent) {
//!         if event.result.is_ok() {
//!             self.events.push(RecordedEvent {
//!                 timestamp_ms: event.timestamp_ms,
//!                 node_id: event.node_id,
//!                 action_name: event.action_name.clone(),
//!                 random_seed: event.random_seed,
//!             });
//!         }
//!     }
//! }
//! ```

use slotmap::KeyData;

// ============================================================================
// Recording Types (for RecordingHook implementation)
// ============================================================================

/// Recorded event for session recording/replay
///
/// This type is designed for action-based recording, where actions are
/// re-executed on replay with the same random seed for deterministic results.
///
/// ## Usage
///
/// ```rust,ignore
/// use glitcher_api::hooks::{RecordedEvent, ActionHook, AfterActionEvent};
///
/// struct RecordingHook {
///     events: Vec<RecordedEvent>,
/// }
///
/// impl ActionHook for RecordingHook {
///     fn after_action(&mut self, event: &AfterActionEvent) {
///         if event.result.is_ok() {
///             self.events.push(RecordedEvent::from_after_event(event));
///         }
///     }
/// }
/// ```
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct RecordedEvent {
    /// Timestamp in milliseconds since session start
    pub timestamp_ms: u64,

    /// Target node ID (stable KeyData for serialization)
    pub node_id: KeyData,

    /// Action name (e.g., "reset", "randomize")
    pub action_name: String,

    /// Random seed used (for deterministic replay)
    pub random_seed: u64,
}

impl RecordedEvent {
    /// Create a RecordedEvent from an AfterActionEvent
    pub fn from_after_event(event: &AfterActionEvent) -> Self {
        Self {
            timestamp_ms: event.timestamp_ms,
            node_id: event.node_id,
            action_name: event.action_name.clone(),
            random_seed: event.random_seed,
        }
    }
}

// ============================================================================
// Hook Event Types
// ============================================================================

/// Event fired before action execution
#[derive(Debug, Clone)]
pub struct BeforeActionEvent {
    /// Timestamp in milliseconds since session start
    pub timestamp_ms: u64,

    /// Target node ID (stable KeyData for serialization)
    pub node_id: KeyData,

    /// Action name (e.g., "reset", "randomize")
    pub action_name: String,

    /// Random seed for deterministic execution
    pub random_seed: u64,

    /// High-frequency execution hint
    pub is_high_frequency: bool,
}

/// Event fired after action execution
#[derive(Debug, Clone)]
pub struct AfterActionEvent {
    /// Timestamp in milliseconds since session start
    pub timestamp_ms: u64,

    /// Target node ID
    pub node_id: KeyData,

    /// Action name
    pub action_name: String,

    /// Random seed used
    pub random_seed: u64,

    /// Number of parameters updated
    pub update_count: usize,

    /// Execution result (Ok = success, Err = error message)
    pub result: Result<(), String>,
}

/// Hook interface for action execution events
///
/// Implement this trait to receive notifications about action execution.
/// Hooks are called in registration order.
///
/// ## Thread Safety
///
/// Hooks must be `Send` to support multi-threaded execution contexts.
/// If your hook needs to share state, use `Arc<Mutex<T>>` or channels.
pub trait ActionHook: Send {
    /// Called before action execution
    ///
    /// This hook is called before the action logic runs.
    /// Use this to:
    /// - Log action invocations
    /// - Prepare state for recording
    /// - Update UI state (mark button as active)
    ///
    /// Note: This hook cannot cancel action execution.
    fn before_action(&mut self, event: &BeforeActionEvent);

    /// Called after action execution
    ///
    /// This hook is called after the action completes (success or failure).
    /// Use this to:
    /// - Record action events
    /// - Update analytics
    /// - Send network sync messages
    /// - Update undo/redo buffers
    ///
    /// The `result` field indicates whether execution succeeded.
    fn after_action(&mut self, event: &AfterActionEvent);

    /// Optional: Hook name for debugging
    fn name(&self) -> &str {
        "AnonymousHook"
    }
}

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

    struct TestHook {
        before_count: usize,
        after_count: usize,
    }

    impl ActionHook for TestHook {
        fn before_action(&mut self, _event: &BeforeActionEvent) {
            self.before_count += 1;
        }

        fn after_action(&mut self, _event: &AfterActionEvent) {
            self.after_count += 1;
        }

        fn name(&self) -> &str {
            "TestHook"
        }
    }

    #[test]
    fn test_hook_trait_object() {
        let mut hook: Box<dyn ActionHook> = Box::new(TestHook {
            before_count: 0,
            after_count: 0,
        });

        let before_event = BeforeActionEvent {
            timestamp_ms: 1000,
            node_id: KeyData::from_ffi(0),
            action_name: "test".to_string(),
            random_seed: 42,
            is_high_frequency: false,
        };

        let after_event = AfterActionEvent {
            timestamp_ms: 1001,
            node_id: KeyData::from_ffi(0),
            action_name: "test".to_string(),
            random_seed: 42,
            update_count: 3,
            result: Ok(()),
        };

        hook.before_action(&before_event);
        hook.after_action(&after_event);

        // Type erasure works correctly
        assert_eq!(hook.name(), "TestHook");
    }

    #[test]
    fn test_multiple_hooks() {
        let mut hooks: Vec<Box<dyn ActionHook>> = vec![
            Box::new(TestHook {
                before_count: 0,
                after_count: 0,
            }),
            Box::new(TestHook {
                before_count: 0,
                after_count: 0,
            }),
        ];

        let before_event = BeforeActionEvent {
            timestamp_ms: 1000,
            node_id: KeyData::from_ffi(0),
            action_name: "test".to_string(),
            random_seed: 42,
            is_high_frequency: false,
        };

        // Call all hooks
        for hook in &mut hooks {
            hook.before_action(&before_event);
        }

        assert_eq!(hooks.len(), 2);
    }

    #[test]
    fn test_event_cloning() {
        let before = BeforeActionEvent {
            timestamp_ms: 1000,
            node_id: KeyData::from_ffi(0),
            action_name: "test".to_string(),
            random_seed: 42,
            is_high_frequency: false,
        };

        let cloned = before.clone();
        assert_eq!(cloned.timestamp_ms, before.timestamp_ms);
        assert_eq!(cloned.action_name, before.action_name);
    }

    #[test]
    fn test_after_event_result() {
        let success = AfterActionEvent {
            timestamp_ms: 1000,
            node_id: KeyData::from_ffi(0),
            action_name: "test".to_string(),
            random_seed: 42,
            update_count: 5,
            result: Ok(()),
        };

        assert!(success.result.is_ok());

        let failure = AfterActionEvent {
            timestamp_ms: 1000,
            node_id: KeyData::from_ffi(0),
            action_name: "test".to_string(),
            random_seed: 42,
            update_count: 0,
            result: Err("test error".to_string()),
        };

        assert!(failure.result.is_err());
    }
}