Skip to main content

mariadb_cli/
lib.rs

1//! One-shot, agent-native command line client for MariaDB servers.
2//!
3//! The process is born, does its work and dies within a single invocation.
4//! There is no daemon, no connection reused across invocations and no state
5//! that survives the process.
6//!
7//! # Channels
8//!
9//! The primary channel carries data only, in the published shape. Diagnostics,
10//! progress and warnings go to the auxiliary channel and never mix with data.
11//!
12//! # Defence against unintended change
13//!
14//! Three layers guard every statement, and only the first does not depend on
15//! reading the statement text correctly:
16//!
17//! 1. Every statement travels as a prepared statement. The server refuses a
18//!    prepared text that carries more than one statement, so the multiple
19//!    command refusal lives on the server side. No local file handler is
20//!    registered either, so a server request to read a client file fails.
21//! 2. The statement is classified by its syntax tree before it is sent, over a
22//!    text already stripped of comments and literals.
23//! 3. Two defences do not depend on this tool behaving correctly, and the
24//!    manual says so: a credential restricted on the server, and the read-only
25//!    lock the server itself holds around work declared as reading. A statement
26//!    that escaped classification would still be refused by the second one.
27
28#![forbid(unsafe_code)]
29// Every public item is part of the published documentation, so an undocumented
30// one is a gap a reader meets rather than a note somebody meant to write later.
31//
32// Refused outright rather than warned about. A warning is a note nobody has to
33// read, and this one had already been left unread: the published documentation
34// is generated from these comments, so an item without one ships a blank space
35// to every reader of the manual. Refusing it costs the writer one sentence and
36// costs the reader nothing.
37#![deny(missing_docs)]
38// The same reasoning applied to the documentation itself. A link that names an
39// item which no longer exists points the reader nowhere, and a code block that
40// was never meant to compile fails the build of the manual rather than the
41// build of the product, which is where nobody is looking.
42#![deny(rustdoc::broken_intra_doc_links)]
43#![deny(rustdoc::invalid_codeblock_attributes)]
44// The stricter half of the linter, refused rather than warned about. Every one
45// of its complaints was answered before this line was written: the casts that
46// discarded bits, the arguments taken by value and never consumed, the items
47// declared after the statements that already ran. Left as warnings they are
48// read once and scrolled past; denied, the next one has to be answered on the
49// day it appears. Where the lint is wrong the exception is written down beside
50// the code with the reason, which is a sentence somebody can argue with.
51#![deny(clippy::pedantic)]
52
53pub mod cli;
54pub mod commands;
55pub mod config;
56pub mod conn;
57pub mod datamove;
58pub mod dispatch;
59pub mod error;
60pub mod exec;
61pub mod history;
62pub mod i18n;
63pub mod introspect;
64pub mod obs;
65pub mod output;
66pub mod runtime;
67pub mod serverinfo;
68pub mod settings;
69pub mod sql;
70pub mod types;
71
72use clap::Parser;
73use error::{ExitNumber, Failure};
74use std::io::Write;
75
76/// Whether this build carries network encryption.
77///
78/// The default build carries it, and carries it without a C toolchain, because
79/// the cryptography provider is written entirely in Rust and installed at
80/// startup. This value is what `meta version` and `conn test` report, so the
81/// product never overstates nor understates its own capability.
82pub const ENCRYPTED_CHANNEL_AVAILABLE: bool = cfg!(feature = "tls");
83
84/// Runs one invocation from start to finish.
85///
86/// The phases run in order: parse arguments, validate preconditions, execute,
87/// release. The exit number is returned rather than applied, so a caller may
88/// drive this function from a test.
89///
90/// Never fails: every failure is rendered on the auxiliary channel and turned
91/// into its published exit number.
92pub fn run<O: Write, E: Write>(
93    argv: Vec<std::ffi::OsString>,
94    out: &mut O,
95    err: &mut E,
96) -> ExitNumber {
97    // A parse that fails never reaches the layer that decides the language, so
98    // the refusal was written in the host language even when the caller named
99    // another one on the same line. The mark is read straight from the argument
100    // list first, and only well enough to answer in the language that was
101    // asked for: a value this build does not carry changes nothing here and is
102    // reported by the parse failure that follows it. A parse that succeeds
103    // installs the language again from the settings, so the stored value keeps
104    // its place and the documented order is left as it is.
105    if let Some(requested) = requested_language(&argv) {
106        let _ = i18n::install(Some(&requested), None);
107    }
108
109    let cli = match cli::Cli::try_parse_from(argv) {
110        Ok(parsed) => parsed,
111        Err(parse_error) => return render_parse_outcome(&parse_error, out, err),
112    };
113
114    // The guard is held for the whole invocation: dropping it early truncates
115    // whatever the file writer still holds, which is the last diagnostics of
116    // the run and exactly the ones worth keeping.
117    let _guard = match install_auxiliary_channel(&cli, err) {
118        Ok(guard) => guard,
119        Err(failure) => {
120            let _ = error::render::write_failure(err, &failure);
121            return failure.exit_number();
122        }
123    };
124
125    // The cryptography provider is installed once, before anything can open a
126    // channel. Doing it here rather than lazily keeps the choice in one place
127    // and turns a provider that cannot be installed into a rendered failure
128    // instead of a panic from inside the encryption stack.
129    // The protocol floor is imposed by which cipher suites the provider offers,
130    // so it has to be decided before the provider is installed and cannot be
131    // handed to the driver later.
132    let floor = settings::protocol_floor(cli.globals.diagnostics.config_dir.as_deref());
133    if let Err(failure) = conn::provider::install(floor) {
134        let _ = error::render::write_failure(err, &failure);
135        return failure.exit_number();
136    }
137
138    match dispatch(&cli, out) {
139        Ok(number) => number,
140        Err(failure) => {
141            let _ = error::render::write_failure(err, &failure);
142            // A closed reader used to need a special case here, because it
143            // carried the `Limit` category and would have ended with the wrong
144            // number. It has its own category now, so the ordinary mapping
145            // answers 141 by itself and there is nothing to special-case.
146            failure.exit_number()
147        }
148    }
149}
150
151/// Installs the auxiliary channel, separating a bad request from a bad file.
152///
153/// The two failures this can meet are not the same thing, and treating them
154/// alike is what made `--lang klingon` end successfully with nothing written
155/// anywhere. Deciding what the channel obeys reads the marks on the command
156/// line, so a mark outside its domain is incorrect use and has to cost the
157/// invocation. Opening the file the diagnostics are kept in does not: the work
158/// the caller asked for still has to happen, so that failure is reported on
159/// the channel itself and the invocation carries on.
160///
161/// An already-installed channel is not a failure at all: the subscriber is
162/// global to the process, so a caller driving `run` more than once inside one
163/// process reaches this on every call after the first.
164///
165/// # Errors
166///
167/// Returns the failure of resolving what the channel obeys, which is a usage
168/// failure for a mark outside its domain and a configuration failure for a
169/// stored value outside its own.
170fn install_auxiliary_channel<E: Write>(
171    cli: &cli::Cli,
172    err: &mut E,
173) -> error::Result<Option<tracing_appender::non_blocking::WorkerGuard>> {
174    // A settings file that cannot be read is left to the work, which loads it
175    // again and reports it there with its own cause. Reporting it twice would
176    // put the same failure on the channel under two different headings.
177    let Ok(config) = config::Config::load(cli.globals.diagnostics.config_dir.as_deref()) else {
178        return Ok(None);
179    };
180
181    let settings = obs::settings::resolve(&config, &cli.globals)?;
182    match obs::install(&settings) {
183        Ok(guard) => Ok(guard),
184        // The subscriber is global to the process, so this is the second call
185        // inside one process and not a fault to report.
186        Err(failure) if failure.code() == "log.already_installed" => Ok(None),
187        Err(failure) => {
188            let _ = error::render::write_failure(err, &failure);
189            Ok(None)
190        }
191    }
192}
193
194/// Reads `--lang` straight from the argument list.
195///
196/// This is not a second parser and must not become one. It answers a single
197/// question the real parser cannot answer once it has failed: which language
198/// the caller asked the answer to be written in. Both spellings the parser
199/// accepts are read, `--lang pt-BR` and `--lang=pt-BR`, because the caller
200/// chooses between them and neither is more correct than the other.
201///
202/// Reading stops at `--`, since what follows it was declared not to be a mark.
203/// An argument that is not text is stepped over rather than ending the search:
204/// a path that no encoding can name says nothing about the language, and
205/// letting it stop the walk would hide a `--lang` written after it.
206fn requested_language(argv: &[std::ffi::OsString]) -> Option<String> {
207    let mut items = argv.iter();
208    while let Some(item) = items.next() {
209        let Some(text) = item.to_str() else { continue };
210        if text == "--" {
211            break;
212        }
213        if text == "--lang" {
214            return items
215                .next()
216                .and_then(|value| value.to_str())
217                .map(str::to_owned);
218        }
219        if let Some(value) = text.strip_prefix("--lang=") {
220            return Some(value.to_owned());
221        }
222    }
223    None
224}
225
226/// Renders an outcome from the argument layer.
227///
228/// Help and version are successful outcomes, not failures, so they reach the
229/// primary channel with a zero exit. Everything else is a usage failure.
230fn render_parse_outcome<O: Write, E: Write>(
231    parse_error: &clap::Error,
232    out: &mut O,
233    err: &mut E,
234) -> ExitNumber {
235    use clap::error::ErrorKind;
236
237    if matches!(
238        parse_error.kind(),
239        ErrorKind::DisplayHelp
240            | ErrorKind::DisplayVersion
241            | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
242    ) {
243        let _ = write!(out, "{parse_error}");
244        return ExitNumber::Success;
245    }
246
247    let failure = Failure::usage(
248        "usage.invalid_arguments",
249        "the arguments given do not match the accepted form",
250    )
251    .with_hint("run with --help to see the accepted form")
252    .with_cause(parse_error.to_string());
253    let _ = error::render::write_failure(err, &failure);
254    ExitNumber::Usage
255}
256
257/// Routes one parsed invocation to the command that serves it, and declares
258/// what the answer cost on the primary channel.
259///
260/// The declaration is made from here rather than from any of the writers
261/// underneath, because this is the one point every shape of answer passes
262/// through: a whole envelope, the receipt of an answer written to a file, and
263/// a continuous flow that wrote its own rows and returned nothing all leave
264/// through this counter. Made after the work rather than inside it, so an
265/// answer cut short by a failure still declares the bytes it had already spent
266/// of the caller's context (FR-139).
267fn dispatch<O: Write>(cli: &cli::Cli, out: &mut O) -> error::Result<ExitNumber> {
268    let mut counted = output::Counted::new(out);
269    // One runtime for the whole invocation, built here rather than around the
270    // part of the work that opens a destination. The signals are watched for as
271    // long as it lives, which is what makes shaping the answer and settling the
272    // file interruptible; see `dispatch::under_signals` for what being deaf in
273    // that stretch actually cost.
274    let outcome = match dispatch::build_runtime() {
275        Ok(runtime) => runtime.block_on(dispatch::under_signals(async |shutdown| {
276            served(cli, &mut counted, shutdown).await
277        })),
278        Err(failure) => Err(failure),
279    };
280    i18n::report::response_volume(counted.bytes(), counted.lines());
281    outcome
282}
283
284/// Serves one invocation onto the channel the volume is counted on.
285async fn served<O: Write>(
286    cli: &cli::Cli,
287    out: &mut O,
288    shutdown: &runtime::Shutdown,
289) -> error::Result<ExitNumber> {
290    // Building the pipeline first refuses a malformed filter before any work
291    // starts, so a typo never costs a connection. The stored settings are read
292    // for it, because the ceiling per cell is a published key that the mark on
293    // the command line only overrides.
294    // Read here for the same reason it is read again further down, and refused
295    // here for one command less. Three places in this codebase say a settings
296    // file that cannot be read is "reported by the work, which loads it again":
297    // this one, the auxiliary channel above, and the protocol floor. None of
298    // them had checked that the work ever got the chance, and it did not — this
299    // line and the one in `dispatch::serve` both refused first, so the
300    // diagnosis written for exactly this case was unreachable (G-019).
301    let config_dir = cli.globals.diagnostics.config_dir.as_deref();
302    let config = match config::Config::load(config_dir) {
303        Ok(config) => config,
304        Err(unreadable) if dispatch::diagnoses_the_settings(&cli.command) => {
305            config::Config::with_nothing_stored(config_dir).map_err(|_| unreadable)?
306        }
307        Err(unreadable) => return Err(unreadable),
308    };
309
310    // The published shape is chosen once, here, so no command decides how its
311    // own answer looks. It is chosen before the pipeline because one of the
312    // pipeline's refusals depends on it.
313    let format = output_shape(cli, &config)?;
314    cli.globals.refuse_a_profile_over_a_flow(format)?;
315    let pipeline = cli.globals.pipeline(&config)?;
316
317    // A caller who asked for a file gets the work written into the file, and
318    // that has to hold for a continuous flow as well. It did not: the flow
319    // wrote its rows to the primary channel and returned nothing to write, and
320    // the branch below was never reached — a successful exit and no file, with
321    // nothing said about either.
322    let Some(path) = cli.globals.output.output.clone() else {
323        let Some(envelope) = dispatch::serve(cli, out, shutdown).await? else {
324            // A continuous flow already wrote its rows and its closing record.
325            return Ok(ExitNumber::Success);
326        };
327        let shaped = signed(cli, pipeline.apply(envelope)?)?;
328        output::format::for_format(format).write_envelope(out, &shaped)?;
329        return Ok(ExitNumber::Success);
330    };
331
332    let mut staged = output::destination::staged(&path)?;
333    let served = dispatch::serve(cli, &mut staged, shutdown).await?;
334    let command = match served {
335        // The flow wrote its rows into the file as they arrived, so nothing is
336        // left to shape and the file is already whole once it is settled.
337        None => cli.command.published_name(),
338        Some(envelope) => {
339            let shaped = signed(cli, pipeline.apply(envelope)?)?;
340            // Almost every answer is written as the envelope that describes it.
341            // An answer that declares one of its fields a document in its own
342            // right is written as that document, because a file named for a
343            // manual page has to be openable by a reader of manual pages.
344            match shaped.raw_document() {
345                Some(document) => staged
346                    .write_all(document.as_bytes())
347                    .map_err(|cause| unwritable(&path, &cause))?,
348                None => output::format::for_format(format).write_envelope(&mut staged, &shaped)?,
349            }
350            shaped.command
351        }
352    };
353
354    let report = staged.finish()?;
355    // What reaches the primary channel is the account of the write, so a caller
356    // that redirected the result still gets a parseable answer.
357    let receipt = output::Envelope::new(command, serde_json::to_value(&report).unwrap_or_default());
358    output::format::for_format(format).write_envelope(out, &receipt)?;
359    Ok(ExitNumber::Success)
360}
361
362/// The failure a destination that stops accepting bytes produces.
363fn unwritable(path: &std::path::Path, cause: &std::io::Error) -> error::Failure {
364    error::Failure::config(
365        "output.destination_unwritable",
366        "the destination stopped accepting the answer",
367    )
368    .with_detail("detail", path.display().to_string())
369    .with_cause(cause.to_string())
370}
371
372/// The shape the primary channel is written in.
373///
374/// The mark on the command line wins over the stored key, which wins over the
375/// built-in shape. Reading only the mark, as this once did, made
376/// `config set output.format` a setting the product stored, read back and
377/// reported as being in force while writing something else.
378///
379/// # Errors
380///
381/// Returns a configuration failure when the stored shape is outside its domain.
382pub fn output_shape(
383    cli: &cli::Cli,
384    config: &config::Config,
385) -> error::Result<cli::globals::OutputFormat> {
386    use cli::globals::OutputFormat;
387
388    if let Some(asked) = cli.globals.output.output_format {
389        return Ok(asked);
390    }
391
392    Ok(match settings::word(config, "output.format")?.as_str() {
393        "ndjson" => OutputFormat::Ndjson,
394        "tsv" => OutputFormat::Tsv,
395        "text" => OutputFormat::Text,
396        // The registry's own domain is what the words above come from, so the
397        // remaining one is the built-in shape and there is no fourth case.
398        _ => OutputFormat::Json,
399    })
400}
401
402/// Attaches the signature of the result, when one was asked for.
403///
404/// A signature over an answer the volume ceiling cut short would be the
405/// signature of a different set from the one the caller meant to sign, and
406/// nothing in it would say so. That is refused rather than emitted.
407///
408/// # Errors
409///
410/// Returns a limit failure when a signature was asked for over an answer that
411/// the volume ceiling had already cut.
412fn signed(cli: &cli::Cli, envelope: output::Envelope) -> error::Result<output::Envelope> {
413    if !cli.globals.output.checksum {
414        return Ok(envelope);
415    }
416
417    if envelope
418        .applied
419        .as_ref()
420        .is_some_and(|applied| applied.output_truncated)
421    {
422        return Err(Failure::limit(
423            "limit.signature_over_a_cut_answer",
424            "the answer was cut to fit the volume ceiling, so it cannot be signed",
425        )
426        .with_hint("raise --max-output-bytes, or drop --checksum"));
427    }
428
429    let signature = match envelope.payload_array_key() {
430        Some(key) => output::checksum::of_rows(&rows_of(&envelope, key)),
431        // An answer that carries no set of rows is signed over its payload as
432        // written, so every command can be signed rather than only some.
433        None => output::checksum::of_bytes(
434            serde_json::to_vec(&envelope.data)
435                .unwrap_or_default()
436                .as_slice(),
437        ),
438    };
439
440    // A signature covers the set as one object, so it cannot be decided before
441    // the last row has arrived. That is a genuine property of signing and not
442    // a defect, but a caller who asked for a flow and received a gathered
443    // answer still has to be told which request cost it. It is declared in the
444    // same field the ordering and the counting use, so there is one way to say
445    // this and not two.
446    let gathered = envelope
447        .applied
448        .clone()
449        .unwrap_or_default()
450        .also_gathered_for_the_signature();
451    Ok(envelope.with_applied(gathered).with_checksum(signature))
452}
453
454/// The rows the signature covers, in the order they are emitted.
455fn rows_of(envelope: &output::Envelope, key: &str) -> Vec<output::Row> {
456    envelope.data[key]
457        .as_array()
458        .map(|rows| {
459            rows.iter()
460                .map(|row| serde_json::from_value(row.clone()).unwrap_or_default())
461                .collect()
462        })
463        .unwrap_or_default()
464}
465
466#[cfg(test)]
467mod tests {
468    use super::*;
469
470    fn invoke(args: &[&str]) -> (ExitNumber, String, String) {
471        let command_line: Vec<std::ffi::OsString> = std::iter::once("mariadb-cli")
472            .chain(args.iter().copied())
473            .map(Into::into)
474            .collect();
475        let (mut out, mut err) = (Vec::new(), Vec::new());
476        let number = run(command_line, &mut out, &mut err);
477        (
478            number,
479            String::from_utf8(out).expect("utf8 out"),
480            String::from_utf8(err).expect("utf8 err"),
481        )
482    }
483
484    #[test]
485    fn help_is_a_success_and_never_a_failure() {
486        let (number, out, err) = invoke(&["--help"]);
487        assert_eq!(number, ExitNumber::Success);
488        assert!(!out.is_empty(), "help belongs on the primary channel");
489        assert!(err.is_empty(), "help is not a failure");
490    }
491
492    #[test]
493    fn a_bad_argument_is_a_usage_failure_on_the_auxiliary_channel() {
494        let (number, out, err) = invoke(&["--no-such-flag"]);
495        assert_eq!(number, ExitNumber::Usage);
496        assert!(
497            out.is_empty(),
498            "a failure never reaches the primary channel"
499        );
500        let parsed: serde_json::Value =
501            serde_json::from_str(err.trim_end()).expect("structured failure");
502        assert_eq!(parsed["error"]["category"], "usage");
503        assert_eq!(parsed["error"]["exit"], 2);
504        assert_eq!(parsed["error"]["retryable"], false);
505    }
506
507    #[test]
508    fn a_malformed_filter_is_refused_before_any_work() {
509        let (number, _, err) = invoke(&["--filter", "broken", "meta", "version"]);
510        assert_eq!(number, ExitNumber::Usage);
511        assert!(err.contains("filter.no_operator"));
512    }
513
514    #[test]
515    fn the_primary_channel_carries_one_parseable_line() {
516        let (number, out, err) = invoke(&["meta", "version"]);
517        assert_eq!(number, ExitNumber::Success);
518        assert!(
519            err.is_empty(),
520            "a clean run says nothing on the auxiliary channel"
521        );
522        let parsed: serde_json::Value =
523            serde_json::from_str(out.trim_end()).expect("one json line");
524        assert_eq!(parsed["command"], "meta version");
525    }
526
527    #[test]
528    fn the_same_invocation_produces_the_same_bytes() {
529        let first = invoke(&["meta", "commands"]).1;
530        let second = invoke(&["meta", "commands"]).1;
531        assert_eq!(first, second, "the answer must be byte-for-byte stable");
532    }
533
534    #[test]
535    fn the_output_pipeline_serves_every_command_without_command_side_code() {
536        let (number, out, _) = invoke(&["--count-only", "meta", "commands"]);
537        assert_eq!(number, ExitNumber::Success);
538        let parsed: serde_json::Value =
539            serde_json::from_str(out.trim_end()).expect("one json line");
540        assert!(parsed["data"]["count"].is_number());
541    }
542}