aion-store 0.25.0

//! `TimerEntry` and timer-facing types.

use aion_core::{TimerId, WorkflowId};
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

/// Durable timer record returned by [`crate::ReadableEventStore::expired_timers`].
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, Hash)]
pub struct TimerEntry {
    /// Workflow that owns the timer.
    pub workflow_id: WorkflowId,
    /// Timer identifier within the owning workflow.
    pub timer_id: TimerId,
    /// Instant at which the timer is due to fire.
    pub fire_at: DateTime<Utc>,
    /// The workflow-history sequence of the `TimerStarted` event that armed
    /// this row, or `0` for an arming that records no `TimerStarted` (the
    /// schedule coordinator's trigger timers — sequence numbers start at 1,
    /// so `0` can never collide with a recorded arming).
    ///
    /// This is the row-identity component that makes value-conditional
    /// retirement discriminate a RE-ARM TO THE IDENTICAL INSTANT: without it,
    /// a named timer re-armed to the same `fire_at` encodes byte-identically
    /// to the consumed arming, so a stale retirement deletes the live
    /// replacement's row — and a past-due replacement is never re-armed by
    /// the boot sweep (which only restores future armings), a permanently
    /// lost wake. Every re-arm records a new `TimerStarted` with a strictly
    /// higher sequence, so `(fire_at, armed_seq)` is unique per arming. The
    /// store treats the value as an opaque identity component: it never
    /// orders or interprets it.
    pub armed_seq: u64,
}

/// The outcome of a value-conditional
/// [`retire_timer`](crate::ReadableEventStore::retire_timer) call.
///
/// Both variants are success — the distinction exists so callers (the boot
/// sweep's counters in particular) can report what actually happened to the
/// row instead of counting attempts as retirements.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TimerRetirement {
    /// The key no longer holds the retired arming's row: it was deleted by
    /// this call, or was already gone (never scheduled, or retired earlier —
    /// the idempotent shape). A distributed backend reports an absent key as
    /// `Retired` too: its tombstone lands unconditionally on an empty key.
    Retired,
    /// A DIFFERENT arming now owns the key (same timer name, new
    /// `(fire_at, armed_seq)` identity — possibly the SAME instant re-armed
    /// under a newer `TimerStarted`). The replacement's row was left
    /// untouched — it is the re-armed timer's only durable claim to a
    /// recovery fire.
    Superseded,
}