indicatrix-worker 0.6.2

Coordinator and render worker for an indicatrix-backed design catalogue. `serve` (default build) is the coordinator: it serves indicatrix-net's read-only design-library protocol to viewers over mutual TLS and accepts joining render workers on a separate worker port. The optional `worker` feature adds render capacity -- `join` (dial a coordinator and render its requests), `serve --render` (render with the coordinator's own CPU/GPU) and `render` (a one-shot scene-to-PNG CLI).
Documentation
//! Computes the two version fields of the library protocol. `DesignSummary::version` is a
//! SHA-256 hash over exactly the fields a search row carries, in a fixed order, each
//! length-prefixed so adjacent fields can never collide, and each `Option` tagged
//! present/absent before its value. `DesignSummary::design_version` and
//! `DesignRecord::version` are one revision token ([`revision_token`]) derived from the
//! design's url and the vault's per-entry revision stamp, so a search row can carry it at
//! O(1) cost per row. See the `serve::library` module doc comment.

use indicatrix_net::library::DesignSummary;
use indicatrix_vault::db::sqlite::Database;
use sha2::{Digest, Sha256};

fn hash_str(hasher: &mut Sha256, s: &str) {
    hasher.update((s.len() as u64).to_le_bytes());
    hasher.update(s.as_bytes());
}

fn hash_opt_str(hasher: &mut Sha256, s: Option<&str>) {
    match s {
        Some(s) => {
            hasher.update([1u8]);
            hash_str(hasher, s);
        }
        None => hasher.update([0u8]),
    }
}

/// SHA-256 over every [`DesignSummary`] field except [`DesignSummary::version`] itself,
/// [`DesignSummary::design_version`] and [`DesignSummary::entry_id`].
///
/// `entry_id` is the server database's row number, not part of the design: a mirror
/// keys designs by `url`, so renumbering the server's database (a rebuilt or
/// re-imported catalogue) must not make every design look changed and force a full
/// re-fetch. The price, paid once: the hash of every design differs from what earlier
/// builds produced, so each existing mirror re-syncs its whole catalogue one time.
pub(super) fn hash_summary(s: &DesignSummary) -> [u8; 32] {
    let mut hasher = Sha256::new();
    hash_str(&mut hasher, &s.title);
    hash_str(&mut hasher, &s.url);
    hash_opt_str(&mut hasher, s.design_id.as_deref());
    hash_opt_str(&mut hasher, s.shape.as_deref());
    hash_opt_str(&mut hasher, s.index_gear.as_deref());
    hash_opt_str(&mut hasher, s.facets_count.as_deref());
    hash_opt_str(&mut hasher, s.designer_info.as_deref());
    hash_opt_str(&mut hasher, s.lw_ratio.as_deref());
    hash_opt_str(&mut hasher, s.refractive_index.as_deref());
    hash_opt_str(&mut hasher, s.volume.as_deref());
    hash_opt_str(&mut hasher, s.competition_diagram.as_deref());
    hasher.update([u8::from(s.ignored)]);
    hasher.finalize().into()
}

/// The vault's revision stamp of one design (`diagram_entries.updated_at`), or the fact
/// that it could not be read.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(super) enum Revision {
    /// The stamp as stored; `None` for a row that predates the column and was never
    /// re-saved.
    Stamped(Option<i64>),
    /// The stamp could not be read (no such row, or the query failed).
    Unreadable,
}

impl Revision {
    /// Reads `entry_id`'s stamp. Every write that replaces or edits a design bumps it
    /// strictly upward, so it moves on any change to the design's entry, detail,
    /// angle table or attachments.
    pub(super) fn read(db: &Database, entry_id: i64) -> Self {
        match db.entry_updated_at(entry_id) {
            Ok(stamp) => Self::Stamped(stamp),
            Err(e) => {
                tracing::debug!("library: no readable revision stamp for entry {entry_id}: {e:#}");
                Self::Unreadable
            }
        }
    }
}

/// The revision token of the design at `url`: SHA-256 over a domain tag, the url and the
/// stamp -- O(1) per design, so a whole search page carries it. A version token, not a
/// content hash: it changes exactly when the stamp does, which is on every edit, and says
/// nothing about what changed. All zero bytes for [`Revision::Unreadable`], which no
/// stamped design can produce, so a client comparing it against a stored token always
/// sees a change.
///
/// Neither the server's `entry_id` (renumbering a rebuilt catalogue must not look like
/// an edit of every design -- a mirror keys designs by `url`) nor any content goes in.
pub(super) fn revision_token(url: &str, revision: Revision) -> [u8; 32] {
    let Revision::Stamped(stamp) = revision else {
        return [0u8; 32];
    };
    let mut hasher = Sha256::new();
    hash_str(&mut hasher, "indicatrix/design-revision/1");
    hash_str(&mut hasher, url);
    match stamp {
        Some(t) => {
            hasher.update([1u8]);
            hasher.update(t.to_le_bytes());
        }
        None => hasher.update([0u8]),
    }
    hasher.finalize().into()
}

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

    #[test]
    fn the_token_follows_the_url_and_the_stamp_only() {
        let a = revision_token("https://example.test/1", Revision::Stamped(Some(100)));
        assert_eq!(
            a,
            revision_token("https://example.test/1", Revision::Stamped(Some(100)))
        );
        assert_ne!(
            a,
            revision_token("https://example.test/1", Revision::Stamped(Some(101)))
        );
        assert_ne!(
            a,
            revision_token("https://example.test/2", Revision::Stamped(Some(100)))
        );
        assert_ne!(
            revision_token("https://example.test/1", Revision::Stamped(None)),
            revision_token("https://example.test/1", Revision::Stamped(Some(0)))
        );
        assert_ne!(a, [0u8; 32]);
    }

    #[test]
    fn an_unreadable_revision_is_the_all_zero_token() {
        assert_eq!(
            revision_token("https://example.test/1", Revision::Unreadable),
            [0u8; 32]
        );
    }
}