1use core::fmt;
5use std::io::{self, BufRead, Read};
6
7use crate::text::read_full;
8
9pub const MAX_SHEBANG_BYTES: usize = 64 * 1024;
18
19const FIRST_CHUNK: usize = 512;
22
23const CHUNK: usize = 8 * 1024;
25
26#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
29#[non_exhaustive]
30pub enum ShlexError {
31 NoClosingQuotation,
33 NoEscapedCharacter,
35}
36
37impl fmt::Display for ShlexError {
38 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
39 f.write_str(match self {
40 Self::NoClosingQuotation => "No closing quotation",
41 Self::NoEscapedCharacter => "No escaped character",
42 })
43 }
44}
45
46impl std::error::Error for ShlexError {}
47
48pub fn shlex_split(s: &str) -> Result<Vec<String>, ShlexError> {
70 #[derive(Clone, Copy, PartialEq, Eq)]
71 enum State {
72 Whitespace,
74 Word,
76 Quote(char),
78 Escape { in_double: bool },
80 }
81 let is_ws = |c: char| matches!(c, ' ' | '\t' | '\r' | '\n');
82 let mut out = Vec::new();
83 let mut token = String::new();
84 let mut quoted = false;
86 let mut state = State::Whitespace;
87 for c in s.chars() {
88 state = match state {
89 State::Whitespace | State::Word if is_ws(c) => {
90 if state == State::Word && (!token.is_empty() || quoted) {
91 out.push(core::mem::take(&mut token));
92 quoted = false;
93 }
94 State::Whitespace
95 }
96 State::Whitespace | State::Word => match c {
97 '\\' => State::Escape { in_double: false },
98 '\'' | '"' => State::Quote(c),
99 _ => {
100 token.push(c);
101 State::Word
102 }
103 },
104 State::Quote(q) => {
105 quoted = true;
106 if c == q {
107 State::Word
108 } else if q == '"' && c == '\\' {
109 State::Escape { in_double: true }
110 } else {
111 token.push(c);
112 state
113 }
114 }
115 State::Escape { in_double } => {
116 if in_double && c != '"' && c != '\\' {
117 token.push('\\');
118 }
119 token.push(c);
120 if in_double {
121 State::Quote('"')
122 } else {
123 State::Word
124 }
125 }
126 };
127 }
128 match state {
129 State::Quote(_) => Err(ShlexError::NoClosingQuotation),
130 State::Escape { .. } => Err(ShlexError::NoEscapedCharacter),
131 State::Whitespace | State::Word => {
132 if !token.is_empty() || quoted {
133 out.push(token);
134 }
135 Ok(out)
136 }
137 }
138}
139
140const fn is_py_ascii_space(b: u8) -> bool {
142 matches!(b, b' ' | b'\t' | b'\n' | b'\r' | 0x0b | 0x0c | 0x1c..=0x1f)
143}
144
145fn shebang_split(line: &str) -> Vec<String> {
147 if !line.contains(['\'', '"', '\\']) {
148 return line
150 .split([' ', '\t', '\r', '\n'])
151 .filter(|t| !t.is_empty())
152 .map(str::to_owned)
153 .collect();
154 }
155 shlex_split(line).unwrap_or_else(|_| {
156 line.split(|c: char| u8::try_from(c).is_ok_and(is_py_ascii_space))
157 .filter(|t| !t.is_empty())
158 .map(str::to_owned)
159 .collect()
160 })
161}
162
163fn printable(line: &[u8]) -> Option<&str> {
170 if line
171 .iter()
172 .all(|&b| matches!(b, 0x20..=0x7e | b'\t' | b'\n' | b'\r' | 0x0b | 0x0c))
173 {
174 core::str::from_utf8(line).ok()
175 } else {
176 None
177 }
178}
179
180fn py_strip(s: &str) -> &str {
182 s.trim_matches(|c: char| u8::try_from(c).is_ok_and(is_py_ascii_space))
183}
184
185fn read_line_limited<R: BufRead + ?Sized>(
189 reader: &mut R,
190 out: &mut Vec<u8>,
191 limit: usize,
192) -> io::Result<bool> {
193 loop {
194 let available = match reader.fill_buf() {
195 Ok(buf) => buf,
196 Err(e) if e.kind() == io::ErrorKind::Interrupted => continue,
197 Err(e) => return Err(e),
198 };
199 if available.is_empty() {
200 return Ok(true);
201 }
202 let room = limit.saturating_sub(out.len());
203 if room == 0 {
204 return Ok(false);
206 }
207 let window = available.get(..room).unwrap_or(available);
208 if let Some(i) = window.iter().position(|&b| b == b'\n') {
209 out.extend_from_slice(window.get(..=i).unwrap_or(window));
210 reader.consume(i + 1);
211 return Ok(true);
212 }
213 let n = window.len();
214 out.extend_from_slice(window);
215 reader.consume(n);
216 }
217}
218
219fn with_line<R: BufRead + ?Sized, T>(
224 reader: &mut R,
225 limit: usize,
226 f: impl FnOnce(&[u8]) -> T,
227) -> io::Result<Option<(T, usize)>> {
228 let available = loop {
229 match reader.fill_buf() {
230 Ok(buf) => break buf,
231 Err(e) if e.kind() == io::ErrorKind::Interrupted => {}
232 Err(e) => return Err(e),
233 }
234 };
235 let window = available.get(..limit).unwrap_or(available);
236 if let Some(i) = window.iter().position(|&b| b == b'\n') {
237 let out = f(window.get(..=i).unwrap_or(window));
238 reader.consume(i + 1);
239 return Ok(Some((out, i + 1)));
240 }
241 let mut line = Vec::new();
242 if !read_line_limited(reader, &mut line, limit)? {
243 return Ok(None);
244 }
245 let used = line.len();
246 Ok(Some((f(&line), used)))
247}
248
249fn tokenize_line(line: &[u8]) -> Option<Vec<String>> {
251 printable(line).map(|text| shebang_split(py_strip(text)))
252}
253
254pub(crate) struct Source<'a, R> {
257 head: &'a [u8],
258 rest: R,
259 buf: Vec<u8>,
260 pos: usize,
261}
262
263impl<'a, R: Read> Source<'a, R> {
264 pub(crate) fn new(head: &'a [u8], rest: R) -> Self {
265 Self {
266 head,
267 rest,
268 buf: Vec::new(),
269 pos: 0,
270 }
271 }
272}
273
274impl<R: Read> Read for Source<'_, R> {
275 fn read(&mut self, out: &mut [u8]) -> io::Result<usize> {
276 let available = self.fill_buf()?;
277 let n = available.len().min(out.len());
278 for (o, a) in out.iter_mut().zip(available) {
279 *o = *a;
280 }
281 self.consume(n);
282 Ok(n)
283 }
284}
285
286impl<R: Read> BufRead for Source<'_, R> {
287 fn fill_buf(&mut self) -> io::Result<&[u8]> {
288 if !self.head.is_empty() {
289 return Ok(self.head);
290 }
291 if self.pos >= self.buf.len() {
292 let size = if self.buf.capacity() == 0 {
293 FIRST_CHUNK
294 } else {
295 CHUNK
296 };
297 self.buf.resize(size, 0);
298 let n = loop {
299 match self.rest.read(&mut self.buf) {
300 Ok(n) => break n.min(size),
301 Err(e) if e.kind() == io::ErrorKind::Interrupted => {}
302 Err(e) => {
303 self.buf.clear();
304 self.pos = 0;
305 return Err(e);
306 }
307 }
308 };
309 self.buf.truncate(n);
310 self.pos = 0;
311 }
312 Ok(self.buf.get(self.pos..).unwrap_or_default())
313 }
314
315 fn consume(&mut self, amt: usize) {
316 if self.head.is_empty() {
317 self.pos = self.pos.saturating_add(amt).min(self.buf.len());
318 } else {
319 self.head = self.head.get(amt..).unwrap_or_default();
320 }
321 }
322}
323
324pub(crate) fn parse_shebang_buf<R: BufRead + ?Sized>(reader: &mut R) -> io::Result<Vec<String>> {
327 let mut budget = MAX_SHEBANG_BYTES;
328 let mut magic = [0u8; 2];
329 if read_full(reader, &mut magic)? != 2 || magic != *b"#!" {
330 return Ok(Vec::new());
331 }
332 budget -= magic.len();
333 let Some((tokens, used)) = with_line(reader, budget, tokenize_line)? else {
334 return Ok(Vec::new());
335 };
336 budget = budget.saturating_sub(used);
337 let Some(mut cmd) = tokens else {
338 return Ok(Vec::new());
339 };
340 match cmd.as_slice() {
341 [env, flag, ..] if env == "/usr/bin/env" && flag == "-S" => {
342 cmd.drain(..2);
343 }
344 [env, ..] if env == "/usr/bin/env" => {
345 cmd.remove(0);
346 }
347 _ => {}
348 }
349 if matches!(cmd.as_slice(), [only] if only == "nix-shell") {
350 return parse_nix_shebang(reader, cmd, budget);
351 }
352 Ok(cmd)
353}
354
355fn parse_nix_shebang<R: BufRead + ?Sized>(
358 reader: &mut R,
359 mut cmd: Vec<String>,
360 mut budget: usize,
361) -> io::Result<Vec<String>> {
362 loop {
363 if budget < 2 {
364 return Ok(cmd);
365 }
366 let mut magic = [0u8; 2];
367 if read_full(reader, &mut magic)? != 2 || magic != *b"#!" {
368 return Ok(cmd);
369 }
370 budget -= 2;
371 let Some((tokens, used)) = with_line(reader, budget, tokenize_line)? else {
372 return Ok(cmd);
373 };
374 budget = budget.saturating_sub(used);
375 let Some(tokens) = tokens else {
376 return Ok(cmd);
377 };
378 for pair in tokens.windows(2) {
379 if let [flag, arg] = pair {
380 if flag == "-i" {
381 cmd = vec![arg.clone()];
382 }
383 }
384 }
385 }
386}
387
388pub fn parse_shebang<R: Read>(reader: R) -> io::Result<Vec<String>> {
419 parse_shebang_buf(&mut Source::new(&[], reader))
420}
421
422#[must_use]
430pub fn parse_shebang_bytes(content: &[u8]) -> Vec<String> {
431 let mut reader = content;
432 parse_shebang_buf(&mut reader).unwrap_or_default()
433}
434
435#[cfg(test)]
436mod tests {
437 use super::*;
438
439 const NONE: Vec<String> = Vec::new();
440
441 fn split(s: &str) -> Result<Vec<String>, ShlexError> {
442 shlex_split(s)
443 }
444
445 #[test]
446 fn shlex_golden() {
447 let ok: &[(&str, &[&str])] = &[
449 ("/bin/sh #foo", &["/bin/sh", "#foo"]),
450 (
451 "/usr/bin/env python # c",
452 &["/usr/bin/env", "python", "#", "c"],
453 ),
454 ("\"/usr/bin/my python\" -x", &["/usr/bin/my python", "-x"]),
455 ("a\\ b c", &["a b", "c"]),
456 ("\"a\\\\b\\q\"", &["a\\b\\q"]),
457 ("x\x0by", &["x\x0by"]),
458 ("x\ry", &["x", "y"]),
459 ("a '' b", &["a", "", "b"]),
460 ("''", &[""]),
461 ("a\"b c\"d", &["ab cd"]),
462 ("'a\\b'", &["a\\b"]),
463 ("\"a\\\"b\"", &["a\"b"]),
464 ("", &[]),
465 (" ", &[]),
466 ("\\'", &["'"]),
467 ];
468 for (input, expected) in ok {
469 let expected: Vec<String> = expected.iter().map(|s| (*s).to_owned()).collect();
470 assert_eq!(split(input), Ok(expected), "{input:?}");
471 }
472 assert_eq!(
473 split("unterminated \"q"),
474 Err(ShlexError::NoClosingQuotation)
475 );
476 assert_eq!(split("'"), Err(ShlexError::NoClosingQuotation));
477 assert_eq!(split("trail\\"), Err(ShlexError::NoEscapedCharacter));
478 assert_eq!(split("\"x\\"), Err(ShlexError::NoEscapedCharacter));
479 assert_eq!(
480 ShlexError::NoClosingQuotation.to_string(),
481 "No closing quotation"
482 );
483 assert_eq!(shebang_split("unterminated \"q"), ["unterminated", "\"q"]);
484 assert_eq!(shebang_split("trail\\"), ["trail\\"]);
485 assert_eq!(shebang_split("a\x0bb 'c"), ["a", "b", "'c"]);
486 }
487
488 #[test]
489 fn upstream_parse_shebang_cases() {
490 let cases: &[(&[u8], &[&str])] = &[
492 (b"", &[]),
493 (b"#!/usr/bin/python", &["/usr/bin/python"]),
494 (b"#!/usr/bin/env python", &["python"]),
495 (b"#! /usr/bin/python", &["/usr/bin/python"]),
496 (b"#!/usr/bin/foo python", &["/usr/bin/foo", "python"]),
497 (b"#!\"/path/with spaces/x\" y", &["/path/with spaces/x", "y"]),
498 (b"#!/path'with/quotes y", &["/path'with/quotes", "y"]),
499 (b"#! /path'with/quotes y ", &["/path'with/quotes", "y"]),
500 (b"#! /usr/bin/env nix-shell\n#! nix-shell -i bash -p python", &["bash"]),
501 (b"#! /usr/bin/env nix-shell\n#! nix-shell -i python -p coreutils", &["python"]),
502 (b"#! /usr/bin/env nix-shell\n#! nix-shell -p coreutils -i python", &["python"]),
503 (b"#! /usr/bin/env nix-shell\n#! nix-shell -p coreutils\n#! nix-shell -i python", &["python"]),
504 (b"#! /usr/bin/env nix-shell\n#!nix-shell -p coreutils\n#!nix-shell -i python", &["python"]),
505 (b"#! /usr/bin/env nix-shell\n#!\xf9\x93\x01\x42\xcd", &["nix-shell"]),
506 (b"#! /usr/bin/env nix-shell\n#!\x00\x00\x00\x00", &["nix-shell"]),
507 (b"#! /usr/bin/nix-shell", &["/usr/bin/nix-shell"]),
508 (b"#! /usr/bin/env nix-shell", &["nix-shell"]),
509 (b"#! /usr/bin/env nix-shell non-portable-argument", &["nix-shell", "non-portable-argument"]),
510 (b"#! /usr/bin/env nix-shell\n#! nix-shell -i", &["nix-shell"]),
511 (
512 b"#!/usr/bin/env nix-shell\n#!nix-shell --argstr x \"a -i python3 p\"\n#!nix-shell -p hello\n#!nix-shell -i bash\n#!nix-shell --argstr y \"b -i runhaskell q\"",
513 &["bash"],
514 ),
515 (b"\xf9\x93\x01\x42\xcd", &[]),
516 (b"#!\xf9\x93\x01\x42\xcd", &[]),
517 (b"#!\x00\x00\x00\x00", &[]),
518 (b"#!/usr/bin/env -S python -u", &["python", "-u"]),
519 (b"#!/usr/bin/env", &[]),
520 (b"#!/usr/bin/env -S", &[]),
521 ];
522 for (input, expected) in cases {
523 assert_eq!(
524 parse_shebang_bytes(input),
525 *expected,
526 "{:?}",
527 String::from_utf8_lossy(input)
528 );
529 let expected: Vec<String> = expected.iter().map(|s| (*s).to_owned()).collect();
530 assert_eq!(parse_shebang(*input).ok(), Some(expected));
531 }
532 }
533
534 #[test]
535 fn printable_and_strip_rules() {
536 assert_eq!(
537 parse_shebang_bytes(b"#!/bin/sh\x0b-x\x0c\r\n"),
538 ["/bin/sh\x0b-x"]
539 );
540 assert_eq!(parse_shebang_bytes(b"#!/bin/sh\r\n"), ["/bin/sh"]);
541 assert_eq!(parse_shebang_bytes(b"#!/bin/sh\x01\n"), NONE);
542 assert_eq!(parse_shebang_bytes("#!/bin/sh é\n".as_bytes()), NONE);
543 assert_eq!(parse_shebang_bytes(b"#!"), NONE);
544 assert_eq!(parse_shebang_bytes(b"#"), NONE);
545 assert_eq!(parse_shebang_bytes(b"#! \n"), NONE);
546 assert_eq!(parse_shebang_bytes(b"#!env python"), ["env", "python"]);
548 assert_eq!(
549 parse_shebang_bytes(b"#!/usr/bin/env -S"),
550 Vec::<String>::new()
551 );
552 assert_eq!(
554 parse_shebang_bytes(b"#!/usr/bin/env -S nix-shell\n#!x -i zsh\n"),
555 ["zsh"]
556 );
557 }
558
559 #[test]
560 fn line_limit() {
561 let mut long = b"#!/bin/sh ".to_vec();
562 long.resize(MAX_SHEBANG_BYTES + 10, b'a');
563 assert_eq!(parse_shebang_bytes(&long), NONE);
564 let mut fits = b"#!/bin/sh ".to_vec();
566 fits.resize(MAX_SHEBANG_BYTES, b'a');
567 assert_eq!(parse_shebang_bytes(&fits).len(), 2);
568 fits.push(b'\n');
570 assert_eq!(parse_shebang_bytes(&fits), NONE);
571 }
572
573 #[test]
574 fn bounded_reads_on_endless_input() {
575 struct Endless {
577 served: usize,
578 }
579 impl Read for Endless {
580 fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
581 for (i, b) in buf.iter_mut().enumerate() {
582 *b = b"#!".get(self.served + i).copied().unwrap_or(b'a');
583 }
584 self.served += buf.len();
585 Ok(buf.len())
586 }
587 }
588 struct Cycle {
590 data: Vec<u8>,
591 pos: usize,
592 }
593 impl Read for Cycle {
594 fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
595 for b in buf.iter_mut() {
596 *b = self.data[self.pos % self.data.len()];
597 self.pos += 1;
598 }
599 Ok(buf.len())
600 }
601 }
602
603 let mut endless = Endless { served: 0 };
604 assert!(parse_shebang(&mut endless).is_ok_and(|v| v.is_empty()));
605 assert!(
606 endless.served <= MAX_SHEBANG_BYTES + CHUNK,
607 "served {}",
608 endless.served
609 );
610
611 let mut nix = Cycle {
613 data: b"#!/usr/bin/env nix-shell\n".to_vec(),
614 pos: 0,
615 };
616 let cmd = parse_shebang(&mut nix).unwrap_or_default();
617 assert_eq!(cmd, ["nix-shell"]);
618 assert!(nix.pos <= MAX_SHEBANG_BYTES + CHUNK, "served {}", nix.pos);
619 }
620
621 #[test]
622 fn source_reads_head_then_rest() {
623 let mut src = Source::new(b"#!/usr/bin/env py", &b"thon3 -u\n#! more"[..]);
624 assert_eq!(
625 parse_shebang_buf(&mut src).unwrap_or_default(),
626 ["python3", "-u"]
627 );
628 let mut rest = String::new();
629 assert!(src.read_to_string(&mut rest).is_ok());
630 assert_eq!(rest, "#! more");
631 }
632
633 #[test]
634 fn read_errors_propagate() {
635 struct Failing;
636 impl Read for Failing {
637 fn read(&mut self, _: &mut [u8]) -> io::Result<usize> {
638 Err(io::Error::other("boom"))
639 }
640 }
641 assert!(parse_shebang(Failing).is_err());
642 let mut src = Source::new(b"#!/bin/sh", Failing);
643 assert!(parse_shebang_buf(&mut src).is_err());
644 }
645}