clipasm 0.5.0

A strict, typed language for compiling and rendering Video and Audio graphs
Documentation
use std::fs;
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::diagnostic::{BuiltinDiagnostic, Diagnostic, Result};
use crate::source::SourceSpan;

use super::staging::StagingDirectory;

const ENTRY_FORMAT_VERSION: u32 = 2;
const MAX_METADATA_BYTES: u64 = 4 * 1024;

#[derive(Deserialize, Serialize)]
struct CacheEntryDocument<'a> {
    format_version: u32,
    execution_namespace: &'a str,
    fingerprint: &'a str,
    content_hash: String,
}

#[derive(Clone, Copy)]
pub(super) struct CacheEntryIdentity<'a> {
    execution_namespace: &'a str,
    fingerprint: &'a str,
}

impl<'a> CacheEntryIdentity<'a> {
    pub(super) const fn new(execution_namespace: &'a str, fingerprint: &'a str) -> Self {
        Self {
            execution_namespace,
            fingerprint,
        }
    }
}

pub(super) struct StagedArtifact {
    _staging: StagingDirectory,
    path: PathBuf,
    metadata: PathBuf,
    destination: PathBuf,
}

pub(super) struct VerifiedArtifact(StagedArtifact);

impl StagedArtifact {
    pub(super) fn new(destination: &Path, extension: &str) -> Result<Self> {
        let staging = StagingDirectory::beside(destination, "cache", BuiltinDiagnostic::CacheIo)?;
        Ok(Self {
            path: staging.path(&format!("artifact.{extension}")),
            metadata: staging.path("artifact.cache.json"),
            destination: destination.to_path_buf(),
            _staging: staging,
        })
    }

    pub(super) fn path(&self) -> &Path {
        &self.path
    }

    pub(super) fn verify(
        self,
        verifier: impl FnOnce(&Path) -> Result<()>,
    ) -> Result<VerifiedArtifact> {
        verifier(&self.path)?;
        Ok(VerifiedArtifact(self))
    }
}

impl VerifiedArtifact {
    pub(super) fn commit(self, identity: CacheEntryIdentity<'_>) -> Result<()> {
        let staged = self.0;
        commit_verified(
            &staged.path,
            &staged.metadata,
            &staged.destination,
            identity,
        )
    }
}

pub(super) fn metadata_path(artifact: &Path) -> PathBuf {
    let mut name = artifact.file_name().unwrap_or_default().to_os_string();
    name.push(".cache.json");
    artifact
        .parent()
        .unwrap_or_else(|| Path::new("."))
        .join(name)
}

pub(super) fn verify_entry(artifact: &Path, identity: CacheEntryIdentity<'_>) -> Result<()> {
    require_regular_file(artifact, "cache artifact")?;
    let metadata_path = metadata_path(artifact);
    let metadata = require_regular_file(&metadata_path, "cache metadata")?;
    if metadata.len() > MAX_METADATA_BYTES {
        return Err(cache_error(
            &metadata_path,
            format!(
                "cache metadata is too large: {} bytes exceeds {MAX_METADATA_BYTES}",
                metadata.len()
            ),
        ));
    }
    let bytes = fs::read(&metadata_path).map_err(|error| {
        cache_error(
            &metadata_path,
            format!("could not read cache metadata: {error}"),
        )
    })?;
    let document: CacheEntryDocument<'_> = serde_json::from_slice(&bytes).map_err(|error| {
        cache_error(
            &metadata_path,
            format!("cache metadata does not match the current schema: {error}"),
        )
    })?;
    if document.format_version != ENTRY_FORMAT_VERSION
        || document.execution_namespace != identity.execution_namespace
        || document.fingerprint != identity.fingerprint
    {
        return Err(cache_error(
            &metadata_path,
            "cache metadata does not identify this prepared node",
        ));
    }
    let actual = hash_file(artifact)?;
    if actual != document.content_hash {
        return Err(cache_error(
            artifact,
            "cache artifact content does not match its recorded hash",
        ));
    }
    Ok(())
}

fn commit_verified(
    artifact: &Path,
    staged_metadata: &Path,
    destination: &Path,
    identity: CacheEntryIdentity<'_>,
) -> Result<()> {
    let content_hash = hash_file(artifact)?;
    let document = CacheEntryDocument {
        format_version: ENTRY_FORMAT_VERSION,
        execution_namespace: identity.execution_namespace,
        fingerprint: identity.fingerprint,
        content_hash,
    };
    let bytes = serde_json::to_vec(&document).map_err(|error| {
        cache_error(
            staged_metadata,
            format!("could not serialize cache metadata: {error}"),
        )
    })?;
    fs::write(staged_metadata, bytes).map_err(|error| {
        cache_error(
            staged_metadata,
            format!("could not write staged cache metadata: {error}"),
        )
    })?;

    let destination_metadata = metadata_path(destination);
    fs::rename(staged_metadata, &destination_metadata).map_err(|error| {
        cache_error(
            &destination_metadata,
            format!("could not commit cache metadata: {error}"),
        )
    })?;
    if let Err(error) = fs::rename(artifact, destination) {
        let cleanup = fs::remove_file(&destination_metadata);
        let diagnostic = cache_error(
            destination,
            format!("could not commit verified cache artifact: {error}"),
        );
        return Err(match cleanup {
            Ok(()) => diagnostic,
            Err(cleanup_error) if cleanup_error.kind() == std::io::ErrorKind::NotFound => {
                diagnostic
            }
            Err(cleanup_error) => diagnostic.note(format!(
                "could not remove committed cache metadata `{}` after artifact failure: {cleanup_error}",
                destination_metadata.display()
            )),
        });
    }
    Ok(())
}

pub(super) fn remove_entry(artifact: &Path) -> Result<()> {
    remove_if_present(artifact)?;
    remove_if_present(&metadata_path(artifact))
}

fn require_regular_file(path: &Path, role: &str) -> Result<fs::Metadata> {
    match fs::symlink_metadata(path) {
        Ok(metadata) if metadata.file_type().is_symlink() => {
            Err(cache_error(path, format!("{role} is a symlink")))
        }
        Ok(metadata) if metadata.is_file() => Ok(metadata),
        Ok(_) => Err(cache_error(path, format!("{role} is not a regular file"))),
        Err(error) => Err(cache_error(
            path,
            format!("could not inspect {role}: {error}"),
        )),
    }
}

fn remove_if_present(path: &Path) -> Result<()> {
    match fs::symlink_metadata(path) {
        Ok(_) => fs::remove_file(path).map_err(|error| {
            cache_error(
                path,
                format!("could not remove invalid cache entry: {error}"),
            )
        }),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
        Err(error) => Err(cache_error(
            path,
            format!("could not inspect invalid cache entry: {error}"),
        )),
    }
}

fn hash_file(path: &Path) -> Result<String> {
    crate::identity::hash_file(path)
        .map_err(|error| cache_error(path, format!("could not hash cache artifact: {error}")))
}

fn cache_error(path: &Path, message: impl Into<String>) -> Diagnostic {
    Diagnostic::builtin(
        BuiltinDiagnostic::CacheIo,
        message,
        SourceSpan::file_start(path),
    )
}

#[cfg(test)]
mod tests {
    use sha2::Digest as _;

    use super::*;

    fn identity<'a>() -> CacheEntryIdentity<'a> {
        CacheEntryIdentity::new("namespace", "fingerprint")
    }

    #[test]
    fn unverified_staging_is_removed_on_drop() {
        let directory = tempfile::tempdir().expect("temporary directory");
        let destination = directory.path().join("artifact.mkv");
        let staged_path = {
            let staged = StagedArtifact::new(&destination, "mkv").expect("staging");
            fs::write(staged.path(), b"invalid artifact").expect("staged bytes");
            staged.path().to_path_buf()
        };
        assert!(!staged_path.exists());
        assert!(!destination.exists());
    }

    #[test]
    fn only_verified_staging_can_be_committed() {
        let directory = tempfile::tempdir().expect("temporary directory");
        let destination = directory.path().join("artifact.mkv");
        let staged = StagedArtifact::new(&destination, "mkv").expect("staging");
        let staging_parent = staged
            .path()
            .parent()
            .expect("staging parent")
            .to_path_buf();
        fs::write(staged.path(), b"verified artifact").expect("staged bytes");
        staged
            .verify(|_| Ok(()))
            .expect("verification")
            .commit(identity())
            .expect("commit");
        assert_eq!(
            fs::read(&destination).expect("artifact"),
            b"verified artifact"
        );
        assert!(!staging_parent.exists());
        verify_entry(&destination, identity()).expect("cache metadata");
    }

    #[test]
    fn committed_metadata_detects_artifact_changes() {
        let directory = tempfile::tempdir().expect("temporary directory");
        let staged = directory.path().join("staged.mkv");
        let staged_metadata = directory.path().join("staged.json");
        let destination = directory.path().join("artifact.mkv");
        fs::write(&staged, b"verified artifact").expect("staged artifact");
        commit_verified(&staged, &staged_metadata, &destination, identity())
            .expect("commit cache entry");
        verify_entry(&destination, identity()).expect("verified entry");

        fs::write(&destination, b"substituted artifact").expect("substitute artifact");
        let error = verify_entry(&destination, identity()).expect_err("content mismatch");
        assert!(error.message.contains("recorded hash"));
    }

    #[test]
    fn metadata_must_match_the_execution_namespace() {
        let directory = tempfile::tempdir().expect("temporary directory");
        let staged = directory.path().join("staged.mkv");
        let staged_metadata = directory.path().join("staged.json");
        let destination = directory.path().join("artifact.mkv");
        fs::write(&staged, b"verified artifact").expect("staged artifact");
        commit_verified(&staged, &staged_metadata, &destination, identity())
            .expect("commit cache entry");

        let wrong = CacheEntryIdentity::new("other-namespace", "fingerprint");
        let error = verify_entry(&destination, wrong).expect_err("namespace mismatch");
        assert!(error.message.contains("does not identify"));
    }

    #[test]
    fn legacy_metadata_is_not_reusable() {
        let directory = tempfile::tempdir().expect("temporary directory");
        let artifact = directory.path().join("artifact.mkv");
        fs::write(&artifact, b"verified artifact").expect("artifact");
        fs::write(
            metadata_path(&artifact),
            serde_json::to_vec(&serde_json::json!({
                "format_version": 1,
                "fingerprint": "fingerprint",
                "content_hash": hex::encode(sha2::Sha256::digest(b"verified artifact")),
            }))
            .expect("legacy metadata"),
        )
        .expect("write legacy metadata");

        let error = verify_entry(&artifact, identity()).expect_err("legacy metadata");
        assert!(error.message.contains("current schema"));
    }

    #[cfg(unix)]
    #[test]
    fn cache_entries_reject_symlinks() {
        use std::os::unix::fs::symlink;

        let directory = tempfile::tempdir().expect("temporary directory");
        let target = directory.path().join("target.mkv");
        let artifact = directory.path().join("artifact.mkv");
        fs::write(&target, b"target").expect("target");
        symlink(&target, &artifact).expect("artifact symlink");
        let error = verify_entry(&artifact, identity()).expect_err("symlink");
        assert!(error.message.contains("symlink"));
    }
}