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
//! One-shot, agent-native command line client for MariaDB servers.
//!
//! The process is born, does its work and dies within a single invocation.
//! There is no daemon, no connection reused across invocations and no state
//! that survives the process.
//!
//! # Channels
//!
//! The primary channel carries data only, in the published shape. Diagnostics,
//! progress and warnings go to the auxiliary channel and never mix with data.
//!
//! # Defence against unintended change
//!
//! Three layers guard every statement, and only the first does not depend on
//! reading the statement text correctly:
//!
//! 1. Every statement travels as a prepared statement. The server refuses a
//!    prepared text that carries more than one statement, so the multiple
//!    command refusal lives on the server side. No local file handler is
//!    registered either, so a server request to read a client file fails.
//! 2. The statement is classified by its syntax tree before it is sent, over a
//!    text already stripped of comments and literals.
//! 3. Two defences do not depend on this tool behaving correctly, and the
//!    manual says so: a credential restricted on the server, and the read-only
//!    lock the server itself holds around work declared as reading. A statement
//!    that escaped classification would still be refused by the second one.

#![forbid(unsafe_code)]
// Every public item is part of the published documentation, so an undocumented
// one is a gap a reader meets rather than a note somebody meant to write later.
//
// Refused outright rather than warned about. A warning is a note nobody has to
// read, and this one had already been left unread: the published documentation
// is generated from these comments, so an item without one ships a blank space
// to every reader of the manual. Refusing it costs the writer one sentence and
// costs the reader nothing.
#![deny(missing_docs)]
// The same reasoning applied to the documentation itself. A link that names an
// item which no longer exists points the reader nowhere, and a code block that
// was never meant to compile fails the build of the manual rather than the
// build of the product, which is where nobody is looking.
#![deny(rustdoc::broken_intra_doc_links)]
#![deny(rustdoc::invalid_codeblock_attributes)]
// The stricter half of the linter, refused rather than warned about. Every one
// of its complaints was answered before this line was written: the casts that
// discarded bits, the arguments taken by value and never consumed, the items
// declared after the statements that already ran. Left as warnings they are
// read once and scrolled past; denied, the next one has to be answered on the
// day it appears. Where the lint is wrong the exception is written down beside
// the code with the reason, which is a sentence somebody can argue with.
#![deny(clippy::pedantic)]

pub mod cli;
pub mod commands;
pub mod config;
pub mod conn;
pub mod datamove;
pub mod dispatch;
pub mod error;
pub mod exec;
pub mod history;
pub mod i18n;
pub mod introspect;
pub mod obs;
pub mod output;
pub mod runtime;
pub mod serverinfo;
pub mod settings;
pub mod sql;
pub mod types;

use clap::Parser;
use error::{ExitNumber, Failure};
use std::io::Write;

/// Whether this build carries network encryption.
///
/// The default build carries it, and carries it without a C toolchain, because
/// the cryptography provider is written entirely in Rust and installed at
/// startup. This value is what `meta version` and `conn test` report, so the
/// product never overstates nor understates its own capability.
pub const ENCRYPTED_CHANNEL_AVAILABLE: bool = cfg!(feature = "tls");

/// Runs one invocation from start to finish.
///
/// The phases run in order: parse arguments, validate preconditions, execute,
/// release. The exit number is returned rather than applied, so a caller may
/// drive this function from a test.
///
/// Never fails: every failure is rendered on the auxiliary channel and turned
/// into its published exit number.
pub fn run<O: Write, E: Write>(
    argv: Vec<std::ffi::OsString>,
    out: &mut O,
    err: &mut E,
) -> ExitNumber {
    // A parse that fails never reaches the layer that decides the language, so
    // the refusal was written in the host language even when the caller named
    // another one on the same line. The mark is read straight from the argument
    // list first, and only well enough to answer in the language that was
    // asked for: a value this build does not carry changes nothing here and is
    // reported by the parse failure that follows it. A parse that succeeds
    // installs the language again from the settings, so the stored value keeps
    // its place and the documented order is left as it is.
    if let Some(requested) = requested_language(&argv) {
        let _ = i18n::install(Some(&requested), None);
    }

    let cli = match cli::Cli::try_parse_from(argv) {
        Ok(parsed) => parsed,
        Err(parse_error) => return render_parse_outcome(&parse_error, out, err),
    };

    // The guard is held for the whole invocation: dropping it early truncates
    // whatever the file writer still holds, which is the last diagnostics of
    // the run and exactly the ones worth keeping.
    let _guard = match install_auxiliary_channel(&cli, err) {
        Ok(guard) => guard,
        Err(failure) => {
            let _ = error::render::write_failure(err, &failure);
            return failure.exit_number();
        }
    };

    // The cryptography provider is installed once, before anything can open a
    // channel. Doing it here rather than lazily keeps the choice in one place
    // and turns a provider that cannot be installed into a rendered failure
    // instead of a panic from inside the encryption stack.
    // The protocol floor is imposed by which cipher suites the provider offers,
    // so it has to be decided before the provider is installed and cannot be
    // handed to the driver later.
    let floor = settings::protocol_floor(cli.globals.diagnostics.config_dir.as_deref());
    if let Err(failure) = conn::provider::install(floor) {
        let _ = error::render::write_failure(err, &failure);
        return failure.exit_number();
    }

    match dispatch(&cli, out) {
        Ok(number) => number,
        Err(failure) => {
            let _ = error::render::write_failure(err, &failure);
            // A closed reader used to need a special case here, because it
            // carried the `Limit` category and would have ended with the wrong
            // number. It has its own category now, so the ordinary mapping
            // answers 141 by itself and there is nothing to special-case.
            failure.exit_number()
        }
    }
}

/// Installs the auxiliary channel, separating a bad request from a bad file.
///
/// The two failures this can meet are not the same thing, and treating them
/// alike is what made `--lang klingon` end successfully with nothing written
/// anywhere. Deciding what the channel obeys reads the marks on the command
/// line, so a mark outside its domain is incorrect use and has to cost the
/// invocation. Opening the file the diagnostics are kept in does not: the work
/// the caller asked for still has to happen, so that failure is reported on
/// the channel itself and the invocation carries on.
///
/// An already-installed channel is not a failure at all: the subscriber is
/// global to the process, so a caller driving `run` more than once inside one
/// process reaches this on every call after the first.
///
/// # Errors
///
/// Returns the failure of resolving what the channel obeys, which is a usage
/// failure for a mark outside its domain and a configuration failure for a
/// stored value outside its own.
fn install_auxiliary_channel<E: Write>(
    cli: &cli::Cli,
    err: &mut E,
) -> error::Result<Option<tracing_appender::non_blocking::WorkerGuard>> {
    // A settings file that cannot be read is left to the work, which loads it
    // again and reports it there with its own cause. Reporting it twice would
    // put the same failure on the channel under two different headings.
    let Ok(config) = config::Config::load(cli.globals.diagnostics.config_dir.as_deref()) else {
        return Ok(None);
    };

    let settings = obs::settings::resolve(&config, &cli.globals)?;
    match obs::install(&settings) {
        Ok(guard) => Ok(guard),
        // The subscriber is global to the process, so this is the second call
        // inside one process and not a fault to report.
        Err(failure) if failure.code() == "log.already_installed" => Ok(None),
        Err(failure) => {
            let _ = error::render::write_failure(err, &failure);
            Ok(None)
        }
    }
}

/// Reads `--lang` straight from the argument list.
///
/// This is not a second parser and must not become one. It answers a single
/// question the real parser cannot answer once it has failed: which language
/// the caller asked the answer to be written in. Both spellings the parser
/// accepts are read, `--lang pt-BR` and `--lang=pt-BR`, because the caller
/// chooses between them and neither is more correct than the other.
///
/// Reading stops at `--`, since what follows it was declared not to be a mark.
/// An argument that is not text is stepped over rather than ending the search:
/// a path that no encoding can name says nothing about the language, and
/// letting it stop the walk would hide a `--lang` written after it.
fn requested_language(argv: &[std::ffi::OsString]) -> Option<String> {
    let mut items = argv.iter();
    while let Some(item) = items.next() {
        let Some(text) = item.to_str() else { continue };
        if text == "--" {
            break;
        }
        if text == "--lang" {
            return items
                .next()
                .and_then(|value| value.to_str())
                .map(str::to_owned);
        }
        if let Some(value) = text.strip_prefix("--lang=") {
            return Some(value.to_owned());
        }
    }
    None
}

/// Renders an outcome from the argument layer.
///
/// Help and version are successful outcomes, not failures, so they reach the
/// primary channel with a zero exit. Everything else is a usage failure.
fn render_parse_outcome<O: Write, E: Write>(
    parse_error: &clap::Error,
    out: &mut O,
    err: &mut E,
) -> ExitNumber {
    use clap::error::ErrorKind;

    if matches!(
        parse_error.kind(),
        ErrorKind::DisplayHelp
            | ErrorKind::DisplayVersion
            | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
    ) {
        let _ = write!(out, "{parse_error}");
        return ExitNumber::Success;
    }

    let failure = Failure::usage(
        "usage.invalid_arguments",
        "the arguments given do not match the accepted form",
    )
    .with_hint("run with --help to see the accepted form")
    .with_cause(parse_error.to_string());
    let _ = error::render::write_failure(err, &failure);
    ExitNumber::Usage
}

/// Routes one parsed invocation to the command that serves it, and declares
/// what the answer cost on the primary channel.
///
/// The declaration is made from here rather than from any of the writers
/// underneath, because this is the one point every shape of answer passes
/// through: a whole envelope, the receipt of an answer written to a file, and
/// a continuous flow that wrote its own rows and returned nothing all leave
/// through this counter. Made after the work rather than inside it, so an
/// answer cut short by a failure still declares the bytes it had already spent
/// of the caller's context (FR-139).
fn dispatch<O: Write>(cli: &cli::Cli, out: &mut O) -> error::Result<ExitNumber> {
    let mut counted = output::Counted::new(out);
    // One runtime for the whole invocation, built here rather than around the
    // part of the work that opens a destination. The signals are watched for as
    // long as it lives, which is what makes shaping the answer and settling the
    // file interruptible; see `dispatch::under_signals` for what being deaf in
    // that stretch actually cost.
    let outcome = match dispatch::build_runtime() {
        Ok(runtime) => runtime.block_on(dispatch::under_signals(async |shutdown| {
            served(cli, &mut counted, shutdown).await
        })),
        Err(failure) => Err(failure),
    };
    i18n::report::response_volume(counted.bytes(), counted.lines());
    outcome
}

/// Serves one invocation onto the channel the volume is counted on.
async fn served<O: Write>(
    cli: &cli::Cli,
    out: &mut O,
    shutdown: &runtime::Shutdown,
) -> error::Result<ExitNumber> {
    // Building the pipeline first refuses a malformed filter before any work
    // starts, so a typo never costs a connection. The stored settings are read
    // for it, because the ceiling per cell is a published key that the mark on
    // the command line only overrides.
    // Read here for the same reason it is read again further down, and refused
    // here for one command less. Three places in this codebase say a settings
    // file that cannot be read is "reported by the work, which loads it again":
    // this one, the auxiliary channel above, and the protocol floor. None of
    // them had checked that the work ever got the chance, and it did not — this
    // line and the one in `dispatch::serve` both refused first, so the
    // diagnosis written for exactly this case was unreachable (G-019).
    let config_dir = cli.globals.diagnostics.config_dir.as_deref();
    let config = match config::Config::load(config_dir) {
        Ok(config) => config,
        Err(unreadable) if dispatch::diagnoses_the_settings(&cli.command) => {
            config::Config::with_nothing_stored(config_dir).map_err(|_| unreadable)?
        }
        Err(unreadable) => return Err(unreadable),
    };

    // The published shape is chosen once, here, so no command decides how its
    // own answer looks. It is chosen before the pipeline because one of the
    // pipeline's refusals depends on it.
    let format = output_shape(cli, &config)?;
    cli.globals.refuse_a_profile_over_a_flow(format)?;
    let pipeline = cli.globals.pipeline(&config)?;

    // A caller who asked for a file gets the work written into the file, and
    // that has to hold for a continuous flow as well. It did not: the flow
    // wrote its rows to the primary channel and returned nothing to write, and
    // the branch below was never reached — a successful exit and no file, with
    // nothing said about either.
    let Some(path) = cli.globals.output.output.clone() else {
        let Some(envelope) = dispatch::serve(cli, out, shutdown).await? else {
            // A continuous flow already wrote its rows and its closing record.
            return Ok(ExitNumber::Success);
        };
        let shaped = signed(cli, pipeline.apply(envelope)?)?;
        output::format::for_format(format).write_envelope(out, &shaped)?;
        return Ok(ExitNumber::Success);
    };

    let mut staged = output::destination::staged(&path)?;
    let served = dispatch::serve(cli, &mut staged, shutdown).await?;
    let command = match served {
        // The flow wrote its rows into the file as they arrived, so nothing is
        // left to shape and the file is already whole once it is settled.
        None => cli.command.published_name(),
        Some(envelope) => {
            let shaped = signed(cli, pipeline.apply(envelope)?)?;
            // Almost every answer is written as the envelope that describes it.
            // An answer that declares one of its fields a document in its own
            // right is written as that document, because a file named for a
            // manual page has to be openable by a reader of manual pages.
            match shaped.raw_document() {
                Some(document) => staged
                    .write_all(document.as_bytes())
                    .map_err(|cause| unwritable(&path, &cause))?,
                None => output::format::for_format(format).write_envelope(&mut staged, &shaped)?,
            }
            shaped.command
        }
    };

    let report = staged.finish()?;
    // What reaches the primary channel is the account of the write, so a caller
    // that redirected the result still gets a parseable answer.
    let receipt = output::Envelope::new(command, serde_json::to_value(&report).unwrap_or_default());
    output::format::for_format(format).write_envelope(out, &receipt)?;
    Ok(ExitNumber::Success)
}

/// The failure a destination that stops accepting bytes produces.
fn unwritable(path: &std::path::Path, cause: &std::io::Error) -> error::Failure {
    error::Failure::config(
        "output.destination_unwritable",
        "the destination stopped accepting the answer",
    )
    .with_detail("detail", path.display().to_string())
    .with_cause(cause.to_string())
}

/// The shape the primary channel is written in.
///
/// The mark on the command line wins over the stored key, which wins over the
/// built-in shape. Reading only the mark, as this once did, made
/// `config set output.format` a setting the product stored, read back and
/// reported as being in force while writing something else.
///
/// # Errors
///
/// Returns a configuration failure when the stored shape is outside its domain.
pub fn output_shape(
    cli: &cli::Cli,
    config: &config::Config,
) -> error::Result<cli::globals::OutputFormat> {
    use cli::globals::OutputFormat;

    if let Some(asked) = cli.globals.output.output_format {
        return Ok(asked);
    }

    Ok(match settings::word(config, "output.format")?.as_str() {
        "ndjson" => OutputFormat::Ndjson,
        "tsv" => OutputFormat::Tsv,
        "text" => OutputFormat::Text,
        // The registry's own domain is what the words above come from, so the
        // remaining one is the built-in shape and there is no fourth case.
        _ => OutputFormat::Json,
    })
}

/// Attaches the signature of the result, when one was asked for.
///
/// A signature over an answer the volume ceiling cut short would be the
/// signature of a different set from the one the caller meant to sign, and
/// nothing in it would say so. That is refused rather than emitted.
///
/// # Errors
///
/// Returns a limit failure when a signature was asked for over an answer that
/// the volume ceiling had already cut.
fn signed(cli: &cli::Cli, envelope: output::Envelope) -> error::Result<output::Envelope> {
    if !cli.globals.output.checksum {
        return Ok(envelope);
    }

    if envelope
        .applied
        .as_ref()
        .is_some_and(|applied| applied.output_truncated)
    {
        return Err(Failure::limit(
            "limit.signature_over_a_cut_answer",
            "the answer was cut to fit the volume ceiling, so it cannot be signed",
        )
        .with_hint("raise --max-output-bytes, or drop --checksum"));
    }

    let signature = match envelope.payload_array_key() {
        Some(key) => output::checksum::of_rows(&rows_of(&envelope, key)),
        // An answer that carries no set of rows is signed over its payload as
        // written, so every command can be signed rather than only some.
        None => output::checksum::of_bytes(
            serde_json::to_vec(&envelope.data)
                .unwrap_or_default()
                .as_slice(),
        ),
    };

    // A signature covers the set as one object, so it cannot be decided before
    // the last row has arrived. That is a genuine property of signing and not
    // a defect, but a caller who asked for a flow and received a gathered
    // answer still has to be told which request cost it. It is declared in the
    // same field the ordering and the counting use, so there is one way to say
    // this and not two.
    let gathered = envelope
        .applied
        .clone()
        .unwrap_or_default()
        .also_gathered_for_the_signature();
    Ok(envelope.with_applied(gathered).with_checksum(signature))
}

/// The rows the signature covers, in the order they are emitted.
fn rows_of(envelope: &output::Envelope, key: &str) -> Vec<output::Row> {
    envelope.data[key]
        .as_array()
        .map(|rows| {
            rows.iter()
                .map(|row| serde_json::from_value(row.clone()).unwrap_or_default())
                .collect()
        })
        .unwrap_or_default()
}

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

    fn invoke(args: &[&str]) -> (ExitNumber, String, String) {
        let command_line: Vec<std::ffi::OsString> = std::iter::once("mariadb-cli")
            .chain(args.iter().copied())
            .map(Into::into)
            .collect();
        let (mut out, mut err) = (Vec::new(), Vec::new());
        let number = run(command_line, &mut out, &mut err);
        (
            number,
            String::from_utf8(out).expect("utf8 out"),
            String::from_utf8(err).expect("utf8 err"),
        )
    }

    #[test]
    fn help_is_a_success_and_never_a_failure() {
        let (number, out, err) = invoke(&["--help"]);
        assert_eq!(number, ExitNumber::Success);
        assert!(!out.is_empty(), "help belongs on the primary channel");
        assert!(err.is_empty(), "help is not a failure");
    }

    #[test]
    fn a_bad_argument_is_a_usage_failure_on_the_auxiliary_channel() {
        let (number, out, err) = invoke(&["--no-such-flag"]);
        assert_eq!(number, ExitNumber::Usage);
        assert!(
            out.is_empty(),
            "a failure never reaches the primary channel"
        );
        let parsed: serde_json::Value =
            serde_json::from_str(err.trim_end()).expect("structured failure");
        assert_eq!(parsed["error"]["category"], "usage");
        assert_eq!(parsed["error"]["exit"], 2);
        assert_eq!(parsed["error"]["retryable"], false);
    }

    #[test]
    fn a_malformed_filter_is_refused_before_any_work() {
        let (number, _, err) = invoke(&["--filter", "broken", "meta", "version"]);
        assert_eq!(number, ExitNumber::Usage);
        assert!(err.contains("filter.no_operator"));
    }

    #[test]
    fn the_primary_channel_carries_one_parseable_line() {
        let (number, out, err) = invoke(&["meta", "version"]);
        assert_eq!(number, ExitNumber::Success);
        assert!(
            err.is_empty(),
            "a clean run says nothing on the auxiliary channel"
        );
        let parsed: serde_json::Value =
            serde_json::from_str(out.trim_end()).expect("one json line");
        assert_eq!(parsed["command"], "meta version");
    }

    #[test]
    fn the_same_invocation_produces_the_same_bytes() {
        let first = invoke(&["meta", "commands"]).1;
        let second = invoke(&["meta", "commands"]).1;
        assert_eq!(first, second, "the answer must be byte-for-byte stable");
    }

    #[test]
    fn the_output_pipeline_serves_every_command_without_command_side_code() {
        let (number, out, _) = invoke(&["--count-only", "meta", "commands"]);
        assert_eq!(number, ExitNumber::Success);
        let parsed: serde_json::Value =
            serde_json::from_str(out.trim_end()).expect("one json line");
        assert!(parsed["data"]["count"].is_number());
    }
}