mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! Writing the result to a file instead of the primary channel.
//!
//! # Why the write is atomic
//!
//! The contract says the file is created whole or not created at all. A caller
//! that reads a half-written file cannot tell it from a complete one, and an
//! invocation stopped by a signal is exactly when that happens.
//!
//! So the bytes go to a temporary file in the *same* directory as the
//! destination and the name is moved into place only once every byte is on
//! disk. A move within one directory is a single operation as far as any reader
//! is concerned: the destination either still holds the old content or already
//! holds the new one. A temporary file elsewhere would not do, because moving
//! across directories can fall back to a copy, and a copy can be seen half done.

use crate::error::{Failure, Result};
use serde::Serialize;
use std::io::Write;
use std::path::{Path, PathBuf};

/// What a written file is reported as.
#[derive(Debug, Clone, Serialize)]
pub struct Report {
    /// Where the bytes ended up.
    pub path: PathBuf,
    /// How many bytes were written.
    pub bytes: u64,
    /// Signature of exactly those bytes.
    pub checksum: String,
}

/// Writes the bytes to the destination, whole or not at all.
///
/// # Errors
///
/// Returns a configuration failure when the destination cannot be written,
/// naming the path, so the caller fixes the destination rather than guessing.
pub fn write(path: &Path, bytes: &[u8]) -> Result<Report> {
    let folder = enclosing(path);
    // The temporary file lives beside the destination so the move that follows
    // stays inside one directory and cannot degrade into a copy.
    let mut staged =
        tempfile::NamedTempFile::new_in(folder).map_err(|cause| unwritable(path, &cause))?;

    staged
        .write_all(bytes)
        .and_then(|()| staged.as_file().sync_all())
        .map_err(|cause| unwritable(path, &cause))?;

    staged
        .persist(path)
        .map_err(|cause| unwritable(path, &cause.error))?;

    Ok(Report {
        path: path.to_path_buf(),
        bytes: bytes.len() as u64,
        checksum: super::checksum::of_bytes(bytes),
    })
}

/// A destination being filled a piece at a time, still whole or not at all.
///
/// # Why this exists beside [`write()`]
///
/// The parentheses are not decoration: `write` names both the function in this
/// module and the macro in the prelude, so the bare form is ambiguous and the
/// crate denies an ambiguous link. Written bare, it took the whole
/// documentation build down with it.
///
/// [`write()`] needs every byte in hand before it starts, which is fine for an
/// answer that was assembled anyway and impossible for one that is arriving. A
/// continuous flow has no complete set of bytes at any moment, so a caller who
/// asked for both a file and a flow used to get the flow on the primary channel
/// and no file at all — a silent nothing, with a successful exit beside it.
///
/// The signature is computed as the bytes go past rather than by reading the
/// file back, so nothing here holds the answer either.
pub struct Staged {
    /// Where the bytes are going once they are all on disk.
    destination: PathBuf,
    /// The file beside the destination that receives them meanwhile.
    file: tempfile::NamedTempFile,
    /// How many bytes have gone past.
    written: u64,
    /// The signature of everything that has gone past.
    digest: super::checksum::ByteSignature,
}

impl std::io::Write for Staged {
    fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
        let taken = self.file.write(bytes)?;
        self.digest.absorb(&bytes[..taken]);
        self.written += taken as u64;
        Ok(taken)
    }

    fn flush(&mut self) -> std::io::Result<()> {
        self.file.flush()
    }
}

impl Staged {
    /// Puts the finished bytes in place and reports what was written.
    ///
    /// # Errors
    ///
    /// Returns a configuration failure when the bytes cannot be settled or the
    /// destination cannot be reached, naming the path.
    pub fn finish(mut self) -> Result<Report> {
        self.file
            .flush()
            .and_then(|()| self.file.as_file().sync_all())
            .map_err(|cause| unwritable(&self.destination, &cause))?;

        self.file
            .persist(&self.destination)
            .map_err(|cause| unwritable(&self.destination, &cause.error))?;

        Ok(Report {
            bytes: self.written,
            checksum: self.digest.finish(),
            path: self.destination,
        })
    }
}

/// Opens a destination that will be filled a piece at a time.
///
/// # Errors
///
/// Returns a configuration failure when nothing can be staged beside the
/// destination, naming the path.
pub fn staged(path: &Path) -> Result<Staged> {
    let folder = enclosing(path);
    let file = tempfile::NamedTempFile::new_in(folder).map_err(|cause| unwritable(path, &cause))?;

    Ok(Staged {
        destination: path.to_path_buf(),
        file,
        written: 0,
        digest: super::checksum::ByteSignature::default(),
    })
}

/// The directory the destination sits in.
///
/// A bare file name has no parent, and staging in the current directory is what
/// keeps the move inside one directory for that case too.
fn enclosing(path: &Path) -> &Path {
    match path.parent() {
        Some(parent) if !parent.as_os_str().is_empty() => parent,
        _ => Path::new("."),
    }
}

/// The failure a destination that cannot be written produces.
fn unwritable(path: &Path, cause: &impl std::fmt::Display) -> Failure {
    Failure::config(
        "output.destination_unwritable",
        format!("the destination `{}` cannot be written", path.display()),
    )
    .with_detail("detail", path.display().to_string())
    .with_hint("point --output at a path inside a writable directory")
    .with_cause(cause.to_string())
}

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

    #[test]
    fn the_bytes_arrive_whole_with_their_own_signature() {
        let scratch = tempfile::tempdir().expect("scratch directory");
        let target = scratch.path().join("result.json");

        let report = write(&target, b"{\"rows\":[]}").expect("writes");
        assert_eq!(report.bytes, 11);
        assert_eq!(std::fs::read(&target).expect("reads"), b"{\"rows\":[]}");
        assert!(report.checksum.starts_with("sha256:"));
    }

    /// Two runs writing the same bytes must report the same signature, or the
    /// signature would be useless for comparing two runs.
    #[test]
    fn the_same_bytes_always_report_the_same_signature() {
        let scratch = tempfile::tempdir().expect("scratch directory");
        let first = write(&scratch.path().join("a"), b"same").expect("writes");
        let second = write(&scratch.path().join("b"), b"same").expect("writes");
        assert_eq!(first.checksum, second.checksum);

        let different = write(&scratch.path().join("c"), b"other").expect("writes");
        assert_ne!(first.checksum, different.checksum);
    }

    /// The destination is replaced whole, so a reader never sees the old
    /// content mixed with the new.
    #[test]
    fn an_existing_destination_is_replaced_whole() {
        let scratch = tempfile::tempdir().expect("scratch directory");
        let target = scratch.path().join("result.json");
        std::fs::write(&target, b"the previous answer").expect("writes");

        write(&target, b"new").expect("writes");
        assert_eq!(std::fs::read(&target).expect("reads"), b"new");
    }

    /// Nothing is staged where the destination cannot be reached, so a failed
    /// write never leaves a stray file behind.
    #[test]
    fn a_destination_that_cannot_be_reached_leaves_nothing_behind() {
        let scratch = tempfile::tempdir().expect("scratch directory");
        let missing = scratch.path().join("no-such-folder").join("result.json");

        let failure = write(&missing, b"x").expect_err("must refuse");
        assert_eq!(failure.code(), "output.destination_unwritable");
        assert_eq!(failure.exit_number().code(), 4);
        assert!(
            std::fs::read_dir(scratch.path())
                .expect("reads")
                .next()
                .is_none(),
            "a failed write must leave the directory as it found it"
        );
    }

    /// A bare file name has no parent directory, and must still be written.
    #[test]
    fn a_bare_name_is_staged_beside_itself() {
        assert_eq!(enclosing(Path::new("result.json")), Path::new("."));
        assert_eq!(enclosing(Path::new("/tmp/result.json")), Path::new("/tmp"));
    }
}