supreme_hook_config/

hook_config.rs

//! The merged, resolved redirection config the proxy DLL actually
//! consumes: [`HookConfig`] (a flat list of [`RedirectionRule`]s) and
//! [`ResolvedAction`], the outcome of resolving one requested path against
//! it. Distinct from [`crate::mod_config::ModConfig`], which is the
//! per-mod *authored* (possibly conditional/templated) shape, see
//! [`ModConfig::resolved_rules`](crate::mod_config::ModConfig::resolved_rules)
//! for how one becomes the other.

use crate::error::HookConfigError;
use crate::mod_config::ModConfig;
use crate::mods_state::MOD_FILE_NAME;
use crate::patch::MemoryPatch;
use glob::{MatchOptions, Pattern};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::path::{Path, PathBuf};

/// Options passed to [`glob::Pattern::matches_with`] for every rule
/// lookup: case-insensitive (Windows paths), and `*` bounded to a single
/// path component while a bare `**` component still matches recursively
/// (the crate special-cases that regardless of `require_literal_separator`).
/// On Windows, `glob`'s separator handling (via `std::path::is_separator`)
/// already treats both `/` and `\` as separators natively, so there's no
/// need to normalize paths ourselves before matching.
pub(crate) const MATCH_OPTIONS: MatchOptions = MatchOptions {
    case_sensitive: false,
    require_literal_separator: true,
    require_literal_leading_dot: false,
};

/// The full set of redirection rules the proxy DLL should apply for a
/// single game session, already merged across every enabled mod. See
/// [`HookConfig::load_from_mods_dir`].
#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
pub struct HookConfig {
    pub rules: Vec<RedirectionRule>,
}

/// Where a rule's replacement content lives.
///
/// A rule's `target` is either a plain local path (the classic string
/// form, a plain redirect) or a struct describing a **remote-backed
/// managed file**: the mod declares *what* the file is and *where its
/// fresh content comes from*, and the proxy DLL's generic managed-file
/// engine takes over from there, no per-mod special-casing inside the
/// DLL.
///
/// ```json
/// "target": ".supreme/mods/mymod/data/file.txt"              // classic
/// "target": {                                                // managed
///     "local":  ".supreme/mods/mymod/high_times/file.txt",
///     "remote": "https://host/ssbz/index.php?action=room_high_times_file&id=${room}",
///     "poll_interval_secs": 10,
///     "push_url": "https://host/ssbz/index.php?action=room_high_times_file&id=${room}"
/// }
/// ```
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(untagged)]
pub enum RuleTarget {
    /// Plain local redirect target, the original, classic form. Relative
    /// paths are interpreted against the game root (joined at resolver
    /// load), exactly as before.
    Path(PathBuf),
    /// Remote-backed managed file. `local` is the physical file the
    /// redirect serves (and the only thing the redirect machinery ever
    /// touches); `remote` is the URL whose body IS the file content (a
    /// plain HTTP GET, response bytes used verbatim); `poll_interval_secs`
    /// is the auto-refresh cadence once the game has accessed the file at
    /// least once, `None`/absent means no polling (fetch only on access);
    /// `push_url` is where every game write of the file is POSTed to
    /// `None`/absent means the file is fetch-only (writes stay
    /// local and are never uploaded).
    ///
    /// All three strings (`local`, `remote`, `push_url`) go through the
    /// same `${...}` interpolation as every other rule string, so a mod can
    /// wire selection-driven values (`${tournament_room_id}`,
    /// `${url_encode(tournament_player)}`, …) into the URLs. `remote` and
    /// `push_url` routinely name the same endpoint (GET = fetch the
    /// canonical content, POST = push a game-written file), the two
    /// properties exist so a mod author can split the directions across
    /// different URLs when their backend wants that.
    Managed {
        local: PathBuf,
        remote: String,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        poll_interval_secs: Option<u64>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        push_url: Option<String>,
    },
}

impl RuleTarget {
    /// The local path this target resolves to (the redirect machinery's
    /// only touch point). For a managed target that is the `local` field.
    #[must_use]
    pub fn path(&self) -> &Path {
        match self {
            RuleTarget::Path(p) => p,
            RuleTarget::Managed { local, .. } => local,
        }
    }

    /// The managed half of this target, if it is one: `(remote URL,
    /// poll interval in seconds, push URL)`.
    #[must_use]
    pub fn managed(&self) -> Option<(&str, Option<u64>, Option<&str>)> {
        match self {
            RuleTarget::Path(_) => None,
            RuleTarget::Managed {
                remote,
                poll_interval_secs,
                push_url,
                ..
            } => Some((remote, *poll_interval_secs, push_url.as_deref())),
        }
    }
}

/// A single glob-based redirection rule.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct RedirectionRule {
    /// Glob pattern matched against the file path the game requests,
    /// relative to the game's root directory (e.g. `data/levels/*.dat`).
    pub glob_pattern: String,
    /// The replacement asset for files matching the glob, relative to the
    /// game's root directory unless absolute, either a plain local path
    /// ([`RuleTarget::Path`], the classic string form) or a remote-backed
    /// managed file ([`RuleTarget::Managed`], struct form; the local path
    /// plus where fresh content comes from and how often to refresh it).
    /// Omittable, `None` means no replacement is configured yet (e.g. a
    /// rule scaffolded ahead of the asset being dropped in), and is
    /// treated exactly like "the replacement doesn't exist": `GracefulFallback`
    /// mode passes through to the original, `HardError` mode blocks the
    /// operation. When present, its meaning depends on the glob's shape,
    /// see [`RedirectionRule::is_literal_glob`]:
    /// - **Wildcard glob** (contains `*`, `?`, or `[`, e.g.
    ///   `data/levels/*.dat` or `mods_source/**`): the target's local path
    ///   is a *directory*. The portion of the matched path below the
    ///   glob's fixed prefix is joined onto it, preserving relative
    ///   structure.
    /// - **Literal glob** (no wildcard at all, e.g.
    ///   `Saved_Data/high_times.txt`): the rule can only ever match that
    ///   one exact path, so the target's local path is the replacement
    ///   *file* itself, used as-is, nothing is joined onto it. A managed
    ///   target additionally requires a literal glob (one remote URL can
    ///   only name one file), enforced by [`ModConfig::validate`].
    #[serde(default)]
    pub target: Option<RuleTarget>,
    pub mode: RedirectionMode,
    /// Content modifications applied to the replacement file's bytes
    /// before they're written to the temp redirection target. Empty by
    /// default: most rules only redirect, they don't also patch bytes.
    #[serde(default)]
    pub patches: Vec<MemoryPatch>,
    /// References a [`crate::mod_config::ModParameter::id`] within the same mod. When
    /// present, this rule only participates in [`ModConfig::resolved_rules`]
    /// if that parameter's current value is "on", a `true` boolean, or a
    /// non-empty dropdown selection (see [`ModConfig`] for the full
    /// picture). `None` means the rule is unconditionally active.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enable_if: Option<String>,
}

impl RedirectionRule {
    /// True if `glob_pattern` contains no wildcard characters (`*`, `?`,
    /// `[`), meaning it can only ever match exactly one path. Such rules
    /// treat `target` as the replacement file directly rather than a
    /// directory to join a matched suffix into, see the field docs on
    /// [`RedirectionRule::target`].
    #[must_use]
    pub fn is_literal_glob(&self) -> bool {
        !self.glob_pattern.contains(['*', '?', '['])
    }
}

#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum RedirectionMode {
    /// If the redirected file doesn't exist, silently open the original.
    GracefulFallback,
    /// If the redirected file doesn't exist, fail the open with a
    /// "file not found" style error instead of touching the original.
    HardError,
}

/// What the hook should do for a given requested path, once a rule has
/// been matched (or not) and the existence of the replacement asset has
/// been checked.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ResolvedAction {
    /// No rule matched this path; pass the call straight through.
    PassThrough,
    /// A rule matched and the replacement asset exists at this path;
    /// the caller should stage a patched temp file and redirect there.
    Redirect { replacement_path: PathBuf },
    /// A rule matched in `GracefulFallback` mode but the replacement
    /// asset is missing; pass through to the original file.
    FallbackToOriginal,
    /// A rule matched in `HardError` mode but the replacement asset is
    /// missing; the caller should fail the open outright.
    HardErrorMissingFile,
}

impl HookConfig {
    /// Loads a `HookConfig` from a single JSON file on disk (a plain
    /// merged/resolved rule set, for a single mod's authored `mod.json`,
    /// use [`ModConfig::load_from_path`] instead).
    ///
    /// # Errors
    ///
    /// Returns an error if the file cannot be read or does not contain
    /// valid JSON matching the expected shape.
    pub fn load_from_path(path: &Path) -> Result<Self, HookConfigError> {
        let bytes = std::fs::read(path).map_err(|source| HookConfigError::Read {
            path: path.to_path_buf(),
            source,
        })?;
        Ok(serde_json::from_slice(&bytes)?)
    }

    /// Serializes and writes this `HookConfig` to a JSON file on disk,
    /// creating parent directories as needed.
    ///
    /// # Errors
    ///
    /// Returns an error if parent directories can't be created, the file
    /// can't be written, or serialization fails.
    pub fn write_to_path(&self, path: &Path) -> Result<(), HookConfigError> {
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent).map_err(|source| HookConfigError::Write {
                path: path.to_path_buf(),
                source,
            })?;
        }
        let json = serde_json::to_vec_pretty(self)?;
        std::fs::write(path, json).map_err(|source| HookConfigError::Write {
            path: path.to_path_buf(),
            source,
        })
    }

    /// Loads and merges every enabled mod's rules from a mods directory
    /// laid out as described on
    /// [`crate::mods_state::DEFAULT_MODS_DIR_NAME`].
    ///
    /// Each mod's rules are filtered and interpolated through
    /// [`ModConfig::resolved_rules`] before merging, by the time a rule
    /// reaches this function's result, any `enable_if` gating and
    /// `${param_id}` interpolation have already been resolved against that
    /// mod's own `configuration`. Mods are then merged by simple
    /// concatenation of their (already-resolved) rule lists, in
    /// [`crate::mods_state::ModsPreset::priority_order`] order (of
    /// [`crate::mods_state::ModsState::active`]), the same order the
    /// launcher's mod list displays, since for the active configuration
    /// display order and merge priority are the same list (unlike a
    /// saved, not-currently-applied preset in
    /// [`crate::mods_state::ModsState::presets`], which freezes its own
    /// order separately until it's applied, see
    /// [`crate::mods_state::ModsState::apply_preset`]). Since rule
    /// resolver scans that concatenated list in order: patch-only matches
    /// accumulate across mods, whereas a usable redirect starts a new
    /// stage at the redirected path and scans the entire list from the
    /// beginning. Thus the first successful conflicting redirect wins at
    /// its current stage, but later mods can still patch the same path or
    /// continue a chain at a redirected path. A mod's rules stay
    /// contiguous and in their authored order.
    ///
    /// A mod in the active priority order whose `mod.json` is missing,
    /// fails to parse, or fails [`ModConfig::validate`] is skipped
    /// entirely (none of its rules are applied) rather than failing the
    /// whole load, one broken or since-removed mod shouldn't take every
    /// other enabled mod down with it. Validation failing here matches
    /// what the launcher's own mod list shows as a broken/red entry, so a
    /// mod that a person can see is broken never has some of its rules
    /// quietly applied anyway. Skipped mods are returned alongside the
    /// merged config so the caller can log them; this crate takes no
    /// logging dependency of its own.
    ///
    /// # Errors
    ///
    /// Returns an error if `mods.json` can't be read (including if
    /// it's missing, unlike
    /// [`load_mods_state`](crate::mods_state::load_mods_state), this
    /// function requires it to exist) or doesn't parse.
    pub fn load_from_mods_dir(
        mods_dir: &Path,
    ) -> Result<(Self, Vec<(String, HookConfigError)>), HookConfigError> {
        let state_path = mods_dir.join(crate::mods_state::MODS_STATE_FILE_NAME);
        let bytes = std::fs::read(&state_path).map_err(|source| HookConfigError::Read {
            path: state_path.clone(),
            source,
        })?;
        let state: crate::mods_state::ModsState = serde_json::from_slice(&bytes)?;
        let mod_names: Vec<String> = state
            .active
            .priority_order()
            .into_iter()
            .map(str::to_string)
            .collect();
        let configurations = state.active.configuration;
        let empty_configuration = HashMap::new();

        let mut merged = HookConfig::default();
        let mut skipped = Vec::new();

        for mod_name in mod_names {
            let cfg_path = mods_dir.join(&mod_name).join(MOD_FILE_NAME);
            match ModConfig::load_from_path(&cfg_path) {
                Ok(mod_config) => match mod_config.validate() {
                    Ok(()) => {
                        let configuration = configurations
                            .get(&mod_name)
                            .unwrap_or(&empty_configuration);
                        merged
                            .rules
                            .extend(mod_config.resolved_rules(configuration));
                    }
                    Err(errors) => skipped.push((
                        mod_name,
                        HookConfigError::Invalid {
                            path: cfg_path,
                            reasons: errors.join("; "),
                        },
                    )),
                },
                Err(e) => skipped.push((mod_name, e)),
            }
        }

        Ok((merged, skipped))
    }

    /// Finds the first rule whose glob matches `requested_path`.
    ///
    /// `requested_path` should be relative to the game's root directory
    /// (callers are responsible for stripping the game root and
    /// normalizing separators before calling this).
    #[must_use]
    pub fn find_matching_rule(&self, requested_path: &str) -> Option<&RedirectionRule> {
        let normalized = requested_path.replace('\\', "/");
        self.rules.iter().find(|rule| {
            Pattern::new(&rule.glob_pattern)
                .is_ok_and(|pattern| pattern.matches_with(&normalized, MATCH_OPTIONS))
        })
    }

    /// Full resolution: given a requested path (relative to the game
    /// root) and a way to check whether a candidate replacement file
    /// exists, decides what the hook should do.
    ///
    /// For a wildcard rule, the path *below* the rule's fixed
    /// (non-wildcard) prefix is preserved when joining onto `target`, not
    /// just the file's basename. This matters for directory-tree rules
    /// such as `mods_source/**`: a request for
    /// `mods_source/textures/snow/ice.dds` resolves under `target` as
    /// `.../textures/snow/ice.dds`, keeping the same relative layout,
    /// rather than flattening every match into a single directory. For a
    /// flat, single-component pattern like `data/levels/*.dat` this still
    /// reduces to just the file's basename, since there's no subdirectory
    /// portion to keep.
    ///
    /// For a literal (non-wildcard) rule, `target` is used directly with
    /// nothing joined onto it, see [`RedirectionRule::is_literal_glob`].
    ///
    /// If `target` is omitted (`None`), this behaves exactly as if a
    /// configured replacement simply didn't exist on disk: `file_exists`
    /// is never called, and the outcome is `FallbackToOriginal` or
    /// `HardErrorMissingFile` per the rule's `mode`.
    ///
    /// `file_exists` is injected rather than calling `std::fs` directly so
    /// this stays testable without touching a real filesystem, and so the
    /// proxy DLL can plug in whatever existence check makes sense for its
    /// context (e.g. going through the real `NtQueryAttributesFile`
    /// trampoline instead of `std::fs`, to avoid recursing into itself).
    #[must_use]
    pub fn resolve(
        &self,
        requested_path: &str,
        file_exists: impl FnOnce(&Path) -> bool,
    ) -> ResolvedAction {
        let normalized = requested_path.replace('\\', "/");
        let Some(rule) = self.find_matching_rule(&normalized) else {
            return ResolvedAction::PassThrough;
        };

        let missing = || match rule.mode {
            RedirectionMode::GracefulFallback => ResolvedAction::FallbackToOriginal,
            RedirectionMode::HardError => ResolvedAction::HardErrorMissingFile,
        };

        let Some(target) = &rule.target else {
            return missing();
        };

        let replacement_path = if rule.is_literal_glob() {
            target.path().to_path_buf()
        } else {
            let suffix = matched_suffix(&rule.glob_pattern, &normalized);
            target.path().join(suffix)
        };

        log::debug!("Probing for replacement: {}", replacement_path.display());

        if file_exists(&replacement_path) {
            ResolvedAction::Redirect { replacement_path }
        } else {
            missing()
        }
    }
}

/// Returns the portion of `requested_path` that falls *below* the rule's
/// fixed (non-wildcard) directory prefix, so directory-tree rules can
/// preserve relative structure instead of collapsing every match down to
/// its basename.
///
/// The "fixed prefix" is everything in `glob_pattern` up to (and
/// including) the last path separator before the first wildcard
/// character (`*`, `?`, or `[`). For `data/levels/*.dat` that's
/// `data/levels/`; for `mods_source/**` that's `mods_source/`. Note this
/// is plain string bookkeeping, not glob matching, the `glob` crate only
/// answers yes/no on a match and doesn't expose which part of the path a
/// wildcard consumed, so there's nothing to reuse from it here.
///
/// Only meaningful for wildcard rules, callers should check
/// [`RedirectionRule::is_literal_glob`] first, since a literal glob has no
/// wildcard prefix boundary to compute here.
pub(crate) fn matched_suffix<'a>(glob_pattern: &str, requested_path: &'a str) -> &'a str {
    let normalized_pattern = glob_pattern.replace('\\', "/");
    let wildcard_idx = normalized_pattern
        .find(['*', '?', '['])
        .unwrap_or(normalized_pattern.len());
    let prefix_end = normalized_pattern[..wildcard_idx]
        .rfind('/')
        .map_or(0, |i| i + 1);
    let prefix_lower = normalized_pattern[..prefix_end].to_lowercase();

    // Case-insensitive prefix check, to match `find_matching_rule`'s
    // contract (see `matching_is_case_insensitive`), rule authors write
    // patterns in whatever case reads naturally (`Data/Levels/...`), while
    // `rel_key`s built from live NT paths are always lowercased. A plain
    // byte-prefix check fails on that mismatch alone and used to fall back
    // to the bare basename, silently discarding the matched subdirectory
    // structure for every rule whose pattern wasn't authored all-lowercase.
    //
    // Compare against lowercased copies to find the prefix length, then
    // slice the *original* `requested_path` at that byte offset so the
    // returned suffix keeps whatever casing the caller's rel_key actually
    // has. `to_lowercase()` is byte-length-preserving for the ASCII
    // separators/drive-letters/extensions these paths are built from, so
    // the offset found in the lowercased copy lines up with the original;
    // `requested_path.get(..)` still guards against a non-ASCII edge case
    // landing the offset off a UTF-8 boundary, falling back to the
    // basename exactly as before rather than panicking or mis-slicing.
    let requested_lower = requested_path.to_lowercase();
    let prefix_matches = requested_lower
        .get(..prefix_end)
        .is_some_and(|head| head == prefix_lower);

    prefix_matches
        .then(|| requested_path.get(prefix_end..))
        .flatten()
        .unwrap_or_else(|| {
            Path::new(requested_path)
                .file_name()
                .and_then(|f| f.to_str())
                .unwrap_or(requested_path)
        })
}