mediaway_test_media/

lib.rs

//! Deterministic test-media generators with a **local gitignored cache**.
//!
//! Cache hits are validated with **BLAKE3** against an expected digest — same
//! path alone is not enough. Binaries must not be committed — see
//! `docs/conventions/testing.md`.

#![forbid(unsafe_code)]

use std::fs::{self, File};
use std::io::{self, Read, Write};
use std::path::{Path, PathBuf};

use thiserror::Error;

/// Default cache directory name under the workspace root.
pub const DEFAULT_CACHE_DIR_NAME: &str = "local/.cache/test-media";

/// BLAKE3 hex digest of a 64×64 opaque red RGBA8 frame (`solid/red_64x64.rgba`).
///
/// Recompute with `hash_bytes(&solid_rgba8_bytes(64, 64, [255, 0, 0, 255]))` if the
/// generator pattern changes.
pub const SOLID_RED_64X64_BLAKE3: &str =
    "a78b4d88cbe2168f9532786db54838c1ae324e2b051c8305ef53eb9bab9602ea";

/// Errors from fixture ensure / generate.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum TestMediaError {
    /// I/O failure while reading or writing the cache.
    #[error("io error: {0}")]
    Io(#[from] io::Error),
    /// Workspace root could not be located.
    #[error("could not locate workspace root (set MEDIAWAY_TEST_MEDIA_CACHE)")]
    WorkspaceRootNotFound,
    /// Cached or generated bytes do not match the expected BLAKE3 digest.
    #[error("hash mismatch for {path}: expected {expected}, got {actual}")]
    HashMismatch {
        /// Fixture path (cache file).
        path: PathBuf,
        /// Expected lowercase hex digest.
        expected: String,
        /// Actual lowercase hex digest.
        actual: String,
    },
    /// Expected digest string is not 64 hex chars.
    #[error("invalid expected blake3 hex (want 64 lowercase hex chars): {0}")]
    InvalidExpectedHash(String),
}

/// Resolve the local fixture cache directory.
///
/// Order: `MEDIAWAY_TEST_MEDIA_CACHE` env → `<workspace>/local/.cache/test-media`.
pub fn cache_dir() -> Result<PathBuf, TestMediaError> {
    if let Ok(p) = std::env::var("MEDIAWAY_TEST_MEDIA_CACHE") {
        return Ok(PathBuf::from(p));
    }
    let root = workspace_root()?;
    Ok(root.join(DEFAULT_CACHE_DIR_NAME))
}

fn workspace_root() -> Result<PathBuf, TestMediaError> {
    let mut dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
    for _ in 0..8 {
        let candidate = dir.join("Cargo.toml");
        if candidate.is_file() {
            let text = fs::read_to_string(&candidate)?;
            if text.contains("[workspace]") {
                return Ok(dir);
            }
        }
        if !dir.pop() {
            break;
        }
    }
    Err(TestMediaError::WorkspaceRootNotFound)
}

/// BLAKE3 hex digest of a file (streaming).
pub fn hash_file(path: &Path) -> Result<String, TestMediaError> {
    let mut file = File::open(path)?;
    let mut hasher = blake3::Hasher::new();
    let mut buf = vec![0_u8; 64 * 1024];
    loop {
        let n = file.read(&mut buf)?;
        if n == 0 {
            break;
        }
        hasher.update(&buf[..n]);
    }
    Ok(hasher.finalize().to_hex().to_string())
}

/// BLAKE3 hex digest of an in-memory buffer.
#[must_use]
pub fn hash_bytes(data: &[u8]) -> String {
    blake3::hash(data).to_hex().to_string()
}

fn normalize_expected_hex(expected: &str) -> Result<String, TestMediaError> {
    let lower = expected.trim().to_ascii_lowercase();
    if lower.len() != 64 || !lower.chars().all(|c| c.is_ascii_hexdigit()) {
        // clone: error owns the original invalid string for Display
        return Err(TestMediaError::InvalidExpectedHash(expected.to_owned()));
    }
    Ok(lower)
}

fn verify_hash(path: &Path, expected_hex: &str) -> Result<(), TestMediaError> {
    let expected = normalize_expected_hex(expected_hex)?;
    let actual = hash_file(path)?;
    if actual != expected {
        return Err(TestMediaError::HashMismatch {
            path: path.to_path_buf(),
            expected,
            actual,
        });
    }
    Ok(())
}

/// Ensure `relative_name` exists under the cache **and** matches `expected_blake3_hex`.
///
/// - Cache hit + matching hash → return path.
/// - Missing or hash mismatch → regenerate, then verify (generator drift fails loudly).
///
/// `relative_name` uses `/` separators (e.g. `solid/red_64x64.rgba`).
pub fn ensure(
    relative_name: &str,
    expected_blake3_hex: &str,
    generate: impl FnOnce(&Path) -> Result<(), TestMediaError>,
) -> Result<PathBuf, TestMediaError> {
    let expected = normalize_expected_hex(expected_blake3_hex)?;
    let path = cache_dir()?.join(relative_name.replace('/', std::path::MAIN_SEPARATOR_STR));

    if path.is_file() && verify_hash(&path, &expected).is_ok() {
        return Ok(path);
    }

    if let Some(parent) = path.parent() {
        fs::create_dir_all(parent)?;
    }
    if path.is_file() {
        fs::remove_file(&path)?;
    }
    generate(&path)?;
    verify_hash(&path, &expected)?;
    Ok(path)
}

/// Write a solid-color packed RGBA8 frame (`width * height * 4` bytes).
pub fn write_solid_rgba8(
    path: &Path,
    width: u32,
    height: u32,
    rgba: [u8; 4],
) -> Result<(), TestMediaError> {
    let mut file = File::create(path)?;
    let mut row = Vec::with_capacity(width as usize * 4);
    for _ in 0..width {
        row.extend_from_slice(&rgba);
    }
    for _ in 0..height {
        file.write_all(&row)?;
    }
    Ok(())
}

/// In-memory solid RGBA8 buffer (for digest computation / tiny fixtures).
#[must_use]
pub fn solid_rgba8_bytes(width: u32, height: u32, rgba: [u8; 4]) -> Vec<u8> {
    let mut out = Vec::with_capacity(width as usize * height as usize * 4);
    for _ in 0..(width * height) {
        out.extend_from_slice(&rgba);
    }
    out
}

/// Ensure a 64×64 opaque red RGBA8 fixture (`solid/red_64x64.rgba`).
pub fn ensure_solid_red_64x64() -> Result<PathBuf, TestMediaError> {
    ensure("solid/red_64x64.rgba", SOLID_RED_64X64_BLAKE3, |path| {
        write_solid_rgba8(path, 64, 64, [255, 0, 0, 255])
    })
}

/// BLAKE3 hex digest of a 64×64 mid-gray NV12 frame (`solid/gray_nv12_64x64.yuv`).
///
/// Recompute with `hash_bytes(&solid_nv12_bytes(64, 64, 128, 128, 128))` if the
/// generator pattern changes.
pub const SOLID_GRAY_NV12_64X64_BLAKE3: &str =
    "7f1b18528da0f7179df926ff90ccd1c4997564d1a970729a0c2f3c75365bf5cd";

/// Write a solid-color NV12 frame: `width * height` luma bytes, then
/// `width * height / 2` bytes of interleaved chroma (`U, V, U, V, …` per row).
pub fn write_solid_nv12(
    path: &Path,
    width: u32,
    height: u32,
    luma: u8,
    chroma_u: u8,
    chroma_v: u8,
) -> Result<(), TestMediaError> {
    let mut file = File::create(path)?;
    let y_row = vec![luma; width as usize];
    for _ in 0..height {
        file.write_all(&y_row)?;
    }
    let uv_row = uv_row_bytes(width, chroma_u, chroma_v);
    for _ in 0..(height / 2) {
        file.write_all(&uv_row)?;
    }
    Ok(())
}

/// In-memory solid-color NV12 buffer (layout matches [`write_solid_nv12`]).
#[must_use]
pub fn solid_nv12_bytes(width: u32, height: u32, luma: u8, chroma_u: u8, chroma_v: u8) -> Vec<u8> {
    let w = width as usize;
    let h = height as usize;
    let mut out = Vec::with_capacity(w * h + w * (h / 2));
    out.extend(std::iter::repeat_n(luma, w * h));
    let uv_row = uv_row_bytes(width, chroma_u, chroma_v);
    for _ in 0..(h / 2) {
        out.extend_from_slice(&uv_row);
    }
    out
}

fn uv_row_bytes(width: u32, chroma_u: u8, chroma_v: u8) -> Vec<u8> {
    let mut row = Vec::with_capacity(width as usize);
    for i in 0..width {
        row.push(if i % 2 == 0 { chroma_u } else { chroma_v });
    }
    row
}

/// Ensure a 64×64 mid-gray NV12 fixture (`solid/gray_nv12_64x64.yuv`).
pub fn ensure_solid_gray_nv12_64x64() -> Result<PathBuf, TestMediaError> {
    ensure(
        "solid/gray_nv12_64x64.yuv",
        SOLID_GRAY_NV12_64X64_BLAKE3,
        |path| write_solid_nv12(path, 64, 64, 128, 128, 128),
    )
}

/// BLAKE3 hex digest of 20 ms of silent 48 kHz stereo 16-bit PCM (`pcm/silence_48k_stereo_20ms.pcm`).
///
/// Recompute with `hash_bytes(&pcm_silence_bytes(960, 2))` if the generator pattern changes.
pub const PCM_SILENCE_48K_STEREO_20MS_BLAKE3: &str =
    "197c5da917d6a2893af03f02e1ac1cc385de0be89be78e979ce1dedb388652cb";

/// In-memory silent interleaved 16-bit PCM buffer (`frames_per_channel * channels * 2` bytes,
/// all zero).
#[must_use]
pub fn pcm_silence_bytes(frames_per_channel: u32, channels: u16) -> Vec<u8> {
    vec![0_u8; frames_per_channel as usize * usize::from(channels) * 2]
}

/// Write a silent interleaved 16-bit PCM buffer.
pub fn write_pcm_silence(
    path: &Path,
    frames_per_channel: u32,
    channels: u16,
) -> Result<(), TestMediaError> {
    let mut file = File::create(path)?;
    file.write_all(&pcm_silence_bytes(frames_per_channel, channels))?;
    Ok(())
}

/// Ensure 20 ms of silent 48 kHz stereo 16-bit PCM (`pcm/silence_48k_stereo_20ms.pcm`).
pub fn ensure_pcm_silence_48k_stereo_20ms() -> Result<PathBuf, TestMediaError> {
    ensure(
        "pcm/silence_48k_stereo_20ms.pcm",
        PCM_SILENCE_48K_STEREO_20MS_BLAKE3,
        |path| write_pcm_silence(path, 960, 2),
    )
}

#[cfg(test)]
#[path = "lib_tests.rs"]
mod tests;