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}