// file: crates/ksp-store-lib/src/health.rs
// version: 1

/// Portable Store health state independent from the selected physical backend.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum StoreHealthState {
    /// The selected Store backend answered the bounded readiness probe and its migration foundation is current.
    Ready,
    /// The Store instance exists but its latest bounded readiness probe could not prove readiness.
    NotReady,
}

/// Safe synchronous Store runtime snapshot without performing backend I/O.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct StoreRuntimeSnapshot {
    backend_kind: crate::StoreBackendKind,
    network: ksp_store_api::RawNetworkId,
    pool_available: u32,
    pool_capacity: u32,
    pool_size: u32,
    pool_waiting: u32,
}

impl StoreRuntimeSnapshot {
    /// Creates one portable runtime projection from backend-owned safe counters.
    #[must_use]
    pub(crate) fn new(
        backend_kind: crate::StoreBackendKind,
        network: ksp_store_api::RawNetworkId,
        pool_capacity: u32,
        pool_size: u32,
        pool_available: u32,
        pool_waiting: u32,
    ) -> Self {
        return Self { backend_kind, network, pool_available, pool_capacity, pool_size, pool_waiting };
    }

    /// Returns the selected backend identity.
    #[must_use]
    pub const fn backend_kind(&self) -> crate::StoreBackendKind {
        return self.backend_kind;
    }

    /// Returns the one logical network bound to this Store instance.
    #[must_use]
    pub const fn network(&self) -> &ksp_store_api::RawNetworkId {
        return &self.network;
    }

    /// Returns the number of currently available pooled backend objects.
    #[must_use]
    pub const fn pool_available(&self) -> u32 {
        return self.pool_available;
    }

    /// Returns the configured maximum pooled backend object count.
    #[must_use]
    pub const fn pool_capacity(&self) -> u32 {
        return self.pool_capacity;
    }

    /// Returns the current pooled backend object count.
    #[must_use]
    pub const fn pool_size(&self) -> u32 {
        return self.pool_size;
    }

    /// Returns the number of tasks currently waiting for a pooled backend object.
    #[must_use]
    pub const fn pool_waiting(&self) -> u32 {
        return self.pool_waiting;
    }
}

/// Portable Store readiness projection containing only safe runtime and migration diagnostics.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct StoreHealthSnapshot {
    last_error_code: std::option::Option<ksp_store_api::ErrorCode>,
    migration_version: std::option::Option<u64>,
    pending_migration_count: u32,
    runtime: StoreRuntimeSnapshot,
    state: StoreHealthState,
}

impl StoreHealthSnapshot {
    /// Creates one safe health projection from already classified backend diagnostics.
    #[must_use]
    pub(crate) fn new(
        state: StoreHealthState,
        runtime: StoreRuntimeSnapshot,
        migration_version: std::option::Option<u64>,
        pending_migration_count: u32,
        last_error_code: std::option::Option<ksp_store_api::ErrorCode>,
    ) -> Self {
        return Self { last_error_code, migration_version, pending_migration_count, runtime, state };
    }

    /// Returns the latest safe error code when readiness could not be proven.
    #[must_use]
    pub const fn last_error_code(&self) -> std::option::Option<ksp_store_api::ErrorCode> {
        return self.last_error_code;
    }

    /// Returns the migration version observed by the readiness probe when available.
    #[must_use]
    pub const fn migration_version(&self) -> std::option::Option<u64> {
        return self.migration_version;
    }

    /// Returns the number of embedded migrations newer than the observed applied version.
    #[must_use]
    pub const fn pending_migration_count(&self) -> u32 {
        return self.pending_migration_count;
    }

    /// Returns the safe synchronous runtime projection captured for this health probe.
    #[must_use]
    pub const fn runtime(&self) -> &StoreRuntimeSnapshot {
        return &self.runtime;
    }

    /// Returns whether this probe proved the Store ready.
    #[must_use]
    pub const fn state(&self) -> StoreHealthState {
        return self.state;
    }
}

#[cfg(test)]
#[path = "../unit_tests/health.rs"]
mod tests;