Skip to main content

rustty/vt/
parser.rs

1//! The bounded, incremental VT parser state machine.
2
3use super::event::{
4    CsiDispatch, EscDispatch, Handler, OscDispatch, StringDispatch, StringKind, StringTermination,
5};
6use super::params::Params;
7use super::utf8::{PushResult, Utf8Decoder};
8
9const DEFAULT_MAX_STRING_BYTES: usize = 4 * 1024;
10const DEFAULT_MAX_PARAMETERS: usize = 32;
11const DEFAULT_MAX_INTERMEDIATES: usize = 16;
12const MAX_PARAMETER_BYTES_PER_VALUE: usize = 64;
13
14#[derive(Clone, Copy, Debug, PartialEq, Eq)]
15enum State {
16    Ground,
17    Escape,
18    EscapeIntermediate,
19    CsiEntry,
20    CsiParameter,
21    CsiIntermediate,
22    CsiIgnore,
23    DcsEntry,
24    DcsParameter,
25    DcsIntermediate,
26    DcsPassthrough,
27    DcsIgnore,
28    String,
29    StringEscape,
30}
31
32/// Limits controlling memory retained while parsing untrusted input.
33#[derive(Clone, Copy, Debug, PartialEq, Eq)]
34pub struct ParserOptions {
35    /// Maximum number of bytes retained for one OSC/DCS/APC/PM/SOS payload.
36    ///
37    /// Zero means that payload bytes are discarded while the parser still
38    /// waits for the string terminator.
39    pub max_string_bytes: usize,
40    /// Maximum number of semicolon-delimited CSI parameters.
41    ///
42    /// A parameter is also limited to 64 bytes of raw digits/subparameters, so
43    /// a sequence cannot evade this bound by sending one enormous value. Zero
44    /// means that non-empty parameter data is discarded.
45    pub max_parameters: usize,
46    /// Maximum number of ESC/CSI intermediate bytes retained.
47    ///
48    /// Zero means that intermediate bytes cause the sequence to be marked
49    /// truncated.
50    pub max_intermediates: usize,
51}
52
53impl Default for ParserOptions {
54    fn default() -> Self {
55        Self {
56            max_string_bytes: DEFAULT_MAX_STRING_BYTES,
57            max_parameters: DEFAULT_MAX_PARAMETERS,
58            max_intermediates: DEFAULT_MAX_INTERMEDIATES,
59        }
60    }
61}
62
63/// An incremental parser for VT control streams.
64///
65/// `Parser` retains only its current state and bounded control-sequence data.
66/// It does not retain any input slice after [`Parser::advance`] returns and can
67/// be moved between threads as ordinary owned Rust state. A handler must have
68/// exclusive mutable access while an input chunk is processed.
69#[derive(Debug)]
70pub struct Parser {
71    options: ParserOptions,
72    state: State,
73    utf8: Utf8Decoder,
74    intermediates: Vec<u8>,
75    private_markers: Vec<u8>,
76    parameters: Vec<u8>,
77    parameter_count: usize,
78    parameter_bytes: usize,
79    sequence_truncated: bool,
80    string_kind: Option<StringKind>,
81    string_final: Option<u8>,
82    string_data: Vec<u8>,
83    string_truncated: bool,
84}
85
86impl Default for Parser {
87    fn default() -> Self {
88        Self::new()
89    }
90}
91
92impl Parser {
93    /// Creates a parser with conservative default limits.
94    #[must_use]
95    pub fn new() -> Self {
96        Self::with_options(ParserOptions::default())
97    }
98
99    /// Creates a parser with caller-selected buffering limits.
100    #[must_use]
101    pub fn with_options(options: ParserOptions) -> Self {
102        Self {
103            options,
104            state: State::Ground,
105            utf8: Utf8Decoder::new(),
106            intermediates: Vec::new(),
107            private_markers: Vec::new(),
108            parameters: Vec::new(),
109            parameter_count: 0,
110            parameter_bytes: 0,
111            sequence_truncated: false,
112            string_kind: None,
113            string_final: None,
114            string_data: Vec::new(),
115            string_truncated: false,
116        }
117    }
118
119    /// Returns the limits used by this parser.
120    #[must_use]
121    pub const fn options(&self) -> ParserOptions {
122        self.options
123    }
124
125    /// Feeds a chunk of bytes to the parser.
126    ///
127    /// A chunk may end in the middle of a UTF-8 scalar, ESC/CSI sequence, or
128    /// control string. Events are delivered synchronously and borrow parser
129    /// storage only for the duration of the handler callback.
130    pub fn advance<H: Handler + ?Sized>(&mut self, handler: &mut H, bytes: &[u8]) {
131        for &byte in bytes {
132            let mut reprocess = true;
133            while reprocess {
134                reprocess = self.process_byte(handler, byte);
135            }
136        }
137    }
138
139    /// Finishes the current stream.
140    ///
141    /// An incomplete UTF-8 scalar produces one U+FFFD replacement character.
142    /// Incomplete or cancelled control sequences are discarded, including
143    /// unterminated control strings. The parser is left in the ground state
144    /// and may immediately receive another stream.
145    pub fn finish<H: Handler + ?Sized>(&mut self, handler: &mut H) {
146        if self.utf8.finish() {
147            handler.print('\u{FFFD}');
148        }
149        self.clear_sequence();
150    }
151
152    /// Discards all pending parser state without dispatching an event.
153    pub fn reset(&mut self) {
154        self.utf8.reset();
155        self.clear_sequence();
156    }
157
158    fn process_byte<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) -> bool {
159        if byte == 0x7F && self.state != State::Ground {
160            return false;
161        }
162        match self.state {
163            State::Ground => self.process_ground(handler, byte),
164            State::Escape => {
165                self.process_escape(handler, byte);
166                false
167            }
168            State::EscapeIntermediate => {
169                self.process_escape_intermediate(handler, byte);
170                false
171            }
172            State::CsiEntry => {
173                self.process_csi_entry(handler, byte);
174                false
175            }
176            State::CsiParameter => {
177                self.process_csi_parameter(handler, byte);
178                false
179            }
180            State::CsiIntermediate => {
181                self.process_csi_intermediate(handler, byte);
182                false
183            }
184            State::CsiIgnore => {
185                self.process_csi_ignore(handler, byte);
186                false
187            }
188            State::DcsEntry => {
189                self.process_dcs_entry(handler, byte);
190                false
191            }
192            State::DcsParameter => {
193                self.process_dcs_parameter(handler, byte);
194                false
195            }
196            State::DcsIntermediate => {
197                self.process_dcs_intermediate(handler, byte);
198                false
199            }
200            State::DcsPassthrough | State::String => {
201                self.process_string(handler, byte);
202                false
203            }
204            State::DcsIgnore => {
205                self.process_dcs_ignore(handler, byte);
206                false
207            }
208            State::StringEscape => self.process_string_escape(handler, byte),
209        }
210    }
211
212    fn process_ground<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) -> bool {
213        if self.utf8.is_pending() {
214            match self.utf8.push(byte) {
215                PushResult::NeedMore => return false,
216                PushResult::Character(character) => {
217                    self.dispatch_decoded_character(handler, character);
218                    return false;
219                }
220                PushResult::Invalid => {
221                    handler.print('\u{FFFD}');
222                    return false;
223                }
224                PushResult::InvalidAndReprocess => {
225                    handler.print('\u{FFFD}');
226                    return true;
227                }
228            }
229        }
230
231        match byte {
232            0x00..=0x1F | 0x7F => {
233                self.process_ground_control(handler, byte);
234                false
235            }
236            0x20..=0x7E => {
237                handler.print(char::from(byte));
238                false
239            }
240            0x80..=0x9F => {
241                self.process_ground_c1(handler, byte);
242                false
243            }
244            _ => match self.utf8.push(byte) {
245                PushResult::NeedMore => false,
246                PushResult::Character(character) => {
247                    self.dispatch_decoded_character(handler, character);
248                    false
249                }
250                PushResult::Invalid | PushResult::InvalidAndReprocess => {
251                    handler.print('\u{FFFD}');
252                    false
253                }
254            },
255        }
256    }
257
258    fn dispatch_decoded_character<H: Handler + ?Sized>(
259        &mut self,
260        handler: &mut H,
261        character: char,
262    ) {
263        let value = u32::from(character);
264        if value <= 0x1F || value == 0x7F {
265            let byte = u8::try_from(value).expect("C0 control code point fits in one byte");
266            self.process_ground_control(handler, byte);
267        } else if value <= 0x9F {
268            let byte = u8::try_from(value).expect("C1 control code point fits in one byte");
269            self.process_ground_c1(handler, byte);
270        } else {
271            handler.print(character);
272        }
273    }
274
275    fn process_ground_control<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
276        match byte {
277            0x1B => self.start_escape(),
278            0x7F => {}
279            _ => handler.execute(byte),
280        }
281    }
282
283    fn process_ground_c1<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
284        match byte {
285            0x90 => self.start_string(StringKind::Dcs),
286            0x98 => self.start_string(StringKind::Sos),
287            0x9B => self.start_csi(),
288            0x9D => self.start_string(StringKind::Osc),
289            0x9E => self.start_string(StringKind::Pm),
290            0x9F => self.start_string(StringKind::Apc),
291            _ => handler.execute(byte),
292        }
293    }
294
295    fn start_c1_sequence(&mut self, byte: u8) -> bool {
296        match byte {
297            0x90 => self.start_string(StringKind::Dcs),
298            0x98 => self.start_string(StringKind::Sos),
299            0x9B => self.start_csi(),
300            0x9D => self.start_string(StringKind::Osc),
301            0x9E => self.start_string(StringKind::Pm),
302            0x9F => self.start_string(StringKind::Apc),
303            _ => return false,
304        }
305        true
306    }
307
308    fn process_active_c1<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) -> bool {
309        if self.start_c1_sequence(byte) {
310            true
311        } else if (0x80..=0x9F).contains(&byte) {
312            handler.execute(byte);
313            true
314        } else {
315            false
316        }
317    }
318
319    fn process_escape<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
320        if Self::is_cancel(byte) {
321            self.clear_sequence();
322            return;
323        }
324        if self.process_active_c1(handler, byte) {
325            return;
326        }
327        match byte {
328            0x1B => self.start_escape(),
329            b'[' => self.start_csi(),
330            b']' => self.start_string(StringKind::Osc),
331            b'P' => self.start_string(StringKind::Dcs),
332            b'X' => self.start_string(StringKind::Sos),
333            b'^' => self.start_string(StringKind::Pm),
334            b'_' => self.start_string(StringKind::Apc),
335            0x20..=0x2F => {
336                self.add_intermediate(byte);
337                self.state = State::EscapeIntermediate;
338            }
339            0x30..=0x7E => self.dispatch_esc(handler, byte),
340            _ => handler.execute(byte),
341        }
342    }
343
344    fn process_escape_intermediate<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
345        if Self::is_cancel(byte) {
346            self.clear_sequence();
347            return;
348        }
349        if self.process_active_c1(handler, byte) {
350            return;
351        }
352        match byte {
353            0x1B => self.start_escape(),
354            0x20..=0x2F => self.add_intermediate(byte),
355            0x30..=0x7E => self.dispatch_esc(handler, byte),
356            _ => handler.execute(byte),
357        }
358    }
359
360    fn process_csi_entry<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
361        if Self::is_cancel(byte) {
362            self.clear_sequence();
363            return;
364        }
365        if self.process_active_c1(handler, byte) {
366            return;
367        }
368        match byte {
369            0x1B => self.start_escape(),
370            0x30..=0x3F => {
371                if is_private_marker(byte) && self.parameters.is_empty() {
372                    self.add_private_marker(byte);
373                } else {
374                    self.add_parameter(byte);
375                }
376                self.state = if self.sequence_truncated {
377                    State::CsiIgnore
378                } else {
379                    State::CsiParameter
380                };
381            }
382            0x20..=0x2F => {
383                self.add_intermediate(byte);
384                self.state = if self.sequence_truncated {
385                    State::CsiIgnore
386                } else {
387                    State::CsiIntermediate
388                };
389            }
390            0x40..=0x7E => self.dispatch_csi(handler, byte),
391            _ => handler.execute(byte),
392        }
393    }
394
395    fn process_csi_parameter<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
396        if Self::is_cancel(byte) {
397            self.clear_sequence();
398            return;
399        }
400        if self.process_active_c1(handler, byte) {
401            return;
402        }
403        match byte {
404            0x1B => self.start_escape(),
405            0x30..=0x3F => {
406                self.add_parameter(byte);
407                if self.sequence_truncated {
408                    self.state = State::CsiIgnore;
409                }
410            }
411            0x20..=0x2F => {
412                self.add_intermediate(byte);
413                self.state = if self.sequence_truncated {
414                    State::CsiIgnore
415                } else {
416                    State::CsiIntermediate
417                };
418            }
419            0x40..=0x7E => self.dispatch_csi(handler, byte),
420            _ => handler.execute(byte),
421        }
422    }
423
424    fn process_csi_intermediate<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
425        if Self::is_cancel(byte) {
426            self.clear_sequence();
427            return;
428        }
429        if self.process_active_c1(handler, byte) {
430            return;
431        }
432        match byte {
433            0x1B => self.start_escape(),
434            0x20..=0x2F => self.add_intermediate(byte),
435            0x40..=0x7E => self.dispatch_csi(handler, byte),
436            0x30..=0x3F => {
437                self.sequence_truncated = true;
438                self.state = State::CsiIgnore;
439            }
440            _ => handler.execute(byte),
441        }
442    }
443
444    fn process_csi_ignore<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
445        if Self::is_cancel(byte) {
446            self.clear_sequence();
447            return;
448        }
449        if self.process_active_c1(handler, byte) {
450            return;
451        }
452        match byte {
453            0x1B => self.start_escape(),
454            0x40..=0x7E => self.dispatch_csi(handler, byte),
455            _ => handler.execute(byte),
456        }
457    }
458
459    fn process_dcs_entry<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
460        if Self::is_cancel(byte) {
461            self.clear_sequence();
462            return;
463        }
464        if byte == 0x9C {
465            self.dispatch_string(handler, StringTermination::St);
466            return;
467        }
468        if self.start_c1_sequence(byte) {
469            return;
470        }
471        match byte {
472            0x1B => self.state = State::StringEscape,
473            0x30..=0x3F => {
474                if is_private_marker(byte) && self.parameters.is_empty() {
475                    self.add_private_marker(byte);
476                } else {
477                    self.add_parameter(byte);
478                }
479                self.state = if self.sequence_truncated {
480                    State::DcsIgnore
481                } else {
482                    State::DcsParameter
483                };
484            }
485            0x20..=0x2F => {
486                self.add_intermediate(byte);
487                self.state = if self.sequence_truncated {
488                    State::DcsIgnore
489                } else {
490                    State::DcsIntermediate
491                };
492            }
493            0x40..=0x7E => self.string_final = Some(byte),
494            0x00..=0x1F => handler.execute(byte),
495            _ => {
496                self.sequence_truncated = true;
497                self.state = State::DcsIgnore;
498            }
499        }
500        if self.string_final.is_some() {
501            self.state = State::DcsPassthrough;
502        }
503    }
504
505    fn process_dcs_parameter<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
506        if Self::is_cancel(byte) {
507            self.clear_sequence();
508            return;
509        }
510        if byte == 0x9C {
511            self.dispatch_string(handler, StringTermination::St);
512            return;
513        }
514        if self.start_c1_sequence(byte) {
515            return;
516        }
517        match byte {
518            0x1B => self.state = State::StringEscape,
519            0x30..=0x3F => {
520                self.add_parameter(byte);
521                if self.sequence_truncated {
522                    self.state = State::DcsIgnore;
523                }
524            }
525            0x20..=0x2F => {
526                self.add_intermediate(byte);
527                self.state = if self.sequence_truncated {
528                    State::DcsIgnore
529                } else {
530                    State::DcsIntermediate
531                };
532            }
533            0x40..=0x7E => {
534                self.string_final = Some(byte);
535                self.state = State::DcsPassthrough;
536            }
537            0x00..=0x1F => handler.execute(byte),
538            _ => {
539                self.sequence_truncated = true;
540                self.state = State::DcsIgnore;
541            }
542        }
543    }
544
545    fn process_dcs_intermediate<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
546        if Self::is_cancel(byte) {
547            self.clear_sequence();
548            return;
549        }
550        if byte == 0x9C {
551            self.dispatch_string(handler, StringTermination::St);
552            return;
553        }
554        if self.start_c1_sequence(byte) {
555            return;
556        }
557        match byte {
558            0x1B => self.state = State::StringEscape,
559            0x20..=0x2F => self.add_intermediate(byte),
560            0x40..=0x7E => {
561                self.string_final = Some(byte);
562                self.state = State::DcsPassthrough;
563            }
564            0x00..=0x1F => handler.execute(byte),
565            _ => {
566                self.sequence_truncated = true;
567                self.state = State::DcsIgnore;
568            }
569        }
570    }
571
572    fn process_dcs_ignore<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
573        if Self::is_cancel(byte) {
574            self.clear_sequence();
575            return;
576        }
577        if byte == 0x9C {
578            self.dispatch_string(handler, StringTermination::St);
579            return;
580        }
581        if self.start_c1_sequence(byte) {
582            return;
583        }
584        match byte {
585            0x1B => self.state = State::StringEscape,
586            0x40..=0x7E if self.string_final.is_none() => {
587                self.string_final = Some(byte);
588            }
589            0x00..=0x1F | 0x80..=0x9F => handler.execute(byte),
590            _ => {}
591        }
592    }
593
594    fn process_string<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) {
595        if Self::is_cancel(byte) {
596            self.clear_sequence();
597            return;
598        }
599        if self.start_c1_sequence(byte) {
600            return;
601        }
602        if byte == 0x1B {
603            self.state = State::StringEscape;
604            return;
605        }
606        if byte == 0x9C {
607            self.dispatch_string(handler, StringTermination::St);
608            return;
609        }
610        if self.string_kind == Some(StringKind::Osc) && byte == 0x07 {
611            self.dispatch_string(handler, StringTermination::Bell);
612            return;
613        }
614        if byte < 0x20 || (0x80..=0x9F).contains(&byte) {
615            handler.execute(byte);
616            return;
617        }
618        self.append_string(byte);
619    }
620
621    fn process_string_escape<H: Handler + ?Sized>(&mut self, handler: &mut H, byte: u8) -> bool {
622        if Self::is_cancel(byte) {
623            self.clear_sequence();
624            return false;
625        }
626        if self.start_c1_sequence(byte) {
627            return false;
628        }
629        if byte == 0x9C {
630            self.dispatch_string(handler, StringTermination::St);
631            return false;
632        }
633        match byte {
634            b'\\' => {
635                self.dispatch_string(handler, StringTermination::St);
636                false
637            }
638            0x1B => false,
639            _ => {
640                self.clear_sequence();
641                self.start_escape();
642                true
643            }
644        }
645    }
646
647    fn dispatch_esc<H: Handler + ?Sized>(&mut self, handler: &mut H, final_byte: u8) {
648        let event = EscDispatch {
649            final_byte,
650            intermediates: &self.intermediates,
651            truncated: self.sequence_truncated,
652        };
653        handler.esc_dispatch(event);
654        self.clear_sequence();
655    }
656
657    fn dispatch_csi<H: Handler + ?Sized>(&mut self, handler: &mut H, final_byte: u8) {
658        let event = CsiDispatch {
659            final_byte,
660            private_markers: &self.private_markers,
661            params: Params::new(&self.parameters),
662            intermediates: &self.intermediates,
663            truncated: self.sequence_truncated,
664        };
665        handler.csi_dispatch(event);
666        self.clear_sequence();
667    }
668
669    fn dispatch_string<H: Handler + ?Sized>(
670        &mut self,
671        handler: &mut H,
672        termination: StringTermination,
673    ) {
674        let Some(kind) = self.string_kind else {
675            self.clear_sequence();
676            return;
677        };
678        if kind == StringKind::Osc {
679            let event = OscDispatch {
680                data: &self.string_data,
681                termination,
682                truncated: self.string_truncated,
683            };
684            handler.osc_dispatch(event);
685        } else {
686            let event = StringDispatch {
687                kind,
688                final_byte: self.string_final,
689                private_markers: &self.private_markers,
690                params: Params::new(&self.parameters),
691                intermediates: &self.intermediates,
692                data: &self.string_data,
693                termination,
694                truncated: self.string_truncated || self.sequence_truncated,
695            };
696            handler.string_dispatch(event);
697        }
698        self.clear_sequence();
699    }
700
701    fn start_escape(&mut self) {
702        self.clear_sequence();
703        self.state = State::Escape;
704    }
705
706    fn start_csi(&mut self) {
707        self.clear_sequence();
708        self.state = State::CsiEntry;
709    }
710
711    fn start_string(&mut self, kind: StringKind) {
712        self.clear_sequence();
713        self.string_kind = Some(kind);
714        self.state = if kind == StringKind::Dcs {
715            State::DcsEntry
716        } else {
717            State::String
718        };
719    }
720
721    fn add_intermediate(&mut self, byte: u8) {
722        if self.intermediates.len() < self.options.max_intermediates {
723            self.intermediates.push(byte);
724        } else {
725            self.sequence_truncated = true;
726        }
727    }
728
729    fn add_private_marker(&mut self, byte: u8) {
730        if self.private_markers.len() < self.options.max_parameters {
731            self.private_markers.push(byte);
732        } else {
733            self.sequence_truncated = true;
734        }
735    }
736
737    fn add_parameter(&mut self, byte: u8) {
738        if self.sequence_truncated {
739            return;
740        }
741        if self.parameter_count == 0 {
742            self.parameter_count = 1;
743        }
744        if byte == b';' {
745            self.parameter_count = self.parameter_count.saturating_add(1);
746            self.parameter_bytes = 0;
747        } else {
748            if self.parameter_bytes >= MAX_PARAMETER_BYTES_PER_VALUE {
749                self.sequence_truncated = true;
750                return;
751            }
752            self.parameter_bytes += 1;
753        }
754        let byte_limit = self
755            .options
756            .max_parameters
757            .saturating_mul(MAX_PARAMETER_BYTES_PER_VALUE);
758        if self.parameter_count > self.options.max_parameters || self.parameters.len() >= byte_limit
759        {
760            self.sequence_truncated = true;
761            return;
762        }
763        self.parameters.push(byte);
764    }
765
766    fn append_string(&mut self, byte: u8) {
767        if self.string_data.len() < self.options.max_string_bytes {
768            self.string_data.push(byte);
769        } else {
770            self.string_truncated = true;
771        }
772    }
773
774    fn is_cancel(byte: u8) -> bool {
775        byte == 0x18 || byte == 0x1A
776    }
777
778    fn clear_sequence(&mut self) {
779        self.state = State::Ground;
780        self.utf8.reset();
781        self.intermediates.clear();
782        self.private_markers.clear();
783        self.parameters.clear();
784        self.parameter_count = 0;
785        self.parameter_bytes = 0;
786        self.sequence_truncated = false;
787        self.string_kind = None;
788        self.string_final = None;
789        self.string_data.clear();
790        self.string_truncated = false;
791    }
792}
793
794const fn is_private_marker(byte: u8) -> bool {
795    byte >= 0x3C && byte <= 0x3F
796}