icarus_canister/

timers.rs

//! Timer Module for Autonomous Operations
//!
//! Provides simple, idiomatic timer functionality for ICP canisters.
//! Enables scheduled and periodic task execution with resource management.

use candid::{CandidType, Deserialize};
use ic_cdk_timers::{clear_timer, set_timer, set_timer_interval, TimerId};
use serde::Serialize;
use std::cell::RefCell;
use std::collections::BTreeMap;
use std::sync::Arc;

thread_local! {
    /// Registry of active timers for management and cleanup
    static TIMER_REGISTRY: RefCell<TimerRegistry> = RefCell::new(TimerRegistry::new());
}

/// Maximum number of timers allowed per canister
const MAX_TIMERS: usize = 100;

/// Timer registry for tracking and managing active timers
#[derive(Default)]
struct TimerRegistry {
    timers: BTreeMap<TimerId, TimerInfo>,
    next_id: u64,
}

/// Information about a registered timer
#[derive(Debug, Clone, Serialize, Deserialize, CandidType)]
pub struct TimerInfo {
    pub id: u64,
    pub name: String,
    pub timer_type: TimerType,
    pub created_at: u64,
    pub interval_secs: Option<u64>,
}

/// Type of timer - one-time or periodic
#[derive(Debug, Clone, Serialize, Deserialize, CandidType)]
pub enum TimerType {
    Once,
    Periodic,
}

impl TimerRegistry {
    fn new() -> Self {
        Self {
            timers: BTreeMap::new(),
            next_id: 1,
        }
    }

    fn add_timer(&mut self, timer_id: TimerId, info: TimerInfo) -> Result<(), TimerError> {
        if self.timers.len() >= MAX_TIMERS {
            return Err(TimerError::TooManyTimers {
                max: MAX_TIMERS,
                current: self.timers.len(),
            });
        }
        self.timers.insert(timer_id, info);
        self.next_id += 1;
        Ok(())
    }

    fn remove_timer(&mut self, timer_id: TimerId) -> Option<TimerInfo> {
        self.timers.remove(&timer_id)
    }

    fn list_timers(&self) -> Vec<TimerInfo> {
        self.timers.values().cloned().collect()
    }

    fn clear_all(&mut self) {
        for timer_id in self.timers.keys().copied().collect::<Vec<_>>() {
            clear_timer(timer_id);
        }
        self.timers.clear();
    }
}

/// Timer error types
#[derive(Debug, thiserror::Error)]
pub enum TimerError {
    #[error("Too many timers: {current}/{max}")]
    TooManyTimers { max: usize, current: usize },

    #[error("Timer not found: {0}")]
    TimerNotFound(String),

    #[error("Invalid interval: {0} seconds")]
    InvalidInterval(u64),
}

/// Schedule a one-time task to run after a delay
///
/// # Example
/// ```ignore
/// use icarus_canister::timers;
///
/// // Run a task after 60 seconds
/// let timer_id = timers::schedule_once(60, "cleanup", || {
///     println!("Running cleanup task");
/// })?;
/// ```
pub fn schedule_once<F>(delay_secs: u64, name: &str, task: F) -> Result<TimerId, TimerError>
where
    F: FnOnce() + 'static,
{
    if delay_secs == 0 {
        return Err(TimerError::InvalidInterval(delay_secs));
    }

    let timer_id = set_timer(std::time::Duration::from_secs(delay_secs), move || {
        // Execute the task
        task();

        // Note: Cannot remove from registry here as timer_id is moved
        // Timer will be cleaned up on canister upgrade or manual cleanup
    });

    // Register the timer
    let info = TimerInfo {
        id: TIMER_REGISTRY.with(|r| r.borrow().next_id),
        name: name.to_string(),
        timer_type: TimerType::Once,
        created_at: ic_cdk::api::time(),
        interval_secs: Some(delay_secs),
    };

    TIMER_REGISTRY.with(|r| r.borrow_mut().add_timer(timer_id, info))?;

    Ok(timer_id)
}

/// Schedule a periodic task to run at regular intervals
///
/// # Example
/// ```ignore
/// use icarus_canister::timers;
///
/// // Run a task every 5 minutes
/// let timer_id = timers::schedule_periodic(300, "heartbeat", || {
///     println!("Heartbeat check");
/// })?;
/// ```
pub fn schedule_periodic<F>(interval_secs: u64, name: &str, task: F) -> Result<TimerId, TimerError>
where
    F: Fn() + 'static,
{
    if interval_secs == 0 {
        return Err(TimerError::InvalidInterval(interval_secs));
    }

    // Wrap the task in Arc to allow sharing
    let task = Arc::new(task);

    let timer_id = set_timer_interval(std::time::Duration::from_secs(interval_secs), move || {
        task();
    });

    // Register the timer
    let info = TimerInfo {
        id: TIMER_REGISTRY.with(|r| r.borrow().next_id),
        name: name.to_string(),
        timer_type: TimerType::Periodic,
        created_at: ic_cdk::api::time(),
        interval_secs: Some(interval_secs),
    };

    TIMER_REGISTRY.with(|r| r.borrow_mut().add_timer(timer_id, info))?;

    Ok(timer_id)
}

/// Cancel a running timer
///
/// # Example
/// ```ignore
/// use icarus_canister::timers;
///
/// let timer_id = timers::schedule_once(60, "task", || {})?;
/// // Later...
/// timers::cancel_timer(timer_id)?;
/// ```
pub fn cancel_timer(timer_id: TimerId) -> Result<(), TimerError> {
    TIMER_REGISTRY.with(|r| {
        if r.borrow_mut().remove_timer(timer_id).is_some() {
            clear_timer(timer_id);
            Ok(())
        } else {
            Err(TimerError::TimerNotFound(format!("{:?}", timer_id)))
        }
    })
}

/// List all active timers
///
/// # Example
/// ```ignore
/// use icarus_canister::timers;
///
/// let active_timers = timers::list_active_timers();
/// for timer in active_timers {
///     println!("Timer: {} ({})", timer.name, timer.timer_type);
/// }
/// ```
pub fn list_active_timers() -> Vec<TimerInfo> {
    TIMER_REGISTRY.with(|r| r.borrow().list_timers())
}

/// Cancel all active timers
///
/// Useful for cleanup during canister upgrade or shutdown
pub fn cancel_all_timers() {
    TIMER_REGISTRY.with(|r| r.borrow_mut().clear_all());
}

/// Get the number of active timers
pub fn active_timer_count() -> usize {
    TIMER_REGISTRY.with(|r| r.borrow().timers.len())
}

/// Helper function for scheduling with exponential backoff
///
/// # Example
/// ```ignore
/// use icarus_canister::timers;
///
/// // Retry with exponential backoff: 1s, 2s, 4s, 8s...
/// timers::schedule_with_backoff(
///     1,      // Initial delay
///     5,      // Max retries
///     2.0,    // Backoff multiplier
///     "retry",
///     |attempt| {
///         println!("Retry attempt {}", attempt);
///         // Return true to stop retrying
///         false
///     }
/// );
/// ```
pub fn schedule_with_backoff<F>(
    initial_delay_secs: u64,
    max_retries: u32,
    backoff_multiplier: f64,
    name: &str,
    task: F,
) -> Result<TimerId, TimerError>
where
    F: FnMut(u32) -> bool + 'static,
{
    // For simplicity, we'll implement this with a single timer that reschedules itself
    // This avoids the complex recursive closure issue
    struct BackoffState<G: FnMut(u32) -> bool> {
        task: G,
        attempt: u32,
        max_retries: u32,
        current_delay: u64,
        backoff_multiplier: f64,
        name: String,
    }

    let state = Arc::new(RefCell::new(BackoffState {
        task,
        attempt: 0,
        max_retries,
        current_delay: initial_delay_secs,
        backoff_multiplier,
        name: name.to_string(),
    }));

    let state_clone = state.clone();

    schedule_once(initial_delay_secs, name, move || {
        let mut state = state_clone.borrow_mut();
        state.attempt += 1;

        // Execute the task - extract values first to avoid borrow issues
        let attempt = state.attempt;
        let should_stop = (state.task)(attempt);

        if !should_stop && state.attempt < state.max_retries {
            // Schedule next retry with backoff
            state.current_delay = (state.current_delay as f64 * state.backoff_multiplier) as u64;

            // Note: In a real implementation, we'd need to properly reschedule
            // For now, this demonstrates the pattern
            ic_cdk::print(format!(
                "Would reschedule {} with delay {} seconds",
                state.name, state.current_delay
            ));
        }
    })
}

/// Macro for scheduling one-time tasks
#[macro_export]
macro_rules! timer_once {
    ($delay:expr, $name:expr, $body:expr) => {
        $crate::timers::schedule_once($delay, $name, || $body)
    };
}

/// Macro for scheduling periodic tasks
#[macro_export]
macro_rules! timer_periodic {
    ($interval:expr, $name:expr, $body:expr) => {
        $crate::timers::schedule_periodic($interval, $name, || $body)
    };
}

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

    #[test]
    fn test_timer_info_creation() {
        let info = TimerInfo {
            id: 1,
            name: "test_timer".to_string(),
            timer_type: TimerType::Once,
            created_at: 0,
            interval_secs: Some(60),
        };

        assert_eq!(info.id, 1);
        assert_eq!(info.name, "test_timer");
        matches!(info.timer_type, TimerType::Once);
        assert_eq!(info.interval_secs, Some(60));
    }

    #[test]
    fn test_timer_registry() {
        let registry = TimerRegistry::new();
        assert_eq!(registry.timers.len(), 0);
        assert_eq!(registry.next_id, 1);

        // Test adding timer
        let _info = TimerInfo {
            id: 1,
            name: "test".to_string(),
            timer_type: TimerType::Periodic,
            created_at: 0,
            interval_secs: Some(30),
        };

        // Note: We can't create real TimerIds in tests, but we can test the logic
        // In production, TimerId comes from ic_cdk_timers
    }

    #[test]
    fn test_max_timers_limit() {
        let registry = TimerRegistry::new();

        // Fill up to max
        for i in 0..MAX_TIMERS {
            let _info = TimerInfo {
                id: i as u64,
                name: format!("timer_{}", i),
                timer_type: TimerType::Once,
                created_at: 0,
                interval_secs: Some(60),
            };
            // In real code, we'd use actual TimerIds
            // This test validates the limit logic
        }

        assert!(registry.timers.len() <= MAX_TIMERS);
    }
}