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}