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
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
//! The same operations applied to a payload that is already gathered.

use super::summary::profile_of;
use super::value::{
    compare, fit_within, lookup, project, redact_in_place, scalar_text, truncate_in_place,
};
use super::Pipeline;
use crate::error::{Failure, Result};
use crate::output::envelope::{Applied, Envelope};
use serde_json::{Map, Value};

impl Pipeline {
    /// Applies every active operation to the envelope, in the fixed order.
    ///
    /// Records what it did in [`Applied`], so a short answer is never
    /// mistaken for a complete one.
    ///
    /// # Errors
    ///
    /// Returns a limit failure when the volume ceiling has no room for the
    /// answer's own frame. FR-039 promises a reply INSIDE the ceiling, and the
    /// ceiling used to be spent on rows alone: the envelope, the declared
    /// columns and the report of what the pipeline did were all added
    /// afterwards, so every answer left over the ceiling by exactly the size of
    /// its own shape. A ceiling too small for the shape has no honest answer to
    /// give, and half a document is not one, so it ends here rather than
    /// emitting something the caller has to measure to distrust.
    pub fn apply(&self, mut envelope: Envelope) -> Result<Envelope> {
        if self.is_identity() {
            return Ok(envelope);
        }
        let Some(key) = envelope.payload_array_key() else {
            // A payload with no array still honours cell shortening, because a
            // single large field is exactly what the ceiling exists for.
            return self.apply_to_scalar_payload(envelope);
        };
        let key = key.to_owned();
        // Read before the rows are taken out of the payload, because the test
        // that decides whether the declared list describes them is made of the
        // rows themselves.
        let columns_key = envelope.payload_columns_key();

        let Some(elements) = envelope
            .data
            .get_mut(&key)
            .and_then(Value::as_array_mut)
            .map(std::mem::take)
        else {
            return Ok(envelope);
        };

        let mut applied = Applied {
            input_count: Some(elements.len()),
            // Declared before anything is reduced, so an operation that needed
            // the whole set is named even when the answer came out empty.
            accumulated_for: self.accumulated_for(),
            ..Applied::default()
        };
        let mut elements = self.reduce(elements, &mut applied);

        if self.count_only {
            envelope.data = Value::Object(Map::from_iter([(
                "count".to_owned(),
                Value::from(elements.len()),
            )]));
            applied.output_count = Some(elements.len());
            return self.within_the_ceiling(envelope.with_applied(applied));
        }

        if self.summary {
            let profile = profile_of(&elements, self.most_frequent_shown);
            applied.output_count = Some(elements.len());
            envelope.data = profile;
            return self.within_the_ceiling(envelope.with_applied(applied));
        }

        // Before the shortening, never after: a credential cut to fit would
        // leave the part that fitted standing in the answer.
        if self.redact {
            for element in &mut elements {
                applied.content_redacted |= redact_in_place(element);
            }
        }
        if let Some(ceiling) = self.truncate_cell {
            for element in &mut elements {
                applied.content_truncated |= truncate_in_place(element, ceiling);
            }
        }
        if let Some(ceiling) = self.max_output_bytes {
            // Measured on the envelope the rows were just taken out of, so what
            // is charged is the frame this very answer will be written with and
            // not a guess at one.
            let room = self.room_for_rows(&envelope, elements.len(), ceiling)?;
            let kept = fit_within(&elements, room);
            if kept < elements.len() {
                applied.output_truncated = true;
                applied.dropped = Some(applied.dropped.unwrap_or(0) + (elements.len() - kept));
                elements.truncate(kept);
            }
        }

        applied.output_count = Some(elements.len());
        if let Some(slot) = envelope.data.get_mut(&key) {
            *slot = Value::Array(elements);
        }
        if let Some(columns_key) = columns_key {
            self.narrow_declared_columns(&mut envelope.data, columns_key);
        }
        Ok(envelope.with_applied(applied))
    }

    /// How many bytes are left for rows once the answer's own frame is paid for.
    ///
    /// The frame is everything the caller receives that is not a row: the
    /// command, the shape version, the destination, the declared columns and
    /// the report of what the pipeline did. None of it was ever charged, which
    /// is why a ceiling of ten bytes produced six hundred and sixty-one.
    ///
    /// The report is measured at its WIDEST rather than as it will finally be
    /// written, because how many rows are dropped is not known until the room
    /// left for them is. Every number in it is bounded by the count of rows in
    /// hand, and every mark that costs bytes is set, so the measurement is an
    /// upper bound and never an under-count. Erring the other way would put the
    /// answer back over the ceiling, which is the defect this repairs.
    ///
    /// # Errors
    ///
    /// Returns a limit failure when the frame alone is already over the
    /// ceiling, because an answer stripped of its frame is not an answer.
    fn room_for_rows(&self, envelope: &Envelope, rows: usize, ceiling: usize) -> Result<usize> {
        let mut probe = envelope.clone();
        probe.applied = Some(self.widest_report(rows));
        let frame = frame_bytes(&probe);
        if frame > ceiling {
            return Err(no_room_for_the_frame(frame, ceiling));
        }
        Ok(ceiling - frame)
    }

    /// Refuses an answer whose payload cannot be shortened by dropping rows.
    ///
    /// A count, a profile and a payload that carries no array are each one
    /// indivisible value: there is nothing to drop from them, so either the
    /// whole thing fits under the ceiling or the ceiling cannot be honoured at
    /// all. Emitting them regardless is what made `--count-only` overshoot as
    /// reliably as a set of rows did.
    ///
    /// # Errors
    ///
    /// Returns a limit failure when the answer does not fit the ceiling.
    fn within_the_ceiling(&self, envelope: Envelope) -> Result<Envelope> {
        let Some(ceiling) = self.max_output_bytes else {
            return Ok(envelope);
        };
        let whole = frame_bytes(&envelope);
        if whole > ceiling {
            return Err(no_room_for_the_frame(whole, ceiling));
        }
        Ok(envelope)
    }

    /// The widest report this pipeline could end up writing, for measuring.
    ///
    /// Every count is set to the rows in hand, which is the largest any of them
    /// can be and therefore the most digits any of them can cost; and
    /// `has_more` carries the longer of its two words. The marks a pipeline
    /// that was never asked for them cannot write are left out, because room
    /// reserved for a field that will not be written is room the caller paid
    /// for and never received. Nothing here is claimed to anybody: this value
    /// is measured and thrown away.
    pub(super) fn widest_report(&self, rows: usize) -> Applied {
        let paging = self.cursor.is_some() || self.limit.is_some();
        Applied {
            input_count: Some(rows),
            output_count: Some(rows),
            content_truncated: self.truncate_cell.is_some(),
            content_redacted: self.redact,
            output_truncated: true,
            dropped: Some(rows),
            next_cursor: paging.then(|| self.cursor.unwrap_or(0).saturating_add(rows)),
            has_more: paging.then_some(false),
            accumulated_for: self.accumulated_for(),
        }
    }

    /// Narrows a declared column list to the columns the rows still carry.
    ///
    /// A payload that names its columns beside its rows must name the ones the
    /// rows actually carry, or a caller building a table from that list renders
    /// a column the projection had already dropped.
    fn narrow_declared_columns(&self, data: &mut Value, columns_key: &str) {
        if self.select.is_empty() {
            return;
        }
        let Some(slot) = data.get_mut(columns_key) else {
            return;
        };
        let Some(declared) = slot.as_array() else {
            return;
        };
        let names: Vec<String> = declared
            .iter()
            .filter_map(|name| name.as_str().map(ToOwned::to_owned))
            .collect();
        *slot = Value::Array(
            self.columns_after_projection(&names)
                .into_iter()
                .map(Value::from)
                .collect(),
        );
    }

    /// Filters, orders, deduplicates, limits and projects, in that order.
    fn reduce(&self, elements: Vec<Value>, applied: &mut Applied) -> Vec<Value> {
        let before = elements.len();
        let mut elements: Vec<Value> = elements
            .into_iter()
            .filter(|element| self.filters.iter().all(|filter| filter.accepts(element)))
            .collect();

        if let Some(path) = &self.sort {
            // Elements missing the key sort last, so their absence never
            // disturbs the order of the ones that have it.
            elements.sort_by(
                |left, right| match (lookup(left, path), lookup(right, path)) {
                    (Some(a), Some(b)) => compare(a, b),
                    (Some(_), None) => std::cmp::Ordering::Less,
                    (None, Some(_)) => std::cmp::Ordering::Greater,
                    (None, None) => std::cmp::Ordering::Equal,
                },
            );
        }

        if let Some(path) = &self.dedupe_by {
            // Elements missing the key are always kept: absence is not a
            // repeated value.
            let mut seen = std::collections::BTreeSet::new();
            elements.retain(|element| {
                lookup(element, path)
                    .is_none_or(|found| seen.insert(scalar_text(found).into_owned()))
            });
        }

        // The mark is applied here, after everything that decides WHICH rows
        // belong to the answer and before the ceiling that decides how many of
        // them leave. Applying it earlier would page over a set the caller
        // never asked for.
        let passed_over = self.cursor.unwrap_or(0).min(elements.len());
        if passed_over > 0 {
            elements.drain(..passed_over);
        }

        if let Some(ceiling) = self.limit {
            applied.has_more = Some(elements.len() > ceiling);
            elements.truncate(ceiling);
        } else if self.cursor.is_some() {
            applied.has_more = Some(false);
        }
        if self.cursor.is_some() || self.limit.is_some() {
            applied.next_cursor = Some(self.cursor.unwrap_or(0) + elements.len());
        }

        if !self.select.is_empty() {
            for element in &mut elements {
                *element = project(element, &self.select);
            }
        }

        let dropped = before.saturating_sub(elements.len());
        if dropped > 0 {
            applied.dropped = Some(dropped);
        }
        elements
    }

    /// Applies cell shortening to a payload that carries no array.
    ///
    /// # Errors
    ///
    /// Returns a limit failure when what is left is still over the volume
    /// ceiling, because there are no rows here to drop to make it fit.
    fn apply_to_scalar_payload(&self, mut envelope: Envelope) -> Result<Envelope> {
        if !self.redact && self.truncate_cell.is_none() {
            return self.within_the_ceiling(envelope);
        }
        let redacted = self.redact && redact_in_place(&mut envelope.data);
        let truncated = self
            .truncate_cell
            .is_some_and(|ceiling| truncate_in_place(&mut envelope.data, ceiling));
        self.within_the_ceiling(envelope.with_applied(Applied {
            content_truncated: truncated,
            content_redacted: redacted,
            ..Applied::default()
        }))
    }
}

/// How many bytes this envelope costs on the channel, ending included.
///
/// Every shape writes the answer and one line ending after it, so the ending is
/// part of what the caller was promised to stay under. An envelope that cannot
/// be serialised is charged everything, because the ceiling must never be
/// honoured by failing to measure.
fn frame_bytes(envelope: &Envelope) -> usize {
    serde_json::to_string(envelope).map_or(usize::MAX, |text| text.len().saturating_add(1))
}

/// The failure a ceiling with no room for the shape of the answer produces.
///
/// FR-039 names this case: a ceiling smaller than a single row ends at the
/// limit number rather than emitting half of one. Half a document parses as
/// nothing, so a caller would have to distrust every short answer to notice.
fn no_room_for_the_frame(needed: usize, ceiling: usize) -> Failure {
    Failure::limit(
        "limit.output_bytes",
        format!("the answer needs {needed} bytes and the volume ceiling is {ceiling}"),
    )
    .with_detail("detail", format!("{needed} > {ceiling}"))
    .with_hint("raise --max-output-bytes, or ask for fewer columns")
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::output::ops::Filter;
    use serde_json::json;

    fn sample() -> Envelope {
        Envelope::new(
            "schema tables",
            json!({"rows": [
                {"name": "alpha", "rows": 10, "engine": "InnoDB"},
                {"name": "beta",  "rows":  2, "engine": "Aria"},
                {"name": "gamma", "rows": 30, "engine": "InnoDB"}
            ]}),
        )
    }

    fn rows(envelope: &Envelope) -> &Vec<Value> {
        envelope.data["rows"].as_array().expect("array payload")
    }

    /// Redaction runs before the shortening, and the order is what makes it work.
    ///
    /// Shortening first would cut the credential and leave the part that fitted
    /// standing in the answer, which is the same leak in fewer characters. This
    /// asks for a ceiling far shorter than the destination and demands that no
    /// piece of the password reaches the answer.
    #[test]
    fn shortening_a_redacted_cell_never_leaves_a_piece_of_the_credential() {
        let carrying = Envelope::new(
            "query run",
            json!({"rows": [{"dsn": "mariadb://reader:hunter2@db.example:3306/loja"}]}),
        );

        let pipeline = Pipeline {
            redact: true,
            truncate_cell: Some(6),
            ..Pipeline::default()
        };
        let answered = pipeline.apply(carrying).expect("the answer is shaped");

        let cell = rows(&answered)[0]["dsn"].as_str().expect("text");
        assert!(
            !cell.contains("hunter") && !cell.contains("hunte") && !cell.contains("hunt"),
            "the shortening left a piece of the credential: {cell}"
        );
    }

    #[test]
    fn the_three_filter_forms_parse_and_select() {
        let pipeline = Pipeline {
            filters: vec![Filter::parse("engine=InnoDB").expect("parses")],
            ..Pipeline::default()
        };
        let out = pipeline.apply(sample()).expect("fits");
        assert_eq!(rows(&out).len(), 2);

        let pipeline = Pipeline {
            filters: vec![Filter::parse("engine!=InnoDB").expect("parses")],
            ..Pipeline::default()
        };
        assert_eq!(rows(&pipeline.apply(sample()).expect("fits")).len(), 1);

        let pipeline = Pipeline {
            filters: vec![Filter::parse("name~mm").expect("parses")],
            ..Pipeline::default()
        };
        assert_eq!(rows(&pipeline.apply(sample()).expect("fits")).len(), 1);
    }

    #[test]
    fn numbers_order_numerically_and_not_as_text() {
        let pipeline = Pipeline {
            sort: Some("rows".to_owned()),
            ..Pipeline::default()
        };
        let out = pipeline.apply(sample()).expect("fits");
        let order: Vec<i64> = rows(&out)
            .iter()
            .map(|row| row["rows"].as_i64().expect("number"))
            .collect();
        assert_eq!(order, vec![2, 10, 30]);
    }

    #[test]
    fn deduplication_keeps_the_first_and_the_keyless() {
        let envelope = Envelope::new(
            "schema tables",
            json!({"rows": [
                {"engine": "InnoDB", "name": "a"},
                {"engine": "InnoDB", "name": "b"},
                {"name": "no-engine"}
            ]}),
        );
        let pipeline = Pipeline {
            dedupe_by: Some("engine".to_owned()),
            ..Pipeline::default()
        };
        let out = pipeline.apply(envelope).expect("fits");
        assert_eq!(rows(&out).len(), 2);
    }

    #[test]
    fn projection_skips_absent_paths_rather_than_emitting_null() {
        let pipeline = Pipeline {
            select: vec!["name".to_owned(), "absent".to_owned()],
            ..Pipeline::default()
        };
        let out = pipeline.apply(sample()).expect("fits");
        let first = rows(&out)[0].as_object().expect("object");
        assert!(first.contains_key("name"));
        assert!(!first.contains_key("absent"));
    }

    #[test]
    fn counting_happens_after_filtering() {
        let pipeline = Pipeline {
            filters: vec![Filter::parse("engine=InnoDB").expect("parses")],
            count_only: true,
            ..Pipeline::default()
        };
        let out = pipeline.apply(sample()).expect("fits");
        assert_eq!(out.data["count"], 2);
    }

    #[test]
    fn cell_shortening_counts_characters_and_never_splits_one() {
        let envelope = Envelope::new("query run", json!({"rows": [{"text": "áéíóú"}]}));
        let pipeline = Pipeline {
            truncate_cell: Some(3),
            ..Pipeline::default()
        };
        let out = pipeline.apply(envelope).expect("fits");
        assert_eq!(rows(&out)[0]["text"], "áéí");
        assert!(out.applied.as_ref().expect("reported").content_truncated);
    }

    /// How many bytes this answer costs on the channel, ending included.
    fn volume(envelope: &Envelope) -> usize {
        serde_json::to_string(envelope).expect("serialises").len() + 1
    }

    /// FR-039. The ceiling is measured against the WHOLE answer and not against
    /// its rows, so what leaves is under what was asked for.
    ///
    /// The ceiling used to be spent on rows alone, which put every answer over
    /// it by the size of its own envelope. Sized here against the whole answer
    /// rather than written as a constant, so the proof keeps meaning the same
    /// thing when a field is added to the envelope.
    #[test]
    fn the_volume_ceiling_drops_whole_rows_and_says_so() {
        let roomy = Pipeline {
            max_output_bytes: Some(usize::MAX),
            ..Pipeline::default()
        };
        let whole = volume(&roomy.apply(sample()).expect("fits"));
        let ceiling = whole - 20;
        let pipeline = Pipeline {
            max_output_bytes: Some(ceiling),
            ..Pipeline::default()
        };
        let out = pipeline.apply(sample()).expect("fits");
        let applied = out.applied.as_ref().expect("reported");
        assert!(applied.output_truncated);
        assert!(rows(&out).len() < 3);
        for row in rows(&out) {
            assert!(row.is_object(), "a kept row must stay whole");
        }
        assert!(
            volume(&out) <= ceiling,
            "the answer left over the ceiling it was cut to fit: {} > {ceiling}",
            volume(&out)
        );
    }

    /// FR-039. A ceiling too small for the shape of the answer ends at the
    /// limit number, because half a document is not a shorter answer.
    #[test]
    fn a_ceiling_with_no_room_for_the_shape_ends_at_the_limit_number() {
        for ceiling in [1usize, 10, 40] {
            let pipeline = Pipeline {
                max_output_bytes: Some(ceiling),
                ..Pipeline::default()
            };
            let refused = pipeline.apply(sample()).expect_err("nothing fits here");
            assert_eq!(refused.category(), crate::error::Category::Limit);
            assert_eq!(refused.exit_number().code(), 10);
        }
    }

    /// FR-039. A count is one indivisible value, so a ceiling it does not fit
    /// is refused rather than overshot: there is no row to drop from it.
    #[test]
    fn a_count_too_large_for_the_ceiling_is_refused_rather_than_emitted() {
        let pipeline = Pipeline {
            count_only: true,
            max_output_bytes: Some(10),
            ..Pipeline::default()
        };
        let refused = pipeline.apply(sample()).expect_err("nothing fits here");
        assert_eq!(refused.exit_number().code(), 10);

        let roomy = Pipeline {
            count_only: true,
            max_output_bytes: Some(4096),
            ..Pipeline::default()
        };
        let out = roomy.apply(sample()).expect("fits");
        assert_eq!(out.data["count"], 3);
        assert!(volume(&out) <= 4096);
    }

    #[test]
    fn an_idle_pipeline_reports_nothing() {
        let out = Pipeline::default().apply(sample()).expect("fits");
        assert!(out.applied.is_none());
        assert_eq!(rows(&out).len(), 3);
    }

    /// Paging must describe the same set on every page, so no row is seen
    /// twice and none is missed. Both values of the mark are driven, because a
    /// first page that happens to look right proves nothing about a second.
    #[test]
    fn every_page_of_a_request_covers_the_set_once() {
        let page = |mark: Option<usize>| {
            let pipeline = Pipeline {
                sort: Some("name".to_owned()),
                cursor: mark,
                limit: Some(2),
                ..Pipeline::default()
            };
            let out = pipeline.apply(sample()).expect("fits");
            let names: Vec<String> = rows(&out)
                .iter()
                .map(|row| row["name"].as_str().expect("text").to_owned())
                .collect();
            (names, out.applied.expect("reported"))
        };

        let (first, first_applied) = page(None);
        assert_eq!(first, ["alpha", "beta"]);
        assert_eq!(first_applied.next_cursor, Some(2));
        assert_eq!(
            first_applied.has_more,
            Some(true),
            "a caller must be told to ask again rather than infer it"
        );

        let (second, second_applied) = page(Some(2));
        assert_eq!(second, ["gamma"]);
        assert_eq!(second_applied.has_more, Some(false));

        // The two pages together are the whole set, each row exactly once.
        let mut walked = first;
        walked.extend(second);
        walked.sort();
        assert_eq!(walked, ["alpha", "beta", "gamma"]);
    }

    /// A mark past the end is an empty page and never a failure: a caller
    /// paging to exhaustion arrives there by walking, not by mistake.
    #[test]
    fn a_mark_past_the_end_is_an_empty_page() {
        let pipeline = Pipeline {
            cursor: Some(99),
            limit: Some(2),
            ..Pipeline::default()
        };
        let out = pipeline.apply(sample()).expect("fits");
        assert!(rows(&out).is_empty());
        assert_eq!(out.applied.expect("reported").has_more, Some(false));
    }

    /// An answer that had to be gathered must say so, or the caller reads a
    /// gathered answer as though the flow guarantee had held.
    #[test]
    fn a_gathered_answer_names_the_operation_that_gathered_it() {
        let pipeline = Pipeline {
            sort: Some("rows".to_owned()),
            ..Pipeline::default()
        };
        let applied = pipeline
            .apply(sample())
            .expect("fits")
            .applied
            .expect("reported");
        assert_eq!(applied.accumulated_for, ["sort"]);

        let both = Pipeline {
            sort: Some("rows".to_owned()),
            count_only: true,
            ..Pipeline::default()
        };
        let applied = both
            .apply(sample())
            .expect("fits")
            .applied
            .expect("reported");
        assert_eq!(applied.accumulated_for, ["sort", "count-only"]);
    }

    /// A payload that names its columns beside its rows must name the ones the
    /// rows carry. Declaring a column the projection dropped makes a caller
    /// render an empty column the data never had.
    #[test]
    fn a_projection_narrows_the_columns_the_answer_declares() {
        let envelope = Envelope::new(
            "query run",
            json!({"columns": ["a", "b", "c"], "rows": [{"a": 1, "b": 2, "c": 3}]}),
        );
        let pipeline = Pipeline {
            select: vec!["a".to_owned(), "c".to_owned()],
            ..Pipeline::default()
        };
        let out = pipeline.apply(envelope).expect("fits");
        assert_eq!(out.data["columns"], json!(["a", "c"]));

        // The declared list is worth nothing unless the rows agree with it.
        let carried: Vec<&String> = rows(&out)[0].as_object().expect("object").keys().collect();
        assert_eq!(carried, ["a", "c"]);
    }

    /// A list of names beside a list of rows is not always about them: a report
    /// of rejected lines names the columns of the file it read, not the fields
    /// of a rejection. Narrowing that list would describe the file by the shape
    /// of the complaints about it.
    #[test]
    fn a_column_list_that_does_not_describe_the_rows_is_left_alone() {
        let envelope = Envelope::new(
            "data import",
            json!({
                "columns": ["id", "name"],
                "rows": [{"row": 3, "reason": "a value was refused"}]
            }),
        );
        let pipeline = Pipeline {
            select: vec!["row".to_owned()],
            ..Pipeline::default()
        };
        let out = pipeline.apply(envelope).expect("fits");
        assert_eq!(
            out.data["columns"],
            json!(["id", "name"]),
            "a list describing something else was narrowed by a projection over the rows"
        );
    }

    /// An answer served row by row must not claim it was gathered.
    #[test]
    fn a_streaming_operation_declares_no_accumulation() {
        let pipeline = Pipeline {
            limit: Some(2),
            ..Pipeline::default()
        };
        let applied = pipeline
            .apply(sample())
            .expect("fits")
            .applied
            .expect("reported");
        assert!(applied.accumulated_for.is_empty());
    }
}