supreme_fs/game_storage/

mod.rs

//! Stateful API for game file management.
//!
//! This module is split by concern:
//! - [`mod@discovery`]: walking the game directory tree.
//! - [`mod@local_ops`]: local hashing/profile-listing/report helpers.
//! - [`mod@hooked_ops`]: hook-aware read/write/exists/remove/list, routes
//!   through active mod redirection rules when the storage was built with
//!   [`GameStorage::with_hooks`] or [`GameStorage::with_hook_resolver`].
//! - `online` (feature = "online"): everything that talks to the remote API
//!   (profiles, content, snapshot upload/download, chunked uploads).

mod discovery;
mod hooked_ops;
mod local_ops;

#[cfg(feature = "online")]
mod online;

// Type ownership: the tournament wire DTOs live in supreme_fs (module
// `game_storage::online::rooms`, surfaced publicly as `supreme_fs::rooms`;
// the account DTOs in `game_storage::online::auth`, surfaced as
// `supreme_fs::auth`), so consumers never need supreme_tournament to talk
// to the rooms API.
#[cfg(feature = "online")]
pub use online::auth::{AccountDto, AuthInfo, AuthPoll};
#[cfg(feature = "online")]
pub use online::fetch::{http_get_bytes, http_get_bytes_opt, http_post_bytes};
#[cfg(feature = "online")]
pub use online::rooms::{
    RoomDto, RoomIdentity, RoomRecordDto, RoomSummaryDto, RoomUploadResult,
    high_times_entries_from_records, room_remove_payload,
};

pub use discovery::DiscoverMode;

use std::path::{Path, PathBuf};
use std::sync::Arc;
use supreme_hook_config::{HookConfig, HookConfigError, HookResolver};

#[cfg(feature = "online")]
use ureq::Agent;

/// Provides a stateful API for game file management.
#[derive(Clone)]
pub struct GameStorage {
    root_path: PathBuf,
    /// When present, `read_*`/`write_*`/`exists`/`remove_file` route
    /// game-relative paths through this resolver first, so a page reading
    /// or writing a game asset sees exactly what the game itself would see
    /// at runtime, including any active mod redirection, without the
    /// launcher ever injecting into the game process. `None` means no
    /// hook-awareness: every operation goes straight to `root_path`,
    /// unchanged from before this existed.
    hook_resolver: Option<Arc<HookResolver>>,
    #[cfg(feature = "online")]
    api_url: Option<String>,
    #[cfg(feature = "online")]
    client: Option<Agent>,
    #[cfg(feature = "online")]
    token: Option<String>,
}

impl GameStorage {
    /// Create a new `GameStorage` instance for local-only storage, with no
    /// hook-awareness: `read_text`/`write_text`/etc. always operate on the
    /// literal path under `game_path`, exactly as before mod redirection
    /// existed. Use [`GameStorage::with_hooks`] for pages that need to see
    /// the game the way a mod-redirected game process would.
    #[must_use]
    pub fn new(game_path: &Path) -> Self {
        Self {
            root_path: game_path.to_path_buf(),
            hook_resolver: None,
            #[cfg(feature = "online")]
            api_url: None,
            #[cfg(feature = "online")]
            client: None,
            #[cfg(feature = "online")]
            token: None,
        }
    }

    /// Create a `GameStorage` instance whose `read_*`/`write_*`/`exists`/
    /// `remove_file`/`list_files` calls are routed through the same
    /// redirection rules the game process would apply at runtime, per
    /// `mods.json` and each enabled mod's `mod.json` under `mods_dir`.
    ///
    /// `temp_dir` is only used for staging *patched* replacement files
    /// (see [`HookResolver::resolve_path`]), most redirection rules never
    /// touch it. Writes always land on the original file or a mod's own
    /// `target`, never in `temp_dir`.
    ///
    /// Mods listed in `mods.json` whose `mod.json` couldn't be read or
    /// parsed are skipped rather than failing the whole call; they're
    /// returned alongside the instance so the caller can surface them
    /// (e.g. in the mod manager page) rather than have them silently
    /// dropped.
    #[must_use]
    pub fn with_hooks(
        game_path: &Path,
        mods_dir: &Path,
        temp_dir: PathBuf,
    ) -> (Self, Vec<(String, HookConfigError)>) {
        let (resolver, skipped) = HookResolver::load(mods_dir, game_path.to_path_buf(), temp_dir);
        let storage = Self {
            root_path: game_path.to_path_buf(),
            hook_resolver: Some(Arc::new(resolver)),
            #[cfg(feature = "online")]
            api_url: None,
            #[cfg(feature = "online")]
            client: None,
            #[cfg(feature = "online")]
            token: None,
        };
        (storage, skipped)
    }

    /// True if this instance routes reads/writes through mod redirection
    /// rules (i.e. was built with [`GameStorage::with_hooks`] or
    /// [`GameStorage::with_hook_resolver`]).
    #[must_use]
    pub fn is_hook_aware(&self) -> bool {
        self.hook_resolver.is_some()
    }

    /// The loaded hook resolver's rule config, when hook-aware (see
    /// [`GameStorage::with_hook_resolver`]).
    ///
    /// The launcher uses this to resolve a game-relative path to its
    /// redirect target with the exact same rule machinery the DLL applies
    /// at runtime (e.g. the tournament instance `high_times` file the
    /// selected track's `Saved_Data/…_high_times.txt` rule points at),
    /// the launcher and the hook can then never disagree about where a
    /// redirected file lives.
    #[must_use]
    pub fn hook_config(&self) -> Option<&HookConfig> {
        self.hook_resolver.as_ref().map(|r| r.config())
    }

    /// Attaches mod-redirection hook-awareness to an already-built
    /// `GameStorage`, e.g. one built with [`GameStorage::with_online`],
    /// which (unlike [`GameStorage::new`]) has no hook-aware counterpart
    /// constructor of its own. Consumes and returns `self` so it composes
    /// with any other constructor rather than needing a dedicated
    /// combined one for every combination.
    ///
    /// Same loading contract as [`GameStorage::with_hooks`]: mods listed
    /// in `mods.json` whose `mod.json` couldn't be read or parsed are
    /// skipped rather than failing the whole call, and returned alongside
    /// the instance.
    #[must_use]
    pub fn with_hook_resolver(
        mut self,
        mods_dir: &Path,
        temp_dir: PathBuf,
    ) -> (Self, Vec<(String, HookConfigError)>) {
        let (resolver, skipped) = HookResolver::load(mods_dir, self.root_path.clone(), temp_dir);
        self.hook_resolver = Some(Arc::new(resolver));
        (self, skipped)
    }

    /// Create a new `GameStorage` instance with online fallback support at `api_url`.
    #[cfg(feature = "online")]
    #[must_use]
    pub fn with_online(game_path: &Path, api_url: &str) -> Self {
        Self::with_online_timeouts(
            game_path,
            api_url,
            std::time::Duration::from_secs(10),
            std::time::Duration::from_secs(300),
        )
    }

    /// [`GameStorage::with_online`] with explicit HTTP timeouts.
    ///
    /// The launcher-facing [`with_online`] defaults (10 s connect / 300 s
    /// global) are right for interactive pages, but an embedded consumer,
    /// e.g. the tournament provider inside the hook DLL, whose cold-miss
    /// fetch runs on a game thread that must never stall for minutes, needs
    /// tighter bounds (bounded timeouts, blocking HTTP
    /// only on the cold path). Platform-neutral: only the ureq agent config
    /// differs.
    #[cfg(feature = "online")]
    #[must_use]
    pub fn with_online_timeouts(
        game_path: &Path,
        api_url: &str,
        timeout_connect: std::time::Duration,
        timeout_global: std::time::Duration,
    ) -> Self {
        let token = std::env::var("SSBZ_API_TOKEN").ok();
        let trimmed_url = online::normalize_api_url(api_url);

        Self {
            root_path: game_path.to_path_buf(),
            hook_resolver: None,
            api_url: Some(trimmed_url),
            client: Some(ureq::Agent::new_with_config(
                ureq::Agent::config_builder()
                    .user_agent("SupremeSnowboardingLauncher")
                    .timeout_connect(Some(timeout_connect))
                    .timeout_global(Some(timeout_global))
                    // Treat 4xx/5xx as ordinary responses so the explicit
                    // `status().is_success()` checks below can read the
                    // server's JSON error body and produce useful messages
                    // instead of an opaque transport error.
                    .http_status_as_error(false)
                    .build(),
            )),
            token,
        }
    }

    /// Check if online features are configured.
    #[must_use]
    pub fn is_online(&self) -> bool {
        #[cfg(feature = "online")]
        {
            self.api_url.is_some()
        }
        #[cfg(not(feature = "online"))]
        {
            false
        }
    }

    /// Clear the online token for this instance. Useful for testing unauthorized access.
    #[cfg(feature = "online")]
    pub fn clear_token(&mut self) {
        self.token = None;
    }

    /// Get the root game path
    #[must_use]
    pub fn game_path(&self) -> &PathBuf {
        &self.root_path
    }

    /// Get the profiles directory path
    #[must_use]
    pub fn profiles_path(&self) -> PathBuf {
        crate::get_profiles_path(&self.root_path)
    }

    /// Get the contents directory path
    #[must_use]
    pub fn contents_path(&self) -> PathBuf {
        crate::get_contents_path(&self.root_path)
    }
}

#[derive(Debug, serde::Deserialize, Clone)]
pub struct OnlineProfileInfo {
    pub filename: String,
    pub name: Option<String>,
    pub description: Option<String>,
    pub version: Option<String>,
    pub size: u64,
    pub mtime: u64,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn new_stores_root_path_and_defaults_to_offline() {
        let storage = GameStorage::new(Path::new("/tmp/my_game"));
        assert_eq!(storage.game_path(), Path::new("/tmp/my_game"));
        assert!(!storage.is_online());
    }

    #[test]
    fn profiles_and_contents_paths_are_derived_from_root() {
        let storage = GameStorage::new(Path::new("/tmp/my_game"));
        assert_eq!(
            storage.profiles_path(),
            Path::new("/tmp/my_game/.supreme/profiles")
        );
        assert_eq!(
            storage.contents_path(),
            Path::new("/tmp/my_game/.supreme/contents")
        );
    }

    #[test]
    fn with_hook_resolver_makes_an_existing_instance_hook_aware() {
        // No mods.json at this (nonexistent) mods_dir -- HookResolver::load
        // gracefully falls back to "no mods enabled" rather than erroring,
        // so this doesn't need a real tempdir to stay filesystem-free like
        // the other tests here.
        let storage = GameStorage::new(Path::new("/tmp/my_game"));
        assert!(!storage.is_hook_aware());

        let (storage, skipped) = storage.with_hook_resolver(
            Path::new("/tmp/my_game/.supreme/mods"),
            PathBuf::from("/tmp/my_game/.supreme/tmp"),
        );
        assert!(skipped.is_empty());
        assert!(storage.is_hook_aware());
        assert_eq!(storage.game_path(), Path::new("/tmp/my_game"));
    }

    #[cfg(feature = "online")]
    #[test]
    fn with_hook_resolver_composes_with_with_online() {
        let storage = GameStorage::with_online(Path::new("/tmp/my_game"), "https://example.com");
        let (storage, skipped) = storage.with_hook_resolver(
            Path::new("/tmp/my_game/.supreme/mods"),
            PathBuf::from("/tmp/my_game/.supreme/tmp"),
        );
        assert!(skipped.is_empty());
        assert!(storage.is_hook_aware());
        assert!(storage.is_online());
    }

    #[cfg(feature = "online")]
    #[test]
    fn with_online_reports_is_online_true() {
        let storage = GameStorage::with_online(Path::new("/tmp/my_game"), "https://example.com");
        assert!(storage.is_online());
    }

    #[cfg(feature = "online")]
    #[test]
    fn with_online_timeouts_matches_with_online_shape() {
        let storage = GameStorage::with_online_timeouts(
            Path::new("/tmp/my_game"),
            "https://example.com",
            std::time::Duration::from_secs(5),
            std::time::Duration::from_secs(15),
        );
        assert!(storage.is_online());
        assert_eq!(storage.game_path(), Path::new("/tmp/my_game"));
    }

    #[cfg(feature = "online")]
    #[test]
    fn clear_token_removes_configured_token() {
        // SAFETY: tests run single-threaded per-process for env var mutation concerns here,
        // and this test does not rely on any other test's environment state.
        unsafe {
            std::env::set_var("SSBZ_API_TOKEN", "secret-token");
        }
        let mut storage =
            GameStorage::with_online(Path::new("/tmp/my_game"), "https://example.com");
        storage.clear_token();
        // clear_token has no public getter, but at minimum this should not panic and
        // the instance should remain online-configured.
        assert!(storage.is_online());
        unsafe {
            std::env::remove_var("SSBZ_API_TOKEN");
        }
    }
}