mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! One document per line.
//!
//! This is the shape a reader consumes while the work is still running: each
//! line stands on its own, so a reader that stops early has still read whole
//! documents. The last line is the record that declares the flow complete, and
//! a reader that never sees it knows the set was cut.

use super::{emit_line, to_compact, to_document, Formatter, END_OF_STREAM_KEY, ROW_COUNT_KEY};
use crate::error::Result;
use crate::output::envelope::{Envelope, Row};
use serde_json::Value;
use std::io::Write;

/// The one-document-per-line shape.
#[derive(Debug, Clone, Copy)]
pub struct Ndjson;

impl Formatter for Ndjson {
    fn name(&self) -> &'static str {
        "ndjson"
    }

    fn write_envelope(&mut self, writer: &mut dyn Write, envelope: &Envelope) -> Result<()> {
        // An answer carrying no set of rows is one document, and writing it as
        // one line is already the shape. Writing a set of rows as one line is
        // not: it is the single-document shape wearing another name, and a
        // caller who asked for this one so it could read a row at a time gets
        // nothing it asked for.
        let Some(key) = envelope.payload_array_key() else {
            return emit_line(writer, &to_compact(envelope)?);
        };

        let mut emitted: u64 = 0;
        if let Some(rows) = envelope.data.get(key).and_then(Value::as_array) {
            for row in rows {
                emit_line(writer, &to_compact(row)?)?;
                emitted += 1;
            }
        }

        // Everything the envelope carries besides the rows travels on the last
        // line, alongside the same closing record a continuous flow writes. A
        // reader therefore learns the count, the gaps and the signature the
        // same way whether the rows were gathered or streamed, and a reader
        // that never sees this line knows the set was cut.
        let mut closing = envelope.clone();
        if let Some(payload) = closing.data.as_object_mut() {
            payload.remove(key);
        }
        emit_line(writer, &closing_record(&closing, emitted)?)
    }

    fn begin_stream(
        &mut self,
        _writer: &mut dyn Write,
        _head: &Envelope,
        _columns: &[String],
    ) -> Result<()> {
        // Nothing opens a flow here: every line already stands on its own.
        Ok(())
    }

    fn write_row(&mut self, writer: &mut dyn Write, row: &Row, line: &mut String) -> Result<()> {
        line.clear();
        line.push_str(&to_compact(row)?);
        emit_line(writer, line)
    }

    fn end_stream(
        &mut self,
        writer: &mut dyn Write,
        tail: &Envelope,
        emitted: u64,
        gaps: &[crate::output::envelope::Gap],
        // Read for one thing only: whether the set was cut. What the pipeline
        // did belongs to the shape whose gathered form reports it, and this
        // shape's closing record carries the count and the tail alone.
        applied: Option<&crate::output::envelope::Applied>,
    ) -> Result<()> {
        // FR-132. A cut set gets no closing record, because in this shape the
        // record IS the statement that the set is whole. The document shape
        // has to close whatever it opened, so it is now asked to close even
        // when cut; this shape has nothing open, and closing it anyway would
        // turn a cut answer into one that says it is complete.
        //
        // Measured: without this, a read whose connection dropped part way
        // through ended with the record that declares completion.
        if applied.is_some_and(|applied| applied.output_truncated) {
            return Ok(());
        }

        // Built from the tail through the same function the gathered path uses,
        // so the last line of a flow and the last line of a gathered answer are
        // one record with one field order and not two that merely resemble each
        // other.
        let mut closing = tail.clone();
        closing.gaps = gaps.to_vec();
        emit_line(writer, &closing_record(&closing, emitted)?)
    }
}

/// The one closing record this shape writes, whichever path fed it.
///
/// The gathered path hands in the answer with its rows already removed, and the
/// flow hands in the tail it was given. Both then carry the same fields in the
/// same order, which is what lets a reader parse one line rather than two.
///
/// # Errors
///
/// Returns a server failure when the record cannot be serialised.
fn closing_record(closing: &Envelope, emitted: u64) -> Result<String> {
    let mut document = to_document(closing)?;
    document.insert(END_OF_STREAM_KEY.to_owned(), Value::Bool(true));
    document.insert(ROW_COUNT_KEY.to_owned(), Value::from(emitted));
    to_compact(&document)
}

#[cfg(test)]
mod tests {
    use super::super::tests::{
        bare_tail, sample_row, stream_through, stream_through_from, tail_from_a_destination,
    };
    use super::*;

    /// The last line of a flow declares where the rows came from, exactly as
    /// the last line of a gathered answer does (FR-143).
    #[test]
    fn the_closing_record_names_the_command_and_the_destination() {
        let rows = vec![sample_row("alpha", 1)];
        let text = stream_through_from(&mut Ndjson, &rows, &tail_from_a_destination());
        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["command"], "query run");
        assert_eq!(parsed["target_resolved"]["host"], "192.0.2.10");
        assert_eq!(parsed["target_resolved"]["database"], "loja");
        assert_eq!(parsed[END_OF_STREAM_KEY], true);
        assert_eq!(parsed[ROW_COUNT_KEY], 1);
    }

    #[test]
    fn every_row_is_a_document_of_its_own() {
        let rows = vec![sample_row("alpha", 1), sample_row("beta", 2)];
        let text = stream_through(&mut Ndjson, &rows);
        let lines: Vec<&str> = text.lines().collect();
        assert_eq!(lines.len(), 3, "two rows and the closing record");
        for line in &lines {
            let _: serde_json::Value = serde_json::from_str(line).expect("each line parses alone");
        }
    }

    #[test]
    fn the_last_line_declares_the_count() {
        let rows = vec![
            sample_row("alpha", 1),
            sample_row("beta", 2),
            sample_row("gamma", 3),
        ];
        let text = stream_through(&mut Ndjson, &rows);
        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], 3);
    }

    #[test]
    fn a_flow_that_was_cut_carries_no_closing_record() {
        let mut out = Vec::new();
        let mut formatter = Ndjson;
        formatter
            .begin_stream(&mut out, &bare_tail(), &[])
            .expect("opens");
        let mut line = String::new();
        formatter
            .write_row(&mut out, &sample_row("alpha", 1), &mut line)
            .expect("writes");
        // The flow is abandoned here, exactly as a dropped connection would.
        let text = String::from_utf8(out).expect("utf8");
        assert!(
            !text.contains(END_OF_STREAM_KEY),
            "a cut flow must not look whole"
        );
    }

    #[test]
    fn every_line_ends_with_a_single_line_feed() {
        let text = stream_through(&mut Ndjson, &[sample_row("alpha", 1)]);
        assert!(!text.contains('\r'), "no platform convention may leak in");
        assert!(text.ends_with('\n'));
    }
}