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.
//!
//! Content addressing 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 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 the browser reads the
/// same names out of origin storage.
pub trait AssetSource {
    /// What a report calls the payload's home. Not a platform path — the
    /// storage underneath is what knows whether there is one — and not a
    /// promise that anything is there.
    fn names(&self, hash: AssetHash) -> String;

    /// 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 at: String,
    pub why: Miss,
}

impl std::fmt::Display for AssetFault {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let path = &self.at;
        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,
        at: 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) -> String {
        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(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(_),
                ..
            }),
        ));
    }
}