Skip to main content

crumbkit_process/run/
output.rs

1//! What a run keeps of each output stream.
2
3use std::fmt;
4use std::process::Stdio;
5use std::sync::Arc;
6use std::time::Instant;
7
8use crate::LineQueue;
9
10#[cfg(test)]
11mod tests;
12
13/// The bytes that a tail keeps beyond its limit before it drops the oldest,
14/// so a long stream is not moved on every read.
15const SLACK: usize = 8 * 1024;
16
17/// What a run keeps of one output stream of the child.
18#[derive(Clone, Debug, Default)]
19#[non_exhaustive]
20pub enum Capture {
21    /// The stream goes to the null device, and the run keeps nothing.
22    #[default]
23    Discard,
24    /// The stream goes to the tool's own stream, and the run keeps nothing.
25    ///
26    /// A child in a group of its own is in the background of the terminal.
27    /// It can write there unless the terminal has `tostop` set, and it is
28    /// stopped when it reads. A stopped child holds a run with no deadline. For a step that
29    /// the person answers, use [`Scope::Child`](crate::Scope::Child) with
30    /// [`Input::Inherit`](crate::Input::Inherit), so the child stays in the
31    /// tool's foreground group and the tool carries on when it ends. Ctrl-C
32    /// then reaches both.
33    Inherit,
34    /// The run keeps the stream's first `limit` bytes. A stream longer than
35    /// `limit` bytes is over its limit, and `over` says what the run does
36    /// then.
37    Whole {
38        /// The most bytes that the run keeps.
39        limit: usize,
40        /// What the run does when the stream passes `limit` bytes.
41        over: OverLimit,
42    },
43    /// The run reads the whole stream and keeps its last `limit` bytes.
44    Tail {
45        /// The most bytes that the run keeps.
46        limit: usize,
47    },
48    /// The run splits the stream into lines on each `end` byte and pushes
49    /// each line, without that byte, to `queue` while the child runs. A
50    /// last line with no end is pushed when the stream ends. The run
51    /// keeps no bytes in its [`Captured`].
52    ///
53    /// The first time the stream passes `total` bytes, the stream is over
54    /// its limit, and `over` says what the run does then. No line is pushed
55    /// after that. A line that passes `line` bytes does the same with
56    /// [`LongLine::Over`], and with [`LongLine::Skip`] the run drops that
57    /// line alone and goes on.
58    ///
59    /// Each queue serves one run, which ends it when it returns.
60    Lines {
61        /// The queue that the run pushes each line to, from
62        /// [`line_queue`](crate::line_queue).
63        queue: LineQueue,
64        /// The most bytes of one line, without its end.
65        line: usize,
66        /// The most bytes of the whole stream, line ends and skipped lines
67        /// included.
68        total: usize,
69        /// What the run does when the stream passes a limit.
70        over: OverLimit,
71        /// What a line longer than `line` bytes does.
72        long: LongLine,
73        /// The byte that ends a line, such as `b'\n'` or `0`.
74        end: u8,
75    },
76}
77
78/// What a line longer than the limit of one line does to a stream
79/// delivered as lines.
80#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
81#[non_exhaustive]
82pub enum LongLine {
83    /// The stream is over its limit, and its `over` policy applies.
84    #[default]
85    Over,
86    /// The run drops that line up to its end and delivers the next line.
87    /// [`Captured::long_line`] tells that it dropped at least one line, and
88    /// [`Captured::over_limit`] stays false unless the total limit passes.
89    Skip,
90}
91
92/// What a run does when a stream that it keeps whole or as lines passes
93/// its limit.
94#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
95#[non_exhaustive]
96pub enum OverLimit {
97    /// The run stops the child with its escalation and ends as
98    /// [`Stopped(OverLimit)`](crate::StopReason::OverLimit).
99    #[default]
100    Stop,
101    /// The run reads the rest of the stream and drops it, so the child
102    /// never waits on a full pipe and runs to its end.
103    Sink,
104}
105
106impl Capture {
107    /// Returns the standard stream that the child gets for this capture.
108    pub(super) fn stdio(&self) -> Stdio {
109        match self {
110            Self::Discard => Stdio::null(),
111            Self::Inherit => Stdio::inherit(),
112            Self::Whole { .. } | Self::Tail { .. } | Self::Lines { .. } => Stdio::piped(),
113        }
114    }
115
116    /// Tells the queue of a stream delivered as lines that the run began
117    /// to stop its child, so a full queue drops a line instead of waiting.
118    pub(super) fn stopping(&self) {
119        if let Self::Lines { queue, .. } = self {
120            queue.stopping();
121        }
122    }
123
124    /// Tells the queue of a stream delivered as lines that the child has
125    /// been reaped, so a full queue drops a line once `deadline` has
126    /// passed.
127    pub(super) fn drain_until(&self, deadline: Instant) {
128        if let Self::Lines { queue, .. } = self {
129            queue.drain_until(deadline);
130        }
131    }
132
133    /// Ends the queue of a stream delivered as lines, so the caller's
134    /// waits end once the queue is empty.
135    pub(super) fn end(&self) {
136        if let Self::Lines { queue, .. } = self {
137            queue.end();
138        }
139    }
140}
141
142/// What a run kept of one output stream.
143#[derive(Clone, Debug, Default, PartialEq, Eq)]
144pub struct Captured {
145    bytes: Vec<u8>,
146    over_limit: bool,
147    long_line: bool,
148}
149
150impl Captured {
151    /// Returns the kept bytes: the first bytes of a stream kept whole, the
152    /// last bytes of a tail, and nothing of a discarded stream.
153    #[must_use]
154    pub fn bytes(&self) -> &[u8] {
155        &self.bytes
156    }
157
158    /// Returns the kept bytes, consuming what was captured.
159    #[must_use]
160    pub fn into_bytes(self) -> Vec<u8> {
161        self.bytes
162    }
163
164    /// Returns true when the stream was longer than its limit, so the kept
165    /// bytes, or the lines delivered, are not all of it.
166    #[must_use]
167    pub const fn over_limit(&self) -> bool {
168        self.over_limit
169    }
170
171    /// Returns true when the run acted on a line of a stream delivered as
172    /// lines that passed the limit of one line: that line took the stream
173    /// over its limit with [`LongLine::Over`], or the run dropped it with
174    /// [`LongLine::Skip`]. A line does not count when the bytes that first
175    /// take it over its own limit also take the stream over the total limit,
176    /// and only [`Captured::over_limit`] tells.
177    #[must_use]
178    pub const fn long_line(&self) -> bool {
179        self.long_line
180    }
181}
182
183/// The caller's function that receives each chunk of one output stream.
184#[derive(Clone)]
185pub(super) struct OutputCopy(Arc<CopyFn>);
186
187/// The caller's function, which the settings hold and a reader thread calls.
188type CopyFn = dyn Fn(&[u8]) + Send + Sync;
189
190impl OutputCopy {
191    /// Wraps the caller's function.
192    pub(super) fn new(copy: impl Fn(&[u8]) + Send + Sync + 'static) -> Self {
193        Self(Arc::new(copy))
194    }
195
196    /// Gives `chunk` to the caller's function.
197    pub(super) fn send(&self, chunk: &[u8]) {
198        (self.0)(chunk);
199    }
200}
201
202impl fmt::Debug for OutputCopy {
203    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
204        f.write_str("OutputCopy(..)")
205    }
206}
207
208/// Keeps the bytes of one stream as its [`Capture`] says.
209#[derive(Debug)]
210pub(super) struct Keeper {
211    capture: Capture,
212    kept: Captured,
213    /// The bytes of the line that a stream delivered as lines has not yet
214    /// ended.
215    line: Vec<u8>,
216    /// The bytes that a stream delivered as lines has read in all.
217    read: usize,
218    /// False once the caller has dropped its side of the line queue.
219    listening: bool,
220    /// True while a stream delivered as lines drops the rest of a long line.
221    skipping: bool,
222}
223
224impl Keeper {
225    /// Returns a keeper that keeps what `capture` asks for.
226    pub(super) fn new(capture: &Capture) -> Self {
227        Self {
228            capture: capture.clone(),
229            kept: Captured::default(),
230            line: Vec::new(),
231            read: 0,
232            listening: true,
233            skipping: false,
234        }
235    }
236
237    /// Keeps what it should of `bytes`, which the stream yielded next, and
238    /// returns true when these bytes take a stream whose policy stops the
239    /// child over its limit for the first time.
240    pub(super) fn add(&mut self, bytes: &[u8]) -> bool {
241        let kept = &mut self.kept;
242        match self.capture {
243            Capture::Discard | Capture::Inherit => false,
244            Capture::Lines {
245                line,
246                total,
247                over,
248                long,
249                end,
250                ..
251            } => self.add_lines(bytes, line, total, long, end) && over == OverLimit::Stop,
252            Capture::Whole { limit, over } => {
253                let room = limit.saturating_sub(kept.bytes.len());
254                kept.bytes
255                    .extend_from_slice(&bytes[..room.min(bytes.len())]);
256                if bytes.len() <= room || kept.over_limit {
257                    return false;
258                }
259                kept.over_limit = true;
260                over == OverLimit::Stop
261            }
262            Capture::Tail { limit } => {
263                kept.bytes.extend_from_slice(bytes);
264                if kept.bytes.len() > limit.saturating_add(SLACK) {
265                    kept.bytes.drain(..kept.bytes.len() - limit);
266                    kept.over_limit = true;
267                }
268                false
269            }
270        }
271    }
272
273    /// Splits `bytes` into lines and pushes each complete line, and
274    /// returns true when these bytes take the stream over `line` bytes for
275    /// one line or `total` bytes in all for the first time.
276    fn add_lines(
277        &mut self,
278        bytes: &[u8],
279        line: usize,
280        total: usize,
281        long: LongLine,
282        end: u8,
283    ) -> bool {
284        if self.kept.over_limit {
285            return false;
286        }
287        let mut rest = bytes;
288        loop {
289            let (piece, ended) = match rest.iter().position(|byte| *byte == end) {
290                Some(at) => (&rest[..at], true),
291                None => (rest, false),
292            };
293            self.read = self.read.saturating_add(piece.len() + usize::from(ended));
294            if !self.skipping {
295                self.line.extend_from_slice(piece);
296            }
297            let over_line = self.line.len() > line;
298            if self.read > total || (over_line && long == LongLine::Over) {
299                self.kept.over_limit = true;
300                self.kept.long_line |= over_line && self.read <= total;
301                self.line = Vec::new();
302                return true;
303            }
304            if over_line {
305                self.skipping = true;
306                self.kept.long_line = true;
307                self.line = Vec::new();
308            }
309            if !ended {
310                return false;
311            }
312            if self.skipping {
313                self.skipping = false;
314            } else {
315                self.push_line();
316            }
317            rest = &rest[piece.len() + 1..];
318            if rest.is_empty() {
319                return false;
320            }
321        }
322    }
323
324    /// Pushes the line kept so far to the queue of a stream delivered as
325    /// lines, unless the caller has dropped its side.
326    fn push_line(&mut self) {
327        let line = std::mem::take(&mut self.line);
328        if let Capture::Lines { queue, .. } = &self.capture
329            && self.listening
330        {
331            self.listening = queue.push(line);
332        }
333    }
334
335    /// Returns what was kept once the stream has ended. A stream delivered
336    /// as lines pushes its last line when that line has no end byte.
337    pub(super) fn finish(mut self) -> Captured {
338        if matches!(self.capture, Capture::Lines { .. })
339            && !self.kept.over_limit
340            && !self.line.is_empty()
341        {
342            self.push_line();
343        }
344        if let Capture::Tail { limit } = self.capture
345            && self.kept.bytes.len() > limit
346        {
347            self.kept.bytes.drain(..self.kept.bytes.len() - limit);
348            self.kept.over_limit = true;
349        }
350        self.kept
351    }
352}