mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! One document per invocation.
//!
//! A continuous flow is still one document: the rows are written into an open
//! array as they arrive, and everything the envelope carries after them joins
//! the same object. Nothing is held back to be assembled at the end, so a long
//! flow costs no more memory than a short one.
//!
//! # The two paths write the same bytes, and that is the whole point
//!
//! This shape is the built-in one, so almost every caller reads it. It was
//! also the one shape a read could not be served as a flow in, which meant the
//! common case was the expensive case: the rows were gathered to be serialised
//! together.
//!
//! Writing them as they arrive is only worth anything if the answer is the
//! same answer. So the opening writes exactly the fields the gathered envelope
//! writes before its payload, in the order serde writes them, and the close
//! writes exactly the ones that come after. A caller cannot tell which path
//! served it, which is what lets the choice be made on cost alone.
//!
//! # Why this shape writes no `end_of_stream`
//!
//! FR-132 asks that a set cut part way through never look whole. The three
//! line-oriented shapes carry a closing record for that, because their output
//! is a sequence of lines and any prefix of it is still a sequence of lines.
//!
//! A document is not like that. The mark that this set is whole is that the
//! document was CLOSED, and a flow cut part way through leaves braces open,
//! which no parser accepts. Adding a field to say the same thing would break
//! the agreement between the two paths and tell a reader nothing the closing
//! brace had not already told it.

use super::{emit, emit_line, to_compact, Formatter, ROW_COUNT_KEY};
use crate::error::Result;
use crate::output::envelope::{Applied, Envelope, Row};
// Writing into a `String` rather than appending a formatted one, so the opening
// of a document costs one buffer instead of one per field.
use std::fmt::Write as _;
use std::io::Write;

/// The single document shape.
#[derive(Debug, Default)]
pub struct Json {
    /// Whether a row has already been written into the open array.
    wrote_row: bool,
}

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

    fn write_envelope(&mut self, writer: &mut dyn Write, envelope: &Envelope) -> Result<()> {
        emit_line(writer, &to_compact(envelope)?)
    }

    fn begin_stream(
        &mut self,
        writer: &mut dyn Write,
        head: &Envelope,
        columns: &[String],
    ) -> Result<()> {
        self.wrote_row = false;
        emit(writer, &opening(head, columns)?)
    }

    fn write_row(&mut self, writer: &mut dyn Write, row: &Row, line: &mut String) -> Result<()> {
        line.clear();
        if self.wrote_row {
            line.push(',');
        }
        line.push_str(&to_compact(row)?);
        self.wrote_row = true;
        emit(writer, line)
    }

    fn end_stream(
        &mut self,
        writer: &mut dyn Write,
        _tail: &Envelope,
        emitted: u64,
        gaps: &[crate::output::envelope::Gap],
        applied: Option<&Applied>,
    ) -> Result<()> {
        // The command and the destination were written when the document
        // opened, because that is where the gathered form writes them (FR-143).
        // What is left is the end of the payload and the two fields the
        // envelope carries after it, in the envelope's own order.
        let counted = declared_row_count(emitted, applied);
        let declared = super::gaps_as_json(gaps)?;
        let reported = match applied {
            Some(applied) => format!(r#","applied":{}"#, to_compact(applied)?),
            None => String::new(),
        };
        emit_line(
            writer,
            &format!(r#"],"{ROW_COUNT_KEY}":{counted}}}{declared}{reported}}}"#),
        )
    }
}

/// Everything the document carries before its rows, as serde would write it.
///
/// Read out of the envelope rather than written by hand, so a field added to
/// the envelope reaches this shape by existing rather than by somebody
/// remembering. The walk stops at the payload because the payload is what the
/// rows go into, and everything after it is written when the flow closes.
///
/// # Errors
///
/// Returns a server failure when the envelope cannot be rendered.
fn opening(head: &Envelope, columns: &[String]) -> Result<String> {
    let document = super::to_document(head)?;
    let mut text = String::from("{");
    for (name, value) in &document {
        if name == PAYLOAD {
            break;
        }
        if text.len() > 1 {
            text.push(',');
        }
        text.push_str(&to_compact(name)?);
        text.push(':');
        text.push_str(&to_compact(value)?);
    }
    if text.len() > 1 {
        text.push(',');
    }
    write!(
        text,
        r#""{PAYLOAD}":{{"columns":{},"rows":["#,
        to_compact(&columns)?
    )
    .map_err(|error| {
        crate::error::Failure::new(
            crate::error::Category::Server,
            "output.not_serialisable",
            "the opening of the answer could not be written",
        )
        .with_cause(error.to_string())
    })?;
    Ok(text)
}

/// The field of the envelope the rows travel inside.
const PAYLOAD: &str = "data";

/// The count the payload declares, which is the count of rows the read returned.
///
/// The gathered form writes the rows the read returned here and reports what
/// the pipeline kept of them separately, under `applied`. A flow knows the same
/// two numbers — what arrived and what left — so it declares the same one, and
/// falls back to what left only when nothing reported what arrived.
fn declared_row_count(emitted: u64, applied: Option<&Applied>) -> u64 {
    applied
        .and_then(|applied| applied.input_count)
        .and_then(|count| u64::try_from(count).ok())
        .unwrap_or(emitted)
}

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

    /// The document a flow writes declares where the rows came from (FR-143).
    ///
    /// The two fields are read back after the whole flow has been written,
    /// because that is how a caller meets them: the document is one value, and
    /// where inside it each field was written is the shape's business.
    #[test]
    fn the_document_names_the_command_and_the_destination() {
        let rows = vec![sample_row("alpha", 1)];
        let text = stream_through_from(&mut Json::default(), &rows, &tail_from_a_destination());
        let parsed: serde_json::Value =
            serde_json::from_str(text.trim_end()).expect("one document");
        assert_eq!(parsed["command"], "query run");
        assert_eq!(parsed["target_resolved"]["host"], "192.0.2.10");
        assert_eq!(parsed["data"][ROW_COUNT_KEY], 1);
    }

    /// The command and the destination are written BEFORE the rows, because
    /// that is where the gathered form of this shape writes them.
    ///
    /// Read on the bytes rather than on the parsed value, because a parser sees
    /// one object either way and the whole point of the repair is that the two
    /// paths write the same bytes.
    #[test]
    fn the_document_opens_with_the_envelope_and_not_with_the_rows() {
        let rows = vec![sample_row("alpha", 1)];
        let text = stream_through_from(&mut Json::default(), &rows, &tail_from_a_destination());
        assert!(
            text.starts_with(r#"{"command":"query run","schema_version":1,"target_resolved":{"#),
            "the document must open as its gathered form opens: {text}"
        );
        let target_at = text.find(r#""target_resolved""#).expect("a destination");
        let rows_at = text.find(r#""rows""#).expect("a payload");
        assert!(
            target_at < rows_at,
            "the envelope precedes the rows: {text}"
        );
    }

    #[test]
    fn an_answer_is_one_document_on_one_line() {
        let envelope = Envelope::new("meta version", json!({"version": "0.1.0"}));
        let mut out = Vec::new();
        Json::default()
            .write_envelope(&mut out, &envelope)
            .expect("writes");
        let text = String::from_utf8(out).expect("utf8");
        assert_eq!(text.matches('\n').count(), 1);
        assert!(text.ends_with('\n'));
        let parsed: serde_json::Value =
            serde_json::from_str(text.trim_end()).expect("one document");
        assert_eq!(parsed["command"], "meta version");
    }

    /// FR-132. A whole flow is one document, and being one document is what
    /// says it is whole.
    ///
    /// This used to assert `end_of_stream`, and no longer does. The field was
    /// this shape borrowing the mark the three line-oriented shapes need, where
    /// it says nothing the closing brace has not already said: a flow cut part
    /// way through leaves the braces open, which no parser accepts, and that is
    /// asserted below. Keeping the field would also have made this shape write
    /// bytes its own gathered form never writes, which is the disagreement the
    /// whole repair exists to remove.
    #[test]
    fn a_whole_flow_is_one_document_that_declares_its_count() {
        let rows = vec![sample_row("alpha", 1), sample_row("beta", 2)];
        let text = stream_through(&mut Json::default(), &rows);
        let parsed: serde_json::Value =
            serde_json::from_str(text.trim_end()).expect("one document");
        assert_eq!(parsed["data"]["rows"].as_array().expect("array").len(), 2);
        assert_eq!(parsed["data"][ROW_COUNT_KEY], 2);
        assert!(
            !text.contains(super::super::END_OF_STREAM_KEY),
            "a document says it is whole by closing: {text}"
        );
    }

    /// FR-132. A flow cut part way through leaves a document nothing can read.
    ///
    /// This is what replaces the borrowed field: the mark is structural. A
    /// reader does not have to trust a flag, because the bytes it was handed
    /// are not a document at all.
    #[test]
    fn a_flow_cut_part_way_through_leaves_a_document_that_never_closes() {
        let mut formatter = Json::default();
        let mut out = Vec::new();
        formatter
            .begin_stream(&mut out, &tail_from_a_destination(), &["name".to_owned()])
            .expect("opens");
        let mut line = String::new();
        formatter
            .write_row(&mut out, &sample_row("alpha", 1), &mut line)
            .expect("writes");
        // The channel died here, so the flow is never closed.
        let text = String::from_utf8(out).expect("utf8");
        assert!(
            serde_json::from_str::<serde_json::Value>(&text).is_err(),
            "a cut flow must not parse as a whole answer: {text}"
        );
    }

    #[test]
    fn an_empty_flow_still_closes_with_a_count_of_zero() {
        let text = stream_through(&mut Json::default(), &[]);
        let parsed: serde_json::Value =
            serde_json::from_str(text.trim_end()).expect("one document");
        assert_eq!(parsed["data"][ROW_COUNT_KEY], 0);
        assert_eq!(parsed["data"]["rows"].as_array().expect("array").len(), 0);
    }

    /// The pipeline's own report reaches the document, because the gathered
    /// form of this shape carries it and the two must not differ.
    #[test]
    fn what_the_pipeline_did_is_reported_exactly_as_the_gathered_form_reports_it() {
        let mut formatter = Json::default();
        let mut out = Vec::new();
        let tail = tail_from_a_destination();
        formatter
            .begin_stream(&mut out, &tail, &["name".to_owned()])
            .expect("opens");
        let reported = Applied {
            input_count: Some(9),
            output_count: Some(0),
            dropped: Some(9),
            ..Applied::default()
        };
        formatter
            .end_stream(&mut out, &tail, 0, &[], Some(&reported))
            .expect("closes");
        let text = String::from_utf8(out).expect("utf8");
        let parsed: serde_json::Value =
            serde_json::from_str(text.trim_end()).expect("one document");
        assert_eq!(parsed["applied"]["input_count"], 9);
        assert_eq!(parsed["applied"]["dropped"], 9);
        assert_eq!(
            parsed["data"][ROW_COUNT_KEY], 9,
            "the payload declares the rows the read returned, as the gathered form does: {text}"
        );
    }

    #[test]
    fn column_order_survives_the_round_trip() {
        let rows = vec![sample_row("alpha", 1)];
        let text = stream_through(&mut Json::default(), &rows);
        let name_at = text.find("\"name\"").expect("name present");
        let size_at = text.find("\"size\"").expect("size present");
        assert!(name_at < size_at, "declared column order must survive");
    }
}