rusty_xml

rusty_xml is a ground-up, pure-Rust remake of libxml2: well-formed XML 1.0 parse, arena DOM, SAX2, pull reader, writer/save, XPath 1.0, DTD, C14N, HTML, and working subsets of RelaxNG / XSD / Schematron. #![forbid(unsafe_code)] on every published crate, no C, no libxml2-sys, no copyleft. Defaults are XML_PARSE_NONET | XML_PARSE_NO_XXE — the safe posture libxml2's own README says the C library does not have.

Part of Remade With Rust by Mata Network — the XML toolkit for the stack that already ships rusty_zstd, rusty_h264, and remade_ffmpeg_rs. Jump to the ecosystem ↓

The headline

A pure-safe-Rust XML 1.0 toolkit that is a reimplementation, not a wrapper, with libxml2 function names as #[doc(alias)] and safe defaults C historically got wrong:

• Parse: UTF-8 well-formed documents, 15 built-in 8-bit encodings (no iconv), push (xmlParseChunk), IO callbacks, local OASIS catalogs. SAX traces are gated line-for-line against pinned xmllint --sax.
• Tree / save / writer / reader: arena DOM, xmlsave (including XML_SAVE_NO_EMPTY / NO_DECL), xmlTextWriter, xmlTextReader. Empty elements are one reader Element, no extra EndElement. parse(write(parse(x))) is a standing gate.
• XPath 1.0 compile + eval; rxmlint --xpath prints xmllint form.
• Validate / canonicalize: DTD internal subset + default attributes, xmlValidateDocument, C14N 1.0 and exclusive, XInclude via a caller loader.
• HTML (HTMLparser.c grammar, implied html/head/body) and working subsets of RelaxNG, XML Schema, and Schematron.
• CLI is rxmlint, never xmllint. Same flag language so a bench script can swap argv[0].
• The C oracle is an external process. We never link libxml2. Pin: libxml2 v2.15.3 (oracle/PIN).

Performance — faster than libxml2

Paired board against pinned libxml2 v2.15.3 xmllint. Pinned to one core (not core 0), High priority, CPU time, arms ABBA-interleaved, N=20 pairs, C-vs-C null arm per row. us/C < 1 means rusty_xml is faster. Raw rows and the full method line: bench/SIDE-BY-SIDE.md.

1.6× to 2.2× faster than the C library, on every file, in every pair.

Two numbers, because one alone would mislead. The table is as shipped: rxmlint links rusty_alloc (pure-Rust mimalloc) and xmllint uses the system allocator — that is what you actually run. Same allocator, both on the system allocator, the parser alone: big-attr 0.80×, big-300k 1.07×. Roughly half the margin is the allocator, and C could adopt one too. Also: C runs xmlCtxtReadFile per --repeat (the Windows pin has no mmap) while we do one fs::read then xml_read_memory — about 1% at these sizes, but it inflates C on small files, so the large rows are the honest result. Flags differ (C defaults to XML_PARSE_COMPACT \| XML_PARSE_BIG_LINES; we force NONET \| NO_XXE). This is CLI-vs-CLI, not a kernel A/B. Correctness is gated byte-identical against the same pinned oracle throughout.

Conformance — where we actually stand

Speed is the easy half. Here is the hard half, measured against the W3C XML Conformance Test Suite rather than against our own corpus, with the pinned C build scored on the identical cases:

Level with the thing we are replacing, by one case. We are meaningfully ahead on rejecting invalid documents and still behind on rejecting malformed ones; the remaining not-well-formed failures are concentrated in name-character classification, where libxml2 and the suite disagree about which edition of XML 1.0 is being tested.

0.2.0 never ran the suite at all. The first run, in 0.3.0, crashed before it scored a single case -- a 32 GB allocation reachable from thirty-two bytes of DTD -- and then scored 59.1%. Everything between there and here came from reading failures rather than guessing: an internal subset parser that was a scanner rather than a parser, four literals that were never character-validated, a validator whose ID branch said "uniqueness checked loosely" and meant not at all, and an entity whose replacement text was inserted as escaped text instead of the markup it was.

Run it yourself — the suite is fetched, never vendored:

pwsh scripts/fetch-xmlconf.ps1
cargo run --release -p rusty_xml-bench --bin xmlconf -- --oracle

What we do gate hard, and what those numbers cost nothing:

• 62 of 64 byte-identical comparisons against pinned xmllint over 16 corpora x {plain, --format, --c14n, --exc-c14n}. The two exceptions are one deliberate divergence: we serialize the internal DTD subset verbatim where C re-serializes and reorders it.
• 0 unsafe in all twelve crates.
• Nothing on the parse, save, format, XPath, stream or canonicalize path recurses per level of nesting, so document depth cannot exhaust the stack.
• A seeded fuzzer (--bin fuzz) holds four invariants: no panics, chunked parsing equals whole parsing at every chunk size, and both XML and HTML round trips are fixed points.

If you need full libxml2 conformance today, use libxml2. If you need a memory-safe XML toolkit that is faster than C, has no C in its dependency tree, and tells you exactly which cases it gets wrong, this is it.

What is this?

rusty_xml is libxml2 remade in Rust. Unlike libxml2-sys / quick-xml / roxmltree — bindings or different grammars — there is no C in the dependency tree here and the public names match C (xmlReadMemory → xml_read_memory, documented with #[doc(alias)]).

libxml2's own README says it is not recommended for untrusted data. That is the defect this remake exists to close: semantic identity under matched options, safe defaults (no network, no XXE, bounded amplification).

It is a reimplementation of the algorithms, not a fork. The C sources are neither distributed nor linked; a pinned xmllint is used only as an external-process oracle (scripts/fetch-oracle.ps1).

cargo-deny enforces the promise: no *-sys crate, no copyleft, and no libxml2-sys anywhere in the graph.

The Remade With Rust ecosystem

Remade With Rust is an initiative by Mata Network to rebuild essential C and C++ tools in Rust — for the memory safety, the predictable performance, and the freedom of a permissive license. Each project is a reimplementation, not a fork: same wire protocols and file formats, new code you can actually depend on.

We build the core to production grade and open-source it so the community can extend it. No copyleft. No surprises. Just the tools we rely on, made faster and safer.

→ All projects: github.com/Remade-With-Rust

Install

One crate — rusty_xml — is the public facade; it re-exports parser, tree, SAX, reader, writer, XPath, and validation. Add it with:

cargo add rusty_xml

or in Cargo.toml:

[dependencies]
rusty_xml = "0.4"

MSRV is 1.85. The library never sets #[global_allocator].

The published crates (all 0.1, MIT OR Apache-2.0):

Not published: rusty_xml-bench (oracle harness), rusty_xml-c-abi (M8 stub).

The library picks no allocator. rusty_xml-alloc pins rusty_alloc for rxmlint; the published library declares no #[global_allocator] and does not depend on it, so an embedding application keeps that choice — and gets the same win for free if it already ships rusty_alloc.

Dropping it into a downstream tool: depend on the facade. Call xml_read_memory / xml_reader_for_memory / xml_xpath_eval. Do not add libxml2-sys. Safe defaults are already on; you do not opt into NONET.

Quick start

use rusty_xml::{default_parse_options, xml_read_memory, xml_save_doc};

fn main() -> Result<(), rusty_xml::XmlError> {
    let xml = br#"<root><item id="1">hi</item></root>"#;
    let doc = xml_read_memory(xml, None, None, default_parse_options())?;
    let bytes = xml_save_doc(&doc, 0);
    assert!(std::str::from_utf8(&bytes).unwrap().contains("<item"));
    Ok(())
}

XPath 1.0 on the same tree:

use rusty_xml::{
    default_parse_options, xml_read_memory, xml_xpath_eval, XmlXPathContext, XPathObject,
};

fn main() -> Result<(), rusty_xml::XmlError> {
    let doc = xml_read_memory(
        br#"<root><item>a</item><item>b</item></root>"#,
        None,
        None,
        default_parse_options(),
    )?;
    let ctx = XmlXPathContext::xml_xpath_new_context(&doc);
    match xml_xpath_eval("count(//item)", &ctx).unwrap() {
        XPathObject::Number(n) => assert_eq!(n, 2.0),
        other => panic!("expected number, got {other:?}"),
    }
    Ok(())
}

Pull reader:

use rusty_xml::{default_parse_options, xml_reader_for_memory};

fn main() -> Result<(), rusty_xml::XmlError> {
    let mut r = xml_reader_for_memory(
        br#"<a><b/></a>"#,
        None,
        None,
        default_parse_options(),
    )?;
    let mut ticks = 0u32;
    while r.read() == 1 {
        ticks += 1;
    }
    assert!(ticks >= 2);
    Ok(())
}

Command-line (never installs as xmllint):

cargo install rusty_xml-cli
rxmlint --noout file.xml
rxmlint --sax --noout file.xml
rxmlint --stream --noout file.xml
rxmlint --xpath "//item" file.xml
rxmlint --c14n file.xml

Architecture

The workspace mirrors libxml2's headers, not its build:

crates/
  rusty_xml           public facade  ← depend on this
  rusty_xml-parser    parser.h — well-formed, encodings, push, catalogs, HTML
  rusty_xml-tree      tree.h — arena DOM
  rusty_xml-sax       SAX2.h — recorder + xmllint-debug dump
  rusty_xml-reader    xmlreader.h
  rusty_xml-writer    xmlsave.h + xmlwriter.h
  rusty_xml-xpath     xpath.h
  rusty_xml-valid     valid.h, c14n, RelaxNG / XSD / Schematron subsets
  rusty_xml-cli       rxmlint (not xmllint)
  rusty_xml-c-abi     optional cdylib, stub until M8. Not published.
  rusty_xml-bench     shells out to pinned xmllint. Never links libxml2.
  rusty_xml-alloc     rusty_alloc seam for binaries only. Library never uses it.
bench/                pinned oracle-vs-us timing harness (pinvs.ps1)
oracle/PIN            libxml2 v2.15.3 pin (binary is gitignored)

Platform support

No C toolchain, no iconv, no nasm. Gzip (XML_PARSE_UNZIP) is not wired yet (a 1f 8b buffer is an error). ISO-2022-JP / Shift_JIS / EUC-JP are unsupported, matching libxml2 built without iconv.

Roadmap

• M0 — pin oracle (libxml2 v2.15.3), C-only board, workspace skeleton
• M1 — character classes, UTF-8 well-formed parse, SAX-exact vs xmllint --sax
• M2 — tree mutation, xmlsave, xmlTextWriter, xmlTextReader, round-trip
• M3 — encodings without iconv, push parser, IO callbacks, local catalogs
• M4 — XPath 1.0 compile + eval, rxmlint --xpath
• M5 — DTD validation, C14N 1.0 + exclusive, XInclude (loader-gated)
• M6 — HTML parser, RelaxNG / XSD / Schematron working subsets
• M7 — performance campaign vs pinned xmllint: faster than C on every corpus file, N=20, 20/20 pairs (bench/SIDE-BY-SIDE.md)
• Optional gzip (miniz_oxide / XML_PARSE_UNZIP)
• M8 — W3C conformance suite wired up and scored against the C oracle (65.0% vs libxml2 79.9%); seeded fuzzer; corpus widened 7 -> 16 files
• M9 — close the conformance gap: 65.0% -> 79.9%, level with libxml2 on the same 2039 cases (ahead on invalid, behind on not-well-formed)
• C ABI cdylib (XMLPUBFUN names) + hardening audit
• Optional gzip (miniz_oxide / XML_PARSE_UNZIP)
• XML 1.1, external entity loading, CJK multi-byte encodings

Plan: docs/plan/rusty_xml.md.

License

MIT OR Apache-2.0, at your option — see LICENSE-MIT and LICENSE-APACHE. No GPL/LGPL and no C anywhere in the dependency tree, CI-enforced with cargo-deny. The C xmllint binary used as a measurement oracle is neither distributed here nor linked; see NOTICE.md.

About Mata Network

Mata Network builds sovereign, self-hostable privacy infrastructure — "stop sacrificing your privacy for convenience": wallet & identity, a password manager, a contact manager, and a browser extension that stops your information leaking as you browse.

Remade With Rust is our open-source home for the permissively-licensed building blocks that work depends on — including remade_ffmpeg_rs (the FFmpeg alternative) and FFAI (the AI media toolkit).

→ www.mata.network