n3_lib/

records.rs

//! Editable wire records driven by audited declarative binary layouts.
//!
//! Float fields contain unsigned IEEE-754 storage bits, not JSON floats.
//! Strings and opaque byte ranges contain lowercase hexadecimal strings.
//! This representation preserves nonfinite values and undecodable text.

use crate::binary::{Error, Reader, Result, Writer};
use serde_json::{Map, Value, json};
use std::sync::OnceLock;

/// Supported storage-record format names, excluding the leading dot.
pub(crate) const RECORD_FORMATS: &[&str] = &[
    "n3pmesh", "n3cskin", "n3cskins", "n3cpart", "n3cplug", "n3shape", "n3chr", "n3joint",
    "n3anim", "n3fxplug", "n3sky", "fxb", "gtd", "opd", "uif",
];

/// Editable JSON-compatible storage record with raw float bits and hex strings.
pub type Record = Map<String, Value>;

/// Resource budgets applied before traversing untrusted records.
#[derive(Clone, Debug)]
pub struct Limits {
    /// Maximum input or output bytes.
    pub bytes: usize,
    /// Maximum traversal nodes, including scalar values.
    pub nodes: usize,
    /// Maximum nested traversal depth.
    pub depth: usize,
    /// Explicit nonserialized layout parameters, such as OPD gridCell and UIF fileVersion.
    pub parameters: std::collections::BTreeMap<String, i64>,
}
impl Default for Limits {
    fn default() -> Self {
        Self {
            bytes: 256 * 1024 * 1024,
            nodes: 8_000_000,
            depth: 128,
            parameters: Default::default(),
        }
    }
}

fn error(message: impl Into<String>) -> Error {
    Error {
        offset: 0,
        message: message.into(),
    }
}
fn definitions() -> &'static Value {
    static SCHEMAS: OnceLock<Value> = OnceLock::new();
    SCHEMAS.get_or_init(|| {
        serde_json::from_str(include_str!("../layouts.json")).expect("Valid bundled format layouts")
    })
}

/// Encode original bytes as lowercase hexadecimal.
pub fn hex(bytes: &[u8]) -> String {
    bytes.iter().map(|byte| format!("{byte:02x}")).collect()
}
/// Decode validated hexadecimal without lossy string substitutions.
pub fn unhex(value: &str) -> Result<Vec<u8>> {
    if !value.len().is_multiple_of(2) || !value.bytes().all(|byte| byte.is_ascii_hexdigit()) {
        return Err(error("Invalid hex byte string"));
    }
    value
        .as_bytes()
        .as_chunks::<2>()
        .0
        .iter()
        .map(|pair| {
            let digit = |byte: u8| match byte {
                b'0'..=b'9' => byte - b'0',
                b'a'..=b'f' => byte - b'a' + 10,
                _ => byte - b'A' + 10,
            };
            Ok(digit(pair[0]) * 16 + digit(pair[1]))
        })
        .collect()
}
/// Store UTF-8 text without changing the wire string representation.
pub fn utf8(value: &str) -> String {
    hex(value.as_bytes())
}

fn expr(value: &Value, context: &Value) -> Result<i64> {
    if let Some(number) = value.as_i64() {
        return Ok(number);
    }
    if let Some(name) = value.as_str() {
        return context[name]
            .as_i64()
            .ok_or_else(|| error(format!("Missing numeric field {name}")));
    }
    if let Some(parts) = value["product"].as_array() {
        return parts.iter().try_fold(1_i64, |product, part| {
            product
                .checked_mul(expr(part, context)?)
                .ok_or_else(|| error("Size overflow"))
        });
    }
    if let Some(parts) = value["gt"].as_array() {
        return Ok(i64::from(
            expr(&parts[0], context)? > expr(&parts[1], context)?,
        ));
    }
    if let Some(parts) = value["eq"].as_array() {
        return Ok(i64::from(
            expr(&parts[0], context)? == expr(&parts[1], context)?,
        ));
    }
    if let Some(parts) = value["minus"].as_array() {
        return expr(&parts[0], context)?
            .checked_sub(expr(&parts[1], context)?)
            .ok_or_else(|| error("Expression overflow"));
    }
    if let Some(parts) = value["divide"].as_array() {
        let divisor = expr(&parts[1], context)?;
        if divisor <= 0 {
            return Err(error("Invalid layout divisor"));
        }
        return Ok(expr(&parts[0], context)?.div_euclid(divisor));
    }
    if let Some(parts) = value["mask"].as_array() {
        return Ok(expr(&parts[0], context)? & expr(&parts[1], context)?);
    }
    if let Some(parts) = value["and"].as_array() {
        for part in parts {
            if expr(part, context)? == 0 {
                return Ok(0);
            }
        }
        return Ok(1);
    }
    if let Some(parts) = value["or"].as_array() {
        for part in parts {
            if expr(part, context)? != 0 {
                return Ok(1);
            }
        }
        return Ok(0);
    }
    if !value["float"].is_null() {
        let number = f32::from_bits(
            u32::try_from(expr(&value["float"], context)?)
                .map_err(|_| error("Invalid f32 bits"))?,
        );
        if !number.is_finite() {
            return Err(error("Nonfinite layout dimension"));
        }
        return Ok(number.floor() as i64);
    }
    if let Some(name) = value["length"].as_str() {
        return context[name]
            .as_str()
            .map(|text| text.len() as i64 / 2)
            .ok_or_else(|| error("Expected hex string"));
    }
    if let Some(parts) = value["choose"].as_array() {
        return expr(
            &parts[if expr(&parts[0], context)? != 0 { 1 } else { 2 }],
            context,
        );
    }
    if let Some(parts) = value["select"].as_array() {
        let tag = expr(&parts[0], context)?;
        if !(0..=1).contains(&tag) {
            return Err(error("Unsupported animation key type"));
        }
        return expr(&parts[tag as usize + 1], context);
    }
    Err(error("Invalid layout expression"))
}
fn count(value: &Value, context: &Value) -> Result<usize> {
    let value = expr(value, context)?;
    if !(0..=8_000_000).contains(&value) {
        return Err(error("Invalid array count"));
    }
    Ok(value as usize)
}
fn minimum(schema: &Value) -> usize {
    if let Some(name) = schema.as_str() {
        if name == "ntf" {
            return 24;
        }
        if !definitions()[name].is_null() {
            return minimum(&definitions()[name]);
        }
        return match name {
            "string" | "f32" | "u32" | "i32" => 4,
            "u16" | "i16" => 2,
            _ => 1,
        };
    }
    if schema["kind"] == "struct" {
        return schema["fields"].as_array().map_or(0, |fields| {
            fields
                .iter()
                .filter(|field| field["when"].is_null() && field["optional"] != true)
                .map(|field| minimum(&field["type"]))
                .sum()
        });
    }
    if schema["kind"] == "choice" {
        return minimum(&schema["yes"]).min(minimum(&schema["no"]));
    }
    schema["count"].as_u64().map_or(0, |count| {
        count as usize
            * if schema["kind"] == "bytes" {
                1
            } else {
                minimum(&schema["item"])
            }
    })
}
enum Io<'a> {
    Read(Reader<'a>),
    Write(Writer),
}
struct State<'a> {
    io: Io<'a>,
    nodes: usize,
    depth: usize,
    parameters: std::collections::BTreeMap<String, i64>,
}
fn scope(parent: &Value, local: &Value) -> Value {
    let mut scope = Map::new();
    for value in [parent, local] {
        if let Some(fields) = value.as_object() {
            for (name, value) in fields {
                if value.is_number() || value.is_string() {
                    scope.insert(name.clone(), value.clone());
                }
            }
        }
    }
    Value::Object(scope)
}
impl State<'_> {
    fn reading(&self) -> bool {
        matches!(self.io, Io::Read(_))
    }
    fn traverse(
        &mut self,
        schema: &Value,
        context: &Value,
        input: &Value,
        depth: usize,
    ) -> Result<Value> {
        if self.nodes == 0 || depth > self.depth {
            return Err(error("Record complexity limit exceeded"));
        }
        self.nodes -= 1;
        if let Some(name) = schema.as_str() {
            if name == "ntf" {
                return match &mut self.io {
                    Io::Read(reader) => {
                        serde_json::to_value(crate::textures::read_texture(reader)?)
                            .map_err(|_| error("Texture serialization failed"))
                    }
                    Io::Write(writer) => {
                        let texture = serde_json::from_value(input.clone())
                            .map_err(|_| error("Invalid texture record"))?;
                        crate::textures::append_texture(writer, &texture)?;
                        Ok(input.clone())
                    }
                };
            }
            if !definitions()[name].is_null() {
                return self.traverse(&definitions()[name], context, input, depth + 1);
            }
            return match &mut self.io {
                Io::Read(reader) => Ok(match name {
                    "string" => json!(hex(&reader.string(1_048_576)?)),
                    "u8" => json!(reader.u8()?),
                    "i8" => json!(reader.i8()?),
                    "u16" => json!(reader.u16()?),
                    "i16" => json!(reader.i16()?),
                    "u32" | "f32" => json!(reader.u32()?),
                    "i32" => json!(reader.i32()?),
                    _ => return Err(error("Unknown primitive")),
                }),
                Io::Write(writer) => {
                    if name == "string" {
                        writer.string(&unhex(
                            input.as_str().ok_or_else(|| error("Expected hex string"))?,
                        )?)?;
                    } else {
                        let value = input
                            .as_i64()
                            .ok_or_else(|| error("Expected integer wire value"))?;
                        let invalid = |_| error(format!("Value outside {name} range"));
                        match name {
                            "u8" => writer.u8(u8::try_from(value).map_err(invalid)?)?,
                            "i8" => writer.i8(i8::try_from(value).map_err(invalid)?)?,
                            "u16" => writer.u16(u16::try_from(value).map_err(invalid)?)?,
                            "i16" => writer.i16(i16::try_from(value).map_err(invalid)?)?,
                            "u32" | "f32" => writer.u32(u32::try_from(value).map_err(invalid)?)?,
                            "i32" => writer.i32(i32::try_from(value).map_err(invalid)?)?,
                            _ => return Err(error("Unknown primitive")),
                        }
                    }
                    Ok(input.clone())
                }
            };
        }
        if schema["kind"] == "choice" {
            return self.traverse(
                &schema[if expr(&schema["condition"], context)? != 0 {
                    "yes"
                } else {
                    "no"
                }],
                context,
                input,
                depth + 1,
            );
        }
        if schema["kind"] == "parameter" {
            let name = schema["name"].as_str().unwrap();
            let value = if self.reading() {
                self.parameters
                    .get(name)
                    .copied()
                    .unwrap_or(schema["default"].as_i64().unwrap())
            } else {
                input
                    .as_i64()
                    .ok_or_else(|| error("Missing layout parameter"))?
            };
            if !(0..=65536).contains(&value) {
                return Err(error("Invalid layout parameter"));
            }
            return Ok(json!(value));
        }
        if schema["kind"] == "tail" {
            return match &mut self.io {
                Io::Read(reader) => Ok(json!(hex(reader.raw(reader.remaining())?))),
                Io::Write(writer) => {
                    writer.raw(&unhex(
                        input
                            .as_str()
                            .ok_or_else(|| error("Expected tail hex bytes"))?,
                    )?)?;
                    Ok(input.clone())
                }
            };
        }
        if schema["kind"] == "struct" {
            let fields = schema["fields"]
                .as_array()
                .ok_or_else(|| error("Missing layout fields"))?;
            let mut result = if self.reading() {
                json!({})
            } else {
                if !input.is_object() {
                    return Err(error("Expected record"));
                }
                input.clone()
            };
            if !self.reading() {
                for field in fields {
                    if let Some(array) = field["sizeOf"].as_str() {
                        if !field["when"].is_null()
                            && expr(&field["when"], &scope(context, &result))? == 0
                        {
                            continue;
                        }
                        if result.get(array).is_none()
                            && (field["optional"] == true
                                || result[field["name"].as_str().unwrap()] == 0)
                        {
                            continue;
                        }
                        let length = result[array]
                            .as_array()
                            .ok_or_else(|| error(format!("Expected array {array}")))?
                            .len();
                        result[field["name"].as_str().unwrap()] = json!(length);
                    }
                }
            }
            let mut omitted = false;
            for field in fields {
                let name = field["name"].as_str().unwrap();
                if !field["when"].is_null() && expr(&field["when"], &scope(context, &result))? == 0
                {
                    continue;
                }
                let absent = match &self.io {
                    Io::Read(reader) => reader.remaining() == 0,
                    Io::Write(_) => result.get(name).is_none(),
                };
                if field["optional"] == true && absent {
                    omitted = true;
                    continue;
                }
                if omitted {
                    return Err(error("Optional tail fields must form a contiguous prefix"));
                }
                result[name] = self.traverse(
                    &field["type"],
                    &scope(context, &result),
                    &result[name],
                    depth + 1,
                )?;
            }
            return Ok(result);
        }
        let length = count(&schema["count"], context)?;
        if schema["kind"] == "bytes" {
            return match &mut self.io {
                Io::Read(reader) => Ok(json!(hex(reader.raw(length)?))),
                Io::Write(writer) => {
                    let bytes = unhex(
                        input
                            .as_str()
                            .ok_or_else(|| error("Expected opaque hex bytes"))?,
                    )?;
                    if bytes.len() != length {
                        return Err(error("Opaque byte count mismatch"));
                    }
                    writer.raw(&bytes)?;
                    Ok(input.clone())
                }
            };
        }
        if length > self.nodes {
            return Err(error("Array exceeds node budget"));
        }
        if let Io::Read(reader) = &self.io
            && length.saturating_mul(minimum(&schema["item"]).max(1)) > reader.remaining()
        {
            return Err(error("Array exceeds available bytes"));
        }
        if !self.reading() && input.as_array().is_none_or(|array| array.len() != length) {
            return Err(error("Array count mismatch"));
        }
        let mut values = Vec::new();
        values
            .try_reserve(length)
            .map_err(|_| error("Array allocation failed"))?;
        for index in 0..length {
            values.push(self.traverse(&schema["item"], context, &input[index], depth + 1)?);
        }
        Ok(Value::Array(values))
    }
}

/// Parse a complete known-layout record under default safety budgets.
pub(crate) fn parse_record(format: &str, bytes: &[u8]) -> Result<Record> {
    parse_record_with_limits(format, bytes, Limits::default())
}
/// Parse a record with explicit byte, node and depth budgets.
pub(crate) fn parse_record_with_limits(
    format: &str,
    bytes: &[u8],
    limits: Limits,
) -> Result<Record> {
    if !RECORD_FORMATS.contains(&format) {
        return Err(error(format!("Unknown record format {format}")));
    }
    if bytes.len() > limits.bytes {
        return Err(error("Input byte budget exceeded"));
    }
    let mut state = State {
        io: Io::Read(Reader::new(bytes)),
        nodes: limits.nodes,
        depth: limits.depth,
        parameters: limits.parameters,
    };
    let record = state.traverse(&json!(format), &json!({}), &Value::Null, 0)?;
    if let Io::Read(reader) = state.io {
        reader.end()?;
    }
    validate(format, &record)?;
    Ok(record.as_object().unwrap().clone())
}
/// Serialize a new or edited record, deriving count prefixes from their arrays.
pub(crate) fn write_record(format: &str, record: &Record) -> Result<Vec<u8>> {
    write_record_with_limits(format, record, Limits::default())
}
/// Serialize and validate edited records under explicit safety budgets.
pub(crate) fn write_record_with_limits(
    format: &str,
    record: &Record,
    mut limits: Limits,
) -> Result<Vec<u8>> {
    if !RECORD_FORMATS.contains(&format) {
        return Err(error("Unknown record format"));
    }
    let mut state = State {
        io: Io::Write(Writer::new(limits.bytes)),
        nodes: limits.nodes,
        depth: limits.depth,
        parameters: limits.parameters.clone(),
    };
    state.traverse(
        &json!(format),
        &json!({}),
        &Value::Object(record.clone()),
        0,
    )?;
    let Io::Write(writer) = state.io else {
        unreachable!()
    };
    let bytes = writer.finish();
    for name in ["gridCell", "fileVersion", "spacingPresent", "type"] {
        if let Some(value) = record.get(name).and_then(Value::as_i64) {
            limits.parameters.insert(name.into(), value);
        }
    }
    parse_record_with_limits(format, &bytes, limits)?;
    Ok(bytes)
}
fn validate(format: &str, record: &Value) -> Result<()> {
    if format == "fxb" {
        if !matches!(record["version"].as_i64(), Some(0..=3)) {
            return Err(error("Unsupported FXB version"));
        }
        for slot in record["slots"].as_array().unwrap() {
            if !matches!(slot["type"].as_i64(), Some(0..=4)) {
                return Err(error("Unsupported FXB part type"));
            }
            if slot["type"] != 0
                && (!matches!(slot["version"].as_i64(), Some(0..=7))
                    || !matches!(slot["baseVersion"].as_i64(), Some(0..=2)))
            {
                return Err(error("Unsupported FXB part version"));
            }
        }
        if record["version"] == 3
            && !matches!(record["trailer"].as_str().unwrap_or("").len(), 88 | 90)
        {
            return Err(error("FXB v3 requires its observed 44/45-byte trailer"));
        }
    }
    if format == "gtd"
        && (!matches!(record["version"].as_i64(), Some(0..=2))
            || !matches!(record["mapSize"].as_i64(), Some(1..=4097)))
    {
        return Err(error("Invalid GTD version or dimensions"));
    }
    if format == "opd" && !matches!(record["gridCell"].as_i64(), Some(1..=1024)) {
        return Err(error("Invalid OPD grid cell"));
    }
    if format == "n3pmesh" {
        let vertices = record["vertexCount"].as_i64().unwrap_or(-1);
        let indices = record["indices"].as_array().unwrap();
        if !(1..=2_000_000).contains(&vertices)
            || indices.is_empty()
            || !indices.len().is_multiple_of(3)
            || indices
                .iter()
                .any(|index| index.as_i64().unwrap_or(-1) >= vertices)
        {
            return Err(error("Invalid mesh vertices or indices"));
        }
        if !(0..=vertices).contains(&record["minVertexCount"].as_i64().unwrap_or(-1))
            || !(0..=indices.len() as i64).contains(&record["minIndexCount"].as_i64().unwrap_or(-1))
        {
            return Err(error("Invalid minimum mesh counts"));
        }
    }
    if format == "n3cskin" {
        let vertices = record["vertexCount"].as_i64().unwrap_or(-1);
        let uvs = record["uvCount"].as_i64().unwrap_or(-1);
        for (field, maximum) in [("vertexIndices", vertices), ("uvIndices", uvs)] {
            if record[field]
                .as_array()
                .unwrap()
                .iter()
                .any(|index| index.as_i64().unwrap_or(-1) >= maximum)
            {
                return Err(error("Skin index out of range"));
            }
        }
        let faces = record["faceCount"].as_i64().unwrap_or(-1);
        if (vertices == 0 || faces == 0) && (vertices != 0 || faces != 0 || uvs != 0) {
            return Err(error("Inconsistent empty skin"));
        }
    }
    if format == "n3cskins" {
        for lod in record["lods"].as_array().unwrap() {
            validate("n3cskin", lod)?;
        }
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn sky_roundtrip_and_edit() -> Result<()> {
        let value = json!({"suns":["00ff","", ""],"clouds":["","","","","",""],"moon":"", "dayChanges":[{"name":"202000", "type":0,"when":500,"param1":4294967295_u32,"param2":0,"howLong":2141266757_u32}]});
        let bytes = write_record("n3sky", value.as_object().unwrap())?;
        let mut record = parse_record("n3sky", &bytes)?;
        assert_eq!(write_record("n3sky", &record)?, bytes);
        record.insert("moon".into(), json!(utf8("new moon")));
        assert_eq!(
            parse_record("n3sky", &write_record("n3sky", &record)?)?["moon"],
            utf8("new moon")
        );
        assert!(parse_record("n3sky", &bytes[..bytes.len() - 1]).is_err());
        Ok(())
    }
}