Skip to main content

crumbkit_process/run/
output.rs

1//! What a run keeps of each output stream.
2
3use std::process::Stdio;
4use std::time::Instant;
5
6use crate::LineQueue;
7
8#[cfg(test)]
9mod tests;
10
11/// The bytes that a tail keeps beyond its limit before it drops the oldest,
12/// so a long stream is not moved on every read.
13const SLACK: usize = 8 * 1024;
14
15/// What a run keeps of one output stream of the child.
16#[derive(Clone, Debug, Default)]
17#[non_exhaustive]
18pub enum Capture {
19    /// The stream goes to the null device, and the run keeps nothing.
20    #[default]
21    Discard,
22    /// The run keeps the stream's first `limit` bytes. A stream longer than
23    /// `limit` bytes is over its limit, and `over` says what the run does
24    /// then.
25    Whole {
26        /// The most bytes that the run keeps.
27        limit: usize,
28        /// What the run does when the stream passes `limit` bytes.
29        over: OverLimit,
30    },
31    /// The run reads the whole stream and keeps its last `limit` bytes.
32    Tail {
33        /// The most bytes that the run keeps.
34        limit: usize,
35    },
36    /// The run splits the stream into lines on each newline and pushes
37    /// each line, without its newline, to `queue` while the child runs. A
38    /// last line with no newline is pushed when the stream ends. The run
39    /// keeps no bytes in its [`Captured`].
40    ///
41    /// The first time one line passes `line` bytes or the stream passes
42    /// `total` bytes, the stream is over its limit, and `over` says what
43    /// the run does then. No line is pushed after that.
44    ///
45    /// Each queue serves one run, which ends it when it returns.
46    Lines {
47        /// The queue that the run pushes each line to, from
48        /// [`line_queue`](crate::line_queue).
49        queue: LineQueue,
50        /// The most bytes of one line, without its newline.
51        line: usize,
52        /// The most bytes of the whole stream, newlines included.
53        total: usize,
54        /// What the run does when the stream passes a limit.
55        over: OverLimit,
56    },
57}
58
59/// What a run does when a stream that it keeps whole or as lines passes
60/// its limit.
61#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
62#[non_exhaustive]
63pub enum OverLimit {
64    /// The run stops the child with its escalation and ends as
65    /// [`Stopped(OverLimit)`](crate::StopReason::OverLimit).
66    #[default]
67    Stop,
68    /// The run reads the rest of the stream and drops it, so the child
69    /// never waits on a full pipe and runs to its end.
70    Sink,
71}
72
73impl Capture {
74    /// Returns the standard stream that the child gets for this capture.
75    pub(super) fn stdio(&self) -> Stdio {
76        match self {
77            Self::Discard => Stdio::null(),
78            Self::Whole { .. } | Self::Tail { .. } | Self::Lines { .. } => Stdio::piped(),
79        }
80    }
81
82    /// Tells the queue of a stream delivered as lines that the run began
83    /// to stop its child, so a full queue drops a line instead of waiting.
84    pub(super) fn stopping(&self) {
85        if let Self::Lines { queue, .. } = self {
86            queue.stopping();
87        }
88    }
89
90    /// Tells the queue of a stream delivered as lines that the child has
91    /// been reaped, so a full queue drops a line once `deadline` has
92    /// passed.
93    pub(super) fn drain_until(&self, deadline: Instant) {
94        if let Self::Lines { queue, .. } = self {
95            queue.drain_until(deadline);
96        }
97    }
98
99    /// Ends the queue of a stream delivered as lines, so the caller's
100    /// waits end once the queue is empty.
101    pub(super) fn end(&self) {
102        if let Self::Lines { queue, .. } = self {
103            queue.end();
104        }
105    }
106}
107
108/// What a run kept of one output stream.
109#[derive(Clone, Debug, Default, PartialEq, Eq)]
110pub struct Captured {
111    bytes: Vec<u8>,
112    over_limit: bool,
113    long_line: bool,
114}
115
116impl Captured {
117    /// Returns the kept bytes: the first bytes of a stream kept whole, the
118    /// last bytes of a tail, and nothing of a discarded stream.
119    #[must_use]
120    pub fn bytes(&self) -> &[u8] {
121        &self.bytes
122    }
123
124    /// Returns the kept bytes, consuming what was captured.
125    #[must_use]
126    pub fn into_bytes(self) -> Vec<u8> {
127        self.bytes
128    }
129
130    /// Returns true when the stream was longer than its limit, so the kept
131    /// bytes, or the lines delivered, are not all of it.
132    #[must_use]
133    pub const fn over_limit(&self) -> bool {
134        self.over_limit
135    }
136
137    /// Returns true when a stream delivered as lines went over its limit
138    /// because one line passed the limit of one line.
139    #[must_use]
140    pub const fn long_line(&self) -> bool {
141        self.long_line
142    }
143}
144
145/// Keeps the bytes of one stream as its [`Capture`] says.
146#[derive(Debug)]
147pub(super) struct Keeper {
148    capture: Capture,
149    kept: Captured,
150    /// The bytes of the line that a stream delivered as lines has not yet
151    /// ended.
152    line: Vec<u8>,
153    /// The bytes that a stream delivered as lines has read in all.
154    read: usize,
155    /// False once the caller has dropped its side of the line queue.
156    listening: bool,
157}
158
159impl Keeper {
160    /// Returns a keeper that keeps what `capture` asks for.
161    pub(super) fn new(capture: &Capture) -> Self {
162        Self {
163            capture: capture.clone(),
164            kept: Captured::default(),
165            line: Vec::new(),
166            read: 0,
167            listening: true,
168        }
169    }
170
171    /// Keeps what it should of `bytes`, which the stream yielded next, and
172    /// returns true when these bytes take a stream whose policy stops the
173    /// child over its limit for the first time.
174    pub(super) fn add(&mut self, bytes: &[u8]) -> bool {
175        let kept = &mut self.kept;
176        match self.capture {
177            Capture::Discard => false,
178            Capture::Lines {
179                line, total, over, ..
180            } => self.add_lines(bytes, line, total) && over == OverLimit::Stop,
181            Capture::Whole { limit, over } => {
182                let room = limit.saturating_sub(kept.bytes.len());
183                kept.bytes
184                    .extend_from_slice(&bytes[..room.min(bytes.len())]);
185                if bytes.len() <= room || kept.over_limit {
186                    return false;
187                }
188                kept.over_limit = true;
189                over == OverLimit::Stop
190            }
191            Capture::Tail { limit } => {
192                kept.bytes.extend_from_slice(bytes);
193                if kept.bytes.len() > limit.saturating_add(SLACK) {
194                    kept.bytes.drain(..kept.bytes.len() - limit);
195                    kept.over_limit = true;
196                }
197                false
198            }
199        }
200    }
201
202    /// Splits `bytes` into lines and pushes each complete line, and
203    /// returns true when these bytes take the stream over the limit of
204    /// `line` bytes for one line or `total` bytes in all for the first time.
205    fn add_lines(&mut self, bytes: &[u8], line: usize, total: usize) -> bool {
206        if self.kept.over_limit {
207            return false;
208        }
209        let mut rest = bytes;
210        loop {
211            let (piece, ended) = match rest.iter().position(|byte| *byte == b'\n') {
212                Some(at) => (&rest[..at], true),
213                None => (rest, false),
214            };
215            self.read = self.read.saturating_add(piece.len() + usize::from(ended));
216            self.line.extend_from_slice(piece);
217            let long = self.line.len() > line;
218            if self.read > total || long {
219                self.kept.over_limit = true;
220                self.kept.long_line = long && self.read <= total;
221                self.line = Vec::new();
222                return true;
223            }
224            if !ended {
225                return false;
226            }
227            self.push_line();
228            rest = &rest[piece.len() + 1..];
229            if rest.is_empty() {
230                return false;
231            }
232        }
233    }
234
235    /// Pushes the line kept so far to the queue of a stream delivered as
236    /// lines, unless the caller has dropped its side.
237    fn push_line(&mut self) {
238        let line = std::mem::take(&mut self.line);
239        if let Capture::Lines { queue, .. } = &self.capture
240            && self.listening
241        {
242            self.listening = queue.push(line);
243        }
244    }
245
246    /// Returns what was kept once the stream has ended. A stream delivered
247    /// as lines pushes its last line when that line has no newline.
248    pub(super) fn finish(mut self) -> Captured {
249        if matches!(self.capture, Capture::Lines { .. })
250            && !self.kept.over_limit
251            && !self.line.is_empty()
252        {
253            self.push_line();
254        }
255        if let Capture::Tail { limit } = self.capture
256            && self.kept.bytes.len() > limit
257        {
258            self.kept.bytes.drain(..self.kept.bytes.len() - limit);
259            self.kept.over_limit = true;
260        }
261        self.kept
262    }
263}