mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! A row travels from the server to the channel without stopping in between.
//!
//! Nothing here holds a collection of rows. A row is rendered into a buffer
//! that is reserved once and reused for every row after it, then written and
//! forgotten. A million rows therefore cost the same memory as one, and the
//! caller sees the first row while the server is still sending the last.
//!
//! Every flow ends with a record that declares how many rows were emitted.
//! That record is written only when the flow reached its end. A connection
//! that drops mid-way leaves the output without it, which is exactly how a
//! reader watching only the primary channel tells a whole set from a cut one.
//! There is no way to switch the record off.

use super::envelope::Row;
use super::format::Formatter;
use crate::error::Result;
use std::io::Write;

/// How much room the reusable line buffer starts with.
///
/// One allocation up front is cheaper than one per row, and the buffer grows
/// on its own if a row turns out to be wider.
pub const INITIAL_LINE_CAPACITY: usize = 4096;

/// Everything a flow needs besides the rows themselves.
///
/// Gathered into one value because the three travel together everywhere: a work
/// that opens a flow always knows all three and never one without the others,
/// and carrying them apart made every call that opened a flow one argument
/// longer than the work it was doing.
pub struct Sink<'a, W: Write> {
    /// The channel the rows are written onto.
    pub writer: W,
    /// The shape they are written in.
    pub formatter: Box<dyn Formatter>,
    /// What the closing record declares besides the count: the command that
    /// produced the set and the destination it came from (FR-143).
    pub tail: &'a crate::output::Envelope,
}

/// A continuous flow of rows onto one channel.
///
/// The flow is finished by calling [`Stream::finish`]. Dropping it instead
/// leaves the output without the closing record, which is the honest outcome
/// for a flow that did not reach its end.
pub struct Stream<W: Write> {
    writer: W,
    formatter: Box<dyn Formatter>,
    /// Reused by every row, so a long flow allocates once.
    line: String,
    emitted: u64,
}

impl<W: Write> Stream<W> {
    /// Opens a flow over the declared columns.
    ///
    /// `head` is the same envelope the flow will close with. A shape that
    /// carries one record per line ignores it, because it meets the command and
    /// the destination at the end; the single document needs it here, because
    /// that is where its gathered form writes them.
    ///
    /// # Errors
    ///
    /// Returns a limit failure when the reader closed the channel before the
    /// first row.
    pub fn open(
        mut writer: W,
        mut formatter: Box<dyn Formatter>,
        head: &crate::output::Envelope,
        columns: &[String],
    ) -> Result<Self> {
        formatter.begin_stream(&mut writer, head, columns)?;
        Ok(Self {
            writer,
            formatter,
            line: String::with_capacity(INITIAL_LINE_CAPACITY),
            emitted: 0,
        })
    }

    /// Writes one row and forgets it.
    ///
    /// # Errors
    ///
    /// Returns a limit failure when the reader closed the channel.
    pub fn write(&mut self, row: &Row) -> Result<()> {
        self.formatter
            .write_row(&mut self.writer, row, &mut self.line)?;
        self.emitted += 1;
        Ok(())
    }

    /// How many rows have been written so far.
    #[must_use]
    pub const fn emitted(&self) -> u64 {
        self.emitted
    }

    /// The room the reusable buffer currently holds.
    ///
    /// Exposed so a test can show the buffer is reused rather than rebuilt.
    #[must_use]
    pub fn buffer_capacity(&self) -> usize {
        self.line.capacity()
    }

    /// Closes the flow with the record that declares it complete.
    ///
    /// The tail and the gaps are both handed in rather than gathered here,
    /// because neither is known by the writer that carried the rows: the tail
    /// names the command and the destination, which the dispatch resolved, and
    /// the gaps name what was left out, which the work that fed the flow knows.
    /// A flow cut by a ceiling still closes: it ended because the product
    /// decided it had, and the gap says so. A flow cut by a lost channel never
    /// reaches this at all, which is what keeps the two kinds of short answer
    /// telling apart from each other.
    ///
    /// `applied` is what the output pipeline did. It is handed in beside the
    /// tail because only the single document reports it: that shape's gathered
    /// form carries the field, so its streamed form has to carry it too or one
    /// request would have two answers.
    ///
    /// # Errors
    ///
    /// Returns a limit failure when the reader closed the channel.
    pub fn finish(
        mut self,
        tail: &crate::output::Envelope,
        gaps: &[crate::output::envelope::Gap],
        applied: Option<&crate::output::envelope::Applied>,
    ) -> Result<u64> {
        self.formatter
            .end_stream(&mut self.writer, tail, self.emitted, gaps, applied)?;
        self.writer.flush().ok();
        Ok(self.emitted)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::output::format::{ndjson::Ndjson, END_OF_STREAM_KEY, ROW_COUNT_KEY};
    use indexmap::IndexMap;
    use serde_json::json;

    /// The tail a flow closes with, carrying no destination.
    ///
    /// These proofs measure the closing record itself, so the tail is kept bare
    /// and what they measure stays the record.
    fn tail() -> crate::output::Envelope {
        crate::output::Envelope::new("query run", json!({}))
    }

    fn row(index: u64) -> Row {
        let mut row = IndexMap::new();
        row.insert("id".to_owned(), json!(index));
        row.insert("name".to_owned(), json!(format!("row-{index}")));
        row
    }

    #[test]
    fn a_whole_flow_ends_with_the_count_it_emitted() {
        let mut out = Vec::new();
        let mut stream = Stream::open(&mut out, Box::new(Ndjson), &tail(), &[]).expect("opens");
        for index in 0..5 {
            stream.write(&row(index)).expect("writes");
        }
        assert_eq!(stream.finish(&tail(), &[], None).expect("closes"), 5);

        let text = String::from_utf8(out).expect("utf8");
        let last = text.lines().next_back().expect("a last line");
        let parsed: serde_json::Value = serde_json::from_str(last).expect("parses");
        assert_eq!(parsed[END_OF_STREAM_KEY], true);
        assert_eq!(parsed[ROW_COUNT_KEY], 5);
        assert_eq!(text.lines().count(), 6, "five rows and the closing record");
    }

    #[test]
    fn a_flow_cut_in_the_middle_carries_no_closing_record() {
        struct FailsAfter {
            remaining: usize,
            written: Vec<u8>,
        }
        impl Write for FailsAfter {
            fn write(&mut self, buffer: &[u8]) -> std::io::Result<usize> {
                if self.remaining == 0 {
                    return Err(std::io::Error::new(
                        std::io::ErrorKind::ConnectionReset,
                        "the connection dropped",
                    ));
                }
                self.remaining -= 1;
                self.written.extend_from_slice(buffer);
                Ok(buffer.len())
            }
            fn flush(&mut self) -> std::io::Result<()> {
                Ok(())
            }
        }

        // Each row costs two writes: the line and its ending.
        let sink = FailsAfter {
            remaining: 4,
            written: Vec::new(),
        };
        let mut stream = Stream::open(sink, Box::new(Ndjson), &tail(), &[]).expect("opens");
        stream.write(&row(0)).expect("first row goes through");
        stream.write(&row(1)).expect("second row goes through");
        let dropped = stream.write(&row(2)).expect_err("the connection dropped");
        assert_eq!(dropped.code(), "output.write_failed");

        // The flow is abandoned, exactly as a dropped connection leaves it.
        drop(stream);
    }

    #[test]
    fn what_reached_the_channel_before_a_drop_is_whole_but_unterminated() {
        let mut out = Vec::new();
        {
            let mut stream = Stream::open(&mut out, Box::new(Ndjson), &tail(), &[]).expect("opens");
            stream.write(&row(0)).expect("writes");
            stream.write(&row(1)).expect("writes");
            // Dropped without finishing: the connection died here.
        }
        let text = String::from_utf8(out).expect("utf8");
        assert_eq!(text.lines().count(), 2, "only the rows that made it");
        assert!(
            !text.contains(END_OF_STREAM_KEY),
            "a cut set must never look whole: {text}"
        );
        for line in text.lines() {
            let _: serde_json::Value = serde_json::from_str(line).expect("each line is whole");
        }
    }

    #[test]
    fn the_line_buffer_is_reused_and_not_rebuilt_per_row() {
        let mut out = Vec::new();
        let mut stream = Stream::open(&mut out, Box::new(Ndjson), &tail(), &[]).expect("opens");
        let before = stream.buffer_capacity();
        assert!(
            before >= INITIAL_LINE_CAPACITY,
            "room is reserved once, up front"
        );
        for index in 0..10_000 {
            stream.write(&row(index)).expect("writes");
        }
        assert_eq!(
            stream.buffer_capacity(),
            before,
            "a long flow must not grow the buffer row by row"
        );
        assert_eq!(stream.finish(&tail(), &[], None).expect("closes"), 10_000);
    }

    #[test]
    fn an_empty_flow_still_declares_itself_complete() {
        let mut out = Vec::new();
        let stream = Stream::open(&mut out, Box::new(Ndjson), &tail(), &[]).expect("opens");
        assert_eq!(stream.finish(&tail(), &[], None).expect("closes"), 0);
        let text = String::from_utf8(out).expect("utf8");
        assert!(text.contains(END_OF_STREAM_KEY));
    }
}