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
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
//! Turning a destination into the driver's option set.
//!
//! This is the only place the product touches the driver's builder, so every
//! decision about how a connection behaves is visible in one file.
//!
//! # The local file defence
//!
//! The driver lets a caller register a handler for the server's request to read
//! a file from this machine. Without one the driver answers such a request with
//! a failure, so a server — compromised, misconfigured or hostile — cannot read
//! a file from the host running this tool.
//!
//! No handler is registered unless `sql.local_file_read` says so, and that key
//! is off by default, so the refusal is what a build does until somebody turns
//! it off deliberately. Turning it on registers a handler whose list of
//! permitted files is exactly the ones this invocation named for itself, so
//! even then the server cannot ask for a file the caller never mentioned.

use super::profile::Profile;
use super::tls::{self, Encryption, Verification};
use crate::error::{Failure, Result};
use mysql_async::{Opts, OptsBuilder, WhiteListFsHandler};
use secrecy::{ExposeSecret, SecretString};
use std::collections::HashMap;
use std::path::PathBuf;
use std::time::Duration;

/// The adjustment that keeps a read from ever persisting anything.
///
/// With automatic confirmation off, a statement the caller did not mean to
/// commit is discarded when the connection closes at the end of the invocation.
pub const AUTOCOMMIT_OFF: &str = "SET autocommit = 0";

/// The block that makes the server itself refuse every change.
///
/// This is the only refusal of change that does not depend on this tool reading
/// the statement correctly. Classification happens here, in this process, over
/// text; a statement that slipped past it would still reach the server. Inside a
/// read-only block the server refuses it outright, so the guarantee survives a
/// classifier that is wrong.
pub const READ_ONLY_BLOCK: &str = "START TRANSACTION READ ONLY";

/// The method that puts the secret on the channel exactly as it is.
///
/// The driver will not use it unless it is asked for by name, which is why the
/// declared method has to reach the option set at all: without this the field
/// was stored, shown and then dropped, and a destination that named this method
/// still failed the handshake.
const CLEAR_PASSWORD: &str = "mysql_clear_password";

/// Everything the configuration layer decides about a connection.
///
/// No field has a value written into this file. A default port, a time budget
/// or a size ceiling is a setting a host owner may need to change, and a value
/// compiled in cannot be changed at all.
// Allowed: every switch here is one published setting, resolved once
// and handed over together. A nested type would be a second name for
// a grouping the registry does not have, and the registry is the one
// place a setting is declared.
#[allow(clippy::struct_excessive_bools)]
#[derive(Debug, Clone)]
pub struct ConnectionSettings {
    /// The secret for this destination, read from the vault for this call.
    pub secret: Option<SecretString>,
    /// The port used when the destination names none.
    pub default_port: u16,
    /// Prefer the local socket over the network when both are known.
    pub prefer_socket: bool,
    /// Compress the network channel.
    pub compress: bool,
    /// Ceiling on the size of one packet.
    pub max_allowed_packet: Option<usize>,
    /// How long the server keeps this connection idle before dropping it.
    pub wait_timeout: Option<usize>,
    /// Interval at which the channel is probed for liveness.
    pub tcp_keepalive: Option<Duration>,
    /// How many prepared statements the driver keeps ready.
    pub stmt_cache_size: usize,
    /// Whether a change count means rows matched rather than rows altered.
    pub count_matched_rows: bool,
    /// The two certificate checks, kept apart from each other.
    pub verification: Verification,
    /// Everything else the encrypted channel obeys.
    ///
    /// Carries the same two checks as `verification`, which stays as a field of
    /// its own because the invariant that both are on is read on its own, and a
    /// caller asking that question should not have to know where the channel
    /// keeps its other decisions.
    pub encryption: Encryption,
    /// The time zone declared on the session, when one is.
    pub timezone: Option<String>,
    /// The character set of the session, when one is declared.
    pub charset: Option<String>,
    /// Adjustments every session gets, before the ones the destination declares.
    pub session_setup: Vec<String>,
    /// Whether the server may ask this host to read a file at all.
    ///
    /// False registers no handler, so the driver refuses every such request and
    /// the defence is the absence of code rather than a list that happens to be
    /// empty. That is the published default.
    pub local_file_read: bool,
    /// The files the server may ask for, when it may ask at all.
    ///
    /// The list is exactly what this invocation named for itself, so turning the
    /// permission on still does not let a server name a file the caller never
    /// mentioned.
    pub readable_local_files: Vec<PathBuf>,
    /// What this client tells the server about itself.
    pub connect_attributes: HashMap<String, String>,
    /// Whether the server is asked to refuse every change on this session.
    pub refuse_change: bool,
    /// How long the server lets one statement run before stopping it itself.
    ///
    /// Absent leaves the server's own setting alone. Present makes the server
    /// the first line of the time budget, so the common case needs no second
    /// connection to stop work this process gave up on.
    pub statement_budget: Option<Duration>,
}

/// Builds the driver options for one destination.
///
/// # Errors
///
/// Returns a configuration failure when the destination names no server, when
/// a certificate is named without its key, or when this build has no encryption
/// and the destination asks for it, and an authentication failure naming the
/// method when the destination declares one this build cannot complete.
pub fn build(profile: &Profile, settings: &ConnectionSettings) -> Result<Opts> {
    profile.ensure_reachable()?;

    let mut builder = OptsBuilder::default()
        .enable_cleartext_plugin(wants_clear_password(profile)?)
        .user(profile.user.clone())
        .db_name(profile.database.clone())
        .tcp_port(profile.port.unwrap_or(settings.default_port))
        .prefer_socket(settings.prefer_socket)
        .stmt_cache_size(settings.stmt_cache_size)
        .client_found_rows(settings.count_matched_rows)
        .max_allowed_packet(settings.max_allowed_packet)
        .wait_timeout(settings.wait_timeout)
        .tcp_keepalive(settings.tcp_keepalive)
        .setup(session_setup(profile, settings)?)
        .ssl_opts(tls::channel(profile, &settings.encryption)?);

    // The permission is what decides whether a handler exists at all. See the
    // module note: with no handler the driver refuses, and that refusal is the
    // whole local file defence.
    builder = builder.local_infile_handler(
        settings
            .local_file_read
            .then(|| WhiteListFsHandler::new(settings.readable_local_files.clone())),
    );

    if let Some(host) = &profile.host {
        builder = builder.ip_or_hostname(host.clone());
    }
    if let Some(socket) = &profile.socket {
        builder = builder.socket(Some(socket.to_string_lossy().into_owned()));
    }
    if let Some(secret) = &settings.secret {
        builder = builder.pass(Some(secret.expose_secret().to_owned()));
    }
    if settings.compress {
        builder = builder.compression(mysql_async::Compression::default());
    }
    if !settings.connect_attributes.is_empty() {
        builder = builder.connect_attributes(settings.connect_attributes.clone());
    }

    Ok(Opts::from(builder))
}

/// Whether the destination declared the method that sends the secret as it is.
///
/// This is where the declared method stops being a field the product wrote down
/// and never read. Only one supported method needs anything in the option set,
/// so the answer is a single truth value; the rest of the work this does is the
/// part that matters, which is refusing a method this build cannot complete
/// before a credential is ever sent. Meeting it here rather than mid-handshake
/// costs no connection and, more to the point, cannot be mistaken for a
/// credential the server refused.
///
/// # Errors
///
/// Returns an authentication failure naming the method when this build cannot
/// complete a handshake with it.
fn wants_clear_password(profile: &Profile) -> Result<bool> {
    let Some(declared) = &profile.auth_method else {
        return Ok(false);
    };
    match declared.trim().to_ascii_lowercase().as_str() {
        CLEAR_PASSWORD => Ok(true),
        // `ed25519` is the name the server calls this method by and
        // `client_ed25519` the name the client side carries, and a caller
        // reading either off a server has written down something true.
        "mysql_native_password"
        | "caching_sha2_password"
        | "client_ed25519"
        | "ed25519"
        | "parsec" => Ok(false),
        _ => Err(super::unsupported_auth_method(declared)),
    }
}

/// The statements run once, in order, as soon as the connection is open.
///
/// The order is what makes each one hold. Automatic confirmation goes off
/// before anything else, so no adjustment ever runs while a change would stick.
/// The time budget is set before the block opens, because a session variable
/// cannot be changed inside a read-only block. The character set comes before
/// the time zone, because the zone is declared as text and the session should
/// already be reading text the way the host asked for. The stored adjustments
/// come before the destination's own, so a destination can override the host
/// rather than the other way round. The block itself is last, so everything
/// before it still counts as setup rather than as work done inside a
/// transaction the caller never asked for.
///
/// # Errors
///
/// Returns a configuration failure when a declared character set or time zone
/// carries anything but the characters such a name is made of.
fn session_setup(profile: &Profile, settings: &ConnectionSettings) -> Result<Vec<String>> {
    let mut setup =
        Vec::with_capacity(profile.session_setup.len() + settings.session_setup.len() + 5);
    setup.push(AUTOCOMMIT_OFF.to_owned());
    if let Some(budget) = settings.statement_budget {
        setup.push(statement_budget(budget));
    }
    if let Some(charset) = &settings.charset {
        setup.push(format!(
            "SET NAMES '{}'",
            plain_name("conn.charset", charset)?
        ));
    }
    if let Some(timezone) = &settings.timezone {
        setup.push(format!(
            "SET time_zone = '{}'",
            plain_name("conn.timezone", timezone)?
        ));
    }
    setup.extend(settings.session_setup.iter().cloned());
    setup.extend(profile.session_setup.iter().cloned());
    if settings.refuse_change {
        setup.push(READ_ONLY_BLOCK.to_owned());
    }
    Ok(setup)
}

/// Refuses a declared name that is not one.
///
/// A character set and a time zone travel to the server inside a quoted text,
/// and a stored value is not a caller's text but it is still text this build
/// did not write. Rather than escape it — which is where quoting bugs live —
/// anything outside what such a name is made of is refused outright.
fn plain_name<'a>(key: &str, value: &'a str) -> Result<&'a str> {
    let acceptable = |character: char| {
        character.is_ascii_alphanumeric() || matches!(character, '_' | '-' | '+' | ':' | '/' | '.')
    };
    if value.is_empty() || !value.chars().all(acceptable) {
        return Err(Failure::config(
            "config.declared_name_is_not_one",
            format!("`{value}` is not something `{key}` can declare on a session"),
        )
        .with_detail("detail", value)
        .with_hint("use a plain name such as utf8mb4, UTC, +00:00 or Europe/Lisbon"));
    }
    Ok(value)
}

/// The adjustment that hands the time budget to the server.
///
/// The server takes fractional seconds, so a budget under a second survives
/// instead of rounding down to no budget at all.
fn statement_budget(budget: Duration) -> String {
    format!("SET SESSION max_statement_time = {}", budget.as_secs_f64())
}

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

    fn settings() -> ConnectionSettings {
        ConnectionSettings {
            secret: None,
            default_port: 3306,
            prefer_socket: true,
            compress: false,
            max_allowed_packet: Some(16 * 1024 * 1024),
            wait_timeout: Some(600),
            tcp_keepalive: Some(Duration::from_secs(30)),
            stmt_cache_size: 32,
            count_matched_rows: true,
            verification: Verification::default(),
            encryption: Encryption::default(),
            timezone: None,
            charset: None,
            session_setup: Vec::new(),
            local_file_read: false,
            readable_local_files: Vec::new(),
            connect_attributes: HashMap::new(),
            refuse_change: false,
            statement_budget: None,
        }
    }

    fn profile() -> Profile {
        Profile {
            host: Some("db.example".to_owned()),
            user: Some("reader".to_owned()),
            database: Some("sales".to_owned()),
            ..Profile::named("main")
        }
    }

    /// The destination's own parts reach the driver unchanged.
    #[test]
    fn the_destination_reaches_the_driver() {
        let opts = build(&profile(), &settings()).expect("builds");
        assert_eq!(opts.ip_or_hostname(), "db.example");
        assert_eq!(opts.user(), Some("reader"));
        assert_eq!(opts.db_name(), Some("sales"));
    }

    /// A destination naming no port takes the configured one, never a number
    /// written into this file.
    #[test]
    fn an_absent_port_takes_the_configured_default() {
        let mut settings = settings();
        settings.default_port = 3307;
        assert_eq!(
            build(&profile(), &settings).expect("builds").tcp_port(),
            3307
        );

        let pinned = Profile {
            port: Some(3399),
            ..profile()
        };
        assert_eq!(build(&pinned, &settings).expect("builds").tcp_port(), 3399);
    }

    /// Automatic confirmation is switched off first, so a read can never
    /// persist anything and a profile adjustment never runs while it could.
    #[test]
    fn automatic_confirmation_is_switched_off_first() {
        let profile = Profile {
            session_setup: vec!["SET time_zone = '+00:00'".to_owned()],
            ..profile()
        };
        let opts = build(&profile, &settings()).expect("builds");
        assert_eq!(
            opts.setup().first().map(String::as_str),
            Some(AUTOCOMMIT_OFF)
        );
        assert_eq!(opts.setup().len(), 2);
    }

    /// The change-count meaning comes from the setting, not from a guess.
    #[test]
    fn the_change_count_meaning_follows_the_setting() {
        let mut settings = settings();
        assert!(build(&profile(), &settings)
            .expect("builds")
            .client_found_rows());
        settings.count_matched_rows = false;
        assert!(!build(&profile(), &settings)
            .expect("builds")
            .client_found_rows());
    }

    /// The secret reaches the driver and never the profile.
    #[test]
    fn the_secret_reaches_the_driver_only() {
        let mut settings = settings();
        settings.secret = Some(SecretString::from("hunter2"));
        let opts = build(&profile(), &settings).expect("builds");
        assert_eq!(opts.pass(), Some("hunter2"));

        let stored = toml::to_string(&profile()).expect("serialises");
        assert!(
            !stored.contains("hunter2"),
            "the profile carries a secret: {stored}"
        );
    }

    /// A socket destination is opened without a host.
    #[test]
    fn a_socket_destination_needs_no_host() {
        let profile = Profile {
            socket: Some(std::path::PathBuf::from("/run/mysqld/mysqld.sock")),
            ..Profile::named("local")
        };
        let opts = build(&profile, &settings()).expect("builds");
        assert_eq!(opts.socket(), Some("/run/mysqld/mysqld.sock"));
        assert!(opts.prefer_socket());
    }

    /// A destination naming no server at all is refused before any connection.
    #[test]
    fn a_destination_naming_no_server_is_refused() {
        let failure = build(&Profile::named("empty"), &settings()).expect_err("must refuse");
        assert_eq!(failure.code(), "profile.no_destination");
    }

    /// The liveness interval reaches the driver as the setting states it.
    #[test]
    fn the_liveness_interval_reaches_the_driver() {
        let opts = build(&profile(), &settings()).expect("builds");
        assert_eq!(opts.tcp_keepalive(), Some(Duration::from_secs(30)));
    }

    /// The declared character set and time zone reach the session, in the order
    /// that makes each one hold.
    #[test]
    fn the_declared_character_set_and_zone_reach_the_session() {
        let mut settings = settings();
        settings.charset = Some("utf8mb4".to_owned());
        settings.timezone = Some("+00:00".to_owned());
        let opts = build(&profile(), &settings).expect("builds");
        let setup = opts.setup();

        let charset = setup
            .iter()
            .position(|line| line == "SET NAMES 'utf8mb4'")
            .expect("the character set is declared");
        let zone = setup
            .iter()
            .position(|line| line == "SET time_zone = '+00:00'")
            .expect("the zone is declared");
        assert!(
            charset < zone,
            "text is read the declared way first: {setup:?}"
        );
    }

    /// A session neither declares nor changes what nobody asked for, so a build
    /// with nothing stored sends no such adjustment at all.
    #[test]
    fn nothing_is_declared_when_nothing_was_stored() {
        let opts = build(&profile(), &settings()).expect("builds");
        assert!(!opts
            .setup()
            .iter()
            .any(|line| line.contains("SET NAMES") || line.contains("time_zone")));
    }

    /// A name that is not one is refused rather than escaped, because escaping
    /// is where quoting bugs live.
    #[test]
    fn a_declared_name_that_is_not_one_is_refused() {
        let mut settings = settings();
        settings.timezone = Some("'; DROP TABLE t; --".to_owned());
        let failure = build(&profile(), &settings).expect_err("must refuse");
        assert_eq!(failure.code(), "config.declared_name_is_not_one");
    }

    /// The stored adjustments run before the destination's own, so a
    /// destination can override the host rather than the other way round.
    #[test]
    fn the_stored_adjustments_run_before_the_destinations_own() {
        let profile = Profile {
            session_setup: vec!["SET sql_mode = 'STRICT_ALL_TABLES'".to_owned()],
            ..profile()
        };
        let mut settings = settings();
        settings.session_setup = vec!["SET sql_mode = 'ANSI'".to_owned()];
        let opts = build(&profile, &settings).expect("builds");
        let setup = opts.setup();

        let stored = setup
            .iter()
            .position(|line| line.contains("ANSI"))
            .expect("the stored adjustment is applied");
        let own = setup
            .iter()
            .position(|line| line.contains("STRICT_ALL_TABLES"))
            .expect("the destination's own adjustment is applied");
        assert!(stored < own, "the destination has the last word: {setup:?}");
    }

    /// Without the permission the driver gets no handler at all, which is what
    /// makes it refuse every request the server makes for a local file.
    #[test]
    fn no_handler_is_registered_until_the_permission_is_given() {
        let opts = build(&profile(), &settings()).expect("builds");
        assert!(
            opts.local_infile_handler().is_none(),
            "the refusal is the absence of a handler"
        );
    }

    /// The permission registers a handler, and the handler permits exactly the
    /// files this invocation named and nothing else.
    #[test]
    fn the_permission_registers_a_handler_over_the_named_files_alone() {
        let mut settings = settings();
        settings.local_file_read = true;
        settings.readable_local_files = vec![std::path::PathBuf::from("/tmp/rows.csv")];
        let opts = build(&profile(), &settings).expect("builds");
        assert!(opts.local_infile_handler().is_some());
    }

    /// The stored demand for encryption reaches the channel, so a destination
    /// that states nothing is still never opened in clear text.
    #[cfg(feature = "tls")]
    #[test]
    fn the_stored_demand_for_encryption_reaches_the_channel() {
        let mut settings = settings();
        assert!(build(&profile(), &settings)
            .expect("builds")
            .ssl_opts()
            .is_none());

        settings.encryption.demanded = true;
        assert!(build(&profile(), &settings)
            .expect("builds")
            .ssl_opts()
            .is_some());
    }

    /// A build without encryption refuses a destination that demands it.
    #[cfg(not(feature = "tls"))]
    #[test]
    fn a_build_without_encryption_refuses_a_destination_that_demands_it() {
        let profile = Profile {
            require_tls: Some(true),
            ..profile()
        };
        let failure = build(&profile, &settings()).expect_err("must refuse");
        assert_eq!(failure.code(), "tls.not_available");
        assert_eq!(failure.exit_number().code(), 4);
    }

    /// The counterpart of the refusal above. Turning a capability on must never
    /// leave a path untested: without this the encrypted build would carry one
    /// test fewer than the plain one.
    #[cfg(feature = "tls")]
    #[test]
    fn a_build_with_encryption_accepts_a_destination_that_demands_it() {
        let profile = Profile {
            require_tls: Some(true),
            ..profile()
        };
        let opts = build(&profile, &settings()).expect("encryption is available");
        assert!(
            opts.ssl_opts().is_some(),
            "a destination that demands encryption must get an encrypted channel"
        );
    }

    /// The block is the only refusal of change that survives a classifier that
    /// is wrong, so it must reach the server whenever change is refused.
    #[test]
    fn refusing_change_opens_a_read_only_block_on_the_server() {
        let mut settings = settings();
        settings.refuse_change = true;
        let opts = build(&profile(), &settings).expect("builds");
        assert_eq!(
            opts.setup().last().map(String::as_str),
            Some(READ_ONLY_BLOCK),
            "the block must be the last thing set up, after every adjustment"
        );
    }

    /// A destination that accepts change must not be put inside the block, or
    /// every write would be refused by a guard the caller never asked for.
    #[test]
    fn accepting_change_opens_no_block() {
        let opts = build(&profile(), &settings()).expect("builds");
        assert!(!opts.setup().iter().any(|line| line == READ_ONLY_BLOCK));
    }

    /// The server enforces the budget itself, so the common case never needs a
    /// second connection to stop work this process gave up on.
    #[test]
    fn the_time_budget_reaches_the_server_as_a_session_adjustment() {
        let mut settings = settings();
        settings.statement_budget = Some(Duration::from_secs(5));
        let opts = build(&profile(), &settings).expect("builds");
        assert!(opts
            .setup()
            .iter()
            .any(|line| line == "SET SESSION max_statement_time = 5"));
    }

    /// A budget under a second must survive: rounding it down would leave the
    /// caller with no budget at all.
    #[test]
    fn a_budget_shorter_than_a_second_is_not_rounded_away() {
        assert_eq!(
            statement_budget(Duration::from_millis(250)),
            "SET SESSION max_statement_time = 0.25"
        );
    }

    /// The budget must be set before the block opens: a session variable
    /// cannot be changed once a read-only transaction is under way.
    #[test]
    fn the_budget_is_set_before_the_block_opens() {
        let mut settings = settings();
        settings.refuse_change = true;
        settings.statement_budget = Some(Duration::from_secs(5));
        let opts = build(&profile(), &settings).expect("builds");
        let setup = opts.setup();
        let budget = setup
            .iter()
            .position(|line| line.contains("max_statement_time"))
            .expect("the budget is set up");
        let block = setup
            .iter()
            .position(|line| line == READ_ONLY_BLOCK)
            .expect("the block is set up");
        assert!(budget < block, "the budget must come first: {setup:?}");
    }
}