ppoppo_clock/

mock.rs

use crate::{Clock, Timer};
use futures::channel::oneshot;
use jiff::Timestamp;
use std::pin::Pin;
use std::sync::{Arc, Mutex, PoisonError};
use std::time::Duration;

// ── FrozenClock ────────────────────────────────────────────────────────────

/// A clock that always returns the same instant. ~80% of test scenarios.
#[derive(Debug)]
pub struct FrozenClock {
    instant: Timestamp,
}

impl FrozenClock {
    /// Parse an RFC 3339 string into a frozen instant. An unparseable string
    /// freezes at the Unix epoch — a test fixture, not an input boundary.
    pub fn at(rfc3339: &str) -> Self {
        let instant = rfc3339.parse().unwrap_or(Timestamp::UNIX_EPOCH);
        Self { instant }
    }

    /// Freeze at `instant`.
    pub fn at_instant(instant: Timestamp) -> Self {
        Self { instant }
    }
}

impl Clock for FrozenClock {
    fn now(&self) -> Timestamp {
        self.instant
    }
}

// ── MockClock ──────────────────────────────────────────────────────────────

type PendingSleeps = Vec<(Timestamp, oneshot::Sender<()>)>;

/// A settable, advanceable clock for time-travel tests.
#[derive(Debug)]
pub struct MockClock {
    inner: Arc<Mutex<Timestamp>>,
    pending: Arc<Mutex<PendingSleeps>>,
}

impl MockClock {
    /// A clock reading `start` until it is set or advanced.
    pub fn new(start: Timestamp) -> Self {
        Self {
            inner: Arc::new(Mutex::new(start)),
            pending: Arc::new(Mutex::new(Vec::new())),
        }
    }

    /// Jump to `instant` and wake every pending sleep whose deadline it
    /// reaches.
    pub fn set_now(&self, instant: Timestamp) {
        let mut guard = self.inner.lock().unwrap_or_else(PoisonError::into_inner);
        *guard = instant;
        drop(guard);
        self.fire_pending();
    }

    /// Move the clock forward by `dur` and wake every pending sleep whose
    /// deadline it reaches.
    pub fn advance_by(&self, dur: Duration) {
        let new_now = {
            let mut guard = self.inner.lock().unwrap_or_else(PoisonError::into_inner);
            *guard = guard.checked_add(dur).unwrap_or(*guard);
            *guard
        };
        self.fire_ready(new_now);
    }

    /// Advance time and fire all sleeps whose deadline has passed.
    /// Equivalent to `tokio::time::advance` for mock-aware code.
    pub fn advance_and_fire(&self, dur: Duration) {
        self.advance_by(dur);
    }

    fn current(&self) -> Timestamp {
        *self.inner.lock().unwrap_or_else(PoisonError::into_inner)
    }

    fn fire_pending(&self) {
        let now = self.current();
        self.fire_ready(now);
    }

    fn fire_ready(&self, now: Timestamp) {
        // Drain matching entries while holding the lock; drop lock before firing.
        // `partition` keeps registration order in both halves.
        let to_fire: PendingSleeps = {
            let mut pending = self.pending.lock().unwrap_or_else(PoisonError::into_inner);
            let (fired, remaining): (PendingSleeps, PendingSleeps) = std::mem::take(&mut *pending)
                .into_iter()
                .partition(|(wake_at, _)| *wake_at <= now);
            *pending = remaining;
            fired
        };
        for (_, sender) in to_fire {
            // ignore send errors — receiver may have been dropped
            let _ = sender.send(());
        }
    }

    pub(crate) fn register_sleep(&self, wake_at: Timestamp) -> oneshot::Receiver<()> {
        let (tx, rx) = oneshot::channel();
        let now = self.current();
        if wake_at <= now {
            // Already past — fire immediately.
            let _ = tx.send(());
        } else {
            let mut pending = self.pending.lock().unwrap_or_else(PoisonError::into_inner);
            pending.push((wake_at, tx));
        }
        rx
    }
}

impl Clock for MockClock {
    fn now(&self) -> Timestamp {
        self.current()
    }
}

// ── AdvanceableTimer ───────────────────────────────────────────────────────

/// A timer whose sleeps resolve only when `MockClock::advance_and_fire` is called.
/// Pair with `MockClock` for deterministic time-travel tests.
#[derive(Debug)]
pub struct AdvanceableTimer {
    clock: Arc<MockClock>,
}

impl AdvanceableTimer {
    /// A timer whose sleeps are deadlines on `clock`.
    pub fn new(clock: Arc<MockClock>) -> Self {
        Self { clock }
    }
}

impl Timer for AdvanceableTimer {
    fn sleep(&self, dur: Duration) -> Pin<Box<dyn Future<Output = ()> + Send>> {
        let now = self.clock.current();
        let wake_at = now.checked_add(dur).unwrap_or(now);
        let rx = self.clock.register_sleep(wake_at);
        Box::pin(async move {
            // Discard errors — if sender dropped, treat as woken up.
            let _ = rx.await;
        })
    }

    fn next_tick(&self) -> Pin<Box<dyn Future<Output = ()> + Send>> {
        Box::pin(futures::future::ready(()))
    }
}

// ── Test ergonomics helpers ────────────────────────────────────────────────

/// Returns an `Arc<dyn Clock>` frozen at the given RFC 3339 string.
pub fn frozen_at(rfc3339: &str) -> Arc<dyn Clock> {
    Arc::new(FrozenClock::at(rfc3339))
}

/// Returns a `(Arc<MockClock>, Arc<AdvanceableTimer>)` pair wired together.
pub fn mock_pair(start: Timestamp) -> (Arc<MockClock>, Arc<AdvanceableTimer>) {
    let clock = Arc::new(MockClock::new(start));
    let timer = Arc::new(AdvanceableTimer::new(Arc::clone(&clock)));
    (clock, timer)
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
    use super::*;

    fn t0() -> Timestamp {
        "2026-05-10T00:00:00Z".parse().expect("valid RFC 3339")
    }

    // ── FrozenClock tests ──────────────────────────────────────────────

    #[test]
    fn frozen_at_parses_rfc3339() {
        let clock = FrozenClock::at("2026-05-10T00:00:00Z");
        assert_eq!(clock.now(), t0());
    }

    #[test]
    fn frozen_clock_at_instant() {
        let clock = FrozenClock::at_instant(t0());
        assert_eq!(clock.now(), t0());
    }

    #[test]
    fn frozen_clock_never_advances() {
        let clock = FrozenClock::at_instant(t0());
        let a = clock.now();
        let b = clock.now();
        assert_eq!(a, b);
    }

    #[test]
    fn frozen_clock_unix_millis() {
        let clock = FrozenClock::at("1970-01-01T00:00:01Z");
        assert_eq!(clock.now_unix_millis(), 1_000);
    }

    #[test]
    fn frozen_at_helper_trait_dispatch() {
        let c: Arc<dyn Clock> = frozen_at("2026-05-10T00:00:00Z");
        assert_eq!(c.now(), t0());
    }

    // ── MockClock tests ────────────────────────────────────────────────

    #[test]
    fn mock_clock_starts_at_given_instant() {
        let clock = MockClock::new(t0());
        assert_eq!(clock.now(), t0());
    }

    #[test]
    fn mock_clock_advance_by_increases_time() {
        let clock = MockClock::new(t0());
        clock.advance_by(Duration::from_secs(1));
        assert_eq!(clock.now(), t0() + jiff::SignedDuration::from_secs(1));
    }

    #[test]
    fn mock_clock_set_now_updates_instant() {
        let clock = MockClock::new(t0());
        let new_now = t0() + jiff::SignedDuration::from_hours(5);
        clock.set_now(new_now);
        assert_eq!(clock.now(), new_now);
    }

    #[test]
    fn mock_clock_trait_dispatch() {
        let c: Arc<dyn Clock> = Arc::new(MockClock::new(t0()));
        assert_eq!(c.now(), t0());
    }

    // ── AdvanceableTimer tests ─────────────────────────────────────────

    #[tokio::test]
    async fn advanceable_timer_sleep_resolves_after_advance() {
        let (clock, timer) = mock_pair(t0());
        let sleep_fut = timer.sleep(Duration::from_secs(60));
        // Advance past the deadline in a concurrent task
        let clock2 = Arc::clone(&clock);
        tokio::spawn(async move {
            clock2.advance_and_fire(Duration::from_secs(60));
        })
        .await
        .ok();
        sleep_fut.await; // should complete
    }

    #[tokio::test]
    async fn advanceable_timer_partial_advance_fires_only_due_sleeps() {
        let (clock, timer) = mock_pair(t0());
        let sleep_30 = timer.sleep(Duration::from_secs(30));
        let sleep_60 = timer.sleep(Duration::from_secs(60));

        clock.advance_and_fire(Duration::from_secs(45));

        // 30s sleep should be done
        sleep_30.await;

        // 60s sleep should NOT yet be done — fire another advance
        clock.advance_and_fire(Duration::from_secs(15));
        sleep_60.await;
    }

    #[tokio::test]
    async fn advanceable_timer_next_tick_resolves_immediately() {
        let (_, timer) = mock_pair(t0());
        timer.next_tick().await;
    }

    #[test]
    fn mock_pair_helper_returns_linked_pair() {
        let (clock, timer) = mock_pair(t0());
        let _: Arc<MockClock> = clock;
        let _: Arc<AdvanceableTimer> = timer;
    }

    #[test]
    fn frozen_clock_send_sync() {
        fn assert_send_sync<T: Send + Sync>() {}
        assert_send_sync::<FrozenClock>();
    }

    #[test]
    fn mock_clock_send_sync() {
        fn assert_send_sync<T: Send + Sync>() {}
        assert_send_sync::<MockClock>();
        assert_send_sync::<AdvanceableTimer>();
    }
}