musefs_core/

template.rs

use std::collections::BTreeMap;
use std::collections::BTreeSet;
use std::iter::Peekable;
use std::str::Chars;
use thiserror::Error;

/// Max surviving segments a single `$!{}` path field may expand into. A hostile
/// 256 KiB tag shaped `a/a/a/...` would otherwise build tens of thousands of
/// directory levels (depth amplification across the DB trust boundary, #303).
const MAX_PATH_FIELD_SEGMENTS: usize = 64;

/// Max `[...]` section nesting depth accepted by [`Template::parse`]. Beyond this
/// the parser rejects the template rather than recursing further (#304). Real
/// templates nest 2–3 deep; 64 is generous headroom that still bounds the
/// adversarial `[[[…` case.
const MAX_SECTION_DEPTH: usize = 64;

/// Why a template was rejected at parse time. Surfaced to the operator via
/// [`crate::CoreError::InvalidTemplate`] when `Musefs::open` parses a bad
/// `--template`.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum TemplateError {
    /// `[...]` sections nested deeper than `limit`.
    #[error("template nesting exceeds the maximum depth of {limit}")]
    NestingTooDeep { limit: usize },
    /// A literal run contains a control byte (`< 0x20`, includes NUL), which is
    /// not a valid POSIX path-component byte.
    #[error("template literal contains control byte {byte:#04x}")]
    ControlByte { byte: u8 },
    /// A `${`/`$!{` field was opened but never closed by `}` before the end of
    /// the template, e.g. `${albumartist`.
    #[error("template has an unterminated '${{' field (missing '}}')")]
    UnterminatedField,
    /// A `[...]` section was opened but never closed by `]` before the end of
    /// the template, e.g. `$album[ - $disc`.
    #[error("template has an unclosed '[' section (missing ']')")]
    UnclosedSection,
}

/// A parsed path template: literal runs, `$field` / `${field}` substitutions
/// (with optional `${a|b}` fallback chains and `$!{field}` slash-preserving path
/// fields), and `[...]` conditional sections. Parse once per mount; `render`
/// then costs one output `String` per call, with no re-parse.
#[derive(Debug, Clone)]
pub struct Template {
    parts: Vec<Part>,
}

#[derive(Debug, Clone)]
enum Part {
    Literal(String),
    /// `names` is the `|`-separated fallback chain (length 1 for a plain field);
    /// `raw` marks a `$!{…}` path field whose '/' are kept as separators.
    Field {
        names: Vec<String>,
        raw: bool,
    },
    /// A `[...]` conditional section: emitted only if at least one field
    /// referenced within it (transitively) is present.
    Section(Vec<Part>),
}

impl Template {
    /// Parse a beets-style template. Returns `Err` for a template that cannot
    /// produce valid path components: control/NUL bytes in literal text
    /// (#275), `[...]` nesting deeper than [`MAX_SECTION_DEPTH`] (#304), an
    /// unterminated `${`/`$!{` field (no closing `}`), or an unclosed `[`
    /// section (no closing `]`).
    ///
    /// - `$field` / `${field}` substitute a tag field; `${a|b|c}` is a fallback
    ///   chain (first present wins). Names are matched case-insensitively.
    /// - `$!{field}` is a path field: the value's '/' are kept as directory
    ///   separators (each segment sanitized; empty / `.` / `..` dropped).
    /// - `[...]` is a conditional section, suppressed when every field it
    ///   references is empty. `$[` and `$]` emit literal brackets.
    /// - A `$` not followed by a recognized form stays literal. An unterminated
    ///   `${`/`$!{` (missing `}`) or an unclosed `[` section (missing `]`) is a
    ///   parse error.
    pub fn parse(template: &str) -> Result<Template, TemplateError> {
        let mut chars = template.chars().peekable();
        let parts = parse_parts(&mut chars, 0)?;
        Ok(Template { parts })
    }

    /// The set of field names this template references, across plain fields,
    /// `$!{}` path fields, `|` fallback chains, and `[...]` sections. Names
    /// are already ASCII-lowercased at parse time, matching `tags_to_fields`'s
    /// key folding, so a key-filtered tag load (`Db::tags_grouped_for_keys`)
    /// fetches exactly what rendering consumes.
    pub fn referenced_fields(&self) -> BTreeSet<String> {
        let mut out = BTreeSet::new();
        collect_field_names(&self.parts, &mut out);
        out
    }

    /// Render one track's path. Outside a section a missing field resolves
    /// through `fallbacks` then `default_fallback`; inside a section a missing
    /// field renders blank and drives suppression. The extension follows a '.'.
    pub fn render(
        &self,
        fields: &BTreeMap<String, &str>,
        fallbacks: &BTreeMap<String, String>,
        default_fallback: &str,
        ext: &str,
    ) -> String {
        let (mut out, _, _) = render_parts(&self.parts, fields, fallbacks, default_fallback, false);
        out.push('.');
        out.push_str(ext);
        out
    }

    /// Like [`render`](Self::render), but returns `None` when any *top-level*
    /// (non-section) field is unresolved — the caller's signal to skip the track
    /// rather than substitute `default_fallback`. Per-field fallback chains and
    /// `[...]` sections behave exactly as in `render`; only the top-level default
    /// substitution is replaced by the skip. Backs `--skip-on-missing`.
    pub fn render_checked(
        &self,
        fields: &BTreeMap<String, &str>,
        fallbacks: &BTreeMap<String, String>,
        ext: &str,
    ) -> Option<String> {
        let (mut out, _, top_complete) = render_parts(&self.parts, fields, fallbacks, "", false);
        if !top_complete {
            return None;
        }
        out.push('.');
        out.push_str(ext);
        Some(out)
    }
}

/// Parse parts until a closing `]` (when `depth > 0`) or end of input. `depth`
/// is the current `[...]` nesting level (0 = top level). A section opened at
/// `depth > 0` that reaches end of input without its `]` is rejected as
/// [`TemplateError::UnclosedSection`].
fn parse_parts(chars: &mut Peekable<Chars>, depth: usize) -> Result<Vec<Part>, TemplateError> {
    let mut parts = Vec::new();
    let mut literal = String::new();
    let mut closed = false;
    while let Some(&c) = chars.peek() {
        match c {
            ']' if depth > 0 => {
                chars.next(); // consume the closing ']'
                closed = true;
                break;
            }
            '[' => {
                chars.next();
                push_literal(&mut parts, &mut literal);
                if depth + 1 > MAX_SECTION_DEPTH {
                    return Err(TemplateError::NestingTooDeep {
                        limit: MAX_SECTION_DEPTH,
                    });
                }
                let inner = parse_parts(chars, depth + 1)?;
                parts.push(Part::Section(inner));
            }
            '$' => {
                chars.next(); // consume '$'
                match chars.peek() {
                    Some('[') => {
                        chars.next();
                        literal.push('[');
                    }
                    Some(']') => {
                        chars.next();
                        literal.push(']');
                    }
                    Some('{') => {
                        chars.next();
                        let names = parse_braced_names(chars)?;
                        push_literal(&mut parts, &mut literal);
                        parts.push(Part::Field { names, raw: false });
                    }
                    Some('!') => {
                        chars.next(); // consume '!'
                        if chars.peek() == Some(&'{') {
                            chars.next(); // consume '{'
                            let names = parse_braced_names(chars)?;
                            push_literal(&mut parts, &mut literal);
                            parts.push(Part::Field { names, raw: true });
                        } else {
                            literal.push('$');
                            literal.push('!');
                        }
                    }
                    Some(&nc) if is_field_char(nc) => {
                        let name = parse_unbraced_name(chars);
                        push_literal(&mut parts, &mut literal);
                        parts.push(Part::Field {
                            names: vec![name],
                            raw: false,
                        });
                    }
                    _ => literal.push('$'),
                }
            }
            _ => {
                if (c as u32) < 0x20 {
                    return Err(TemplateError::ControlByte { byte: c as u8 });
                }
                literal.push(c);
                chars.next();
            }
        }
    }
    push_literal(&mut parts, &mut literal);
    if depth > 0 && !closed {
        return Err(TemplateError::UnclosedSection);
    }
    Ok(parts)
}

fn push_literal(parts: &mut Vec<Part>, literal: &mut String) {
    if !literal.is_empty() {
        parts.push(Part::Literal(std::mem::take(literal)));
    }
}

/// Consume up to the next `}` and split on `|` into the candidate name list,
/// lowercased for case-insensitive lookup. Reaching end of input before the
/// closing `}` is a [`TemplateError::UnterminatedField`].
fn parse_braced_names(chars: &mut Peekable<Chars>) -> Result<Vec<String>, TemplateError> {
    let mut content = String::new();
    let mut closed = false;
    for nc in chars.by_ref() {
        if nc == '}' {
            closed = true;
            break;
        }
        content.push(nc);
    }
    if !closed {
        return Err(TemplateError::UnterminatedField);
    }
    Ok(content.split('|').map(str::to_ascii_lowercase).collect())
}

fn parse_unbraced_name(chars: &mut Peekable<Chars>) -> String {
    let mut name = String::new();
    while let Some(&nc) = chars.peek() {
        if is_field_char(nc) {
            name.push(nc);
            chars.next();
        } else {
            break;
        }
    }
    name.to_ascii_lowercase()
}

fn collect_field_names(parts: &[Part], out: &mut BTreeSet<String>) {
    for part in parts {
        match part {
            Part::Literal(_) => {}
            Part::Field { names, .. } => {
                for name in names {
                    out.insert(name.clone());
                }
            }
            Part::Section(inner) => collect_field_names(inner, out),
        }
    }
}

/// Render `parts`, returning the text, whether at least one referenced field
/// was present, and whether every *top-level* field resolved (no
/// `default_fallback` substitution was needed). `in_section` gates
/// `default_fallback`: it is substituted only at the top level (outside any
/// `[...]`), and only a top-level miss clears `top_complete`.
fn render_parts(
    parts: &[Part],
    fields: &BTreeMap<String, &str>,
    fallbacks: &BTreeMap<String, String>,
    default_fallback: &str,
    in_section: bool,
) -> (String, bool, bool) {
    let mut out = String::new();
    let mut any_present = false;
    let mut top_complete = true;
    for part in parts {
        match part {
            Part::Literal(lit) => out.push_str(lit),
            Part::Field { names, raw: false } => {
                if let Some(value) = resolve_plain(names, fields, fallbacks) {
                    sanitize_into(&mut out, value);
                    any_present = true;
                } else if !in_section {
                    sanitize_into(&mut out, default_fallback);
                    top_complete = false;
                }
            }
            Part::Field { names, raw: true } => {
                if let Some(path) = resolve_path(names, fields, fallbacks) {
                    out.push_str(&path);
                    any_present = true;
                } else if !in_section {
                    sanitize_into(&mut out, default_fallback);
                    top_complete = false;
                }
            }
            Part::Section(inner) => {
                let (text, present, _) =
                    render_parts(inner, fields, fallbacks, default_fallback, true);
                if present {
                    out.push_str(&text);
                    any_present = true;
                }
            }
        }
    }
    (out, any_present, top_complete)
}

/// First candidate with a non-empty value, checked against `fields` then
/// `fallbacks`.
fn resolve_plain<'a>(
    names: &[String],
    fields: &BTreeMap<String, &'a str>,
    fallbacks: &'a BTreeMap<String, String>,
) -> Option<&'a str> {
    for name in names {
        if let Some(v) = fields.get(name).copied().filter(|v| !v.is_empty()) {
            return Some(v);
        }
        if let Some(v) = fallbacks
            .get(name)
            .map(String::as_str)
            .filter(|v| !v.is_empty())
        {
            return Some(v);
        }
    }
    None
}

/// First candidate that yields at least one surviving path segment, returned as
/// the sanitized multi-segment path.
fn resolve_path(
    names: &[String],
    fields: &BTreeMap<String, &str>,
    fallbacks: &BTreeMap<String, String>,
) -> Option<String> {
    for name in names {
        let value = fields
            .get(name)
            .copied()
            .or_else(|| fallbacks.get(name).map(String::as_str));
        if let Some(value) = value {
            let path = sanitize_path(value);
            if !path.is_empty() {
                return Some(path);
            }
        }
    }
    None
}

/// Append `value` with '/' and control characters replaced by '_' so it stays a
/// single path component. The template's own '/' separators are literals, not
/// passed through here.
fn sanitize_into(out: &mut String, value: &str) {
    for c in value.chars() {
        if c == '/' || (c as u32) < 0x20 {
            out.push('_');
        } else {
            out.push(c);
        }
    }
}

/// Split `value` on '/', drop empty / `.` / `..` segments, sanitize each
/// surviving segment, and rejoin with '/'. Guarantees no empty, `.`, `..`, or
/// leading/trailing-slash components reach the virtual tree. Stops after
/// `MAX_PATH_FIELD_SEGMENTS` surviving segments, bounding the depth a single
/// hostile path-field value can amplify into (#303).
fn sanitize_path(value: &str) -> String {
    let mut out = String::new();
    let mut count = 0usize;
    for segment in value.split('/') {
        if count == MAX_PATH_FIELD_SEGMENTS {
            break;
        }
        if segment.is_empty() || segment == "." || segment == ".." {
            continue;
        }
        if !out.is_empty() {
            out.push('/');
        }
        sanitize_into(&mut out, segment);
        count += 1;
    }
    out
}

fn is_field_char(c: char) -> bool {
    c.is_ascii_alphanumeric() || c == '_'
}

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

    #[test]
    fn referenced_fields_collects_plain_path_section_and_fallback_names() {
        let t = Template::parse("$artist/$!{beets_path}/[$disc - ]${title|name}")
            .expect("valid template");
        let f = t.referenced_fields();
        assert!(f.contains("artist"));
        assert!(f.contains("beets_path"));
        assert!(f.contains("disc"));
        assert!(f.contains("title"));
        assert!(f.contains("name"));
        // No spurious entries from literals.
        assert_eq!(f.len(), 5);
    }

    #[test]
    fn nesting_at_limit_parses_one_past_limit_rejected() {
        let at_limit = "[".repeat(MAX_SECTION_DEPTH) + &"]".repeat(MAX_SECTION_DEPTH);
        assert!(
            Template::parse(&at_limit).is_ok(),
            "{MAX_SECTION_DEPTH} deep parses"
        );

        let past_limit = "[".repeat(MAX_SECTION_DEPTH + 1);
        assert!(matches!(
            Template::parse(&past_limit),
            Err(TemplateError::NestingTooDeep { limit }) if limit == MAX_SECTION_DEPTH
        ));
    }
}