mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
//! The four shapes the primary channel may take.
//!
//! Every formatter obeys the same three rules, and a formatter that breaks any
//! of them is a defect:
//!
//! 1. A line ends with a single line feed, on every operating system. The
//!    platform's own convention is never consulted, so a file written on one
//!    host compares equal to the same file written on another.
//! 2. The encoding is always UTF-8.
//! 3. Field order is fixed by the payload and never by a hash, so two runs of
//!    the same work produce the same bytes.
//!
//! Only the plain text shape is meant for a person to read. The other three
//! are meant for a program.

pub mod json;
pub mod ndjson;
pub mod text;
pub mod tsv;

use super::envelope::{Envelope, Row, Target};
use crate::cli::globals::OutputFormat;
use crate::error::{Failure, Result};
use serde_json::Value;
use std::io::Write;

/// The column names of a set of rows, in first-seen order.
///
/// Both column-shaped writers need this and both had their own copy of it,
/// under two different names — `column_names` beside the padded form and
/// `columns_of` beside the separated one — with identical bodies. Two copies of
/// one decision is two places to change when the decision changes, and the
/// second one is the copy that gets missed. First-seen order is such a
/// decision: it is what makes a row set with a ragged shape come out with its
/// columns in the order a reader met them, and both writers have to agree on it
/// or the same data reads differently depending on which one was asked for.
pub(super) fn column_names(elements: &[Value]) -> Vec<String> {
    let mut names: Vec<String> = Vec::new();
    for element in elements {
        let Some(fields) = element.as_object() else {
            continue;
        };
        for name in fields.keys() {
            if !names.iter().any(|seen| seen == name) {
                names.push(name.clone());
            }
        }
    }
    names
}

/// The line ending every formatter emits, on every platform.
pub const LINE_ENDING: char = '\n';

/// One shape of the primary channel.
///
/// The writer is taken as a trait object so a stream may hold a formatter
/// chosen at run time without the choice spreading through the call graph.
pub trait Formatter {
    /// The published name of this shape.
    fn name(&self) -> &'static str;

    /// Writes one whole answer.
    ///
    /// # Errors
    ///
    /// Returns a limit failure when the reader closed the channel, and a
    /// server failure when the answer could not be written.
    fn write_envelope(&mut self, writer: &mut dyn Write, envelope: &Envelope) -> Result<()>;

    /// Opens a continuous flow of rows over the declared columns.
    ///
    /// The columns are known before the first row arrives, so a shape that
    /// needs a header or a width never has to hold rows back to compute one.
    ///
    /// `head` is the envelope a flow never builds, and it arrives here for the
    /// same reason it arrives at [`Formatter::end_stream`]: the command that
    /// produced the set and the destination it came from are not properties of
    /// any row. A shape that carries one record per line writes them at the
    /// end, because a line-oriented reader meets them there. The single
    /// document has to write them BEFORE the rows, because that is where its
    /// own gathered form writes them, and a document whose fields arrived in
    /// another order would be a second shape wearing the first one's name.
    ///
    /// # Errors
    ///
    /// Returns a limit failure when the reader closed the channel.
    fn begin_stream(
        &mut self,
        writer: &mut dyn Write,
        head: &Envelope,
        columns: &[String],
    ) -> Result<()>;

    /// Writes one row of a continuous flow.
    ///
    /// `line` is a buffer the caller owns and reuses, so a long flow does not
    /// allocate once per row.
    ///
    /// # Errors
    ///
    /// Returns a limit failure when the reader closed the channel.
    fn write_row(&mut self, writer: &mut dyn Write, row: &Row, line: &mut String) -> Result<()>;

    /// Closes a continuous flow, declaring the count and what was left out.
    ///
    /// This record is what tells a whole set from a cut one. It is emitted only
    /// on a flow that ran to the end, and there is no way to switch it off.
    ///
    /// `tail` is the envelope a flow never builds: the command that produced
    /// the set and the destination it came from. A flow used to close without
    /// either, so the one shape that exists to be read while the work is still
    /// running was the one shape that never said where its rows had come from,
    /// which is exactly what FR-143 forbids.
    ///
    /// The gaps travel beside it rather than inside it because what a flow left
    /// out is known by the work that fed it and not by the work that named the
    /// destination. A set cut by a ceiling is still a set that ended by the
    /// product's own decision, so it still closes; what the gap adds is the
    /// reason, which FR-129 says may never be left silent.
    ///
    /// `applied` travels beside the tail rather than inside it because only the
    /// single document has anywhere to put it: its gathered form reports what
    /// the output pipeline did, so its streamed form has to report the same
    /// thing or one request would have two answers. Folding it into the tail
    /// would add a field to the closing record of the three line-oriented
    /// shapes as well, which nothing asked for.
    ///
    /// # Errors
    ///
    /// Returns a limit failure when the reader closed the channel.
    fn end_stream(
        &mut self,
        writer: &mut dyn Write,
        tail: &Envelope,
        emitted: u64,
        gaps: &[crate::output::envelope::Gap],
        applied: Option<&crate::output::envelope::Applied>,
    ) -> Result<()>;
}

/// The key the closing record uses to declare the flow complete.
pub const END_OF_STREAM_KEY: &str = "end_of_stream";

/// The key the closing record uses to declare what was left out.
pub const GAPS_KEY: &str = "gaps";

/// The gaps as the tail of a closing record, or nothing when there are none.
///
/// Written as a tail rather than as a whole field so a flow that left nothing
/// out closes with exactly the bytes it closed with before. A reader that never
/// meets a gap therefore sees no change at all, and the shape stays stable for
/// the case that is by far the common one.
///
/// # Errors
///
/// Returns a software failure when the gaps cannot be rendered, which would
/// mean a gap carrying text that is not valid to serialise.
fn gaps_as_json(gaps: &[crate::output::envelope::Gap]) -> Result<String> {
    if gaps.is_empty() {
        return Ok(String::new());
    }
    let rendered = to_compact(&gaps)?;
    Ok(format!(r#","{GAPS_KEY}":{rendered}"#))
}

/// The causes of the gaps, joined, for the shapes that carry no structure.
///
/// A line-oriented shape has no room for an object, and dropping the gap there
/// would leave one shape declaring what another hides. The cause is the stable
/// part of a gap — the prose beside it is for a person — so the cause is what
/// travels.
fn causes_of(gaps: &[crate::output::envelope::Gap]) -> String {
    gaps.iter()
        .map(|gap| gap.cause.as_str())
        .collect::<Vec<_>>()
        .join(",")
}

/// The key the closing record uses to declare how many rows were emitted.
pub const ROW_COUNT_KEY: &str = "row_count";

/// The destination as one piece of text, for the shapes that carry no structure.
///
/// A line-oriented shape has no room for an object, so the destination has to
/// arrive as text or not at all. The pieces are joined in the order a person
/// reads them — who served it, where it is, which database — and a piece that
/// was never decided is simply left out rather than written as an empty one.
#[must_use]
pub fn destination_text(target: &Target) -> String {
    let mut text = String::new();
    if let Some(profile) = &target.profile {
        text.push_str(profile);
        text.push('@');
    }
    if let Some(socket) = &target.socket {
        text.push_str(socket);
    } else if let Some(host) = &target.host {
        text.push_str(host);
        if let Some(port) = target.port {
            text.push(':');
            text.push_str(&port.to_string());
        }
    }
    if let Some(database) = &target.database {
        text.push('/');
        text.push_str(database);
    }
    text
}

/// The destination of a closing record as text, when there is one to write.
///
/// Answers `None` for a tail that names no destination and for one whose
/// destination turned out to be entirely undecided, so a shape never writes a
/// piece of text that says nothing.
fn destination_of(tail: &Envelope) -> Option<String> {
    let text = destination_text(tail.target.as_ref()?);
    (!text.is_empty()).then_some(text)
}

/// Builds the formatter for one published shape.
#[must_use]
pub fn for_format(format: OutputFormat) -> Box<dyn Formatter> {
    match format {
        OutputFormat::Json => Box::new(json::Json::default()),
        OutputFormat::Ndjson => Box::new(ndjson::Ndjson),
        OutputFormat::Tsv => Box::new(tsv::Tsv::default()),
        OutputFormat::Text => Box::new(text::Text::default()),
    }
}

/// Writes text through, turning a write error into a published failure.
///
/// A closed reader is not a fault of the work: it is the caller saying it has
/// read enough, and it carries its own published number.
///
/// # Errors
///
/// Returns a limit failure for a closed channel and a server failure for any
/// other write error.
pub fn emit(writer: &mut dyn Write, text: &str) -> Result<()> {
    writer
        .write_all(text.as_bytes())
        .map_err(|error| classify(&error))
}

/// Writes text and the single line feed that always ends a line.
///
/// # Errors
///
/// Returns a limit failure for a closed channel and a server failure for any
/// other write error.
pub fn emit_line(writer: &mut dyn Write, text: &str) -> Result<()> {
    emit(writer, text)?;
    writer
        .write_all(&[LINE_ENDING as u8])
        .map_err(|error| classify(&error))
}

/// Turns a write error into the published failure it belongs to.
///
/// # A category this copy carried for longer than the other one
///
/// A closed reader used to be reported as `Limit`, told apart from a real
/// ceiling only by the stable code. Giving it a category of its own is what
/// closed the gap recorded as G-002, and the change was made in
/// [`crate::output::sink`] — where the same decision was written a second time,
/// word for word, and where it stayed correct.
///
/// It was not made here. So every writer of a shaped answer — the padded form,
/// the separated one, the line-per-record one and the single document — went on
/// answering a walked-away reader with the ceiling category and its exit number
/// of 10, where the published contract says 141. The proofs read the code,
/// which was right in both copies, and the code is the one thing the two copies
/// agreed on.
///
/// The decision is stated once now, and `sink` reads it from here. This is the
/// exact failure the gap recorded as G-015 predicts for a decision written
/// twice: the second copy is not the one that gets fixed.
pub(crate) fn classify(error: &std::io::Error) -> Failure {
    if error.kind() == std::io::ErrorKind::BrokenPipe {
        // Its own category, not `Limit`. A reader that read enough and walked
        // away has nothing in common with a ceiling being reached, and sharing
        // a category made a caller read the stable code to tell them apart.
        return Failure::new(
            crate::error::Category::ChannelClosed,
            "output.broken_pipe",
            "the output channel was closed by the reader",
        );
    }
    Failure::new(
        crate::error::Category::Server,
        "output.write_failed",
        "the answer could not be written",
    )
    .with_cause(error.to_string())
}

/// Serialises a value compactly, in the payload's own field order.
///
/// # Errors
///
/// Returns a server failure when the value cannot be serialised.
pub fn to_compact(value: &impl serde::Serialize) -> Result<String> {
    serde_json::to_string(value).map_err(|error| {
        Failure::new(
            crate::error::Category::Server,
            "output.not_serialisable",
            "the answer could not be serialised",
        )
        .with_cause(error.to_string())
    })
}

/// Turns a value into its object form, so a shape may add a field to it.
///
/// A formatter that has to write more than the value carries — the record that
/// closes a set, for instance — needs somewhere to put it. Building that here
/// keeps the payload's own field order, because the order is a property of the
/// value and not of the writer.
///
/// # Errors
///
/// Returns a server failure when the value cannot be serialised, and when it
/// is not an object at all and therefore has no field to add to.
pub fn to_document(
    value: &impl serde::Serialize,
) -> Result<serde_json::Map<String, serde_json::Value>> {
    let document = serde_json::to_value(value).map_err(|error| {
        Failure::new(
            crate::error::Category::Server,
            "output.not_serialisable",
            "the answer could not be serialised",
        )
        .with_cause(error.to_string())
    })?;

    match document {
        serde_json::Value::Object(fields) => Ok(fields),
        _ => Err(Failure::new(
            crate::error::Category::Server,
            "output.not_a_document",
            "the answer is not an object and cannot carry a closing record",
        )),
    }
}

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

    /// Builds a row in a fixed column order.
    pub(super) fn sample_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
    }

    /// The tail of a flow that reached no destination at all.
    ///
    /// Used by the proofs that measure the closing record itself, so what they
    /// measure stays the record and never a destination they invented.
    pub(super) fn bare_tail() -> Envelope {
        Envelope::new("query run", json!({}))
    }

    /// The tail of a flow served by a destination, as the product builds one.
    pub(super) fn tail_from_a_destination() -> Envelope {
        bare_tail().from_destination(
            Target {
                profile: Some("producao".to_owned()),
                host: Some("192.0.2.10".to_owned()),
                port: Some(3306),
                socket: None,
                database: Some("loja".to_owned()),
            },
            crate::output::envelope::TargetSource::Argv,
        )
    }

    /// Runs a whole flow and returns what reached the channel.
    pub(super) fn stream_through(formatter: &mut dyn Formatter, rows: &[Row]) -> String {
        stream_through_from(formatter, rows, &bare_tail())
    }

    /// Runs a whole flow served by the given tail, and returns what it wrote.
    pub(super) fn stream_through_from(
        formatter: &mut dyn Formatter,
        rows: &[Row],
        tail: &Envelope,
    ) -> String {
        let mut out = Vec::new();
        let columns = vec!["name".to_owned(), "size".to_owned()];
        formatter
            .begin_stream(&mut out, tail, &columns)
            .expect("opens");
        let mut line = String::new();
        for row in rows {
            formatter
                .write_row(&mut out, row, &mut line)
                .expect("writes");
        }
        let count = u64::try_from(rows.len()).expect("fits");
        formatter
            .end_stream(&mut out, tail, count, &[], None)
            .expect("closes");
        String::from_utf8(out).expect("utf8")
    }

    /// Runs a whole flow whose set the volume ceiling cut short.
    ///
    /// Every shape has a rule for this and, until these proofs, not one of them
    /// was read by anything. The rule that omits the closing record was written
    /// with a measured regression beside it and was itself unmeasured.
    pub(super) fn stream_through_cut(formatter: &mut dyn Formatter, rows: &[Row]) -> String {
        let tail = bare_tail();
        let mut out = Vec::new();
        let columns = vec!["name".to_owned(), "size".to_owned()];
        formatter
            .begin_stream(&mut out, &tail, &columns)
            .expect("opens");
        let mut line = String::new();
        for row in rows {
            formatter
                .write_row(&mut out, row, &mut line)
                .expect("writes");
        }
        let count = u64::try_from(rows.len()).expect("fits");
        let cut = crate::output::envelope::Applied {
            output_truncated: true,
            ..crate::output::envelope::Applied::default()
        };
        formatter
            .end_stream(&mut out, &tail, count, &[], Some(&cut))
            .expect("closes");
        String::from_utf8(out).expect("utf8")
    }

    /// No shape tells a reader that a cut set is whole.
    ///
    /// The two shapes a program reads answer by withholding the record that
    /// claims completeness, because in those shapes the record IS the claim.
    /// The shape a person reads cannot withhold it — a person left with rows
    /// and no closing line would read that as the end — so it says so instead.
    ///
    /// Written as one proof over all four shapes rather than three of its own,
    /// because the property belongs to the product and not to any one writer,
    /// and a shape added tomorrow has to answer it here.
    #[test]
    fn no_shape_claims_a_cut_set_is_whole() {
        let rows = vec![sample_row("alpha", 1)];

        for shape in [OutputFormat::Ndjson, OutputFormat::Tsv] {
            let written = stream_through_cut(&mut *for_format(shape), &rows);
            assert!(
                !written.contains(END_OF_STREAM_KEY),
                "{shape:?} closed a cut flow: {written}"
            );
        }

        let read_by_a_person = stream_through_cut(&mut *for_format(OutputFormat::Text), &rows);
        assert!(
            read_by_a_person.contains("cut"),
            "the shape a person reads said nothing about the cut: {read_by_a_person}"
        );
    }

    /// A flow nobody cut still closes, in every shape that closes at all.
    ///
    /// The guard above passes trivially if a shape stops closing altogether, so
    /// this is what stops the fix from becoming the next defect.
    #[test]
    fn a_whole_set_still_gets_the_record_that_declares_it_whole() {
        let rows = vec![sample_row("alpha", 1)];

        for shape in [OutputFormat::Ndjson, OutputFormat::Tsv, OutputFormat::Text] {
            let written = stream_through(&mut *for_format(shape), &rows);
            assert!(
                written.contains(END_OF_STREAM_KEY),
                "{shape:?} lost its closing record: {written}"
            );
            assert!(
                !written.contains("cut"),
                "{shape:?} reported a cut that never happened: {written}"
            );
        }
    }

    #[test]
    fn every_published_shape_has_a_formatter_with_its_own_name() {
        let shapes = [
            OutputFormat::Json,
            OutputFormat::Ndjson,
            OutputFormat::Tsv,
            OutputFormat::Text,
        ];
        let mut names: Vec<&str> = shapes
            .into_iter()
            .map(|shape| for_format(shape).name())
            .collect();
        let before = names.len();
        names.sort_unstable();
        names.dedup();
        assert_eq!(
            names.len(),
            before,
            "each shape must name itself distinctly"
        );
    }

    #[test]
    fn a_line_never_carries_the_platform_convention() {
        let mut out = Vec::new();
        emit_line(&mut out, "one").expect("writes");
        assert_eq!(out, b"one\n", "a line ends with a single line feed");
    }

    /// A walked-away reader answers the same on this door as on the other one.
    ///
    /// This assertion used to read the stable code and stop there, and stopping
    /// there is what let the two doors drift apart. The sibling in
    /// [`crate::output::sink`] was corrected to give a closed reader its own
    /// category; this path was not, and went on answering with the ceiling
    /// category and its exit number of 10 where the contract publishes 141. The
    /// code was `output.broken_pipe` on both the whole time, so the one thing
    /// this test read was the one thing that never moved.
    ///
    /// Both the category and the number are read now, because the category is
    /// what a caller branches on and the number is what a shell branches on,
    /// and neither is recoverable from the code alone.
    #[test]
    fn a_closed_reader_maps_to_the_published_broken_pipe_failure() {
        struct Closed;
        impl Write for Closed {
            fn write(&mut self, _: &[u8]) -> std::io::Result<usize> {
                Err(std::io::Error::new(
                    std::io::ErrorKind::BrokenPipe,
                    "closed",
                ))
            }
            fn flush(&mut self) -> std::io::Result<()> {
                Ok(())
            }
        }
        let failure = emit(&mut Closed, "anything").expect_err("must fail");
        assert_eq!(failure.code(), "output.broken_pipe");
        assert_eq!(failure.category(), crate::error::Category::ChannelClosed);
        assert_ne!(failure.category(), crate::error::Category::Limit);
        assert_eq!(failure.exit_number().code(), 141);
    }

    /// The two doors onto the primary channel answer a closed reader alike.
    ///
    /// Written as one assertion across both rather than as a better assertion
    /// on each, because what failed here was not either door on its own. Each
    /// was internally consistent and each had a proof that passed. What nothing
    /// measured was that they agreed, and they had not agreed for as long as
    /// the second category existed.
    #[test]
    fn both_doors_onto_the_channel_answer_a_closed_reader_alike() {
        let closed = std::io::Error::new(std::io::ErrorKind::BrokenPipe, "closed");
        let shaped = classify(&closed);
        let enveloped = crate::output::sink::classify_for_proof(&closed);
        assert_eq!(shaped.code(), enveloped.code());
        assert_eq!(shaped.category(), enveloped.category());
        assert_eq!(shaped.exit_number().code(), enveloped.exit_number().code());
    }
}