blockworx_doc/

block_model.rs

//! The block model: entities and namespaces of the document.
//! Rationale: `docs/doc-ng-design-notes.md`.

use crate::{
    entity::entity,
    geometry::{FracVal, GridPoint, GridRect, PinSlot, ScreenRect, Waypoint},
    hash::AssetHash,
    id::{AreaId, BlockId, ImageId, PinId, RouteId, RouteLabelId, TextId},
    values::{LabelSide, PinDir, Role},
};
use serde::{Deserialize, Serialize};
use std::num::NonZeroU32;
use std::sync::Arc;

/// One atomic value on its block; the zero icon (null hash, empty rect)
/// means "no image".
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default)]
pub struct Icon {
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    pub asset: AssetHash,
    #[serde(default, skip_serializing_if = "crate::entity::is_default")]
    pub rect: ScreenRect,
}

entity! {
    /// A namespace of four independent registers — no id, no lifecycle.
    pub struct Label(update LabelUpdate, id ()) {
        registers {
            Name => name: String,
            Side => side: LabelSide,
            Offset => offset: FracVal,
            Hidden => hidden: bool,
        }
        namespaces {}
        constants {}
    }
}

entity! {
    pub struct Block(update BlockUpdate, id BlockId) {
        registers {
            /// `Id::NULL` = the document itself.
            Parent => parent: BlockId,
            Rect => rect: GridRect,
            Locked => locked: bool,
            Role => role: Role,
            Icon => icon: Icon,
        }
        namespaces {
            Title => title: Label,
            TypeLabel => type_label: Label,
        }
        constants {}
    }
}

entity! {
    pub struct Pin(update PinUpdate, id PinId) {
        registers {
            Owner => owner: BlockId,
            Name => name: String,
            TypeName => type_name: String,
            Tag => tag: String,
            TagHidden => tag_hidden: bool,
            /// The port body's placement inside the block's own interior
            /// view — a different scope from `slot`, which places the pin
            /// on the block-as-child.
            Rect => rect: GridRect,
            Slot => slot: PinSlot,
            Dir => dir: PinDir,
            /// The one authored accent. Stub and port-pin accents are
            /// propagated from route roles — derived state, computed
            /// client-side, never in the log.
            PortAccent => port_accent: Role,
            /// The port body's facing: `false` = the default, opposite the
            /// pin's edge (`slot.side.flip()`); `true` = frozen to face
            /// `slot.side` itself.
            FlipLR => flip_lr: bool,
        }
        namespaces {}
        constants {}
    }
}

entity! {
    pub struct Route(update RouteUpdate, id RouteId) {
        registers {
            Owner => owner: BlockId,
            Name => name: String,
            Role => role: Role,
            Waypoints => waypoints: Vec<Waypoint>,
        }
        namespaces {}
        constants {
            /// Endpoints are creation-time constants; re-pointing one is
            /// delete-and-recreate.
            from: PinId,
            to: PinId,
        }
    }
}

entity! {
    pub struct RouteLabel(update RouteLabelUpdate, id RouteLabelId) {
        registers {
            Owner => owner: RouteId,
            /// Offset along the route.
            Pos => pos: FracVal,
        }
        namespaces {}
        constants {}
    }
}

entity! {
    pub struct Text(update TextUpdate, id TextId) {
        registers {
            Owner => owner: BlockId,
            Text => text: String,
            Pos => pos: GridPoint,
            Role => role: Role,
            /// The box's width in grid cells, set by resizing it; `None` is
            /// a box as wide as its text.
            Width => width: Option<NonZeroU32>,
        }
        namespaces {}
        constants {}
    }
}

entity! {
    pub struct Area(update AreaUpdate, id AreaId) {
        registers {
            Owner => owner: BlockId,
            Rect => rect: GridRect,
            Role => role: Role,
        }
        namespaces {
            Title => title: Label,
        }
        constants {}
    }
}

entity! {
    /// A free-floating placed image (block icons are the atomic [`Icon`] value).
    pub struct Image(update ImageUpdate, id ImageId) {
        registers {
            Owner => owner: BlockId,
            Asset => asset: AssetHash,
            Rect => rect: ScreenRect,
        }
        namespaces {}
        constants {}
    }
}

/// `Arc`: crosses the sync thread boundary.
///
/// The variant names the payload's format; the [`AssetHash`] keying it
/// covers the bytes alone — an asset is addressed by its content, and the
/// format is how to read that content, not part of its identity.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum Asset {
    Svg(#[serde(with = "svg_payload")] Arc<[u8]>),
    Png(#[serde(with = "png_payload")] Arc<[u8]>),
}

/// The largest artwork payload a commit may carry. A payload is create-only
/// and the document holds every one it has ever been given, so an unbounded
/// one is unbounded forever: it is folded again on every open. Four
/// megabytes is generous for a diagram symbol and small enough that a stray
/// photograph is refused rather than archived.
pub const ASSET_LIMIT: usize = 4 * 1024 * 1024;

impl Asset {
    pub fn bytes(&self) -> &[u8] {
        match self {
            Asset::Svg(bytes) | Asset::Png(bytes) => bytes,
        }
    }

    /// Whether this payload is small enough to be committed.
    pub fn within_limit(&self) -> bool {
        self.bytes().len() <= ASSET_LIMIT
    }

    /// The key this payload travels under.
    pub fn hash(&self) -> AssetHash {
        AssetHash::of(self.bytes())
    }
}

/// An SVG payload in a format a human reads: its own source text,
/// verbatim, so the document stays greppable and an artwork diff reads as
/// the drawing it is. Every construction site builds one from a `String`
/// ([`crate::block_model::Asset`]'s callers read SVG as text), so the
/// bytes are UTF-8 and the encode cannot fail in practice.
mod svg_payload {
    use serde::{Deserializer, Serializer, ser};
    use std::sync::Arc;

    pub fn serialize<S: Serializer>(bytes: &Arc<[u8]>, serializer: S) -> Result<S::Ok, S::Error> {
        if serializer.is_human_readable() {
            let text = std::str::from_utf8(bytes).map_err(ser::Error::custom)?;
            serializer.serialize_str(text)
        } else {
            serializer.serialize_bytes(bytes)
        }
    }

    pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Arc<[u8]>, D::Error> {
        if deserializer.is_human_readable() {
            deserializer.deserialize_any(super::payload::Verbatim)
        } else {
            deserializer.deserialize_byte_buf(super::payload::Verbatim)
        }
    }
}

/// A PNG payload in a format a human reads: **standard-alphabet base64
/// with padding** (RFC 4648 §4, `A–Z a–z 0–9 + /`, `=`-padded), since the
/// bytes are not text.
mod png_payload {
    use base64::{Engine as _, engine::general_purpose::STANDARD};
    use serde::{Deserializer, Serializer};
    use std::sync::Arc;

    pub fn serialize<S: Serializer>(bytes: &Arc<[u8]>, serializer: S) -> Result<S::Ok, S::Error> {
        if serializer.is_human_readable() {
            serializer.serialize_str(&STANDARD.encode(bytes))
        } else {
            serializer.serialize_bytes(bytes)
        }
    }

    pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Arc<[u8]>, D::Error> {
        if deserializer.is_human_readable() {
            deserializer.deserialize_any(super::payload::Base64)
        } else {
            deserializer.deserialize_byte_buf(super::payload::Base64)
        }
    }
}

/// Serde has no `Arc<[u8]>` without its `rc` feature, and reading is
/// deliberately wider than writing: a binary format hands over a byte
/// string, a text format hands over the spelling its variant writes, and
/// either may also arrive as the array of numbers written by builds before
/// this was format-aware.
mod payload {
    use base64::{Engine as _, engine::general_purpose::STANDARD};
    use serde::de;
    use std::sync::Arc;

    /// The text *is* the bytes.
    pub struct Verbatim;

    /// The text is base64 over the bytes.
    pub struct Base64;

    macro_rules! payload_visitor {
        ($visitor:ident, $expecting:literal, |$text:ident| $decode:expr) => {
            impl<'de> de::Visitor<'de> for $visitor {
                type Value = Arc<[u8]>;

                fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                    f.write_str($expecting)
                }

                fn visit_str<E: de::Error>(self, $text: &str) -> Result<Self::Value, E> {
                    $decode
                }

                fn visit_bytes<E: de::Error>(self, bytes: &[u8]) -> Result<Self::Value, E> {
                    Ok(Arc::from(bytes))
                }

                fn visit_byte_buf<E: de::Error>(self, bytes: Vec<u8>) -> Result<Self::Value, E> {
                    Ok(Arc::from(bytes))
                }

                fn visit_seq<A: de::SeqAccess<'de>>(
                    self,
                    mut seq: A,
                ) -> Result<Self::Value, A::Error> {
                    let mut bytes = Vec::with_capacity(seq.size_hint().unwrap_or_default());
                    while let Some(byte) = seq.next_element::<u8>()? {
                        bytes.push(byte);
                    }
                    Ok(Arc::from(bytes))
                }
            }
        };
    }

    payload_visitor!(
        Verbatim,
        "a byte string, source text, or a sequence of bytes",
        |text| Ok(Arc::from(text.as_bytes()))
    );
    payload_visitor!(
        Base64,
        "a byte string, base64 text, or a sequence of bytes",
        |text| STANDARD
            .decode(text)
            .map(Arc::from)
            .map_err(de::Error::custom)
    );
}

#[cfg(test)]
mod tests {
    use super::{ASSET_LIMIT, Asset};

    fn svg() -> Asset {
        Asset::Svg(b"<svg/>".as_slice().into())
    }

    /// The greppable spelling the projection rests on: an SVG travels as
    /// its own source, a PNG as base64, and the tags are the format's
    /// lower-case ones.
    #[test]
    fn a_payload_round_trips_through_json_in_its_own_spelling() {
        let text = serde_json::to_string(&svg()).expect("it serializes");
        assert_eq!(text, r#"{"svg":"<svg/>"}"#, "verbatim source text");
        assert_eq!(
            serde_json::from_str::<Asset>(&text).expect("and parses back"),
            svg(),
        );

        let png = Asset::Png(b"\x89PNG".as_slice().into());
        let text = serde_json::to_string(&png).expect("it serializes");
        assert_eq!(text, r#"{"png":"iVBORw=="}"#, "standard-alphabet base64");
        assert_eq!(
            serde_json::from_str::<Asset>(&text).expect("and parses back"),
            png,
        );
    }

    /// A payload written as a JSON array of numbers still reads as those
    /// bytes, which is what keeps an older container replayable.
    #[test]
    fn a_payload_written_as_a_number_array_still_reads() {
        assert_eq!(
            serde_json::from_str::<Asset>(r#"{"svg":[60,115,118,103,47,62]}"#)
                .expect("the number-array spelling parses"),
            svg(),
        );
        assert_eq!(
            serde_json::from_str::<Asset>(r#"{"png":[]}"#).expect("an empty one too"),
            Asset::Png(b"".as_slice().into()),
        );
    }

    #[test]
    fn png_text_that_is_not_base64_is_refused_rather_than_taken_as_its_own_bytes() {
        assert!(serde_json::from_str::<Asset>(r#"{"png":"not base64!!"}"#).is_err());
    }

    /// A binary format still gets a byte string. This is what
    /// `Document::content_hash` canonicalizes through, so the text
    /// spelling above must not have reached it — CBOR major type 2, not
    /// an array.
    #[test]
    fn a_binary_format_still_writes_a_byte_string() {
        let mut bytes = Vec::new();
        ciborium::into_writer(&Asset::Png(b"hi".as_slice().into()), &mut bytes)
            .expect("it serializes");
        assert_eq!(bytes, b"\xa1cpngBhi", "a map of one, then a 2-byte string");
        assert_eq!(
            ciborium::from_reader::<Asset, _>(bytes.as_slice()).expect("and parses back"),
            Asset::Png(b"hi".as_slice().into()),
        );
    }

    /// Base64 is 4 characters per 3 bytes, so the text form of a PNG at
    /// the limit is the size a record has to carry if nobody extracts it —
    /// the number that makes the store's `assets/` directory worth its
    /// complexity.
    #[test]
    fn the_text_form_of_a_png_is_a_third_larger_than_the_payload() {
        let big = Asset::Png(vec![0u8; 3 * 1024].into());
        let text = serde_json::to_string(&big).expect("it serializes");
        assert!(
            text.len() > 4 * 1024 && text.len() < 5 * 1024,
            "{}",
            text.len()
        );
        assert_eq!(ASSET_LIMIT, 4 * 1024 * 1024);
    }
}