easydoc-reader

SAX-streaming DOCX/DOC reader with O(1) memory footprint

English | 简体中文

Overview · Capabilities · Architecture · Quick Start · Security · API · Upstream · Quality

Status: alpha pre-release (latest on crates.io) MSRV: Rust 1.88 Edition: 2024 Resolver: 3 Maturity: Alpha -- public API may change Last verified: 2026-08-11

1. Overview

easydoc-reader is a Rust crate for streaming DOCX (and legacy DOC) document reading, designed for O(1) memory usage regardless of document size. It is part of the easydoc-rust workspace and corresponds to the read layer of Java EasyExcel (com.alibaba.excel).

1.1 What It Is

• A SAX-style streaming DOCX reader built on quick-xml for O(1) memory parsing.
• Extracts paragraphs, headings, tables (with merge), images (binary), multi-level lists, hyperlinks, nested tables, and OMML math formulas.
• Provides four view modes (Plain, Annotated, Outline, Stats) for LLM-friendly document analysis.
• Includes SSRF, ZIP bomb, and Zip Slip security guards.

1.2 What It Is Not

• Not a DOCX editor -- use easydoc-writer for writing.
• Not a Markdown converter -- use easydoc-markdown for conversion.
• Not a 1:1 port of any single Java class; it combines concepts from multiple EasyExcel reader components.
• Legacy DOC support depends on office_oxide boundaries and is not equivalent to DOCX coverage.

2. Capabilities

2.1 Document Format Support Matrix

2.2 Status Definitions

2.3 View Modes

3. Architecture

DOCX file (ZIP archive)
        │
        ▼
ZIP validation (bomb / Zip Slip / entry limits)
        │
        ▼
word/document.xml extraction
        │
        ▼
quick-xml SAX parser (O(1) memory)
        │
        ├──► DocumentEvent stream (EventSink)
        └──► DocumentBlock tree (read_blocks)
        │
        ▼
ViewMode rendering (Plain / Annotated / Outline / Stats)

3.1 Crate Dependencies

flowchart TB
    USER["Application"] --> READER["easydoc-reader"]
    READER --> CORE["easydoc-core"]
    READER --> OXIDE["office_oxide"]
    READER --> QXML["quick-xml"]
    READER --> ZIP["zip"]

3.2 Key Types

4. Quick Start

4.1 Installation

[dependencies]
easydoc-reader = "0.1.0-alpha"

4.2 Streaming Read (Event-based)

use std::path::Path;
use easydoc_reader::DocxSaxReader;
use easydoc_core::ContentCollector;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut reader = DocxSaxReader::from_path(Path::new("report.docx"))?;
    let mut collector = ContentCollector::new();
    reader.read_events(&mut collector)?;
    let content = collector.into_content();

    for block in &content.blocks {
        println!("{:?}", block);
    }
    Ok(())
}

4.3 Block-based Read (with Math)

use std::path::Path;
use easydoc_reader::DocxSaxReader;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut reader = DocxSaxReader::from_path(Path::new("report.docx"))?;
    let blocks = reader.read_blocks()?;

    for block in &blocks {
        println!("{:?}", block);
    }
    Ok(())
}

4.4 View Mode Rendering

use std::path::Path;
use easydoc_reader::{DocxSaxReader, ViewMode, render_view};
use easydoc_core::ContentCollector;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut reader = DocxSaxReader::from_path(Path::new("report.docx"))?;
    let mut collector = ContentCollector::new();
    reader.read_events(&mut collector)?;
    let content = collector.into_content();

    let outline = render_view(&content, &ViewMode::Outline { max_level: 3 })?;
    println!("{}", outline);
    Ok(())
}

4.5 Typed Table Extraction

use easydoc_reader::DocReadBuilder;
use easydoc_core::DocxRow;

#[derive(Debug, DocxRow)]
struct Employee {
    #[easydoc(name = "Name")]
    name: String,
    #[easydoc(name = "Age")]
    age: u32,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let employees: Vec<Employee> = DocReadBuilder::new("staff.docx").do_read()?;
    for emp in &employees {
        println!("{}: {}", emp.name, emp.age);
    }
    Ok(())
}

5. Security

5.1 Security Guards

5.2 SSRF Protection Details

The SsrfGuard validates all hyperlinks extracted from DOCX documents:

• Allowed schemes: http, https, mailto
• Blocked hosts: localhost
• Blocked IPv4: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 100.64.0.0/10, 0.0.0.0/8
• Blocked IPv6: loopback, unspecified, unique-local (fc00::/7), link-local (fe80::/10), multicast (ff00::/8)

use easydoc_reader::security::SsrfGuard;

let guard = SsrfGuard::new();
assert!(guard.check_url("https://example.com").is_ok());
assert!(guard.check_url("http://127.0.0.1/admin").is_err());

5.3 Custom Security Policy

use easydoc_reader::security::SecurityPolicy;
use easydoc_reader::DocxSaxReader;
use std::path::Path;

let policy = SecurityPolicy::permissive(); // trusted input only
let reader = DocxSaxReader::from_path_with_security(
    Path::new("trusted.docx"),
    policy,
)?;

6. API Reference

6.1 Core API

6.2 Error Model

7. Upstream Compatibility

7.1 Java EasyExcel Mapping

This crate corresponds to the read layer of Java EasyExcel. The design draws from multiple upstream components:

7.2 Differences from Java

• No reflection: Rust uses derive macros (DocxRow) instead of Java reflection for typed extraction.
• No partial sheet read: DOCX has no sheet concept; full document is streamed.
• Math formulas: read_blocks() returns DocumentBlock::Math with raw OMML XML; read_events() drops math (no DocumentEvent::Math variant).

8. Quality & Testing

8.1 Unsafe Policy

This crate uses #![deny(unsafe_code)]. The workspace enforces unsafe_code = "forbid" via [workspace.lints.rust].

8.2 Test Categories

8.3 Building & Testing

cargo check -p easydoc-reader
cargo test -p easydoc-reader
cargo clippy -p easydoc-reader -- -D warnings
cargo doc -p easydoc-reader --no-deps

Back to top · docs.rs · crates.io · Issues