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}