blockworx/store/

assets.rs

//! Artwork at the container boundary: `assets/<hash>.<ext>` is the one
//! home for bytes, and everything else keeps only the hash.
//!
//! The playbook's container layout has always said `assets/<hash>`; since
//! P5 it is load-bearing rather than an optimization. A rev file is the
//! whole document, so a 1.5 MB symbol written into it would be written
//! again into every rev that stands after it — and the same file is
//! git-diffed and read on every open. Content addressing means the bytes
//! land once, are never rewritten, and are never deleted: reclaiming what
//! nothing references belongs to compaction, not to an edit.
//!
//! `crates/doc` knows nothing about any of this. A document is stripped on
//! its way into a rev file and re-attached on its way out
//! ([`Document::without_assets`](blockworx_doc::document::Document::without_assets)),
//! so the document crate only ever sees payloads with their bytes in hand.

use std::path::PathBuf;

use blockworx_doc::{block_model::Asset, hash::AssetHash};
use serde::{Deserialize, Serialize};

/// How to read a payload's bytes — which is also its file extension. Not
/// derived from the [`Asset`] variant name: the durable spelling is
/// lowercase because it is a file suffix.
#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
pub enum AssetFormat {
    #[serde(rename = "svg")]
    Svg,
    #[serde(rename = "png")]
    Png,
}

impl AssetFormat {
    /// Every format a payload can be filed under. A hash names one byte
    /// string, so at most one of these files can exist — which is what
    /// lets a reader ask for a payload by hash alone.
    pub const ALL: [Self; 2] = [Self::Svg, Self::Png];

    pub fn of(asset: &Asset) -> Self {
        match asset {
            Asset::Svg(_) => Self::Svg,
            Asset::Png(_) => Self::Png,
        }
    }

    pub fn extension(self) -> &'static str {
        match self {
            Self::Svg => "svg",
            Self::Png => "png",
        }
    }

    fn asset(self, bytes: Vec<u8>) -> Asset {
        match self {
            Self::Svg => Asset::Svg(bytes.into()),
            Self::Png => Asset::Png(bytes.into()),
        }
    }

    /// `<hash>.<ext>`, the name a payload is filed under.
    pub fn file_name(self, hash: AssetHash) -> String {
        format!("{hash}.{}", self.extension())
    }
}

/// Where payloads are read back from. A trait rather than a directory
/// because a session with no files reads its own, and Phase 8's browser
/// reads the same names out of origin storage.
pub trait AssetSource {
    /// Where the payload is kept, for a report to name. Not a promise
    /// that anything is there.
    fn names(&self, hash: AssetHash) -> PathBuf;

    /// The payload's bytes and the format that reads them, unverified —
    /// [`hydrate`] is what checks them.
    ///
    /// # Errors
    /// Whatever the backing store says when the payload is not there to
    /// be read.
    fn find(&self, hash: AssetHash) -> std::io::Result<(AssetFormat, Vec<u8>)>;
}

/// Where payloads are written. Separate from [`AssetSource`] because a
/// read-only session has one and not the other.
pub trait AssetSink {
    /// File `asset` under `hash`, durably, if it is not already there.
    ///
    /// # Errors
    /// The write that did not land.
    fn put(&mut self, hash: AssetHash, asset: &Asset) -> std::io::Result<()>;
}

/// Why a payload could not be handed back.
#[derive(Debug)]
pub enum Miss {
    Unreadable(std::io::Error),
    /// The bytes filed under a hash do not hash to it. Content addressing
    /// is self-verifying, so this is caught here rather than as a document
    /// that quietly draws the wrong picture.
    Corrupt {
        found: AssetHash,
    },
}

/// A reference a document makes and the store cannot honour.
#[derive(Debug, thiserror::Error)]
pub struct AssetFault {
    pub hash: AssetHash,
    pub path: PathBuf,
    pub why: Miss,
}

impl std::fmt::Display for AssetFault {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let path = self.path.display();
        match &self.why {
            Miss::Unreadable(error) => write!(
                f,
                "the document places artwork the container no longer holds: {path} ({error})",
            ),
            Miss::Corrupt { found } => write!(
                f,
                "the document places artwork addressed as {named}, but {path} holds bytes that \
                 hash to {found} — the payload has been replaced",
                named = self.hash,
            ),
        }
    }
}

/// Read `hash`'s payload back and check it against the hash that named it.
///
/// # Errors
/// [`AssetFault`] when the payload is not there, or is not the payload.
pub fn hydrate(source: &dyn AssetSource, hash: AssetHash) -> Result<Asset, AssetFault> {
    let fault = |why| AssetFault {
        hash,
        path: source.names(hash),
        why,
    };
    let (format, bytes) = source.find(hash).map_err(|e| fault(Miss::Unreadable(e)))?;
    let found = AssetHash::of(&bytes);
    if found != hash {
        return Err(fault(Miss::Corrupt { found }));
    }
    Ok(format.asset(bytes))
}

/// Payloads that die with the process — a session with no container, and
/// what a test stands a rev store on.
#[derive(Default, Debug)]
pub struct Held(blockworx_doc::hash::HashedMap<blockworx_doc::hash::AssetKind, Asset>);

impl AssetSource for Held {
    fn names(&self, hash: AssetHash) -> PathBuf {
        PathBuf::from(format!("{hash} in this session"))
    }

    fn find(&self, hash: AssetHash) -> std::io::Result<(AssetFormat, Vec<u8>)> {
        self.0
            .get(&hash)
            .map(|asset| (AssetFormat::of(asset), asset.bytes().to_vec()))
            .ok_or_else(|| std::io::Error::from(std::io::ErrorKind::NotFound))
    }
}

impl AssetSink for Held {
    fn put(&mut self, hash: AssetHash, asset: &Asset) -> std::io::Result<()> {
        self.0.entry(hash).or_insert_with(|| asset.clone());
        Ok(())
    }
}

#[cfg(not(target_arch = "wasm32"))]
pub use native::Dir;

#[cfg(not(target_arch = "wasm32"))]
mod native {
    use super::{Asset, AssetFormat, AssetHash, AssetSink, AssetSource, PathBuf};
    use crate::store::container::ASSETS;
    use std::fs::{File, OpenOptions};
    use std::io::Write as _;
    use std::path::Path;

    /// A container's `assets/` directory.
    pub struct Dir(PathBuf);

    impl Dir {
        pub fn at(root: &Path) -> Self {
            Self(root.join(ASSETS))
        }

        fn path(&self, hash: AssetHash, format: AssetFormat) -> PathBuf {
            self.0.join(format.file_name(hash))
        }
    }

    impl AssetSource for Dir {
        fn names(&self, hash: AssetHash) -> PathBuf {
            self.0.join(hash.to_string())
        }

        fn find(&self, hash: AssetHash) -> std::io::Result<(AssetFormat, Vec<u8>)> {
            let mut missing = std::io::Error::from(std::io::ErrorKind::NotFound);
            for format in AssetFormat::ALL {
                match std::fs::read(self.path(hash, format)) {
                    Ok(bytes) => return Ok((format, bytes)),
                    Err(error) => missing = error,
                }
            }
            Err(missing)
        }
    }

    impl AssetSink for Dir {
        /// Create-only: a file already under a content hash's name already
        /// holds those bytes, so there is nothing a second write could
        /// say. The directory entry is fsync'd with the file, because the
        /// rev that names these bytes is written next.
        fn put(&mut self, hash: AssetHash, asset: &Asset) -> std::io::Result<()> {
            std::fs::create_dir_all(&self.0)?;
            let path = self.path(hash, AssetFormat::of(asset));
            let mut file = match OpenOptions::new().write(true).create_new(true).open(path) {
                Ok(file) => file,
                Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => return Ok(()),
                Err(error) => return Err(error),
            };
            file.write_all(asset.bytes())?;
            file.sync_all()?;
            sync_dir(&self.0)
        }
    }

    #[cfg(unix)]
    fn sync_dir(dir: &Path) -> std::io::Result<()> {
        File::open(dir)?.sync_all()
    }

    #[cfg(not(unix))]
    fn sync_dir(_dir: &Path) -> std::io::Result<()> {
        Ok(())
    }
}

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

    /// The format is a file suffix and a durable JSON tag at once, so both
    /// spellings are pinned where a rename would have to notice them.
    #[test]
    fn a_payload_is_filed_under_its_hash_and_its_format() {
        let asset = Asset::Svg(b"<svg/>".as_slice().into());
        assert_eq!(AssetFormat::of(&asset), AssetFormat::Svg);
        assert_eq!(
            AssetFormat::Svg.file_name(asset.hash()),
            format!("{}.svg", asset.hash()),
        );
        assert_eq!(
            serde_json::to_string(&AssetFormat::Svg).expect("it serializes"),
            "\"svg\"",
        );
        assert_eq!(
            AssetFormat::of(&Asset::Png(b"".as_slice().into())).extension(),
            "png",
        );
    }

    /// Asking by hash alone is what lets a rev file carry references and
    /// nothing else — and the answer is verified against the name.
    #[test]
    fn a_payload_comes_back_by_hash_and_is_checked_against_it() {
        let asset = Asset::Png(b"artwork".as_slice().into());
        let mut store = Held::default();
        store.put(asset.hash(), &asset).expect("it is held");

        assert_eq!(hydrate(&store, asset.hash()).expect("it comes back"), asset);
        assert!(matches!(
            hydrate(&store, Asset::Svg(b"<svg/>".as_slice().into()).hash()),
            Err(AssetFault {
                why: Miss::Unreadable(_),
                ..
            }),
        ));
    }
}