rusteerio 0.1.1 → 1.0.1

package/native/src/codec.rs

@@ -10,6 +10,9 @@ pub(crate) fn has_encoding(value: &str) -> bool {
     value.chars().any(is_reserved)
 }
 pub(crate) fn from_units(units: &[u16]) -> String {
+    if units.iter().all(|unit| !(0xd800..=0xe800).contains(unit)) {
+        return String::from_utf16_lossy(units);
+    }
     let mut output = String::with_capacity(units.len());
     let mut index = 0;
     while index < units.len() {
@@ -38,28 +41,69 @@ pub(crate) fn from_units(units: &[u16]) -> String {
     }
     output
 }
-pub(crate) fn to_units(value: &str) -> Vec<u16> {
-    let mut output = Vec::with_capacity(value.len());
-    let mut chars = value.chars().peekable();
-    while let Some(ch) = chars.next() {
-        if ch == ESCAPE && chars.peek().copied().is_some_and(is_reserved) {
-            output.push(chars.next().unwrap() as u16);
-        } else if ('\u{e000}'..'\u{e800}').contains(&ch) {
-            output.push(0xd800 + (ch as u16 - 0xe000));
-        } else {
-            let mut encoded = [0; 2];
-            output.extend_from_slice(ch.encode_utf16(&mut encoded));
-        }
+/// Receives the UTF-16 units of a string from [`visit_units`].
+pub(crate) trait UnitSink {
+    /// A run of ASCII bytes starting at byte offset `start`, one unit each.
+    fn ascii(&mut self, start: usize, run: &[u8]);
+    /// One unit and the byte offset of the character that starts there, or
+    /// `None` for the low half of a surrogate pair.
+    fn unit(&mut self, offset: Option<usize>, unit: u16);
+}
+
+impl UnitSink for Vec<u16> {
+    fn ascii(&mut self, _: usize, run: &[u8]) {
+        self.extend(run.iter().map(|value| u16::from(*value)));
+    }
+    fn unit(&mut self, _: Option<usize>, unit: u16) {
+        self.push(unit);
     }
-    output
 }
-pub(crate) fn logical_len(value: &str) -> usize {
-    if has_encoding(value) {
-        to_units(value).len()
-    } else {
-        value.encode_utf16().count()
+
+/// Feeds the UTF-16 units of `value` to `sink`. With `framed`, lossless frames
+/// decode to their original units.
+pub(crate) fn visit_units(value: &str, framed: bool, sink: &mut impl UnitSink) {
+    let bytes = value.as_bytes();
+    let mut byte = 0;
+    while byte < bytes.len() {
+        let ascii = bytes[byte..]
+            .iter()
+            .position(|value| !value.is_ascii())
+            .unwrap_or(bytes.len() - byte);
+        sink.ascii(byte, &bytes[byte..byte + ascii]);
+        byte += ascii;
+        let Some(ch) = value[byte..].chars().next() else {
+            break;
+        };
+        let start = byte;
+        byte += ch.len_utf8();
+        if framed && ch == ESCAPE {
+            if let Some(next) = value[byte..]
+                .chars()
+                .next()
+                .filter(|next| is_reserved(*next))
+            {
+                sink.unit(Some(start), next as u16);
+                byte += next.len_utf8();
+                continue;
+            }
+        }
+        if framed && ('\u{e000}'..ESCAPE).contains(&ch) {
+            sink.unit(Some(start), 0xd800 + (ch as u16 - 0xe000));
+            continue;
+        }
+        let mut encoded = [0; 2];
+        let encoded = ch.encode_utf16(&mut encoded);
+        sink.unit(Some(start), encoded[0]);
+        if let Some(low) = encoded.get(1) {
+            sink.unit(None, *low);
+        }
     }
 }
+pub(crate) fn to_units(value: &str) -> Vec<u16> {
+    let mut output = Vec::with_capacity(value.len());
+    visit_units(value, has_encoding(value), &mut output);
+    output
+}
 pub(crate) fn to_usv(value: &str) -> String {
     if has_encoding(value) {
         String::from_utf16_lossy(&to_units(value))

package/native/src/hook_sink.rs

@@ -1,7 +1,7 @@
 //! An active user-supplied tree adapter. Rust runs the HTML5 algorithm; the
 //! adapter supplies every construction, mutation and tree-inspection decision.
 use std::borrow::Cow;
-use std::cell::{Ref, RefCell};
+use std::cell::{Cell, Ref, RefCell};
 use std::collections::HashMap;
 use std::rc::Rc;
 
@@ -196,6 +196,26 @@ struct HookSink {
     context: Option<Rc<crate::diagnostics::DiagnosticContext>>,
     diagnostics: RefCell<Vec<Value>>,
     locations: Option<crate::tracker::Locations<u32>>,
+    pending_escape: Cell<Option<TextTarget>>,
+}
+
+/// Where a text chunk is inserted: appended to `parent`, or before `sibling`.
+#[derive(Clone, Copy, PartialEq, Eq)]
+struct TextTarget {
+    parent: u32,
+    sibling: Option<u32>,
+}
+
+/// Whether the final character is a codec escape whose character has not
+/// arrived yet. Escapes pair with the following character.
+fn ends_with_unpaired_escape(text: &str) -> bool {
+    let mut chars = text.chars();
+    while let Some(ch) = chars.next() {
+        if ch == crate::codec::ESCAPE && chars.next().is_none() {
+            return true;
+        }
+    }
+    false
 }
 
 impl HookSink {
@@ -203,6 +223,17 @@ impl HookSink {
         if self.error.borrow().is_some() {
             return Value::Null;
         }
+        if matches!(
+            method,
+            "appendChild"
+                | "insertBefore"
+                | "detachNode"
+                | "setDocumentType"
+                | "setTemplateContent"
+                | "__snapshot"
+        ) {
+            self.flush_escape();
+        }
         let result = self.bridge.call(method, args);
         match result {
             Ok(value) => value,
@@ -215,6 +246,38 @@ impl HookSink {
     fn node(&self, method: &str, args: Value) -> u32 {
         self.call(method, args).as_u64().unwrap_or(0) as u32
     }
+    /// The tokenizer may split a codec escape from its character across text
+    /// chunks. Adapters decode each chunk separately, so a trailing escape is
+    /// held until the next chunk for the same target.
+    fn insert_text(&self, target: TextTarget, text: &str) {
+        let mut data = String::with_capacity(text.len() + crate::codec::ESCAPE.len_utf8());
+        if let Some(pending) = self.pending_escape.take() {
+            if pending == target {
+                data.push(crate::codec::ESCAPE);
+            } else {
+                self.send_text(pending, &crate::codec::ESCAPE.to_string());
+            }
+        }
+        data.push_str(text);
+        if ends_with_unpaired_escape(&data) {
+            data.pop();
+            self.pending_escape.set(Some(target));
+        }
+        if !data.is_empty() {
+            self.send_text(target, &data);
+        }
+    }
+    fn send_text(&self, target: TextTarget, data: &str) {
+        match target.sibling {
+            None => self.call("insertText", json!([target.parent, data])),
+            Some(sibling) => self.call("insertTextBefore", json!([target.parent, data, sibling])),
+        };
+    }
+    fn flush_escape(&self) {
+        if let Some(pending) = self.pending_escape.take() {
+            self.send_text(pending, &crate::codec::ESCAPE.to_string());
+        }
+    }
     fn attrs(attrs: Vec<Attribute>) -> Value {
         Value::Array(
             attrs
@@ -463,7 +526,11 @@ impl TreeSink for HookSink {
                 }
             }
             NodeOrText::AppendText(text) => {
-                self.call("insertText", json!([parent, text.as_ref()]));
+                let target = TextTarget {
+                    parent: *parent,
+                    sibling: None,
+                };
+                self.insert_text(target, text.as_ref());
                 self.mark_text(*parent, None, text.as_ref());
             }
         }
@@ -530,7 +597,11 @@ impl TreeSink for HookSink {
                 self.call("insertBefore", json!([parent, node, sibling]));
             }
             NodeOrText::AppendText(text) => {
-                self.call("insertTextBefore", json!([parent, text.as_ref(), sibling]));
+                let target = TextTarget {
+                    parent,
+                    sibling: Some(*sibling),
+                };
+                self.insert_text(target, text.as_ref());
                 self.mark_text(parent, Some(*sibling), text.as_ref());
             }
         }
@@ -589,6 +660,7 @@ fn parser(
         context: None,
         diagnostics: RefCell::new(Vec::new()),
         locations: None,
+        pending_escape: Cell::new(None),
     };
     sink.call(
         if is_document {
@@ -659,6 +731,7 @@ pub(crate) fn parse(
             diagnostics: RefCell::new(Vec::new()),
             locations: (options.get("sourceCodeLocationInfo") == Some(&Value::Bool(true)))
                 .then(|| crate::tracker::Locations::new(context.clone())),
+            pending_escape: Cell::new(None),
         };
         sink.call(
             if is_document {
@@ -706,6 +779,7 @@ where
         diagnostics: RefCell::new(Vec::new()),
         locations: (options.get("sourceCodeLocationInfo") == Some(&Value::Bool(true)))
             .then(|| crate::tracker::Locations::new(context.clone())),
+        pending_escape: Cell::new(None),
     };
     sink.call(
         if is_document {

package/native/src/lib.rs

@@ -23,6 +23,7 @@ mod gc;
 mod hook_sink;
 mod hook_stream;
 mod location;
+mod markup_tokenizer;
 mod runtime;
 mod selector;
 mod sink;
@@ -35,8 +36,90 @@ pub use runtime::{configure_worker_pool, worker_pool_info, WorkerPoolInfo};
 pub use stream::NativeStream;
 
 const HTML_NS: &str = "http://www.w3.org/1999/xhtml";
+const XML_NS: &str = "http://www.w3.org/XML/1998/namespace";
+const XMLNS_NS: &str = "http://www.w3.org/2000/xmlns/";
+const XLINK_NS: &str = "http://www.w3.org/1999/xlink";
+
+/// Writes an attribute's serialized name. Like parse5, the namespace rather
+/// than the stored prefix selects the qualifier: HTML5 gives foreign `xmlns`
+/// attributes an empty prefix, which must not become `:xmlns`. Other namespaces
+/// keep a non-empty prefix; an empty or missing one writes the bare name.
+pub(crate) fn push_attribute_name(
+    output: &mut String,
+    local: &str,
+    namespace: Option<&str>,
+    prefix: Option<&str>,
+) {
+    match namespace.filter(|namespace| !namespace.is_empty()) {
+        None => {}
+        Some(XML_NS) => output.push_str("xml:"),
+        Some(XMLNS_NS) => {
+            if local != "xmlns" {
+                output.push_str("xmlns:");
+            }
+        }
+        Some(XLINK_NS) => output.push_str("xlink:"),
+        Some(_) => {
+            if let Some(prefix) = prefix.filter(|prefix| !prefix.is_empty()) {
+                output.push_str(prefix);
+                output.push(':');
+            }
+        }
+    }
+    output.push_str(local);
+}
 
-#[napi]
+/// Orders attributes the way a JavaScript object enumerates its keys: integer
+/// keys first, ascending, then insertion order. Cheerio serializes attributes
+/// from such an object.
+pub(crate) fn js_property_order<'a, T, I>(entries: I) -> JsPropertyOrder<I>
+where
+    I: Iterator<Item = (&'a str, T)> + Clone,
+{
+    if !entries.clone().any(|(name, _)| array_index(name).is_some()) {
+        return JsPropertyOrder::Unchanged(entries);
+    }
+    let mut keyed: Vec<_> = entries
+        .map(|entry| {
+            (
+                array_index(entry.0).map_or((1, 0), |index| (0, index)),
+                entry,
+            )
+        })
+        .collect();
+    keyed.sort_by_key(|(key, _)| *key);
+    let sorted: Vec<_> = keyed.into_iter().map(|(_, entry)| entry).collect();
+    JsPropertyOrder::Sorted(sorted.into_iter())
+}
+
+pub(crate) enum JsPropertyOrder<I: Iterator> {
+    Unchanged(I),
+    Sorted(std::vec::IntoIter<I::Item>),
+}
+
+impl<I: Iterator> Iterator for JsPropertyOrder<I> {
+    type Item = I::Item;
+    fn next(&mut self) -> Option<Self::Item> {
+        match self {
+            Self::Unchanged(entries) => entries.next(),
+            Self::Sorted(entries) => entries.next(),
+        }
+    }
+}
+
+fn array_index(name: &str) -> Option<u32> {
+    let is_canonical = !name.is_empty()
+        && name.len() <= 10
+        && name.bytes().all(|byte| byte.is_ascii_digit())
+        && (name == "0" || !name.starts_with('0'));
+    is_canonical
+        .then(|| name.parse::<u64>().ok())
+        .flatten()
+        .filter(|value| *value < u64::from(u32::MAX))
+        .map(|value| value as u32)
+}
+
+#[napi(custom_finalize)]
 pub struct NativeDocument {
     html: RefCell<Option<Html>>,
     // Stable public IDs are preorder positions, rather than parser allocation
@@ -51,10 +134,43 @@ pub struct NativeDocument {
     managed: Cell<bool>,
     diagnostics: RefCell<Vec<Value>>,
     locations: RefCell<HashMap<u32, Value>>,
+    // V8 cannot see native allocations. Reporting them lets its GC collect
+    // unreachable documents under native memory pressure.
+    content_bytes: Cell<usize>,
+    reported_heap_bytes: Cell<i64>,
+}
+
+impl ObjectFinalize for NativeDocument {
+    fn finalize(self, mut env: Env) -> Result<()> {
+        let reported = self.reported_heap_bytes.get();
+        if reported != 0 {
+            // Accounting is advisory; a failure must not throw from a finalizer.
+            let _ = env.adjust_external_memory(-reported);
+        }
+        Ok(())
+    }
 }
 
+fn html_node_content_bytes(node: &Node) -> usize {
+    match node {
+        Node::Text(text) => text.len(),
+        Node::Comment(comment) => comment.len(),
+        Node::Element(element) => element.attrs.iter().map(|(_, value)| value.len()).sum(),
+        _ => 0,
+    }
+}
+
+/// Approximate retained bytes per node in each representation, excluding the
+/// text and attribute content counted separately. V8 treats the total only as
+/// allocation pressure, so these err on the high side.
+const IMMUTABLE_NODE_BYTES: usize = 256;
+const ARENA_NODE_BYTES: usize = 512;
+/// Smaller changes to an already reported size are skipped to keep operations cheap.
+const HEAP_REPORT_STEP: i64 = 64 * 1024;
+
 impl NativeDocument {
     pub(crate) fn from_arena(arena: arena::DomArena, options: Value) -> Self {
+        let content_bytes = arena.nodes.iter().map(arena::DomNode::content_bytes).sum();
         Self {
             html: RefCell::new(None),
             ids: RefCell::new(Vec::new()),
@@ -67,6 +183,8 @@ impl NativeDocument {
             managed: Cell::new(false),
             diagnostics: RefCell::new(Vec::new()),
             locations: RefCell::new(HashMap::new()),
+            content_bytes: Cell::new(content_bytes),
+            reported_heap_bytes: Cell::new(0),
         }
     }
     pub(crate) fn set_diagnostic_records(&self, records: Vec<Value>) {
@@ -82,6 +200,39 @@ impl NativeDocument {
         Self::parse_options(source, is_document, serde_json::json!({}), None)
     }
 
+    fn estimated_heap_bytes(&self) -> i64 {
+        let live_arena_nodes = self.arena.borrow().as_ref().map_or(0, |arena| {
+            arena.nodes.len().saturating_sub(arena.free.len())
+        });
+        let immutable_nodes = self.ids.borrow().len();
+        let retained_source = self.source.borrow().as_ref().map_or(0, String::capacity);
+        let content = if live_arena_nodes + immutable_nodes == 0 {
+            0
+        } else {
+            self.content_bytes.get()
+        };
+        let bytes = content
+            + retained_source
+            + immutable_nodes * IMMUTABLE_NODE_BYTES
+            + live_arena_nodes * ARENA_NODE_BYTES;
+        i64::try_from(bytes).unwrap_or(i64::MAX)
+    }
+
+    fn report_heap_bytes(&self, mut env: Env) {
+        let reported = self.reported_heap_bytes.get();
+        let estimated = self.estimated_heap_bytes();
+        let change = estimated - reported;
+        let is_small_update = reported != 0 && estimated != 0 && change.abs() < HEAP_REPORT_STEP;
+        if change != 0 && !is_small_update && env.adjust_external_memory(change).is_ok() {
+            self.reported_heap_bytes.set(estimated);
+        }
+    }
+
+    fn reported<T>(&self, env: Env, value: T) -> T {
+        self.report_heap_bytes(env);
+        value
+    }
+
     pub(crate) fn parse_options(
         source: &str,
         is_document: bool,
@@ -262,6 +413,7 @@ impl NativeDocument {
                     && value != &&serde_json::json!("")
             })
             .and(source);
+        let content_bytes = html.tree.values().map(html_node_content_bytes).sum();
         Self {
             html: RefCell::new(Some(html)),
             ids: RefCell::new(ids),
@@ -274,6 +426,8 @@ impl NativeDocument {
             managed: Cell::new(false),
             diagnostics: RefCell::new(diagnostics),
             locations: RefCell::new(locations),
+            content_bytes: Cell::new(content_bytes),
+            reported_heap_bytes: Cell::new(0),
         }
     }
 
@@ -583,7 +737,16 @@ impl NativeDocument {
             }
         }
     }
-    #[napi]
+    #[napi(js_name = "collectGarbage")]
+    pub fn collect_garbage_and_report(&self, env: Env) -> MemoryStats {
+        let stats = self.collect_garbage();
+        self.report_heap_bytes(env);
+        MemoryStats {
+            external_bytes: self.reported_heap_bytes.get(),
+            ..stats
+        }
+    }
+
     pub fn collect_garbage(&self) -> MemoryStats {
         self.needs_collect.set(false);
         if self.arena.borrow().is_none() && self.managed.get() && self.retained.borrow().is_empty()
@@ -599,6 +762,7 @@ impl NativeDocument {
                 retained: 0,
                 reclaimed,
                 immutable_nodes: 0,
+                external_bytes: self.reported_heap_bytes.get(),
             };
         }
         if let Some(arena) = self.arena.borrow_mut().as_mut() {
@@ -610,6 +774,7 @@ impl NativeDocument {
                 retained: stats.retained,
                 reclaimed: stats.reclaimed,
                 immutable_nodes: 0,
+                external_bytes: self.reported_heap_bytes.get(),
             }
         } else {
             let count = self.ids.borrow().len() as u32;
@@ -619,6 +784,7 @@ impl NativeDocument {
                 retained: self.retained.borrow().len() as u32,
                 reclaimed: 0,
                 immutable_nodes: count,
+                external_bytes: self.reported_heap_bytes.get(),
             }
         }
     }
@@ -629,19 +795,30 @@ impl NativeDocument {
     }
 
     #[napi]
-    pub fn root_id(&self) -> u32 {
+    pub fn root_id(&self, env: Env) -> u32 {
+        self.report_heap_bytes(env);
         0
     }
 
-    #[napi]
+    #[napi(js_name = "select")]
+    pub fn select_and_report(
+        &self,
+        env: Env,
+        selector: String,
+        contexts: Option<Vec<u32>>,
+    ) -> Result<Vec<u32>> {
+        self.reported(env, self.select(selector, contexts))
+    }
+
     pub fn select(&self, selector: String, contexts: Option<Vec<u32>>) -> Result<Vec<u32>> {
         self.select_ids(&selector, contexts.as_deref())
     }
 
     #[napi]
-    pub fn matches(&self, selector: String, ids: Vec<u32>) -> Result<Vec<u32>> {
+    pub fn matches(&self, env: Env, selector: String, ids: Vec<u32>) -> Result<Vec<u32>> {
         self.ensure_arena()?;
-        selector::filter(self.arena.borrow().as_ref().unwrap(), &selector, &ids)
+        let matched = selector::filter(self.arena.borrow().as_ref().unwrap(), &selector, &ids);
+        self.reported(env, matched)
     }
 
     #[napi]
@@ -671,7 +848,11 @@ impl NativeDocument {
         self.text_ids(&ids)
     }
 
-    #[napi]
+    #[napi(js_name = "innerHtml")]
+    pub fn inner_html_and_report(&self, env: Env, id: u32) -> String {
+        self.reported(env, self.inner_html(id))
+    }
+
     pub fn inner_html(&self, id: u32) -> String {
         if (self.tag_name(id).as_deref() == Some("template") || self.arena.borrow().is_some())
             && self.ensure_arena().is_ok()
@@ -704,7 +885,11 @@ impl NativeDocument {
         .flatten()
     }
 
-    #[napi]
+    #[napi(js_name = "exportTree")]
+    pub fn export_tree_and_report(&self, env: Env) -> Result<String> {
+        self.reported(env, self.export_tree())
+    }
+
     pub fn export_tree(&self) -> Result<String> {
         if self.source.borrow().is_some() {
             self.ensure_arena()?;
@@ -718,7 +903,11 @@ impl NativeDocument {
         serde_json::to_string(&records).map_err(json_error)
     }
 
-    #[napi]
+    #[napi(js_name = "node")]
+    pub fn node_and_report(&self, env: Env, id: u32) -> Result<String> {
+        self.reported(env, self.node(id))
+    }
+
     pub fn node(&self, id: u32) -> Result<String> {
         if self.source.borrow().is_some() {
             self.ensure_arena()?;
@@ -729,13 +918,26 @@ impl NativeDocument {
         serde_json::to_string(&self.arena.borrow().as_ref().unwrap().node(id)).map_err(json_error)
     }
 
-    #[napi]
+    #[napi(js_name = "create")]
+    pub fn create_and_report(
+        &self,
+        env: Env,
+        html: String,
+        context_id: Option<u32>,
+        options_json: Option<String>,
+    ) -> Result<Vec<u32>> {
+        let created = self.create(html, context_id, options_json);
+        self.reported(env, created)
+    }
+
     pub fn create(
         &self,
         html: String,
         context_id: Option<u32>,
         _options_json: Option<String>,
     ) -> Result<Vec<u32>> {
+        self.content_bytes
+            .set(self.content_bytes.get().saturating_add(html.len()));
         self.ensure_arena()?;
         self.arena
             .borrow_mut()
@@ -746,7 +948,19 @@ impl NativeDocument {
 
     /// Move a branch between native documents. JavaScript only redirects its
     /// existing stable handles using the returned complete descendant mapping.
-    #[napi]
+    #[napi(js_name = "adopt")]
+    pub fn adopt_and_report(
+        &self,
+        env: Env,
+        source: &NativeDocument,
+        ids: Vec<u32>,
+        detach: Option<bool>,
+    ) -> Result<String> {
+        let adopted = self.adopt(source, ids, detach);
+        source.report_heap_bytes(env);
+        self.reported(env, adopted)
+    }
+
     pub fn adopt(
         &self,
         source: &NativeDocument,
@@ -840,7 +1054,11 @@ impl NativeDocument {
             .map_err(json_error)
     }
 
-    #[napi]
+    #[napi(js_name = "op")]
+    pub fn op_and_report(&self, env: Env, command: String, args_json: String) -> Result<String> {
+        self.reported(env, self.op(command, args_json))
+    }
+
     pub fn op(&self, command: String, args_json: String) -> Result<String> {
         self.maybe_collect();
         let args: Value = serde_json::from_str(&args_json).map_err(json_error)?;
@@ -964,6 +1182,8 @@ pub struct MemoryStats {
     pub retained: u32,
     pub reclaimed: u32,
     pub immutable_nodes: u32,
+    /// Native bytes currently reported to V8 for this document.
+    pub external_bytes: i64,
 }
 
 /// The Cheerio DOM adapter exposes foreign attributes by local name, whereas
@@ -1154,13 +1374,20 @@ fn serialize_node(node: NodeRef<'_, Node>, output: &mut String) {
             Node::Element(element) => {
                 output.push('<');
                 output.push_str(element.name());
-                for (name, value) in &element.attrs {
+                let attributes = js_property_order(
+                    element
+                        .attrs
+                        .iter()
+                        .map(|(name, value)| (name.local.as_ref(), (name, value))),
+                );
+                for (_, (name, value)) in attributes {
                     output.push(' ');
-                    if let Some(prefix) = &name.prefix {
-                        output.push_str(prefix);
-                        output.push(':');
-                    }
-                    output.push_str(&name.local);
+                    push_attribute_name(
+                        output,
+                        &name.local,
+                        Some(name.ns.as_ref()),
+                        name.prefix.as_deref(),
+                    );
                     output.push_str("=\"");
                     escape_html(value, true, output);
                     output.push('"');