yeti_types/schema/

store.rs

//! `@store` directive types.
//!
//! `@store` owns the storage-engine axis: durability tier, physical
//! volume, eviction window, compression. Replaces the older
//! `@table(storage:)` + `@table(expiration:)` args.
//!
//! The 4-tier `durability` knob is a single ordered scale —
//! `memory < lossy < soft < strong` — that maps directly to
//! `BackendType` + `RocksDB` WAL / sync flags. Single axis eliminates
//! invalid combinations the older two-axis design admitted (e.g.
//! `backend: "memory", durability: "strong"`).

use serde::{Deserialize, Serialize};

use crate::backend::BackendType;

/// Durability tier from `@store(durability:)`.
///
/// Monotonically increasing in cost and decreasing in crash-loss window.
/// See the design doc for the per-tier semantics and the
/// crash-loss windows.
// Variant order is durability-ascending (Memory < Lossy < Soft < Strong), so
// the derived `Ord` lets a database take the MAX tier across its tables — the
// RocksDB WAL is per-database, so one soft/strong table pulls the whole DB up.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub enum DurabilityTier {
    /// `"memory"` — `BackendType::InMemory`, nothing survives restart.
    Memory,
    /// `"lossy"` — `RocksDB` with WAL **disabled** (`disable_wal = true`).
    /// Survives clean restart; loses up to a memtable flush window
    /// (~minutes) on crash.
    Lossy,
    /// `"soft"` — `RocksDB` with WAL on, OS-controlled fsync
    /// (`sync_writes = false`). Survives crash; loses ~seconds on
    /// power-loss. `RocksDB` default.
    Soft,
    /// `"strong"` — `RocksDB` with WAL on + `WriteOptions::sync = true`
    /// (per-write fsync). Zero loss; full cost.
    Strong,
}

impl DurabilityTier {
    /// Parse a `@store(durability:)` string. Case-insensitive.
    #[must_use]
    pub fn parse(s: &str) -> Option<Self> {
        match s.to_ascii_lowercase().as_str() {
            "memory" => Some(Self::Memory),
            "lossy" => Some(Self::Lossy),
            "soft" => Some(Self::Soft),
            "strong" => Some(Self::Strong),
            _ => None,
        }
    }

    /// The `BackendType` this tier maps to.
    #[must_use]
    pub const fn backend_type(self) -> BackendType {
        match self {
            Self::Memory => BackendType::InMemory,
            Self::Lossy | Self::Soft | Self::Strong => BackendType::Disk,
        }
    }

    /// Whether this tier requires the WAL to be enabled at backend
    /// open time. `Memory` has nothing to write to; `Lossy` opts out;
    /// `Soft` + `Strong` need WAL on.
    #[must_use]
    pub const fn requires_wal(self) -> bool {
        match self {
            Self::Memory | Self::Lossy => false,
            Self::Soft | Self::Strong => true,
        }
    }

    /// Whether this tier requests per-write `fsync` via
    /// `WriteOptions::sync = true`. Only `Strong` does.
    #[must_use]
    pub const fn sync_writes(self) -> bool {
        matches!(self, Self::Strong)
    }
}

impl Default for DurabilityTier {
    /// Defaults to `Soft` — `RocksDB` on-disk, WAL on, no per-write
    /// fsync. Matches yeti's default for user-data
    /// tables (`BackendType::Disk` with WAL enabled).
    fn default() -> Self {
        Self::Soft
    }
}

/// Named data-retention class from `@store(class:)`.
///
/// A retention class is an operator-facing handle for a canonical
/// eviction window: rather than computing `evictAfter` in raw seconds, a
/// schema declares `@store(class: "hot")` and the loader resolves the
/// class to the seconds value that populates
/// [`StoreConfig::evict_after`]. From that point the existing TTL
/// machinery does the rest — the per-record [`expiration header`] and the
/// `yeti.expiration_filter` compaction filter reclaim aged records with
/// no class-specific reclaim code.
///
/// The canonical durations are fixed by this enum so a class means the
/// same window across every table and every deployment. A schema that
/// needs a non-canonical window keeps using raw `@store(evictAfter: N)`;
/// the two are mutually exclusive (declaring both is a schema error).
///
/// [`expiration header`]: crate::backend
// Variant order is window-ascending (Hot < Warm < AuditArchive) so the
// derived `Ord` sorts classes by retention length.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub enum RetentionClass {
    /// `"hot"` — 30 days. Operational data with a short useful life:
    /// recent events, session-scoped state, ephemeral caches that still
    /// want crash durability.
    Hot,
    /// `"warm"` — 90 days. Data kept for a quarter: rolling analytics
    /// windows, recent history surfaced in dashboards.
    Warm,
    /// `"audit-archive"` — 7 years (2557 days). Compliance-retained
    /// records: audit logs, financial records, anything under a
    /// multi-year statutory hold.
    AuditArchive,
}

impl RetentionClass {
    /// Seconds in one day.
    const SECS_PER_DAY: u64 = 86_400;

    /// Parse a `@store(class:)` string. Case-insensitive; the
    /// `audit-archive` class also accepts the `audit_archive` spelling so
    /// either separator works in a schema file.
    #[must_use]
    pub fn parse(s: &str) -> Option<Self> {
        match s.to_ascii_lowercase().as_str() {
            "hot" => Some(Self::Hot),
            "warm" => Some(Self::Warm),
            "audit-archive" | "audit_archive" => Some(Self::AuditArchive),
            _ => None,
        }
    }

    /// The canonical eviction window for this class, in seconds. This is
    /// the value routed into [`StoreConfig::evict_after`], so a
    /// class-tagged table flows through the identical TTL + compaction
    /// path as a raw `evictAfter`.
    #[must_use]
    pub const fn evict_after_secs(self) -> u64 {
        match self {
            // 30 days.
            Self::Hot => 30 * Self::SECS_PER_DAY,
            // 90 days.
            Self::Warm => 90 * Self::SECS_PER_DAY,
            // 7 years (365 * 7 = 2555, plus 2 leap days = 2557).
            Self::AuditArchive => 2557 * Self::SECS_PER_DAY,
        }
    }

    /// The canonical name as it appears in a schema directive.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Hot => "hot",
            Self::Warm => "warm",
            Self::AuditArchive => "audit-archive",
        }
    }
}

/// `@store` directive — storage-engine axis.
///
/// Bare `@store` (no args) inherits all defaults. Each field is
/// optional; omitted fields fall back to platform defaults.
#[derive(Debug, Clone, Default)]
pub struct StoreConfig {
    /// `@store(durability: ...)`. None = platform default
    /// (currently `Soft` for user data; `Strong` for system
    /// databases like `yeti-auth`, `yeti-queue`).
    pub durability: Option<DurabilityTier>,
    /// `@store(volume: ...)`. None = use the app's default volume.
    /// When set: if the value starts with `/` or contains `://`,
    /// treat as a literal path/URL; otherwise resolve through
    /// `yeti-config.yaml storage.volumes`. Reserved value
    /// `"adaptive"` is parsed but rejected at backend open until
    /// Ships adaptive-tier storage.
    pub volume: Option<String>,
    /// `@store(evictAfter: N)` — seconds before a record is evicted.
    /// Replaces the older `@table(expiration: N)` arg.
    ///
    /// When `@store(class:)` is set, the loader resolves the class to
    /// its canonical window (see [`RetentionClass::evict_after_secs`])
    /// and stores the result here, so every downstream consumer reads a
    /// single `evict_after` seconds value regardless of how the schema
    /// expressed retention. Declaring both `class` and a raw
    /// `evictAfter` is a schema error — the two are mutually exclusive.
    pub evict_after: Option<u64>,
    /// `@store(class: "hot|warm|audit-archive")` — the named retention
    /// class this table opted into, if any. Kept alongside the
    /// resolved [`Self::evict_after`] so tooling can report the operator's
    /// declared intent, not just the derived seconds.
    pub retention_class: Option<RetentionClass>,
    /// `@store(compression: bool)` — per-table override of the
    /// deployment-wide compression setting.
    pub compression: Option<bool>,
    /// `@store(flushIntervalMs: N)` — bounded crash-loss window in ms.
    /// Provides a fourth point on the durability scale
    /// between `lossy` (~minutes) and `soft` (~seconds): periodic
    /// `fsync()` of the WAL every N ms. Mutually exclusive with
    /// `durability: "strong"` (already fsync-per-write) and
    /// `durability: "lossy"` (no WAL to fsync). Runtime wiring to
    /// `RocksDB`'s `wal_bytes_per_sync` / background `SyncWAL` is
    /// deferred — this commit lands the directive surface so schemas
    /// can declare it.
    pub flush_interval_ms: Option<u64>,
}

#[cfg(test)]
mod tests {
    use super::{DurabilityTier, RetentionClass};

    #[test]
    fn retention_class_parse_is_case_insensitive() {
        assert_eq!(RetentionClass::parse("hot"), Some(RetentionClass::Hot));
        assert_eq!(RetentionClass::parse("HOT"), Some(RetentionClass::Hot));
        assert_eq!(RetentionClass::parse("Warm"), Some(RetentionClass::Warm));
        assert_eq!(
            RetentionClass::parse("audit-archive"),
            Some(RetentionClass::AuditArchive)
        );
        // Underscore spelling is an accepted alias.
        assert_eq!(
            RetentionClass::parse("AUDIT_ARCHIVE"),
            Some(RetentionClass::AuditArchive)
        );
        assert_eq!(RetentionClass::parse("frozen"), None);
        assert_eq!(RetentionClass::parse(""), None);
    }

    #[test]
    fn retention_class_canonical_windows() {
        // 30 days / 90 days / 7 years (2557 days incl. leap days).
        assert_eq!(RetentionClass::Hot.evict_after_secs(), 30 * 86_400);
        assert_eq!(RetentionClass::Warm.evict_after_secs(), 90 * 86_400);
        assert_eq!(
            RetentionClass::AuditArchive.evict_after_secs(),
            2557 * 86_400
        );
        // Windows are strictly ascending, matching the derived Ord.
        assert!(RetentionClass::Hot < RetentionClass::Warm);
        assert!(RetentionClass::Warm < RetentionClass::AuditArchive);
        assert!(RetentionClass::Hot.evict_after_secs() < RetentionClass::Warm.evict_after_secs());
        assert!(
            RetentionClass::Warm.evict_after_secs()
                < RetentionClass::AuditArchive.evict_after_secs()
        );
    }

    #[test]
    fn retention_class_as_str_round_trips_through_parse() {
        for class in [
            RetentionClass::Hot,
            RetentionClass::Warm,
            RetentionClass::AuditArchive,
        ] {
            assert_eq!(RetentionClass::parse(class.as_str()), Some(class));
        }
    }

    #[test]
    fn durability_default_is_soft() {
        // Guards against an accidental default change while we're in here.
        assert_eq!(DurabilityTier::default(), DurabilityTier::Soft);
    }
}