amethystate 0.20.1

use crate::store::{OpenStore, StorageResult};
use crate::{MigrationReport, Store, StoreBuilder};
use std::fmt;
use std::path::Path;
use std::sync::OnceLock;

/// The process-wide store.
///
/// Rust does not drop statics, so nothing here is closed on the way out: an
/// ordinary store writes what it has buffered from its `Drop`, and this one
/// never reaches one. [`shutdown`] is that step, said out loud.
static GLOBAL_STORE: OnceLock<Store> = OnceLock::new();

/// Closes the process-wide store when it goes out of scope.
///
/// A local is dropped and a static is not, which is the whole of why this
/// exists: held in `main`, it closes the store at the end of `main` - while the
/// logger, the threads and the allocator are all still up - rather than leaving
/// the last writes to a static that is never dropped.
///
/// [`GlobalStoreGuard::close`] is the door and the `Drop` is the net. Closing
/// by hand hands back what the last flush did, so a caller who can offer a
/// retry or save elsewhere gets the chance; letting it drop closes just the
/// same and logs a failure that nobody is left to act on.
///
/// Dropping it early closes the store early, and every read and write after
/// that answers [`StorageError::Closed`](crate::store::StorageError::Closed).
/// Binding it in `main` is what puts that at the end rather than in the middle.
#[must_use = "dropped here, the global store is closed here - bind it in `main` \
              (`let _ame = ...`) so the last writes are flushed on the way out"]
#[derive(Debug)]
pub struct GlobalStoreGuard {
    _private: (),
}

impl GlobalStoreGuard {
    /// Closes the process-wide store and hands back what the closing flush did.
    ///
    /// ```no_run
    /// fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let ame = amethystate::init_global("./app/settings");
    ///
    ///     // ...
    ///
    ///     ame.close()?;
    ///     Ok(())
    /// }
    /// ```
    #[allow(clippy::needless_doctest_main)]
    pub fn close(self) -> StorageResult<()> {
        let closing = shutdown();
        std::mem::forget(self);
        closing
    }
}

impl Drop for GlobalStoreGuard {
    fn drop(&mut self) {
        if let Err(report) = shutdown() {
            tracing::error!(
                target: "amethystate",
                error = ?report,
                "the global store's closing flush failed: what it still held is not on disk",
            );
        }
    }
}

pub trait IntoGlobalStore: Sized {
    fn into_store_builder(self) -> StoreBuilder;

    /// Opens the process-wide store, once, and hands back the guard that
    /// closes it.
    ///
    /// Runs the steps handed to the builder and no others.
    /// [`IntoGlobalStore::init_global_with_migration`] is the one that also picks
    /// up every `#[migrate]` step in the binary, and says what the pass did -
    /// the same split as
    /// [`build`](crate::StoreBuilder::build) and
    /// [`build_with_migration`](crate::StoreBuilder::build_with_migration).
    ///
    /// Panics when the store will not open or one is in place already;
    /// [`try_init_global`] answers both as an error.
    fn init_global(self) -> GlobalStoreGuard {
        try_init_global(self).unwrap_or_else(|why| {
            panic!("amethystate: the global store was not put in place: {why:?}")
        })
    }

    /// [`IntoGlobalStore::init_global`], with every `#[migrate]` step in the
    /// binary collected as well, and what the pass did.
    fn init_global_with_migration(self) -> (MigrationReport, GlobalStoreGuard) {
        try_init_global_with_migration(self).unwrap_or_else(|why| {
            panic!("amethystate: the global store was not put in place: {why:?}")
        })
    }
}

/// Why the process-wide store was not put in place.
pub enum InitGlobal {
    /// The store would not open. Nothing was installed.
    Open(OpenStore),

    /// A store is in place already, and no second one was opened.
    AlreadyInstalled,
}

impl fmt::Display for InitGlobal {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Open(_) => f.write_str("the global store would not open"),
            Self::AlreadyInstalled => f.write_str("a global store is in place already"),
        }
    }
}

impl fmt::Debug for InitGlobal {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Open(why) => write!(f, "{self}: {why:?}"),
            Self::AlreadyInstalled => fmt::Display::fmt(self, f),
        }
    }
}

impl std::error::Error for InitGlobal {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Open(why) => Some(why),
            Self::AlreadyInstalled => None,
        }
    }
}

/// A store handed to [`install_global`] while another was in place, handed
/// back untouched.
pub struct AlreadyInstalled {
    pub store: Store,
}

impl fmt::Display for AlreadyInstalled {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("a global store is in place already")
    }
}

impl fmt::Debug for AlreadyInstalled {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(self, f)
    }
}

impl std::error::Error for AlreadyInstalled {}

/// Puts a store that is already open in place as the process-wide one.
///
/// For a caller that opens the store itself - to answer a failed open as its
/// own error, or to hand the same store to something else first.
pub fn install_global(store: Store) -> Result<GlobalStoreGuard, AlreadyInstalled> {
    GLOBAL_STORE
        .set(store)
        .map_err(|store| AlreadyInstalled { store })?;

    Ok(GlobalStoreGuard { _private: () })
}

/// [`init_global`], answering a store that will not open, or one already in
/// place, as an error rather than a panic.
///
/// Nothing is opened when a store is in place already.
pub fn try_init_global<T: IntoGlobalStore>(source: T) -> Result<GlobalStoreGuard, InitGlobal> {
    if GLOBAL_STORE.get().is_some() {
        return Err(InitGlobal::AlreadyInstalled);
    }

    let store = source
        .into_store_builder()
        .build()
        .map_err(InitGlobal::Open)?;

    install_global(store).map_err(|_| InitGlobal::AlreadyInstalled)
}

/// [`init_global_with_migration`], answering a store that will not open, or
/// one already in place, as an error rather than a panic.
pub fn try_init_global_with_migration<T: IntoGlobalStore>(
    source: T,
) -> Result<(MigrationReport, GlobalStoreGuard), InitGlobal> {
    if GLOBAL_STORE.get().is_some() {
        return Err(InitGlobal::AlreadyInstalled);
    }

    let (store, report) = source
        .into_store_builder()
        .build_with_migration()
        .map_err(InitGlobal::Open)?;

    let guard = install_global(store).map_err(|_| InitGlobal::AlreadyInstalled)?;
    Ok((report, guard))
}

impl IntoGlobalStore for StoreBuilder {
    fn into_store_builder(self) -> StoreBuilder {
        self
    }
}

impl IntoGlobalStore for &str {
    fn into_store_builder(self) -> StoreBuilder {
        StoreBuilder::new(self)
    }
}

impl IntoGlobalStore for &Path {
    fn into_store_builder(self) -> StoreBuilder {
        StoreBuilder::new(self)
    }
}

/// Opens the process-wide store, once.
///
/// ```no_run
/// fn main() {
///     let _ame = amethystate::init_global("./app/settings");
///
///     // ...
/// }
/// ```
#[allow(clippy::needless_doctest_main)]
pub fn init_global<T: IntoGlobalStore>(source: T) -> GlobalStoreGuard {
    source.init_global()
}

/// [`init_global`], with every `#[migrate]` step in the binary collected as
/// well, and what the pass did.
pub fn init_global_with_migration<T: IntoGlobalStore>(
    source: T,
) -> (MigrationReport, GlobalStoreGuard) {
    source.init_global_with_migration()
}

/// The process-wide store.
///
/// Panics when nothing installed one. Every generated accessor on a struct
/// opened globally goes through here, so the panic is what a field read before
/// `init_global` looks like - and it says that rather than leaving a caller
/// with an unwrap on a `None`.
pub fn global_store() -> Store {
    GLOBAL_STORE
        .get()
        .expect(
            "amethystate: the global store is not initialized.\n\
             Call `init_global` or `init_global_with_migration` during startup, \
             and keep the guard it returns alive for as long as the store is used.",
        )
        .clone()
}

/// Closes the process-wide store: writes what it still holds, stops its
/// background thread and lets go of the file.
///
/// [`GlobalStoreGuard`] calls this and logs a failure; call it directly when
/// the failure is worth acting on - offering to retry, saving elsewhere, or
/// not exiting yet - since only a caller can do any of that.
///
/// Nothing else can stand in. A static is never dropped, so the close every
/// other store gets from `Drop` never runs here, and the thread would outlive
/// `main` for the same reason. Left out, everything written inside the last
/// debounce interval is lost on a clean return.
///
/// Afterwards the store answers every read and write with
/// [`StorageError::Closed`](crate::store::StorageError::Closed), so this
/// belongs where nothing follows it. Calling it twice is fine.
///
/// Does nothing, successfully, when no global store was ever initialised.
///
/// ```no_run
/// fn main() -> Result<(), Box<dyn std::error::Error>> {
///     let _ame = amethystate::init_global("./app/settings");
///
///     // ...
///
///     amethystate::shutdown()?;
///     Ok(())
/// }
/// ```
pub fn shutdown() -> StorageResult<()> {
    match GLOBAL_STORE.get() {
        Some(store) => Ok(store.close()?),
        None => Ok(()),
    }
}