shep-daemon 0.25.2

The supervision engine behind shep: process spawning, restart policy, the log plane, watch and cron restarts, and the RPC server
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
//! [`AnsiLines`], the filter between a pty's master and the line reader.
//!
//! A full-screen sheep repaints by moving its cursor up and printing the
//! frame again. The filter keeps the rows it wrote, so a repaint writes only
//! the rows that changed.

use core::pin::Pin;
use core::task::{Context, Poll, ready};

use std::collections::VecDeque;
use std::io;

use tokio::io::{AsyncRead, ReadBuf};

/// Bytes read off the inner reader per poll.
const SCRATCH: usize = 4096;

/// Bytes of an OSC, DCS or similar string sequence kept before the filter
/// gives up on its terminator and returns to plain text.
///
/// Real titles and hyperlinks are far shorter; a stray introducer must not
/// swallow the rest of the log.
const STRING_LIMIT: usize = 4096;

/// CSI final bytes that move the cursor or erase: each ends the line being
/// written, since what follows overwrites or replaces it.
const LINE_BREAKING_FINALS: &[u8] = b"ABCDEFGHJKXadef`";

/// Rows the filter keeps, so a repaint can be compared against what it
/// replaces.
///
/// A pty opens at [`super::pty::PTY_ROWS`] 50 and `shep attach` resizes it to
/// the operator's terminal. Past this the oldest rows go.
const SCREEN_ROWS: usize = 256;

/// Bytes a row may hold before the filter stops being able to keep it.
///
/// [`SCRATCH`] is what one read carries, so a row that reaches this goes out
/// a read at a time instead of as a whole allocation.
const SCREEN_ROW_BYTES: usize = SCRATCH;

/// Where the filter is inside an escape sequence.
#[derive(Clone, Copy, PartialEq, Eq)]
enum State {
    Ground,
    /// After `ESC`.
    Escape,
    /// After `ESC` and an intermediate byte, as in `ESC ( B`.
    EscapeIntermediate,
    /// Inside `ESC [`, up to its final byte.
    Csi,
    /// Inside an OSC, DCS, SOS, PM or APC string. Only OSC ends on `BEL`.
    Text {
        bell_ends: bool,
        seen: usize,
    },
    /// An `ESC` inside such a string, which ends it if `\` follows.
    TextEscape,
}

/// Reads another reader's bytes as plain text: escape sequences removed, line
/// ends normalised, and invalid UTF-8 replaced.
///
/// A sequence vanishes even when a read boundary falls inside it. A run of
/// `\r` counts as one, and with a CSI that moves the cursor or erases ends a
/// line that has text; `\r\n` becomes `\n`. The output is valid UTF-8 for
/// `LineReader`, with `U+FFFD` for each invalid sequence.
pub(super) struct AnsiLines<R> {
    inner: R,
    state: State,
    /// A `\r` was last seen and not yet resolved by the byte after it. A run
    /// of them counts as one.
    cr_pending: bool,
    /// The line being written has a visible byte.
    line_has_text: bool,
    /// A CSI just ended the row, and nothing has been drawn since. The `\n`
    /// that follows ends that same screen row, as in `text ESC [ K \n`, so it
    /// takes no slot of its own. Holds whether the row was written.
    closed: Option<bool>,
    /// Bytes of the row being written that are not out yet. Never past
    /// [`SCREEN_ROW_BYTES`].
    row: Vec<u8>,
    /// The row being written passed [`SCREEN_ROW_BYTES`], so part of it went
    /// out as it was read. It holds a slot as nothing to compare against.
    spilling: bool,
    /// Rows written so far, oldest first, capped at [`SCREEN_ROWS`]. `None`
    /// is one that went out as it was read, so a repaint against it is
    /// written.
    screen: VecDeque<Option<Vec<u8>>>,
    /// Rows ahead that replace the tail of [`Self::screen`], from a cursor-up.
    /// Never past it unless [`Self::blind`] holds.
    replacing: usize,
    /// The window reaches past what is kept, so it names nothing to compare
    /// against. Every row in it is written.
    blind: bool,
    /// Digits of the CSI's first parameter, saturating.
    csi_param: u32,
    /// That parameter ended at `;`, so the digits after it are another's.
    csi_closed: bool,
    /// Leading bytes of a character the last read cut short.
    carry: Vec<u8>,
    /// Filtered, valid UTF-8 not yet handed to the caller.
    ready: Vec<u8>,
    sent: usize,
    eof: bool,
}

impl<R> AnsiLines<R> {
    /// A filter over `inner`.
    pub(super) fn new(inner: R) -> Self {
        Self {
            inner,
            state: State::Ground,
            cr_pending: false,
            line_has_text: false,
            closed: None,
            row: Vec::new(),
            spilling: false,
            screen: VecDeque::new(),
            replacing: 0,
            blind: false,
            csi_param: 0,
            csi_closed: false,
            carry: Vec::new(),
            ready: Vec::new(),
            sent: 0,
            eof: false,
        }
    }

    /// Ends the line being written if it has text. A line with none is
    /// already ended, and what was drawn on it is whitespace a cursor move
    /// left behind or a `\r` moved back over: the next row starts where the
    /// cursor now is.
    fn break_line(&mut self, text: &mut Vec<u8>) {
        if self.line_has_text {
            let written = self.end_row(text, true);
            self.closed = Some(written);
        } else {
            self.row.clear();
        }
    }

    /// Ends the row being written. A row that repeats the one it replaces is
    /// dropped. Every other row is written and kept. `line_end` is false for
    /// a stream that stops mid-row, which owes that row no newline. Returns
    /// whether the row was written.
    fn end_row(&mut self, text: &mut Vec<u8>, line_end: bool) -> bool {
        let row = core::mem::take(&mut self.row);
        let spilled = core::mem::replace(&mut self.spilling, false);
        self.line_has_text = false;
        // `cursor_up` keeps `replacing` within `screen.len()` unless the
        // window is blind, so the subtraction below cannot underflow.
        let target = match self.replacing {
            0 => None,
            _ if self.blind => None,
            n => Some(self.screen.len() - n),
        };
        // A row that spilled went out a read at a time and holds no bytes a
        // repaint can be compared to.
        let repeat = match target {
            Some(i) if !spilled => self.screen[i].as_deref() == Some(row.as_slice()),
            _ => false,
        };
        if !repeat {
            text.extend_from_slice(&row);
            if line_end {
                text.push(b'\n');
            }
        }
        // A spilled row still holds its slot, as `None`, so a repaint
        // against it is written.
        let kept = (!spilled).then_some(row);
        match (target, repeat) {
            (Some(i), false) => self.screen[i] = kept,
            (None, false) => {
                if self.screen.len() == SCREEN_ROWS {
                    self.screen.pop_front();
                }
                self.screen.push_back(kept);
            }
            (_, true) => {}
        }
        self.replacing = self.replacing.saturating_sub(1);
        if self.replacing == 0 {
            self.blind = false;
        }
        !repeat
    }

    /// Resolves a pending `\r` as a bare one.
    fn settle_cr(&mut self, text: &mut Vec<u8>) {
        if self.cr_pending {
            self.cr_pending = false;
            self.break_line(text);
        }
    }

    /// Marks the rows ahead as replacing the last `rows` kept rows.
    ///
    /// A window past what is kept is blind: it names rows the filter never
    /// saw, and stays blind until it ends. The bound at [`SCREEN_ROWS`]
    /// stops one stray cursor-up from blinding the filter for good.
    fn cursor_up(&mut self, rows: usize) {
        let total = self.replacing.saturating_add(rows);
        self.blind |= total > self.screen.len();
        self.replacing = total.min(SCREEN_ROWS);
    }

    /// Feeds one byte through the state machine, appending plain bytes to
    /// `text`.
    fn step(&mut self, byte: u8, text: &mut Vec<u8>) {
        match self.state {
            State::Ground => self.ground(byte, text),
            State::Escape => match byte {
                b'[' => {
                    self.state = State::Csi;
                    self.csi_param = 0;
                    self.csi_closed = false;
                }
                b']' => {
                    self.state = State::Text {
                        bell_ends: true,
                        seen: 0,
                    }
                }
                b'P' | b'X' | b'^' | b'_' => {
                    self.state = State::Text {
                        bell_ends: false,
                        seen: 0,
                    }
                }
                0x20..=0x2f => self.state = State::EscapeIntermediate,
                0x1b => {}
                0x30..=0x7e => self.state = State::Ground,
                _ => {
                    self.state = State::Ground;
                    self.ground(byte, text);
                }
            },
            State::EscapeIntermediate => match byte {
                0x20..=0x2f => {}
                0x30..=0x7e => self.state = State::Ground,
                _ => {
                    self.state = State::Ground;
                    self.ground(byte, text);
                }
            },
            State::Csi => match byte {
                0x20..=0x3f => match byte {
                    b'0'..=b'9' if !self.csi_closed => {
                        self.csi_param = self
                            .csi_param
                            .saturating_mul(10)
                            .saturating_add(u32::from(byte - b'0'));
                    }
                    b';' => self.csi_closed = true,
                    _ => {}
                },
                0x40..=0x7e => {
                    self.state = State::Ground;
                    let up = byte == b'A';
                    // ECMA-48 reads an omitted or zero parameter as one.
                    let rows = usize::try_from(self.csi_param.max(1)).unwrap_or(usize::MAX);
                    if LINE_BREAKING_FINALS.contains(&byte) {
                        self.settle_cr(text);
                        self.break_line(text);
                    }
                    if up {
                        self.cursor_up(rows);
                    }
                }
                0x1b => self.state = State::Escape,
                _ => {
                    self.state = State::Ground;
                    self.ground(byte, text);
                }
            },
            State::Text { bell_ends, seen } => match byte {
                0x07 if bell_ends => self.state = State::Ground,
                0x1b => self.state = State::TextEscape,
                _ if seen >= STRING_LIMIT => {
                    self.state = State::Ground;
                    self.ground(byte, text);
                }
                _ => {
                    self.state = State::Text {
                        bell_ends,
                        seen: seen + 1,
                    }
                }
            },
            State::TextEscape => match byte {
                b'\\' => self.state = State::Ground,
                _ => {
                    self.state = State::Escape;
                    self.step(byte, text);
                }
            },
        }
    }

    /// A byte outside any escape sequence.
    fn ground(&mut self, byte: u8, text: &mut Vec<u8>) {
        match byte {
            b'\r' => self.cr_pending = true,
            b'\n' => {
                self.cr_pending = false;
                match self.closed.take() {
                    // The row a CSI ended is this row. The log keeps the
                    // newline it always had, but only beside a written row.
                    Some(written) if self.row.is_empty() => {
                        if written {
                            text.push(b'\n');
                        }
                    }
                    _ => {
                        self.end_row(text, true);
                    }
                }
            }
            0x1b => {
                self.settle_cr(text);
                self.state = State::Escape;
            }
            // The other C0 controls and DEL draw nothing in a log.
            0x00..=0x08 | 0x0b..=0x0c | 0x0e..=0x1a | 0x1c..=0x1f | 0x7f => {}
            _ => {
                self.settle_cr(text);
                self.push_byte(byte, text);
                if byte != b'\t' && byte != b' ' {
                    self.line_has_text = true;
                }
            }
        }
    }

    /// Adds a visible byte to the row being written. A row that reaches
    /// [`SCREEN_ROW_BYTES`] goes out as it is read, so a run of bytes with no
    /// line end costs one read and never the whole run.
    fn push_byte(&mut self, byte: u8, text: &mut Vec<u8>) {
        self.closed = None;
        self.row.push(byte);
        if self.row.len() < SCREEN_ROW_BYTES {
            return;
        }
        text.extend_from_slice(&self.row);
        self.row.clear();
        self.spilling = true;
        self.line_has_text = true;
    }

    /// Moves `text` into `ready`, holding back a character cut short at its
    /// end unless `last`, and replacing each invalid sequence.
    fn decode(&mut self, text: &[u8], last: bool) {
        let mut bytes = core::mem::take(&mut self.carry);
        bytes.extend_from_slice(text);
        let mut rest = bytes.as_slice();
        loop {
            match core::str::from_utf8(rest) {
                Ok(valid) => {
                    self.ready.extend_from_slice(valid.as_bytes());
                    return;
                }
                Err(error) => {
                    let (valid, after) = rest.split_at(error.valid_up_to());
                    self.ready.extend_from_slice(valid);
                    match error.error_len() {
                        Some(skip) => {
                            self.ready.extend_from_slice("\u{fffd}".as_bytes());
                            rest = &after[skip..];
                        }
                        None if last => {
                            self.ready.extend_from_slice("\u{fffd}".as_bytes());
                            return;
                        }
                        None => {
                            self.carry = after.to_vec();
                            return;
                        }
                    }
                }
            }
        }
    }
}

impl<R: AsyncRead + Unpin> AsyncRead for AnsiLines<R> {
    fn poll_read(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        buf: &mut ReadBuf<'_>,
    ) -> Poll<io::Result<()>> {
        let this = self.get_mut();
        while this.sent == this.ready.len() && !this.eof {
            this.ready.clear();
            this.sent = 0;
            let mut scratch = [0u8; SCRATCH];
            let mut read = ReadBuf::new(&mut scratch);
            ready!(Pin::new(&mut this.inner).poll_read(cx, &mut read))?;
            let mut text = Vec::with_capacity(read.filled().len());
            if read.filled().is_empty() {
                this.eof = true;
                this.settle_cr(&mut text);
                // A last row with no line end is compared like any other, so
                // an unchanged one is still dropped, but no newline is owed
                // to a stream that has none left.
                if !this.row.is_empty() {
                    this.end_row(&mut text, false);
                }
            }
            for &byte in read.filled() {
                this.step(byte, &mut text);
            }
            let last = this.eof;
            this.decode(&text, last);
        }
        let pending = &this.ready[this.sent..];
        let count = pending.len().min(buf.remaining());
        buf.put_slice(&pending[..count]);
        this.sent += count;
        Poll::Ready(Ok(()))
    }
}

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

    use std::collections::VecDeque;

    use tokio::io::AsyncReadExt as _;

    /// Hands out one prepared chunk per read, so a test chooses where every
    /// read boundary falls.
    struct Chunks(VecDeque<Vec<u8>>);

    impl AsyncRead for Chunks {
        fn poll_read(
            mut self: Pin<&mut Self>,
            _cx: &mut Context<'_>,
            buf: &mut ReadBuf<'_>,
        ) -> Poll<io::Result<()>> {
            if let Some(chunk) = self.0.pop_front() {
                buf.put_slice(&chunk);
            }
            Poll::Ready(Ok(()))
        }
    }

    async fn filtered(chunks: &[&[u8]]) -> String {
        let reader = Chunks(chunks.iter().map(|chunk| chunk.to_vec()).collect());
        let mut text = String::new();
        AnsiLines::new(reader)
            .read_to_string(&mut text)
            .await
            .expect("the filter's output must be valid UTF-8");
        text
    }

    /// `n` rows of `r0`, `r1` and so on, each ended by a newline.
    fn rows(n: usize) -> String {
        (0..n).map(|row| format!("r{row}\n")).collect()
    }

    #[tokio::test]
    async fn a_sequence_split_across_two_reads_is_removed_whole() {
        assert_eq!(
            filtered(&[b"\x1b[3", b"1mred\x1b[0", b"m\n"]).await,
            "red\n"
        );
        assert_eq!(filtered(&[b"a\x1b]0;ti", b"tle\x07b\n"]).await, "ab\n");
        assert_eq!(
            filtered(&[b"a\x1b]8;;http://x\x1b", b"\\link\n"]).await,
            "alink\n"
        );
    }

    #[tokio::test]
    async fn a_cursor_move_and_a_bare_carriage_return_end_a_line() {
        assert_eq!(filtered(&[b"10%\r20%\r30%\n"]).await, "10%\n20%\n30%\n");
        assert_eq!(filtered(&[b"one\x1b[2;1Htwo\n"]).await, "one\ntwo\n");
        assert_eq!(filtered(&[b"gone\x1b[Kthere\n"]).await, "gone\nthere\n");
        // HPR and VPR move the cursor relative to it, like `C` and `B`.
        assert_eq!(filtered(&[b"a\x1b[1ab\x1b[1ec\n"]).await, "a\nb\nc\n");
    }

    #[tokio::test]
    async fn a_multibyte_character_split_across_two_reads_decodes_whole() {
        assert_eq!(
            filtered(&[b"na\xc3", b"\xafve \xe2\x82", b"\xac\n"]).await,
            "naïve €\n"
        );
    }

    #[tokio::test]
    async fn a_carriage_return_before_a_newline_is_just_the_newline() {
        assert_eq!(filtered(&[b"a\r", b"\nb\r\n\r\n"]).await, "a\nb\n\n");
    }

    #[tokio::test]
    async fn a_doubled_carriage_return_before_a_newline_is_just_the_newline() {
        // A tty with a full output queue writes `\r\r\n` where the program
        // wrote `\n`. A terminal draws that as one line break.
        assert_eq!(filtered(&[b"a\r\r\nb\n"]).await, "a\nb\n");
        assert_eq!(filtered(&[b"a\r", b"\r\nb\n"]).await, "a\nb\n");
        assert_eq!(filtered(&[b"a\r\r\r\nb\n"]).await, "a\nb\n");
    }

    #[tokio::test]
    async fn a_doubled_carriage_return_before_text_still_ends_the_line() {
        assert_eq!(filtered(&[b"a\r\rb\n"]).await, "a\nb\n");
        assert_eq!(filtered(&[b"a\r", b"\rb\n"]).await, "a\nb\n");
    }

    #[tokio::test]
    async fn a_redraw_leaves_no_blank_line_between_its_parts() {
        assert_eq!(filtered(&[b"a\n\r\x1b[Kb\n"]).await, "a\nb\n");
    }

    #[tokio::test]
    async fn a_repainted_frame_identical_to_the_last_writes_nothing() {
        assert_eq!(
            filtered(&[b"one\ntwo\n\x1b[2Aone\ntwo\n"]).await,
            "one\ntwo\n"
        );
    }

    #[tokio::test]
    async fn a_repainted_frame_writes_only_its_changed_rows() {
        assert_eq!(
            filtered(&[b"one\ntwo\n\x1b[2Aone\nTWO\n"]).await,
            "one\ntwo\nTWO\n"
        );
    }

    #[tokio::test]
    async fn a_frame_longer_than_the_one_it_replaces_writes_its_extra_rows() {
        assert_eq!(
            filtered(&[b"one\ntwo\n\x1b[2Aone\ntwo\nthree\n"]).await,
            "one\ntwo\nthree\n"
        );
    }

    #[tokio::test]
    async fn a_repainted_frame_split_across_reads_is_still_recognised() {
        assert_eq!(
            filtered(&[b"one\ntwo\n\x1b[2", b"Aone\ntw", b"o\n"]).await,
            "one\ntwo\n"
        );
    }

    #[tokio::test]
    async fn a_cursor_up_past_the_kept_rows_writes_every_row() {
        assert_eq!(
            filtered(&[b"one\ntwo\n\x1b[9Aone\ntwo\n"]).await,
            "one\ntwo\none\ntwo\n"
        );
    }

    #[tokio::test]
    async fn stacked_cursor_ups_open_one_window_past_the_kept_rows() {
        // Two cursor-ups of 2 over 3 kept rows reach past them together, so
        // the frame they name is written whole.
        assert_eq!(
            filtered(&[b"one\ntwo\nthree\n\x1b[2A\x1b[2Aone\ntwo\nthree\n"]).await,
            "one\ntwo\nthree\none\ntwo\nthree\n"
        );
    }

    #[tokio::test]
    async fn a_blind_window_stays_blind_until_it_ends() {
        // The window the first cursor-up opens is still open at the second,
        // so the row after it is written rather than dropped against an
        // unrelated kept row.
        assert_eq!(
            filtered(&[b"one\ntwo\n\x1b[3AX\n\x1b[1Aone\n"]).await,
            "one\ntwo\nX\none\n"
        );
        // Once the window drains, a cursor-up inside the kept rows dedups.
        assert_eq!(
            filtered(&[b"one\ntwo\n\x1b[3Ax\ny\nz\n\x1b[3Ax\ny\nz\n"]).await,
            "one\ntwo\nx\ny\nz\n"
        );
    }

    #[tokio::test]
    async fn a_repaint_inside_the_kept_rows_writes_nothing_at_the_cap() {
        let screen = rows(SCREEN_ROWS);
        let input = format!("{screen}\x1b[{SCREEN_ROWS}A{screen}");
        assert_eq!(filtered(&[input.as_bytes()]).await, screen);
    }

    #[tokio::test]
    async fn a_repaint_past_the_cap_writes_every_row() {
        let screen = rows(SCREEN_ROWS + 1);
        let input = format!("{screen}\x1b[{}A{screen}", SCREEN_ROWS + 1);
        let chunks: Vec<&[u8]> = input.as_bytes().chunks(512).collect();
        assert_eq!(filtered(&chunks).await, format!("{screen}{screen}"));
    }

    #[tokio::test]
    async fn a_row_past_the_kept_cap_goes_out_as_it_is_read() {
        let long: String = core::iter::repeat_n('x', SCREEN_ROW_BYTES * 3).collect();
        // A row that reaches the cap is never kept, so a repaint against it
        // is written like any other.
        let input = format!("{long}\n{long}\n\x1b[1A{long}\n");
        let chunks: Vec<&[u8]> = input.as_bytes().chunks(512).collect();
        assert_eq!(filtered(&chunks).await, format!("{long}\n{long}\n{long}\n"));
    }

    #[tokio::test]
    async fn a_repaint_that_ends_the_stream_drops_its_unchanged_last_row() {
        assert_eq!(
            filtered(&[b"one\ntwo\n\x1b[2Aone\ntwo"]).await,
            "one\ntwo\n"
        );
        // A last row that changed goes out, with no newline owed to it.
        assert_eq!(
            filtered(&[b"one\ntwo\n\x1b[2Aone\nTWO"]).await,
            "one\ntwo\nTWO"
        );
    }

    #[tokio::test]
    async fn whitespace_a_cursor_move_leaves_behind_is_not_part_of_the_next_row() {
        // The space sits on the row the cursor left, so the repaint below it
        // is still the unchanged `one` it is.
        assert_eq!(filtered(&[b"one\r\n \x1b[A\rone\r\n"]).await, "one\n");
        // A whitespace-only row a real newline ends is still a row.
        assert_eq!(filtered(&[b"a\n   \nb\n"]).await, "a\n   \nb\n");
    }

    #[tokio::test]
    async fn a_row_ended_by_an_erase_and_a_newline_is_one_screen_row() {
        // Each row is `text ESC [ K \n`: the erase ends it and the newline
        // ends the same screen row, so `ESC [ 2 A` names these two rows.
        assert_eq!(
            filtered(&[b"a\x1b[K\nb\x1b[K\n\x1b[2Aa\x1b[K\nb\x1b[K\n"]).await,
            "a\n\nb\n\n"
        );
        assert_eq!(
            filtered(&[b"a\x1b[K\r\nb\x1b[K\r\n\x1b[2Aa\x1b[K\r\nb\x1b[K\r\n"]).await,
            "a\n\nb\n\n"
        );
    }

    #[tokio::test]
    async fn a_changed_row_after_an_erase_and_a_newline_is_written() {
        // The first repainted row `b` replaces `a`, so it differs.
        assert_eq!(
            filtered(&[b"a\x1b[K\nb\x1b[K\n\x1b[2Ab\x1b[K\nc\x1b[K\n"]).await,
            "a\n\nb\n\nb\n\nc\n\n"
        );
    }

    #[tokio::test]
    async fn invalid_bytes_and_a_cut_short_end_become_replacement_characters() {
        assert_eq!(filtered(&[b"a\xffb\xc3"]).await, "a\u{fffd}b\u{fffd}");
    }

    #[tokio::test]
    async fn colour_and_other_escapes_leave_only_the_text() {
        assert_eq!(
            filtered(&[b"\x1b[1;32mok\x1b[0m \x1b(B\x1b=done\x1bPq\x1b\\\n"]).await,
            "ok done\n"
        );
    }

    #[tokio::test]
    async fn an_unterminated_string_sequence_gives_the_log_back() {
        let mut input = b"\x1b]0;".to_vec();
        input.extend(core::iter::repeat_n(b'x', STRING_LIMIT + 8));
        input.extend_from_slice(b"\nlater\n");
        let chunks: Vec<&[u8]> = input.chunks(512).collect();
        assert!(filtered(&chunks).await.ends_with("later\n"));
    }
}