wowlab_engine_adapter_data/remote/cache/

error.rs

use std::{fmt, sync::Arc};

use wowlab_fs::{
    error,
    path::{Path, PathBuf},
};
use wowlab_supabase::SupabaseError;

/// Operation that failed while loading or maintaining game-data cache state.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum CacheOperation {
    CreateDirectory,
    ReadEntry,
    WriteEntry,
    CommitEntry,
    DeleteEntry,
    ClearCategory,
    ReadPatchVersion,
    WritePatchVersion,
    FetchRemote,
    LoadShared,
}

impl fmt::Display for CacheOperation {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(match self {
            Self::CreateDirectory => "create cache directory",
            Self::ReadEntry => "read cache entry",
            Self::WriteEntry => "write cache entry",
            Self::CommitEntry => "commit cache entry",
            Self::DeleteEntry => "delete cache entry",
            Self::ClearCategory => "clear cache category",
            Self::ReadPatchVersion => "read patch version",
            Self::WritePatchVersion => "write patch version",
            Self::FetchRemote => "fetch remote data",
            Self::LoadShared => "load shared cache value",
        })
    }
}

wowlab_engine_macros::define_error! {
/// Failure while loading or maintaining the patch-versioned game-data cache.
#[non_exhaustive]
pub struct CacheError {
    #[source]
    kind: CacheErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum CacheErrorKind {
    #[error(
        "cache {operation} failed{entry}: {source}",
        entry = CacheEntryLocation::new(entry_key.as_deref())
    )]
    Filesystem {
        operation: CacheOperation,
        entry_key: Option<String>,
        #[source]
        source: error::Error,
    },
    #[error(
        "cache {operation} failed{location}: {source}",
        location = CacheFailureLocation::new(path, entry_key.as_deref())
    )]
    Json {
        operation: CacheOperation,
        path: PathBuf,
        entry_key: Option<String>,
        #[source]
        source: serde_json::Error,
    },
    #[error("cache {operation} failed for {entry_key}: {source}")]
    Remote {
        operation: CacheOperation,
        entry_key: String,
        #[source]
        source: SupabaseError,
    },
    #[error("Not found: {resource} with {key}={value}")]
    MissingRow {
        resource: String,
        key: String,
        value: String,
    },
    #[error("cache {operation} failed for {entry_key}: {source}")]
    Shared {
        operation: CacheOperation,
        entry_key: String,
        #[source]
        source: Arc<CacheError>,
    },
}
}

struct CacheFailureLocation<'a> {
    path: &'a Path,
    entry_key: Option<&'a str>,
}

impl<'a> CacheFailureLocation<'a> {
    const fn new(path: &'a Path, entry_key: Option<&'a str>) -> Self {
        Self { path, entry_key }
    }
}

impl fmt::Display for CacheFailureLocation<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if let Some(entry_key) = self.entry_key {
            write!(f, " for {entry_key} at {}", self.path.display())
        } else {
            write!(f, " at {}", self.path.display())
        }
    }
}

struct CacheEntryLocation<'a>(Option<&'a str>);

impl<'a> CacheEntryLocation<'a> {
    const fn new(entry_key: Option<&'a str>) -> Self {
        Self(entry_key)
    }
}

impl fmt::Display for CacheEntryLocation<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.0 {
            Some(entry_key) => write!(f, " for {entry_key}"),
            None => Ok(()),
        }
    }
}

impl CacheError {
    pub(super) fn filesystem(
        operation: CacheOperation,
        entry_key: Option<String>,
        source: error::Error,
    ) -> Self {
        Self {
            kind: CacheErrorKind::Filesystem {
                operation,
                entry_key,
                source,
            },
        }
    }

    pub(super) fn json(
        operation: CacheOperation,
        path: impl Into<PathBuf>,
        entry_key: Option<String>,
        source: serde_json::Error,
    ) -> Self {
        Self {
            kind: CacheErrorKind::Json {
                operation,
                path: path.into(),
                entry_key,
                source,
            },
        }
    }

    pub(super) fn remote(entry_key: impl Into<String>, source: SupabaseError) -> Self {
        Self {
            kind: CacheErrorKind::Remote {
                operation: CacheOperation::FetchRemote,
                entry_key: entry_key.into(),
                source,
            },
        }
    }

    pub(super) fn missing(
        resource: impl Into<String>,
        key: impl Into<String>,
        value: impl Into<String>,
    ) -> Self {
        Self {
            kind: CacheErrorKind::MissingRow {
                resource: resource.into(),
                key: key.into(),
                value: value.into(),
            },
        }
    }

    pub(super) fn shared(entry_key: impl Into<String>, source: Arc<Self>) -> Self {
        Self {
            kind: CacheErrorKind::Shared {
                operation: CacheOperation::LoadShared,
                entry_key: entry_key.into(),
                source,
            },
        }
    }

    /// Returns the failed cache operation.
    #[must_use]
    pub fn operation(&self) -> CacheOperation {
        match &self.kind {
            CacheErrorKind::Filesystem { operation, .. }
            | CacheErrorKind::Json { operation, .. }
            | CacheErrorKind::Remote { operation, .. }
            | CacheErrorKind::Shared { operation, .. } => *operation,
            CacheErrorKind::MissingRow { .. } => CacheOperation::FetchRemote,
        }
    }

    /// Returns the affected filesystem path for disk-cache failures.
    #[must_use]
    pub fn path(&self) -> Option<&Path> {
        match &self.kind {
            CacheErrorKind::Filesystem { source, .. } => Some(source.path()),
            CacheErrorKind::Json { path, .. } => Some(path),
            _ => None,
        }
    }

    /// Returns the stable cache entry identity when one entry was involved.
    #[must_use]
    pub fn entry_key(&self) -> Option<&str> {
        match &self.kind {
            CacheErrorKind::Filesystem { entry_key, .. }
            | CacheErrorKind::Json { entry_key, .. } => entry_key.as_deref(),
            CacheErrorKind::Remote { entry_key, .. } | CacheErrorKind::Shared { entry_key, .. } => {
                Some(entry_key)
            }
            CacheErrorKind::MissingRow { .. } => None,
        }
    }

    /// Returns the missing remote-row identity, when applicable.
    #[must_use]
    pub fn missing_row(&self) -> Option<(&str, &str, &str)> {
        match &self.kind {
            CacheErrorKind::MissingRow {
                resource,
                key,
                value,
            } => Some((resource, key, value)),
            _ => None,
        }
    }
}

impl fmt::Debug for CacheError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CacheError")
            .field("operation", &self.operation())
            .field("entry_key", &self.entry_key())
            .field("path", &self.path().map(|_| "<redacted>"))
            .field("source", &"<redacted>")
            .finish_non_exhaustive()
    }
}