mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! The signature of a result, for comparing two runs without keeping the data.
//!
//! # What the signature covers
//!
//! It is computed over the canonical form of the result: the column names and
//! the converted values, in the order the server declared them. It is never
//! computed over the formatted text.
//!
//! That choice matters. A caller that reads a set as one document and then
//! reads it again as one document per line is looking at the same data, and
//! must get the same signature; a signature taken over the formatted bytes
//! would change with the shape and say the data changed when it did not.
//! Separators between name, value and row are control characters that cannot
//! occur inside a rendered value, so two different results can never be fed in
//! as the same run of bytes.
//!
//! The digest is a pure Rust implementation, so the default build still needs
//! no C toolchain. The requirement names no algorithm; the name is carried in
//! the signature itself, so a later change stays readable.

use super::envelope::Row;
use serde_json::Value;
use sha2::{Digest, Sha256};

/// Separates a column name from its value.
const NAME_END: u8 = 0x1f;

/// Separates one field from the next.
const FIELD_END: u8 = 0x1e;

/// Separates one row from the next.
const ROW_END: u8 = 0x1d;

/// The name carried by every signature this release produces.
const ALGORITHM: &str = "sha256";

/// Accumulates the signature of a result as its rows go past.
///
/// Rows are fed in one at a time and never kept, so signing a long result
/// costs no more memory than signing a short one.
#[derive(Debug, Default)]
pub struct Signature {
    digest: Sha256,
    rows: u64,
}

impl Signature {
    /// Starts an empty signature.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Folds one row into the signature.
    pub fn absorb(&mut self, row: &Row) {
        for (name, value) in row {
            self.digest.update(name.as_bytes());
            self.digest.update([NAME_END]);
            self.digest.update(canonical(value).as_bytes());
            self.digest.update([FIELD_END]);
        }
        self.digest.update([ROW_END]);
        self.rows += 1;
    }

    /// How many rows have been folded in.
    #[must_use]
    pub const fn rows(&self) -> u64 {
        self.rows
    }

    /// Closes the signature and renders it.
    ///
    /// The row count is folded in last, so a result and the same result with a
    /// trailing empty row never share a signature.
    #[must_use]
    pub fn finish(mut self) -> String {
        self.digest.update(self.rows.to_be_bytes());
        format!("{ALGORITHM}:{}", hex::encode(self.digest.finalize()))
    }
}

/// The signature of a run of bytes exactly as they were written.
///
/// Kept apart from the row signature on purpose. This one answers "are these
/// two files the same"; the row signature answers "are these two result sets
/// the same", which stays true across a change of shape or of field order.
///
/// # Examples
///
/// The same bytes always answer the same, and one byte of difference is
/// enough to part them. Both halves matter: a signature that only agreed with
/// itself would be useless, and one that agreed with everything worse.
///
/// ```
/// use mariadb_cli::output::checksum::of_bytes;
///
/// assert_eq!(of_bytes(b"linha\n"), of_bytes(b"linha\n"));
/// assert_ne!(of_bytes(b"linha\n"), of_bytes(b"linhb\n"));
/// ```
///
/// The algorithm travels with the signature, so a reader never has to guess
/// which one produced it:
///
/// ```
/// use mariadb_cli::output::checksum::of_bytes;
///
/// assert!(of_bytes(b"").starts_with("sha256:"));
/// ```
#[must_use]
pub fn of_bytes(bytes: &[u8]) -> String {
    let mut digest = Sha256::new();
    digest.update(bytes);
    format!("{ALGORITHM}:{}", hex::encode(digest.finalize()))
}

/// The same signature as [`of_bytes`], over bytes that arrive a piece at a time.
///
/// A file being filled by a continuous flow never has all its bytes in one
/// place, so [`of_bytes`] cannot be reached for it. This folds them in as they
/// go past and renders exactly what that function would have rendered, which is
/// what lets a streamed file and a gathered one be compared at all.
///
/// The algorithm name stays inside this module either way. A second literal
/// elsewhere would be one more place to forget the day it changes.
#[derive(Debug, Default)]
pub struct ByteSignature {
    /// What has been folded in so far.
    digest: Sha256,
}

impl ByteSignature {
    /// Folds one run of bytes in.
    pub fn absorb(&mut self, bytes: &[u8]) {
        self.digest.update(bytes);
    }

    /// Closes the signature and renders it.
    #[must_use]
    pub fn finish(self) -> String {
        format!("{ALGORITHM}:{}", hex::encode(self.digest.finalize()))
    }
}

/// The signature of a whole set of rows.
#[must_use]
pub fn of_rows(rows: &[Row]) -> String {
    let mut signature = Signature::new();
    for row in rows {
        signature.absorb(row);
    }
    signature.finish()
}

/// The canonical text of one value.
///
/// Absence gets a marker of its own so it can never collide with the text that
/// marker is made of, and a structure keeps the field order it arrived with.
fn canonical(value: &Value) -> String {
    match value {
        Value::Null => "\u{0}absent".to_owned(),
        Value::String(text) => text.clone(),
        other => serde_json::to_string(other).unwrap_or_else(|_| other.to_string()),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use indexmap::IndexMap;
    use serde_json::json;

    fn row(name: &str, size: i64) -> Row {
        let mut row = IndexMap::new();
        row.insert("name".to_owned(), json!(name));
        row.insert("size".to_owned(), json!(size));
        row
    }

    #[test]
    fn the_same_input_always_produces_the_same_signature() {
        let rows = vec![row("alpha", 1), row("beta", 2)];
        assert_eq!(of_rows(&rows), of_rows(&rows));

        let again = vec![row("alpha", 1), row("beta", 2)];
        assert_eq!(
            of_rows(&rows),
            of_rows(&again),
            "a rebuilt result signs the same"
        );
    }

    #[test]
    fn the_signature_names_its_own_algorithm() {
        let signature = of_rows(&[row("alpha", 1)]);
        assert!(signature.starts_with("sha256:"), "{signature}");
        assert_eq!(signature.len(), "sha256:".len() + 64);
    }

    #[test]
    fn changing_one_cell_changes_the_signature() {
        assert_ne!(of_rows(&[row("alpha", 1)]), of_rows(&[row("alpha", 2)]));
        assert_ne!(of_rows(&[row("alpha", 1)]), of_rows(&[row("alphb", 1)]));
    }

    #[test]
    fn feeding_rows_one_at_a_time_matches_signing_them_together() {
        let rows = vec![row("alpha", 1), row("beta", 2), row("gamma", 3)];
        let mut streamed = Signature::new();
        for one in &rows {
            streamed.absorb(one);
        }
        assert_eq!(streamed.rows(), 3);
        assert_eq!(streamed.finish(), of_rows(&rows));
    }

    #[test]
    fn a_field_boundary_cannot_be_forged_from_content() {
        let mut joined = IndexMap::new();
        joined.insert("name".to_owned(), json!("alpha\u{1f}1"));
        let mut split = IndexMap::new();
        split.insert("name".to_owned(), json!("alpha"));
        split.insert("1".to_owned(), json!(""));
        assert_ne!(of_rows(&[joined]), of_rows(&[split]));
    }

    #[test]
    fn absence_signs_differently_from_empty_text() {
        let mut absent = IndexMap::new();
        absent.insert("name".to_owned(), Value::Null);
        let mut empty = IndexMap::new();
        empty.insert("name".to_owned(), json!(""));
        assert_ne!(of_rows(&[absent]), of_rows(&[empty]));
    }

    #[test]
    fn a_trailing_empty_row_changes_the_signature() {
        let one = vec![row("alpha", 1)];
        let two = vec![row("alpha", 1), IndexMap::new()];
        assert_ne!(of_rows(&one), of_rows(&two));
    }

    #[test]
    fn column_order_is_part_of_the_result_and_part_of_the_signature() {
        let mut reversed = IndexMap::new();
        reversed.insert("size".to_owned(), json!(1));
        reversed.insert("name".to_owned(), json!("alpha"));
        assert_ne!(of_rows(&[row("alpha", 1)]), of_rows(&[reversed]));
    }
}