rakata_extract/

twoda_cache.rs

//! Resolver-backed lazy cache of parsed 2DA tables.
//!
//! Decoders that map raw engine integers (UTI property kinds, UTC class
//! ids, TPC palette refs, ...) to typed semantics need repeated read
//! access to the same handful of 2DA tables: `itempropdef.2da`,
//! `baseitems.2da`, `iprp_*.2da`, etc. Re-resolving and re-parsing
//! those tables on every property read is wasteful, and pushing the
//! cache into each format consumer fragments the duplication.
//!
//! [`TwoDaCache`] is the shared primitive: borrow a [`Resolver`], call
//! [`TwoDaCache::twoda`] with a bare table name (no extension), get
//! back a borrowed [`TwoDa`]. The first call resolves, parses, and
//! caches the table; subsequent calls hand back the cached parse.
//! A single instance can serve a whole batch decode pass across
//! multiple format decoders.

use std::collections::hash_map::Entry;
use std::collections::HashMap;
use std::fmt::{Display, Formatter};

use rakata_core::{ResRef, ResRefError, ResourceType, ResourceTypeCode};
use rakata_formats::twoda::{read_twoda_from_bytes, TwoDa, TwoDaBinaryError};

use crate::resolver::Resolver;

/// A validated 2DA table name (e.g. `racialtypes`, `appearance`).
///
/// Wraps [`ResRef`] so cache keys are distinguishable from arbitrary
/// resrefs at the type level. Layers an ASCII-only check on top of
/// `ResRef`'s broader Windows-1252 acceptance: vanilla K1 2DA names
/// are pure ASCII, and `chitin.key`'s filename table is ASCII-only,
/// so an extended-character 2DA name would not resolve anyway.
///
/// The name does **not** include the `.2da` extension -- the
/// [`ResourceTypeCode`] supplies that at resolver lookup time.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct TwoDaName(ResRef);

impl TwoDaName {
    /// Creates a 2DA name from a string.
    ///
    /// 2DA filenames are conventionally ASCII; this constructor
    /// enforces that invariant on top of [`ResRef`]'s broader
    /// Windows-1252 acceptance, since extended-character 2DA names
    /// would not round-trip through `chitin.key`'s ASCII-only
    /// filename table anyway.
    pub fn new(name: impl AsRef<str>) -> Result<Self, ResRefError> {
        let resref = ResRef::new(name)?;
        if !resref.as_bytes().iter().all(u8::is_ascii) {
            // Find the first non-ASCII byte to report which character
            // tripped the rejection.
            let bad = resref
                .as_bytes()
                .iter()
                .find(|b| !b.is_ascii())
                .copied()
                .expect("just verified at least one byte fails is_ascii");
            return Err(ResRefError::InvalidChar {
                ch: char::from(bad),
            });
        }
        Ok(Self(resref))
    }

    /// Returns a reference to the underlying [`ResRef`] for resolver
    /// lookups that take `&ResRef` directly.
    pub fn as_resref(&self) -> &ResRef {
        &self.0
    }

    /// Returns the canonical lowercase string form of the name,
    /// suitable for passing to [`TwoDaCache::twoda`] without an
    /// extra round trip through [`TwoDaName::new`].
    ///
    /// `TwoDaName` enforces an ASCII-only invariant on construction
    /// (2DA filenames are conventionally ASCII), so this can return
    /// a borrowed `&str` directly.
    pub fn as_str(&self) -> &str {
        // SAFETY-equivalent: TwoDaName::new and ::from_static both
        // verify the bytes are ASCII before constructing, so the
        // underlying ResRef bytes are guaranteed valid UTF-8.
        std::str::from_utf8(self.0.as_bytes()).expect("TwoDaName bytes are ASCII by construction")
    }

    /// `const`-friendly constructor for `pub const` table-name
    /// declarations.
    ///
    /// Validation runs at compile time via [`ResRef::const_new`]; an
    /// invalid input panics during compilation rather than at first
    /// use. Mirrors `http::HeaderName::from_static`. Use this only
    /// for hardcoded vanilla / known table names whose validity you
    /// can verify by inspection -- runtime-discovered names should
    /// go through [`Self::new`] instead.
    pub const fn from_static(name: &'static str) -> Self {
        match ResRef::const_new(name) {
            Ok(resref) => Self(resref),
            // String literal failed ResRef validation -- this is a
            // programmer error, not a recoverable runtime condition.
            Err(_) => panic!("invalid 2DA name passed to TwoDaName::from_static"),
        }
    }
}

impl AsRef<str> for TwoDaName {
    fn as_ref(&self) -> &str {
        self.as_str()
    }
}

impl Display for TwoDaName {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        Display::fmt(&self.0, f)
    }
}

impl AsRef<ResRef> for TwoDaName {
    fn as_ref(&self) -> &ResRef {
        &self.0
    }
}

/// Errors produced by [`TwoDaCache`] operations.
///
/// These flow back to the decoder that requested the lookup; callers
/// can choose to surface a diagnostic, fall back to a default decode
/// (e.g. `Unknown` variant), or propagate depending on whether the
/// missing table is fatal to the operation.
#[derive(Debug, thiserror::Error)]
pub enum TwoDaCacheError {
    /// The supplied table name failed [`ResRef`] validation. Carries
    /// the original (invalid) string so callers can surface it
    /// verbatim in diagnostics.
    #[error("invalid 2DA name `{name}`")]
    InvalidName {
        /// Caller-supplied name that failed validation.
        name: String,
        /// Underlying [`ResRef`] validation error.
        #[source]
        source: ResRefError,
    },
    /// The named 2DA could not be resolved through any configured source.
    #[error("2DA `{name}` not found in resource tree")]
    Missing {
        /// Validated table name the caller requested.
        name: TwoDaName,
    },
    /// The named 2DA was located but failed to parse.
    #[error("2DA `{name}` failed to parse")]
    Parse {
        /// Validated table name whose bytes failed to parse.
        name: TwoDaName,
        /// Underlying 2DA parse error.
        #[source]
        source: TwoDaBinaryError,
    },
}

/// Resolver-backed cache of parsed 2DA tables.
///
/// Borrows a [`Resolver`] for resref-to-bytes lookups and owns a
/// lazily-populated [`HashMap`] of parsed [`TwoDa`] tables keyed by
/// [`TwoDaName`]. Construct once, reuse across decode passes.
///
/// Single-threaded by design: [`Self::twoda`] takes `&mut self` so
/// the cache can grow on miss without interior mutability or
/// `Arc<Mutex<_>>` overhead. If a decoder needs data from two tables
/// in one call, it should pull the typed primitives it needs out of
/// the first borrow before requesting the next.
pub struct TwoDaCache<'a> {
    resolver: &'a Resolver<'a>,
    cache: HashMap<TwoDaName, TwoDa>,
}

impl<'a> TwoDaCache<'a> {
    /// Constructs a new cache backed by the given resolver.
    ///
    /// The resolver is borrowed for the lifetime of the cache, so the
    /// caller is free to keep adding sources to the resolver before
    /// constructing the cache but must not mutate it through that
    /// reference once the cache exists.
    pub fn new(resolver: &'a Resolver<'a>) -> Self {
        Self {
            resolver,
            cache: HashMap::new(),
        }
    }

    /// Returns a reference to the named 2DA, lazily loading and caching
    /// it on first request.
    ///
    /// `name` is anything that yields a bare table name string without
    /// the `.2da` extension. Two natural inputs:
    /// - a `&str` literal (`cache.twoda("itempropdef")`),
    /// - a [`TwoDaName`] constant from the [`tables`] module
    ///   (`cache.twoda(tables::ITEMPROPDEF)`).
    ///
    /// On a cache miss the name is validated, the resolver is asked
    /// for the table, and on hit the bytes are parsed via
    /// [`read_twoda_from_bytes`] before being inserted into the
    /// cache.
    ///
    /// Errors:
    /// - [`TwoDaCacheError::InvalidName`] when the resolved string
    ///   fails [`ResRef`] validation. Cannot fire when the input is a
    ///   [`TwoDaName`] (already validated) or a [`tables`] constant
    ///   (validated at compile time).
    /// - [`TwoDaCacheError::Missing`] when no resolver source contains
    ///   the requested table.
    /// - [`TwoDaCacheError::Parse`] when the bytes are present but
    ///   fail to parse as a valid 2DA.
    pub fn twoda(&mut self, name: impl AsRef<str>) -> Result<&TwoDa, TwoDaCacheError> {
        let name = name.as_ref();
        let validated = TwoDaName::new(name).map_err(|source| TwoDaCacheError::InvalidName {
            name: name.to_string(),
            source,
        })?;
        match self.cache.entry(validated) {
            Entry::Occupied(occupied) => Ok(occupied.into_mut()),
            Entry::Vacant(vacant) => {
                let result = self
                    .resolver
                    .resolve(
                        validated.as_resref(),
                        ResourceTypeCode::from(ResourceType::TwoDa),
                    )
                    .ok_or(TwoDaCacheError::Missing { name: validated })?;
                let twoda = read_twoda_from_bytes(result.data.as_ref()).map_err(|source| {
                    TwoDaCacheError::Parse {
                        name: validated,
                        source,
                    }
                })?;
                Ok(vacant.insert(twoda))
            }
        }
    }
}

/// Compile-time-validated [`TwoDaName`] constants for the vanilla
/// K1 2DA tables the workspace currently consumes.
///
/// Constants land here as new tables get used; growing the module is
/// a one-line `pub const FOO: TwoDaName = TwoDaName::from_static("foo");`
/// addition. Mod-extended or runtime-discovered tables go through
/// [`TwoDaName::new`] at the call site instead.
pub mod tables {
    use super::TwoDaName;

    /// `appearance.2da` -- character / creature appearance table.
    pub const APPEARANCE: TwoDaName = TwoDaName::from_static("appearance");
    /// `baseitems.2da` -- base item type table (model, equip slot,
    /// weapon class, etc.).
    pub const BASEITEMS: TwoDaName = TwoDaName::from_static("baseitems");
    /// `classes.2da` -- character class definitions.
    pub const CLASSES: TwoDaName = TwoDaName::from_static("classes");
    /// `feat.2da` -- feat definitions (combat techniques, weapon and
    /// armour proficiencies, Force feats, droid upgrades, etc.).
    pub const FEAT: TwoDaName = TwoDaName::from_static("feat");
    /// `genericdoors.2da` -- door appearance / model table.
    pub const GENERICDOORS: TwoDaName = TwoDaName::from_static("genericdoors");
    /// `itempropdef.2da` -- master item-property kind table; root of
    /// the per-property subtype dispatch chain.
    pub const ITEMPROPDEF: TwoDaName = TwoDaName::from_static("itempropdef");
    /// `placeables.2da` -- placeable appearance table.
    pub const PLACEABLES: TwoDaName = TwoDaName::from_static("placeables");
    /// `portraits.2da` -- character portrait list.
    pub const PORTRAITS: TwoDaName = TwoDaName::from_static("portraits");
    /// `racialtypes.2da` -- creature race table.
    pub const RACIALTYPES: TwoDaName = TwoDaName::from_static("racialtypes");
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::resolver::{OverrideSource, ResolverSourceRef};
    use rakata_formats::twoda::{write_twoda_to_vec, TwoDaRow};

    #[test]
    fn twoda_name_accepts_vanilla_table_names() {
        for name in [
            "appearance",
            "racialtypes",
            "classes",
            "baseitems",
            "spells",
            "feat",
            "itempropdef",
            "iprp_damagecost",
        ] {
            let parsed = TwoDaName::new(name).expect("vanilla 2da name must validate");
            assert_eq!(parsed.to_string(), name);
        }
    }

    #[test]
    fn twoda_name_rejects_non_ascii_input() {
        // ResRef accepts any byte that round-trips through Windows-1252,
        // so `é` (0xE9) is a valid resref byte. TwoDaName layers an
        // ASCII-only check on top because 2DA filenames in chitin.key
        // are conventionally ASCII, so the constructor still rejects
        // here even though plain ResRef::new would accept.
        let err = TwoDaName::new("café").expect_err("must reject");
        assert!(matches!(err, ResRefError::InvalidChar { .. }));
    }

    #[test]
    fn twoda_name_lowercases_to_match_resref_canonicalisation() {
        let name = TwoDaName::new("Appearance").expect("valid name");
        assert_eq!(name.to_string(), "appearance");
    }

    #[test]
    fn twoda_name_implements_asref_resref_for_resolver_calls() {
        fn takes_resref(r: &ResRef) -> Vec<u8> {
            r.as_bytes().to_vec()
        }
        let name = TwoDaName::new("baseitems").expect("valid name");
        assert_eq!(takes_resref(name.as_ref()), b"baseitems");
    }

    fn fixture_table() -> TwoDa {
        TwoDa {
            headers: vec!["label".to_string(), "value".to_string()],
            rows: vec![
                TwoDaRow {
                    label: "0".to_string(),
                    cells: vec!["alpha".to_string(), "1".to_string()],
                },
                TwoDaRow {
                    label: "1".to_string(),
                    cells: vec!["beta".to_string(), "2".to_string()],
                },
            ],
        }
    }

    fn override_with_table(name: &str, table: &TwoDa) -> OverrideSource {
        let bytes = write_twoda_to_vec(table).expect("write 2da fixture");
        let mut overrides = OverrideSource::new();
        overrides
            .add_entry(
                name,
                ResourceTypeCode::from(ResourceType::TwoDa),
                bytes,
                "test",
            )
            .expect("add override entry");
        overrides
    }

    #[test]
    fn twoda_returns_missing_when_no_source_contains_table() {
        let resolver = Resolver::new();
        let mut cache = TwoDaCache::new(&resolver);
        let err = cache
            .twoda("appearance")
            .expect_err("empty resolver must surface missing");
        assert!(matches!(
            err,
            TwoDaCacheError::Missing { name } if name.to_string() == "appearance"
        ));
    }

    #[test]
    fn twoda_returns_invalid_name_for_non_ascii_input() {
        // The cache rejects only non-ASCII / multi-byte UTF-8 input;
        // arbitrary ASCII bytes (`+`, `!`, space, etc.) are valid in
        // resrefs per the engine audit. Use a multi-byte UTF-8 string
        // to trigger the InvalidName path.
        let resolver = Resolver::new();
        let mut cache = TwoDaCache::new(&resolver);
        let err = cache
            .twoda("café")
            .expect_err("non-ASCII name must surface InvalidName");
        assert!(matches!(
            err,
            TwoDaCacheError::InvalidName { ref name, source: ResRefError::InvalidChar { .. } }
                if name == "café"
        ));
    }

    #[test]
    fn twoda_loads_parses_and_caches_table_via_resolver() {
        let table = fixture_table();
        let overrides = override_with_table("appearance", &table);
        let resolver = Resolver::new().with_source(ResolverSourceRef::Override(&overrides));
        let mut cache = TwoDaCache::new(&resolver);

        let loaded = cache.twoda("appearance").expect("must resolve and parse");
        assert_eq!(loaded.headers, vec!["label", "value"]);
        assert_eq!(loaded.rows.len(), 2);
        assert_eq!(loaded.rows[1].cells[0], "beta");

        let first_ptr = std::ptr::from_ref(cache.twoda("appearance").expect("must resolve"));
        let second_ptr = std::ptr::from_ref(cache.twoda("appearance").expect("must resolve"));
        assert_eq!(
            first_ptr, second_ptr,
            "cache must return the same allocation on hit"
        );
    }

    #[test]
    fn twoda_canonicalises_name_so_case_does_not_split_cache() {
        let table = fixture_table();
        let overrides = override_with_table("appearance", &table);
        let resolver = Resolver::new().with_source(ResolverSourceRef::Override(&overrides));
        let mut cache = TwoDaCache::new(&resolver);

        let lower = std::ptr::from_ref(cache.twoda("appearance").expect("must resolve"));
        let upper = std::ptr::from_ref(cache.twoda("Appearance").expect("must resolve"));
        assert_eq!(
            lower, upper,
            "case variants must hash to the same cache slot"
        );
    }

    #[test]
    fn twoda_surfaces_parse_error_when_bytes_are_invalid() {
        let mut overrides = OverrideSource::new();
        overrides
            .add_entry(
                "broken",
                ResourceTypeCode::from(ResourceType::TwoDa),
                b"not a valid 2da file".to_vec(),
                "test",
            )
            .expect("add override entry");
        let resolver = Resolver::new().with_source(ResolverSourceRef::Override(&overrides));
        let mut cache = TwoDaCache::new(&resolver);

        let err = cache.twoda("broken").expect_err("invalid bytes must error");
        assert!(matches!(
            err,
            TwoDaCacheError::Parse { name, .. } if name.to_string() == "broken"
        ));
    }

    #[test]
    fn twoda_name_as_str_returns_canonical_form() {
        let name = TwoDaName::new("Appearance").expect("valid name");
        assert_eq!(name.as_str(), "appearance");
    }

    #[test]
    fn twoda_accepts_as_str_round_trip_from_typed_name() {
        // A caller holding a TwoDaName can pass `name.as_str()` to
        // the &str entry point and reach the cached slot it would
        // have reached by passing the literal directly.
        let table = fixture_table();
        let overrides = override_with_table("appearance", &table);
        let resolver = Resolver::new().with_source(ResolverSourceRef::Override(&overrides));
        let mut cache = TwoDaCache::new(&resolver);

        let name = TwoDaName::new("appearance").expect("valid name");
        let via_literal = std::ptr::from_ref(cache.twoda("appearance").expect("must resolve"));
        let via_typed = std::ptr::from_ref(cache.twoda(name.as_str()).expect("must resolve"));
        assert_eq!(via_literal, via_typed);
    }

    #[test]
    fn missing_error_displays_table_name() {
        let name = TwoDaName::new("racialtypes").expect("valid name");
        let err = TwoDaCacheError::Missing { name };
        assert_eq!(
            format!("{err}"),
            "2DA `racialtypes` not found in resource tree"
        );
    }

    #[test]
    fn from_static_produces_valid_name_for_known_tables() {
        // Every `tables::*` entry must round-trip without panic. If a
        // future addition contains an invalid character, the const
        // initialization would fail at compile time -- this test is a
        // belt-and-suspenders check that the runtime values match.
        assert_eq!(tables::ITEMPROPDEF.as_str(), "itempropdef");
        assert_eq!(tables::BASEITEMS.as_str(), "baseitems");
        assert_eq!(tables::PORTRAITS.as_str(), "portraits");
        assert_eq!(tables::APPEARANCE.as_str(), "appearance");
    }

    #[test]
    fn twoda_accepts_typed_constant_via_as_ref() {
        // The cache method takes `impl AsRef<str>`, so a `TwoDaName`
        // (which impls AsRef<str>) is interchangeable with a `&str`
        // literal at the call site.
        let table = fixture_table();
        let overrides = override_with_table("itempropdef", &table);
        let resolver = Resolver::new().with_source(ResolverSourceRef::Override(&overrides));
        let mut cache = TwoDaCache::new(&resolver);

        let via_constant = std::ptr::from_ref(
            cache
                .twoda(tables::ITEMPROPDEF)
                .expect("constant must resolve"),
        );
        let via_literal =
            std::ptr::from_ref(cache.twoda("itempropdef").expect("literal must resolve"));
        assert_eq!(
            via_constant, via_literal,
            "typed constant and literal must hash to the same cache slot"
        );
    }

    #[test]
    fn invalid_name_error_displays_caller_input() {
        let err = TwoDaCacheError::InvalidName {
            name: "café".to_string(),
            source: ResRefError::InvalidChar { ch: 'é' },
        };
        assert_eq!(format!("{err}"), "invalid 2DA name `café`");
    }
}