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}