//! Shared-memory observation store.
//!
//! This module defines the [`Store`] trait plus its [`TrimPolicy`] and
//! [`StoreError`] types. Everything here is `#![no_std]`-clean and does **not**
//! require the `alloc` feature — only concrete backends (see
//! [`mem_store`](crate::mem_store)) need allocation, so the trait, policy, and
//! error types remain available on `no_std` targets as well.

use crate::observation::{Observation, ObservationId, Tick};

/// Ejection-policy knobs consumed by [`Store::trim`].
///
/// Rules are applied in the order listed here: per-topic retention, then a
/// global age cutoff, then a global count cap. Any field left as `None` is
/// ignored.
#[derive(Clone, Debug, Default)]
pub struct TrimPolicy {
    /// Keep the `N` youngest (lowest current age) observations per exact topic.
    pub keep_per_topic: Option<usize>,
    /// Drop any observation whose current age (in ms) exceeds this value.
    pub max_age_ms: Option<u64>,
    /// Drop the oldest observations until the total count is at most this value.
    pub max_count: Option<usize>,
}

/// Errors returned by [`Store`] operations.
#[derive(Debug, PartialEq, Eq)]
pub enum StoreError {
    /// The store is full and cannot accept new observations.
    Full,
    /// A backend-internal failure.
    Backend,
}

/// A content-addressed, age-aware collection of [`Observation`]s.
///
/// Identity is the content-derived [`ObservationId`]; two observations that
/// differ only in age or `observed_at` share an id and dedupe on insert. Ages
/// are reported as *current* ages, advanced by the elapsed ticks since each
/// observation was stored.
#[allow(clippy::len_without_is_empty)]
pub trait Store {
    /// Insert an observation.
    ///
    /// Returns `Ok(true)` if it was newly inserted, or `Ok(false)` if an
    /// observation with the same id already exists (in which case the existing
    /// entry — and its stored age lineage — is left untouched).
    fn insert(&mut self, obs: Observation, now: Tick) -> Result<bool, StoreError>;

    /// Returns `true` if an observation with `id` is currently stored.
    fn contains(&self, id: &ObservationId) -> bool;

    /// Returns the observation with `id`, with `age_ms` advanced by
    /// `now - stored_at` (saturating at 0 elapsed when `now < stored_at`).
    fn get(&self, id: &ObservationId, now: Tick) -> Option<Observation>;

    /// Number of observations currently stored.
    fn len(&self) -> usize;

    /// Visit every stored observation id.
    fn for_each_id(&self, f: &mut dyn FnMut(&ObservationId));

    /// Visit every stored observation whose topic starts with `prefix`
    /// (an empty prefix matches all), each age-adjusted to `now`.
    fn for_each_topic(&self, prefix: &[u8], now: Tick, f: &mut dyn FnMut(&Observation));

    /// Apply [`TrimPolicy`] rules in order (per-topic, age, count) and return
    /// the number of observations removed. Trimmed ids are not tombstoned:
    /// re-inserting them later is accepted.
    fn trim(&mut self, policy: &TrimPolicy, now: Tick) -> usize;
}

/// Current (age-adjusted) age of a stored observation at tick `now`.
#[inline]
#[cfg(feature = "alloc")]
pub(crate) fn current_age(obs: &Observation, stored_at: Tick, now: Tick) -> u64 {
    obs.age_ms.saturating_add(now.saturating_sub(stored_at))
}