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}