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
//! Telling a person what the work is doing while it does it.
//!
//! Every line here goes to the auxiliary channel and never to the primary one:
//! progress is prose written for a person, and a caller parsing the result must
//! not have to skip past it.
//!
//! Each line carries its own message identifier as a structured field. The
//! prose changes with the language of the reader, so a collector that had only
//! the prose to go on would have to match on a sentence that is different on
//! every host; the identifier is the same everywhere and is what such a
//! collector branches on. For the same reason every other field is a value or
//! an identifier, never a translated sentence.
//!
//! Call sites name a message through the constants below rather than through a
//! literal, so a message that no catalogue carries is caught by a test instead
//! of reaching a reader as its own bare name.

use super::active;

/// The connection is being opened.
pub const CHANNEL_OPENING: &str = "channel-opening";
/// The connection is open and the server named itself.
pub const CHANNEL_OPENED: &str = "channel-opened";
/// The connection could not be opened, and the attempt still cost time.
pub const CHANNEL_OPEN_FAILED: &str = "channel-open-failed";
/// The server is being told the work is finished.
pub const CHANNEL_CLOSING: &str = "channel-closing";
/// The answer declares what it cost on the primary channel.
pub const RESPONSE_VOLUME: &str = "response-volume";
/// An attempt failed in a way that repeating may fix.
pub const ATTEMPT_RETRYING: &str = "attempt-retrying";
/// An attempt failed in a way that repeating cannot fix.
pub const ATTEMPT_PERMANENT: &str = "attempt-permanent";
/// The time allowed for repeating ran out before the attempts did.
pub const ATTEMPT_BUDGET_SPENT: &str = "attempt-budget-spent";
/// A phase went past the time it was given.
pub const BUDGET_EXCEEDED: &str = "budget-exceeded";
/// The server is being asked to stop the work.
pub const BUDGET_ABORT_REQUESTED: &str = "budget-abort-requested";
/// The server confirmed the work has stopped.
pub const BUDGET_ABORT_CONFIRMED: &str = "budget-abort-confirmed";
/// The request to stop never reached the server.
pub const BUDGET_ABORT_UNCONFIRMED: &str = "budget-abort-unconfirmed";
/// A copy has started.
pub const COPY_STARTED: &str = "copy-started";
/// One table of a copy has started.
pub const COPY_TABLE: &str = "copy-table";
/// A table cannot take part in a consistent snapshot.
pub const COPY_SNAPSHOT_UNAVAILABLE: &str = "copy-snapshot-unavailable";
/// A copy has finished.
pub const COPY_FINISHED: &str = "copy-finished";
/// One batch of a load reached the server.
pub const LOAD_BATCH_COMMITTED: &str = "load-batch-committed";
/// One row of a load was refused.
pub const LOAD_ROW_REJECTED: &str = "load-row-rejected";
/// A load has finished.
pub const LOAD_FINISHED: &str = "load-finished";
/// A statement is being sent to the server.
pub const STATEMENT_SENDING: &str = "statement-sending";
/// The table being changed has no key that identifies a row.
pub const SAFETY_NO_UNIQUE_KEY: &str = "safety-no-unique-key";
/// The invocation left behind state that dies with the process.
///
/// One message serves every state, with the state's own stable identifier
/// substituted into it, so a new state is a catalogue entry and not new code.
pub const EPHEMERAL_STATE: &str = "ephemeral-state";

/// A table shape was asked for and the answer carries no rows.
///
/// This one and the two that follow are the only messages here that reach the
/// PRIMARY channel, and they reach only its plain text shape. That shape is
/// published as being for a human reader, so what it carries is prose; the
/// machine shapes carry keys and codes and never a sentence. They were English
/// literals in the formatter until a proof ran the product under `--lang pt-BR`
/// and read `(no rows)` back.
pub const TABLE_NO_ROWS: &str = "table-no-rows";
/// Part of the answer could not be delivered, and the plain shape says which.
pub const ENVELOPE_GAP: &str = "envelope-gap";
/// A field the row does not carry, or carries as null.
///
/// The third of the messages reaching the plain shape, and it was left behind
/// when the first two were moved here. The comment above records that `(no
/// rows)` was found by running the product under `--lang pt-BR` and reading
/// English back; `(absent)` sat four lines away from it in the same formatter
/// and survived that correction, which is what a fix applied to the instance
/// rather than to the family looks like.
pub const TABLE_ABSENT: &str = "table-absent";
/// The manual section a generated page announces itself under.
///
/// A manual page is read by a person, so its section heading follows the
/// reader's language like the rest of the prose. This was the single Portuguese
/// literal left anywhere in the product's source, which meant an English reader
/// was told the page was a "Manual do usuário".
pub const MANUAL_SECTION: &str = "manual-section";
/// A system without permission bits stored the profile file unnarrowed.
///
/// Two of the product's thirteen progress lines were English literals written
/// straight into the `tracing` call, and both live under `cfg(not(unix))` — so
/// no build on this host ever reaches them, and no proof here ever read them.
/// A reader on Windows was the only one who would have seen them, in a language
/// they may not have asked for.
pub const PERMISSIONS_UNAVAILABLE_PROFILES: &str = "permissions-unavailable-profiles";
/// A system without permission bits stored the settings file unnarrowed.
pub const PERMISSIONS_UNAVAILABLE_SETTINGS: &str = "permissions-unavailable-settings";

/// Every message this module can emit.
///
/// Gathered here so a test can prove that each one is carried by each language
/// this build serves, which is what keeps a reader from ever meeting a bare
/// message name where a sentence belonged.
pub const ALL: [&str; 28] = [
    CHANNEL_OPENING,
    CHANNEL_OPENED,
    CHANNEL_OPEN_FAILED,
    CHANNEL_CLOSING,
    RESPONSE_VOLUME,
    ATTEMPT_RETRYING,
    ATTEMPT_PERMANENT,
    ATTEMPT_BUDGET_SPENT,
    BUDGET_EXCEEDED,
    BUDGET_ABORT_REQUESTED,
    BUDGET_ABORT_CONFIRMED,
    BUDGET_ABORT_UNCONFIRMED,
    COPY_STARTED,
    COPY_TABLE,
    COPY_SNAPSHOT_UNAVAILABLE,
    COPY_FINISHED,
    LOAD_BATCH_COMMITTED,
    LOAD_ROW_REJECTED,
    LOAD_FINISHED,
    STATEMENT_SENDING,
    SAFETY_NO_UNIQUE_KEY,
    EPHEMERAL_STATE,
    TABLE_NO_ROWS,
    ENVELOPE_GAP,
    TABLE_ABSENT,
    MANUAL_SECTION,
    PERMISSIONS_UNAVAILABLE_PROFILES,
    PERMISSIONS_UNAVAILABLE_SETTINGS,
];

/// The prose of one message in the language in force.
///
/// Kept apart from the emitting helpers so a test can read exactly what a
/// reader would have seen without installing a channel to capture it.
#[must_use]
pub fn prose(id: &str, arguments: &[(&str, &str)]) -> String {
    active().format(id, arguments)
}

/// Says one thing at the level ordinary progress is reported at.
fn say(id: &str, arguments: &[(&str, &str)]) {
    tracing::info!(message_id = id, "{}", prose(id, arguments));
}

/// Says one thing the reader has to act on, at the level that earns attention.
fn warn(id: &str, arguments: &[(&str, &str)]) {
    tracing::warn!(message_id = id, "{}", prose(id, arguments));
}

/// Says one thing only a reader asking for detail wants to see.
fn detail(id: &str, arguments: &[(&str, &str)]) {
    tracing::debug!(message_id = id, "{}", prose(id, arguments));
}

/// The profile store was written on a system that cannot narrow a file.
///
/// The path travels as a field of its own as well as inside the sentence, for
/// the reason the whole module gives: the sentence differs by language and the
/// field does not, so a collector reads the field.
pub fn permissions_unavailable_profiles(file: &str) {
    tracing::warn!(
        message_id = PERMISSIONS_UNAVAILABLE_PROFILES,
        file,
        "{}",
        prose(PERMISSIONS_UNAVAILABLE_PROFILES, &[])
    );
}

/// The settings file was written on a system that cannot narrow a file.
pub fn permissions_unavailable_settings(file: &str) {
    tracing::warn!(
        message_id = PERMISSIONS_UNAVAILABLE_SETTINGS,
        file,
        "{}",
        prose(PERMISSIONS_UNAVAILABLE_SETTINGS, &[])
    );
}

/// The connection to a destination is being opened.
pub fn channel_opening(destination: &str) {
    say(CHANNEL_OPENING, &[("destination", destination)]);
}

/// The connection is open, with the server's own version and what it cost.
///
/// The time is what reaching the destination took, and it is deliberately not
/// the time the command then took: a caller deciding between one large
/// invocation and several small ones is choosing how many times to pay this
/// number, and a single total tells them nothing about it (FR-138).
///
/// The number is emitted as a field of its own as well as inside the sentence.
/// The sentence changes with the language of the reader, so a collector that
/// had only the sentence would have to read a different one on every host.
pub fn channel_opened(version: &str, millis: u128) {
    tracing::info!(
        message_id = CHANNEL_OPENED,
        open_millis = millis,
        "{}",
        prose(
            CHANNEL_OPENED,
            &[("version", version), ("millis", &millis.to_string())]
        )
    );
}

/// The connection could not be opened, with what the attempt cost anyway.
///
/// A destination that was never reached still consumed the budget, the waits
/// between the repetitions and the caller's patience. Declaring the cost only
/// on the paths that succeeded would hide it exactly where it is largest, so
/// it is declared here too (FR-138).
pub fn channel_open_failed(millis: u128) {
    tracing::warn!(
        message_id = CHANNEL_OPEN_FAILED,
        open_millis = millis,
        "{}",
        prose(CHANNEL_OPEN_FAILED, &[("millis", &millis.to_string())])
    );
}

/// The server is being told the caller is finished, with what the work cost.
///
/// This is the other half of the pair [`channel_opened`] opens: the time the
/// command itself took, apart from the time reaching the destination took
/// (FR-138).
pub fn channel_closing(millis: u128) {
    tracing::info!(
        message_id = CHANNEL_CLOSING,
        command_millis = millis,
        "{}",
        prose(CHANNEL_CLOSING, &[("millis", &millis.to_string())])
    );
}

/// What the answer cost on the primary channel, in bytes and in lines.
///
/// Counted as the bytes really written rather than as the size of anything
/// before it was shaped, because a caller budgeting its own context is
/// budgeting for what arrives and not for what was measured on the way. A
/// number here that disagrees with the primary channel is a defect of this
/// product and never a rounding (FR-139).
pub fn response_volume(bytes: u64, lines: u64) {
    tracing::info!(
        message_id = RESPONSE_VOLUME,
        output_bytes = bytes,
        output_lines = lines,
        "{}",
        prose(
            RESPONSE_VOLUME,
            &[("bytes", &bytes.to_string()), ("lines", &lines.to_string())]
        )
    );
}

/// An attempt failed and will be repeated after a wait.
pub fn attempt_retrying(attempt: u32, attempts: u32, wait_millis: u128) {
    warn(
        ATTEMPT_RETRYING,
        &[
            ("attempt", &attempt.to_string()),
            ("attempts", &attempts.to_string()),
            ("wait", &wait_millis.to_string()),
        ],
    );
}

/// An attempt failed in a way no repetition can fix.
pub fn attempt_permanent() {
    detail(ATTEMPT_PERMANENT, &[]);
}

/// The time allowed for repeating ran out while attempts were still left.
pub fn attempt_budget_spent(spent_millis: u128, budget_millis: u128) {
    warn(
        ATTEMPT_BUDGET_SPENT,
        &[
            ("spent", &spent_millis.to_string()),
            ("budget", &budget_millis.to_string()),
        ],
    );
}

/// A phase ran past the time it was given.
pub fn budget_exceeded(phase: &str, seconds: u64) {
    warn(
        BUDGET_EXCEEDED,
        &[("phase", phase), ("seconds", &seconds.to_string())],
    );
}

/// The server is being asked to stop work that ran too long.
pub fn budget_abort_requested() {
    warn(BUDGET_ABORT_REQUESTED, &[]);
}

/// The server confirmed the work has stopped.
pub fn budget_abort_confirmed() {
    say(BUDGET_ABORT_CONFIRMED, &[]);
}

/// The request to stop never reached the server, so work may still be running.
pub fn budget_abort_unconfirmed() {
    warn(BUDGET_ABORT_UNCONFIRMED, &[]);
}

/// A copy of several tables to a destination has started.
pub fn copy_started(tables: usize, path: &str) {
    say(
        COPY_STARTED,
        &[("tables", &tables.to_string()), ("path", path)],
    );
}

/// One table of the copy has started.
pub fn copy_table(table: &str) {
    say(COPY_TABLE, &[("table", table)]);
}

/// A table cannot take part in the consistent snapshot the copy asked for.
pub fn copy_snapshot_unavailable(table: &str) {
    warn(COPY_SNAPSHOT_UNAVAILABLE, &[("table", table)]);
}

/// The copy finished, with what it moved.
pub fn copy_finished(rows: u64, bytes: u64) {
    say(
        COPY_FINISHED,
        &[("rows", &rows.to_string()), ("bytes", &bytes.to_string())],
    );
}

/// One batch reached the server, with the mark a resumed load starts from.
pub fn load_batch_committed(written: u64, offset: u64) {
    say(
        LOAD_BATCH_COMMITTED,
        &[
            ("written", &written.to_string()),
            ("offset", &offset.to_string()),
        ],
    );
}

/// One row was refused, with the reason the server or the reader gave.
pub fn load_row_rejected(row: u64, reason: &str) {
    warn(
        LOAD_ROW_REJECTED,
        &[("row", &row.to_string()), ("reason", reason)],
    );
}

/// The load finished, with what it wrote and what it refused.
pub fn load_finished(written: u64, rejected: u64) {
    say(
        LOAD_FINISHED,
        &[
            ("written", &written.to_string()),
            ("rejected", &rejected.to_string()),
        ],
    );
}

/// A statement is on its way to the server.
///
/// The values are counted rather than shown. A value may be a credential, and a
/// diagnostic that prints one has leaked it into every log that captured the
/// auxiliary channel.
pub fn statement_sending(statement: &str, values: usize, classification: &str) {
    tracing::debug!(
        message_id = STATEMENT_SENDING,
        statement = statement,
        values = values,
        classification = classification,
        "{}",
        prose(STATEMENT_SENDING, &[])
    );
}

/// The table being changed has no key that identifies a single row.
pub fn safety_no_unique_key(table: &str) {
    tracing::warn!(
        message_id = SAFETY_NO_UNIQUE_KEY,
        table = table,
        "{}",
        prose(SAFETY_NO_UNIQUE_KEY, &[("table", table)])
    );
}

/// The invocation left behind state that dies when the process ends.
///
/// `state` is the stable identifier of that state, and it is emitted as itself
/// as well as substituted into the prose, so a caller keeps something to branch
/// on while a person reads a sentence.
pub fn ephemeral_state(state: &str) {
    tracing::warn!(
        message_id = EPHEMERAL_STATE,
        state = state,
        "{}",
        prose(EPHEMERAL_STATE, &[("state", state)])
    );
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::i18n::{negotiate, Messages, SUPPORTED};

    /// Every message this module can emit is carried by every language this
    /// build serves, so no reader ever meets a bare message name.
    #[test]
    fn every_message_this_module_emits_is_carried_by_every_language() {
        for tag in SUPPORTED {
            let language = negotiate::parse(tag).expect("a language");
            let messages = Messages::load(language).expect("carried by this build");
            for id in ALL {
                assert!(messages.carries(id), "`{tag}` is missing `{id}`");
            }
        }
    }

    /// Naming a message twice would mean two call sites drifting apart while
    /// both looked correct, so the list is proved to hold each name once.
    #[test]
    fn no_message_is_named_twice() {
        let unique: std::collections::BTreeSet<&str> = ALL.iter().copied().collect();
        assert_eq!(unique.len(), ALL.len(), "a message is named more than once");
    }

    /// Emitting says something in every language, and never the bare name of
    /// the message, which is what an absent message would render as.
    #[test]
    fn every_message_renders_as_prose_and_never_as_its_own_name() {
        for id in ALL {
            let rendered = prose(id, &[]);
            assert!(!rendered.is_empty(), "`{id}` rendered as nothing");
            assert_ne!(rendered, id, "`{id}` has no prose behind it");
        }
    }

    /// Emitting with no channel installed is what happens in an ordinary quiet
    /// invocation, and it must cost nothing and break nothing.
    #[test]
    fn emitting_into_a_silent_channel_never_stops_the_work() {
        channel_opening("a-host");
        channel_opened("11.4.0", 12);
        channel_open_failed(4_000);
        channel_closing(37);
        response_volume(2048, 1);
        attempt_retrying(1, 3, 250);
        attempt_permanent();
        budget_exceeded("read", 30);
        budget_abort_requested();
        budget_abort_confirmed();
        budget_abort_unconfirmed();
        copy_started(4, "/tmp/out");
        copy_table("orders");
        copy_snapshot_unavailable("orders");
        copy_finished(10, 2048);
        load_batch_committed(1000, 1000);
        load_row_rejected(7, "the value is not a number");
        load_finished(1000, 7);
        statement_sending("SELECT ?", 1, "read");
        safety_no_unique_key("orders");
        ephemeral_state("temporary_table");
    }
}