Skip to main content

muskitty_html5_parser/
lib.rs

1//! MusKitty HTML Parser
2//!
3//! Implements the WHATWG HTML parsing algorithm.
4//!
5//! # Architecture
6//!
7//! The parser follows the standard two-stage model (§13.2.1):
8//! 1. **Tokenization** ([`tokenizer`]) — consumes a stream of code points
9//!    and emits tokens.
10//! 2. **Tree construction** ([`parser`]) — consumes tokens and builds the DOM.
11//!
12//! # References
13//!
14//! - WHATWG HTML Living Standard: <https://html.spec.whatwg.org/multipage/parsing.html>
15//! - WPT test suite: <https://github.com/web-platform-tests/wpt/tree/master/html/syntax/parsing>
16
17pub mod error;
18pub mod parser;
19pub mod serialize;
20
21use std::cell::RefCell;
22use std::rc::Rc;
23
24use crate::error::ParseError;
25use crate::parser::{HtmlTreeConstructor, InsertionMode};
26use muskitty_dom::{append_child, drain_children, remove_child, Node};
27use muskitty_html5_tokenizer::{HtmlTokenizer, State, Token, Tokenizer};
28
29/// 默认输入大小上限:64 MiB(参考 Chromium 的输入保护策略)。
30pub const MAX_INPUT_BYTES: usize = 64 * 1024 * 1024;
31
32/// 默认 open elements 栈深度上限:512(参考 Chromium `kMaxHTMLParserDOMDepth`、
33/// WebKit `maxDOMTreeDepth = 500`)。
34pub const MAX_OPEN_ELEMENTS: usize = 512;
35
36/// 解析结果:包含 Document 与累积的解析错误。
37pub struct ParseOutput {
38    /// Document 节点。可能为部分构建(若触发 `InputTooLarge` 则反映
39    /// 截止点的 DOM 状态;若触发 `DomDepthExceeded` 则某些深嵌套元素
40    /// 未被插入)。
41    pub document: Rc<RefCell<Node>>,
42    /// 解析过程中累积的错误(含 `InputTooLarge` / `DomDepthExceeded`)。
43    pub errors: Vec<ParseError>,
44}
45
46/// Parse an HTML string into a Document node.
47///
48/// Implements the two-stage model of §13.2.1: construct a tokenizer over
49/// `input`, construct a tree constructor targeting a fresh Document, then
50/// feed every emitted token to the tree constructor until EOF.
51///
52/// 向后兼容入口:使用默认限制(`MAX_INPUT_BYTES` / `MAX_OPEN_ELEMENTS`),
53/// 丢弃累积的解析错误。需要错误信息的调用方应使用 [`parse_with_limits`]。
54pub fn parse(input: &str) -> Rc<RefCell<Node>> {
55    parse_with_limits(input, MAX_INPUT_BYTES, MAX_OPEN_ELEMENTS).document
56}
57
58/// 解析 HTML 字符串,自定义输入大小与栈深度限制。
59///
60/// # 行为
61/// - 输入字节数超 `max_bytes`:立即停止解析,返回空 Document +
62///   `ParseError::InputTooLarge`。
63/// - open elements 栈深度超 `max_open_elements`:跳过当前 push(解析继续)
64///   + `ParseError::DomDepthExceeded`。
65///
66/// 参考 WHATWG §13.2.6 错误恢复语义:parser 不应因资源限制而崩溃。
67pub fn parse_with_limits(input: &str, max_bytes: usize, max_open_elements: usize) -> ParseOutput {
68    let document = Node::new_document();
69
70    // §1: 输入大小检查(参考 Chromium 输入保护策略)。
71    if input.len() > max_bytes {
72        return ParseOutput {
73            document,
74            errors: vec![ParseError::InputTooLarge {
75                actual: input.len(),
76                limit: max_bytes,
77            }],
78        };
79    }
80
81    let mut tokenizer = HtmlTokenizer::new(input);
82    let mut constructor = HtmlTreeConstructor::new(document.clone());
83    constructor.max_open_elements = max_open_elements;
84    run_tokenizer_loop(&mut constructor, &mut tokenizer);
85    // §13.2.7 "stop parsing" step 4: pop all nodes off the stack of open
86    // elements. This fires the maybe-clone hook (§4.10.10) for any open
87    // <option> elements, mirroring their content into <selectedcontent>.
88    constructor.finalize();
89    ParseOutput {
90        document,
91        errors: constructor.errors,
92    }
93}
94
95/// Drive a tokenizer to completion, feeding every token to the tree
96/// constructor (§13.2.1 two-stage model). Shared by full-document parsing
97/// ([`parse_with_limits`]) and fragment parsing ([`parse_fragment`]).
98///
99/// The tokenizer's initial state is set by the caller (Data for documents,
100/// `fragment_tokenizer_state` for fragments). Returns after EOF.
101fn run_tokenizer_loop(constructor: &mut HtmlTreeConstructor, tokenizer: &mut dyn Tokenizer) {
102    loop {
103        // §13.2.5.42: The markup declaration open state needs to know
104        // whether the adjusted current node is in foreign content to decide
105        // between CDATA section state (foreign) and bogus comment state
106        // (HTML) when encountering `<![CDATA[`. Sync the flag before each
107        // token is produced so the tokenizer sees the post-previous-token
108        // open elements stack state.
109        let in_foreign = constructor.current_node_in_foreign_content();
110        tokenizer.set_foreign_content(in_foreign);
111        let Some(token) = tokenizer.next_token() else {
112            break;
113        };
114        constructor.run(&token, tokenizer);
115        if matches!(token, Token::EOF) {
116            break;
117        }
118    }
119}
120
121/// Parse an HTML fragment (§13.4.2) and return the resulting
122/// `DocumentFragment`.
123///
124/// `context_element` determines the parsing rules: its namespace/name drive
125/// the insertion-mode reset (§13.2.6.4.1), its name selects the tokenizer's
126/// initial state (§13.4.2 step 4), and a `<template>` context enters
127/// InTemplate mode (§13.4.2 step 5).
128///
129/// The algorithm creates a fresh Document, appends a synthetic `<html>` root
130/// directly to the returned fragment, parses the input into that root, then
131/// unwraps the root's children into the fragment (html5lib `getFragment()`:
132/// `openElements[0].reparentChildren(fragment)`).
133pub fn parse_fragment(input: &str, context_element: &Rc<RefCell<Node>>) -> Rc<RefCell<Node>> {
134    let doc = Node::new_document();
135    let fragment = Node::new_document_fragment(&doc);
136    if input.len() > MAX_INPUT_BYTES {
137        return fragment;
138    }
139    let context = match recreate_context_element(context_element, &doc) {
140        Some(c) => c,
141        None => {
142            // F-9(审计 H-M2):上下文非 Element(如对 Text/Comment/Document
143            // 调用 [`set_inner_html`])。此前 `expect` panic——脚本桥接入后
144            // 即远程 DoS。按 §13.4.2 "follow the rules for the context
145            // element" 精神兜底:取中性流内容容器 `<div>` 作上下文(Data
146            // 状态 + InBody 插入模式),保证输入内容按 body 语义完整解析,
147            // 优雅降级不中断。(`<html>` 上下文会落入 BeforeHead 模式、
148            // 隐式 head/body 吞掉内容,故不采用。)
149            Node::new_element_html("div", vec![], &doc)
150        }
151    };
152    let mut constructor = HtmlTreeConstructor::new(doc);
153    constructor.fragment_context = Some(context.clone());
154    constructor.fragment_root = Some(fragment.clone());
155
156    // §13.4.2 step 11: the root `<html>` is appended to the fragment (not
157    // the Document), so the parsed content lands directly under the fragment.
158    let root = Node::new_element_html("html", vec![], &constructor.document);
159    let _ = append_child(&fragment, root.clone());
160    constructor.open_elements.push(root.clone());
161
162    // §13.4.2 step 5: template context enters the template insertion modes.
163    if is_html_template(context_element) {
164        constructor
165            .template_insertion_modes
166            .push(InsertionMode::InTemplate);
167    }
168    // §13.4.2 step 7: set the insertion mode via the reset algorithm (the
169    // fragment context substitutes for the stack root at `is_last`).
170    crate::parser::dispatch::reset_insertion_mode(&mut constructor);
171
172    let mut tokenizer = HtmlTokenizer::new(input);
173    if let Some(state) = fragment_tokenizer_state(context_element) {
174        tokenizer.set_state(state);
175    }
176    // Note: the tokenizer's appropriate end tag name is deliberately NOT set
177    // to the context element's name. Per html5lib, it is only set when the
178    // tree constructor processes a real start tag; in fragment parsing the
179    // input is raw content of the context (e.g. `</script>` inside a script
180    // context is literal text, not a closing tag — tests4.dat #9).
181
182    run_tokenizer_loop(&mut constructor, &mut tokenizer);
183    constructor.finalize();
184
185    // Unwrap: move the root's children into the fragment, then drop the root.
186    let children = drain_children(&root);
187    for child in children {
188        let _ = append_child(&fragment, child);
189    }
190    let _ = remove_child(&fragment, &root);
191    fragment
192}
193
194/// §13.4.2 step 6: create a copy of the context element in the new
195/// Document (same namespace / prefix / local name / attributes).
196///
197/// F-9: 上下文非 Element 时返回 `None`(调用方按 `<html>` 上下文兜底),
198/// 不再 panic。
199fn recreate_context_element(
200    context_element: &Rc<RefCell<Node>>,
201    doc: &Rc<RefCell<Node>>,
202) -> Option<Rc<RefCell<Node>>> {
203    let borrowed = context_element.borrow();
204    let e = borrowed.kind.as_element()?;
205    let attrs = e.attributes.clone();
206    Some(match e.namespace {
207        muskitty_dom::Namespace::Html => Node::new_element_html(&e.local_name, attrs, doc),
208        ns => Node::new_element_ns(e.local_name.clone(), ns, e.prefix.clone(), attrs, doc),
209    })
210}
211
212/// Whether the context element is an HTML `<template>` (§13.4.2 step 5).
213fn is_html_template(context_element: &Rc<RefCell<Node>>) -> bool {
214    context_element
215        .borrow()
216        .kind
217        .as_element()
218        .is_some_and(|e| e.namespace == muskitty_dom::Namespace::Html && e.local_name == "template")
219}
220
221/// §13.4.2 step 4: the tokenizer state selected by the context element.
222/// `None` → Data state.
223///
224/// The rules name HTML elements (a "title element" is an HTML-namespace
225/// element), so a foreign `<title>` (e.g. `svg title` context) stays in
226/// Data state and its `</title>` is a real end tag (foreign-fragment.dat #8).
227fn fragment_tokenizer_state(context_element: &Rc<RefCell<Node>>) -> Option<State> {
228    let borrowed = context_element.borrow();
229    // F-9: 非 Element 上下文 → Data 状态(调用方已按 `<html>` 兜底)。
230    let e = borrowed.kind.as_element()?;
231    if e.namespace != muskitty_dom::Namespace::Html {
232        return None;
233    }
234    match e.local_name.as_str() {
235        "title" | "textarea" => Some(State::RCDATA),
236        "style" | "xmp" | "iframe" | "noembed" | "noframes" => Some(State::RAWTEXT),
237        "script" => Some(State::ScriptData),
238        "plaintext" => Some(State::PLAINTEXT),
239        // "noscript" with the scripting flag enabled → RAWTEXT; our parser
240        // runs with scripting disabled, so noscript stays in Data.
241        _ => None,
242    }
243}
244
245#[cfg(test)]
246mod tests {
247    use super::*;
248
249    #[test]
250    fn parse_returns_document_for_normal_input() {
251        // 向后兼容入口:正常 HTML 返回 Document
252        let doc = parse("<div>hello</div>");
253        // Document 应有子节点
254        assert!(!doc.borrow().child_nodes().is_empty());
255    }
256
257    #[test]
258    fn input_too_large_returns_empty_document_and_error() {
259        // 1 MiB 输入,限制为 1 KB
260        let huge: String = "x".repeat(1024 * 1024);
261        let out = parse_with_limits(&huge, 1024, MAX_OPEN_ELEMENTS);
262        assert!(matches!(
263            out.errors.first(),
264            Some(ParseError::InputTooLarge { actual, limit })
265                if *actual == 1024 * 1024 && *limit == 1024
266        ));
267        // 空 Document(未开始解析)
268        assert!(out.document.borrow().child_nodes().is_empty());
269    }
270
271    #[test]
272    fn dom_depth_exceeded_skips_push_but_continues() {
273        // 嵌套 100 层 div,限制为 50
274        let html = "<div>".repeat(100);
275        let out = parse_with_limits(&html, MAX_INPUT_BYTES, 50);
276        // 应至少触发一次 DomDepthExceeded 错误
277        assert!(
278            out.errors
279                .iter()
280                .any(|e| matches!(e, ParseError::DomDepthExceeded { .. })),
281            "expected DomDepthExceeded error"
282        );
283        // 但解析应继续,Document 非空(前 50 层已构建)
284        assert!(!out.document.borrow().child_nodes().is_empty());
285    }
286
287    #[test]
288    fn normal_input_within_limits_no_errors() {
289        let out = parse_with_limits("<div></div>", MAX_INPUT_BYTES, MAX_OPEN_ELEMENTS);
290        assert!(out.errors.is_empty(), "expected no errors");
291    }
292
293    // ── Fragment parsing (§13.4.2) ────────────────────────────────────
294
295    fn context_element(local_name: &str) -> Rc<RefCell<Node>> {
296        let doc = Node::new_document();
297        Node::new_element_html(local_name, vec![], &doc)
298    }
299
300    /// Element local name for elements, node_name otherwise (e.g. "#text").
301    fn fragment_child_names(fragment: &Rc<RefCell<Node>>) -> Vec<String> {
302        fragment
303            .borrow()
304            .child_nodes()
305            .iter()
306            .map(|n| {
307                let borrowed = n.borrow();
308                borrowed
309                    .kind
310                    .as_element()
311                    .map(|e| e.local_name.clone())
312                    .unwrap_or_else(|| borrowed.node_name.clone())
313            })
314            .collect()
315    }
316
317    #[test]
318    fn parse_fragment_returns_document_fragment() {
319        let frag = parse_fragment("<b>x</b>", &context_element("div"));
320        assert_eq!(
321            frag.borrow().node_type,
322            muskitty_dom::NodeType::DocumentFragment
323        );
324        assert_eq!(fragment_child_names(&frag), vec!["b"]);
325    }
326
327    #[test]
328    fn parse_fragment_div_context_uses_in_body() {
329        let frag = parse_fragment("<span>hi</span>", &context_element("div"));
330        assert_eq!(fragment_child_names(&frag), vec!["span"]);
331        // The synthetic <html> root is unwrapped — no stray <html> in output.
332        assert!(fragment_child_names(&frag).iter().all(|n| n != "html"));
333    }
334
335    #[test]
336    fn parse_fragment_table_context_uses_in_table() {
337        // InTable: <tr> switches to InTableBody which wraps it in <tbody>,
338        // so the fragment's single top-level child is the <tbody> (matching
339        // the WPT expected `| <tbody>` / `|   <tr>`).
340        let frag = parse_fragment("<tr><td>x</td></tr>", &context_element("table"));
341        assert_eq!(fragment_child_names(&frag), vec!["tbody"]);
342    }
343
344    #[test]
345    fn parse_fragment_title_context_uses_rcdata() {
346        // title context → RCDATA: markup inside is consumed as text, so the
347        // fragment holds a single Text node with the literal input.
348        let frag = parse_fragment("<b>bold</b>", &context_element("title"));
349        assert_eq!(fragment_child_names(&frag), vec!["#text"]);
350        assert_eq!(
351            crate::serialize::inner_html(&frag),
352            "&lt;b&gt;bold&lt;/b&gt;"
353        );
354    }
355
356    #[test]
357    fn parse_fragment_script_context_uses_script_data() {
358        // script context → ScriptData: the input is raw text (only
359        // "</script" would terminate it), so the fragment is one Text node.
360        let frag = parse_fragment("if (a<b) {}", &context_element("script"));
361        assert_eq!(fragment_child_names(&frag), vec!["#text"]);
362        assert_eq!(crate::serialize::inner_html(&frag), "if (a&lt;b) {}");
363    }
364
365    // —— F-9: 非 Element 上下文兜底(不再 panic)——
366
367    #[test]
368    fn parse_fragment_text_context_degrades_not_panics() {
369        // F-9:Text 节点作为上下文 → 按 `<html>`(Data 状态 + InBody)
370        // 兜底解析,产出正常 fragment。
371        let doc = Node::new_document();
372        let text = Node::new_text("hello", &doc);
373        let frag = parse_fragment("<b>x</b>", &text);
374        assert_eq!(fragment_child_names(&frag), vec!["b"]);
375    }
376
377    #[test]
378    fn parse_fragment_document_context_degrades_not_panics() {
379        let doc = Node::new_document();
380        let frag = parse_fragment("<b>x</b>", &doc);
381        assert_eq!(fragment_child_names(&frag), vec!["b"]);
382    }
383
384    #[test]
385    fn set_inner_html_on_text_node_does_not_panic() {
386        // F-9 端到端:脚本桥接路径(text.innerHTML = ...)不得 abort。
387        let doc = Node::new_document();
388        let text = Node::new_text("old", &doc);
389        crate::serialize::set_inner_html(&text, "<b>x</b>");
390        let children = text.borrow().child_nodes().to_vec();
391        assert_eq!(children.len(), 1, "content must be replaced");
392        // DOM 惯例:HTML 元素 node_name 为大写。
393        assert_eq!(children[0].borrow().node_name, "B");
394    }
395}