Skip to main content

crumbkit_process/run/
output.rs

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