Skip to main content

mariadb_cli/output/
envelope.rs

1//! The stable shape every command answers with.
2//!
3//! One shape serves the whole surface, so a caller learns it once. Commands
4//! fill the payload; they never invent envelope fields of their own.
5
6use indexmap::IndexMap;
7use serde::Serialize;
8use serde_json::Value;
9
10/// A gap: something the caller asked for that could not be delivered.
11///
12/// A shrunken answer without a declared gap is a defect. Gaps do not change
13/// the exit number, because the request was partly served.
14#[derive(Debug, Clone, Serialize)]
15pub struct Gap {
16    /// The object that could not be delivered.
17    pub object: String,
18    /// Why it could not be delivered, in stable snake_case.
19    pub cause: String,
20    /// What was missing, in human prose.
21    pub detail: String,
22}
23
24impl Gap {
25    /// Records one undelivered object with its cause.
26    #[must_use]
27    pub fn new(
28        object: impl Into<String>,
29        cause: impl Into<String>,
30        detail: impl Into<String>,
31    ) -> Self {
32        Self {
33            object: object.into(),
34            cause: cause.into(),
35            detail: detail.into(),
36        }
37    }
38}
39
40/// What the output pipeline did to the payload, when it did anything.
41///
42/// Emitted only when at least one operation was active, so an untouched answer
43/// carries no extra weight.
44#[derive(Debug, Clone, Default, Serialize)]
45pub struct Applied {
46    /// Elements the pipeline received.
47    #[serde(skip_serializing_if = "Option::is_none")]
48    pub input_count: Option<usize>,
49    /// Elements the pipeline emitted.
50    #[serde(skip_serializing_if = "Option::is_none")]
51    pub output_count: Option<usize>,
52    /// Whether any cell was shortened.
53    #[serde(skip_serializing_if = "std::ops::Not::not")]
54    pub content_truncated: bool,
55    /// Whether credential-shaped text inside any cell was replaced by the mark.
56    ///
57    /// Reported rather than left silent for the reason the shortening is: a
58    /// caller comparing two answers has to be able to tell a value that was
59    /// never there from one this product took out.
60    #[serde(skip_serializing_if = "std::ops::Not::not")]
61    pub content_redacted: bool,
62    /// Whether whole rows were dropped to fit the volume ceiling.
63    #[serde(skip_serializing_if = "std::ops::Not::not")]
64    pub output_truncated: bool,
65    /// How many elements were dropped.
66    #[serde(skip_serializing_if = "Option::is_none")]
67    pub dropped: Option<usize>,
68    /// The mark that asks for the page after this one.
69    ///
70    /// A plain offset, and deliberately not an encoded blob. A caller has to be
71    /// able to predict and construct the next mark from what it already knows,
72    /// which is why the opaque cursor was dropped from the design: a reader
73    /// that cannot build the mark cannot page without this answer in hand.
74    #[serde(skip_serializing_if = "Option::is_none")]
75    pub next_cursor: Option<usize>,
76    /// Whether anything remains after this page.
77    ///
78    /// Absent means the question was not asked. Present and false is the answer
79    /// that lets a caller stop, which is the whole reason paging is worth
80    /// declaring rather than leaving to be inferred from a short page.
81    #[serde(skip_serializing_if = "Option::is_none")]
82    pub has_more: Option<bool>,
83    /// The operations that needed the whole set gathered before answering.
84    ///
85    /// A read is served as a continuous flow, whose memory cost does not grow
86    /// with the number of rows. Ordering the whole result and counting the
87    /// whole result cannot be: the answer is a property of the set and not of
88    /// any row in it. Naming them here is what keeps that from happening in
89    /// silence, so a caller who asked for a flow and got a gathered answer is
90    /// told which operation cost it.
91    #[serde(skip_serializing_if = "no_operation_gathered")]
92    pub accumulated_for: &'static [&'static str],
93}
94
95/// Whether no operation needed the whole set, so nothing has to be declared.
96fn no_operation_gathered(names: &&'static [&'static str]) -> bool {
97    names.is_empty()
98}
99
100/// The name the signature is declared under, matching the mark that asks for it.
101pub const SIGNATURE_OPERATION: &str = "checksum";
102
103impl Applied {
104    /// Adds the signature to what this answer had to be gathered for.
105    ///
106    /// The names are a fixed slice rather than a list built at run time, so
107    /// that the same set of operations always yields the same bytes and costs
108    /// no allocation. Adding one is therefore a choice among the combinations
109    /// that exist, and there are only these four.
110    #[must_use]
111    pub fn also_gathered_for_the_signature(mut self) -> Self {
112        let gathered = self.accumulated_for;
113        self.accumulated_for = match (gathered.contains(&"sort"), gathered.contains(&"count-only"))
114        {
115            (true, true) => &["sort", "count-only", SIGNATURE_OPERATION],
116            (true, false) => &["sort", SIGNATURE_OPERATION],
117            (false, true) => &["count-only", SIGNATURE_OPERATION],
118            (false, false) => &[SIGNATURE_OPERATION],
119        };
120        self
121    }
122
123    /// Whether anything worth reporting happened.
124    #[must_use]
125    pub const fn is_silent(&self) -> bool {
126        self.input_count.is_none()
127            && self.output_count.is_none()
128            && !self.content_truncated
129            // A report carrying only the redaction was silently dropped here
130            // while the redaction itself worked, so an answer came back altered
131            // and said nothing about it. Every field of this record has to be
132            // named in this list, or the record reports only the fields
133            // somebody remembered.
134            && !self.content_redacted
135            && !self.output_truncated
136            && self.dropped.is_none()
137            && self.accumulated_for.is_empty()
138    }
139}
140
141/// Where the destination of this invocation was decided.
142///
143/// A closed domain, because a caller reading it back has to be able to tell
144/// "I chose this" from "something chose it for me" without a second lookup.
145#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
146#[serde(rename_all = "lowercase")]
147pub enum TargetSource {
148    /// Written on the call, as a profile name.
149    Argv,
150    /// Written on the call, as one text carrying the whole destination.
151    Dsn,
152    /// Written on the call, as a rule that chooses several destinations at once.
153    ///
154    /// `--all-profiles` used to report `config`, which read as "something chose
155    /// this for me" about a call that had said which destinations it wanted.
156    /// The distinction this domain exists to make was the one it got wrong: the
157    /// caller was explicit, and about more than one destination, and the answer
158    /// described them as inherited.
159    Selector,
160    /// Inherited from the stored default, and named by nobody on the call.
161    Config,
162}
163
164/// The destination an answer came from, and how it was chosen.
165///
166/// # Why an answer carries its own question back
167///
168/// Everything else in the envelope describes the result. This describes an
169/// input, which looks redundant until the input was never written down: a call
170/// that names no profile is served by whichever one the stored default points
171/// at, and the answer used to say nothing about which that was. The one
172/// decision the product made on the caller's behalf was the only one it did not
173/// declare.
174#[derive(Debug, Clone, Serialize)]
175pub struct Target {
176    /// The profile that served this call, when a stored profile did.
177    #[serde(skip_serializing_if = "Option::is_none")]
178    pub profile: Option<String>,
179    /// The address reached, when the destination is reached over a network.
180    #[serde(skip_serializing_if = "Option::is_none")]
181    pub host: Option<String>,
182    /// The port reached, when the destination is reached over a network.
183    #[serde(skip_serializing_if = "Option::is_none")]
184    pub port: Option<u16>,
185    /// The local channel reached, when the destination is reached without one.
186    ///
187    /// Present instead of the address and the port rather than beside them, so
188    /// an answer never describes a network hop that did not happen.
189    #[serde(skip_serializing_if = "Option::is_none")]
190    pub socket: Option<String>,
191    /// The database the call was scoped to, when it was scoped to one.
192    #[serde(skip_serializing_if = "Option::is_none")]
193    pub database: Option<String>,
194}
195
196/// The answer of one command.
197///
198/// Field order is fixed by construction, so the same input yields the same
199/// bytes on every platform.
200#[derive(Debug, Clone, Serialize)]
201pub struct Envelope {
202    /// The command that produced this answer, as published in the surface map.
203    pub command: &'static str,
204    /// Version of this envelope shape.
205    pub schema_version: u32,
206    /// The destination this answer came from, when one was reached.
207    ///
208    /// Absent for the commands that answer without a destination, because
209    /// naming one there would be inventing a fact.
210    ///
211    /// Spelled `target_resolved` on the wire, beside `target_source`, so a
212    /// reader finds the destination and the reason it was that destination as
213    /// two facts at the same level rather than one nested inside the other.
214    #[serde(rename = "target_resolved", skip_serializing_if = "Option::is_none")]
215    pub target: Option<Target>,
216    /// How the destination above was chosen.
217    ///
218    /// Beside the destination rather than within it, because a caller checking
219    /// that a change was aimed and not inherited asks only this, and a check
220    /// that has to walk into a nested object to find its answer is a check
221    /// somebody writes wrongly once.
222    #[serde(skip_serializing_if = "Option::is_none")]
223    pub target_source: Option<TargetSource>,
224    /// The command's own result.
225    pub data: Value,
226    /// Objects the caller asked for and did not get, with the cause of each.
227    #[serde(skip_serializing_if = "Vec::is_empty")]
228    pub gaps: Vec<Gap>,
229    /// What the output pipeline did, when it did anything.
230    #[serde(skip_serializing_if = "Option::is_none")]
231    pub applied: Option<Applied>,
232    /// Signature of the result, when the caller asked for one.
233    #[serde(skip_serializing_if = "Option::is_none")]
234    pub checksum: Option<String>,
235    /// The field of `data` that is a document in its own right, when one is.
236    ///
237    /// Almost every answer is data the envelope describes, and writing it to a
238    /// file means writing the envelope. A few answers are not: a manual page is
239    /// a document with a format of its own, and a reader of manual pages cannot
240    /// open an envelope with the page inside a field.
241    ///
242    /// Naming the field rather than carrying a second copy of it keeps the
243    /// primary channel exactly as it was — the envelope still travels whole,
244    /// with the page in it — and lets the one place that writes to a file know
245    /// there is something inside worth writing on its own.
246    ///
247    /// Never serialised. It is an instruction to the writer, not part of the
248    /// answer, and a caller reading the envelope must not find it there.
249    #[serde(skip)]
250    pub raw_field: Option<&'static str>,
251}
252
253/// The current envelope shape version.
254pub const SCHEMA_VERSION: u32 = 1;
255
256impl Envelope {
257    /// Builds an answer for the given command.
258    #[must_use]
259    pub fn new(command: &'static str, data: Value) -> Self {
260        Self {
261            command,
262            schema_version: SCHEMA_VERSION,
263            target: None,
264            target_source: None,
265            data,
266            gaps: Vec::new(),
267            applied: None,
268            checksum: None,
269            raw_field: None,
270        }
271    }
272
273    /// Records the destination this answer came from.
274    ///
275    /// Applied at the one place a destination is opened, rather than by each
276    /// command, because no command owns this fact and every one of them that
277    /// reaches a server has it.
278    ///
279    /// Takes the two facts together, so an answer can never carry a
280    /// destination without saying who chose it.
281    #[must_use]
282    pub fn from_destination(mut self, target: Target, source: TargetSource) -> Self {
283        self.target = Some(target);
284        self.target_source = Some(source);
285        self
286    }
287
288    /// Declares which field of the payload is a document in its own right.
289    ///
290    /// The envelope is unchanged for every caller that reads it. What changes
291    /// is what reaches a file when the caller asked for one: the named field's
292    /// text, and not the envelope around it.
293    #[must_use]
294    pub fn with_raw_field(mut self, field: &'static str) -> Self {
295        self.raw_field = Some(field);
296        self
297    }
298
299    /// The document this answer carries in its own right, when it carries one.
300    ///
301    /// Answers `None` when the named field is absent or is not text, so a
302    /// declaration that stopped being true writes the envelope rather than
303    /// writing nothing at all.
304    #[must_use]
305    pub fn raw_document(&self) -> Option<&str> {
306        self.data.get(self.raw_field?)?.as_str()
307    }
308
309    /// Declares one object the caller asked for and did not get.
310    #[must_use]
311    pub fn with_gap(mut self, gap: Gap) -> Self {
312        self.gaps.push(gap);
313        self
314    }
315
316    /// Records what the output pipeline did, unless it did nothing.
317    #[must_use]
318    pub fn with_applied(mut self, applied: Applied) -> Self {
319        if !applied.is_silent() {
320            self.applied = Some(applied);
321        }
322        self
323    }
324
325    /// Attaches the signature of the result.
326    #[must_use]
327    pub fn with_checksum(mut self, checksum: impl Into<String>) -> Self {
328        self.checksum = Some(checksum.into());
329        self
330    }
331
332    /// The field that lists the columns of the payload rows, when one does.
333    ///
334    /// A payload may carry a list of names beside a list of rows without the
335    /// two being about each other: a report of rejected lines names the columns
336    /// of the file it read, not the fields of a rejection. The list is read as a
337    /// description of the rows only when every key the rows carry is named in
338    /// it, which is what makes it safe to narrow when a projection drops fields.
339    #[must_use]
340    pub fn payload_columns_key(&self) -> Option<&'static str> {
341        const COLUMNS: &str = "columns";
342        let map = self.data.as_object()?;
343        let declared: Vec<&str> = map
344            .get(COLUMNS)?
345            .as_array()?
346            .iter()
347            .map(Value::as_str)
348            .collect::<Option<Vec<&str>>>()?;
349        if declared.is_empty() {
350            return None;
351        }
352        let rows = map.get(self.payload_array_key()?)?.as_array()?;
353        rows.iter()
354            .all(|row| {
355                row.as_object()
356                    .is_some_and(|fields| fields.keys().all(|key| declared.contains(&key.as_str())))
357            })
358            .then_some(COLUMNS)
359    }
360
361    /// Borrows the array the output pipeline should act on, if there is one.
362    ///
363    /// The payload key is found by trying the published names in a fixed
364    /// order, so the same payload always resolves to the same array.
365    #[must_use]
366    pub fn payload_array_key(&self) -> Option<&'static str> {
367        const CANDIDATES: [&str; 6] = ["rows", "items", "objects", "results", "entries", "records"];
368        let map = self.data.as_object()?;
369        CANDIDATES
370            .into_iter()
371            .find(|key| map.get(*key).is_some_and(Value::is_array))
372    }
373}
374
375/// A row as it travels through the output pipeline.
376///
377/// An ordered map keeps column order stable without paying for a hash, and
378/// makes the same query produce the same bytes on every run.
379pub type Row = IndexMap<String, Value>;
380
381#[cfg(test)]
382mod tests {
383    use super::*;
384    use serde_json::json;
385
386    #[test]
387    fn a_clean_answer_carries_no_optional_weight() {
388        let envelope = Envelope::new("schema tables", json!({"rows": []}));
389        let line = serde_json::to_string(&envelope).expect("serialises");
390        assert!(!line.contains("gaps"), "empty gaps must not appear: {line}");
391        assert!(!line.contains("applied"), "silent pipeline must not appear");
392        assert!(
393            !line.contains("checksum"),
394            "absent checksum must not appear"
395        );
396    }
397
398    #[test]
399    fn a_declared_gap_appears_without_changing_the_shape() {
400        let envelope =
401            Envelope::new("schema databases", json!({"rows": ["a"]})).with_gap(Gap::new(
402                "restricted_db",
403                "permission",
404                "the credential may not list this database",
405            ));
406        let parsed = serde_json::to_value(&envelope).expect("serialises");
407        assert_eq!(parsed["gaps"][0]["cause"], "permission");
408        assert_eq!(parsed["gaps"][0]["object"], "restricted_db");
409    }
410
411    #[test]
412    fn a_silent_pipeline_is_not_reported() {
413        let envelope =
414            Envelope::new("query run", json!({"rows": []})).with_applied(Applied::default());
415        assert!(envelope.applied.is_none());
416    }
417
418    #[test]
419    fn the_payload_array_is_found_by_published_order() {
420        let envelope = Envelope::new("query run", json!({"rows": [1, 2], "count": 2}));
421        assert_eq!(envelope.payload_array_key(), Some("rows"));
422
423        let no_array = Envelope::new("meta version", json!({"version": "0.1.0"}));
424        assert_eq!(no_array.payload_array_key(), None);
425    }
426}