easypdf-rust

An idiomatic Rust PDF toolkit -- create, read, manipulate, convert, encrypt, and sign.

Inspired by Alibaba EasyExcel's builder-pattern API design.

English · 简体中文

Version: 0.1.1 · MSRV: Rust 1.88 · Edition: 2024 · License: Apache-2.0

Architecture

9-crate workspace with clean separation of concerns:

flowchart TB
    facade["<b>easypdf</b>\nEasyPdf facade + builders"]
    core["<b>easypdf-core</b>\ntypes + errors + crypto + model + io + layout"]
    derive["<b>easypdf-derive</b>\n#[derive(PdfModel)]"]
    reader["<b>easypdf-reader</b>\nread + manipulate + streaming"]
    writer["<b>easypdf-writer</b>\nwrite + template + backends"]
    markdown["<b>easypdf-markdown</b>\npipeline + table + OCR + render"]
    ocr["<b>easypdf-ocr</b>\ncloud OCR engines"]
    runtime["<b>easypdf-runtime</b>\nMCP server + resident daemon"]
    test["<b>easypdf-test</b>\nintegration tests"]

    facade --> reader & writer & markdown & ocr
    runtime --> reader & writer & markdown
    markdown --> reader & core
    reader --> core
    writer --> core
    ocr --> markdown & core
    derive --> core
    test --> facade

    style facade fill:#e1f5fe
    style core fill:#fff3e0
    style runtime fill:#f3e5f5

Key Capabilities

Quick Start

# Cargo.toml
[dependencies]
easypdf = "0.1.1"

Create a PDF:

use easypdf::prelude::*;

EasyPdf::create("output.pdf")
    .page(PageSize::A4)
    .add_text("Hello, world!")
        .font(PdfFont::helvetica(12.0))
        .position(72.0, 700.0)
    .do_write()?;
# Ok::<(), easypdf::PdfError>(())

Read a PDF:

use easypdf::prelude::*;

let text = EasyPdf::read("input.pdf")
    .pages(0..10)
    .extract_text()?;
# Ok::<(), easypdf::PdfError>(())

Merge PDFs:

use easypdf::prelude::*;

EasyPdf::merge(&["a.pdf", "b.pdf", "c.pdf"], "merged.pdf")?;
# Ok::<(), easypdf::PdfError>(())

Fill a form:

use easypdf::prelude::*;

#[derive(PdfModel)]
struct MyData {
    #[pdf(field = "name")]
    name: String,
}

EasyPdf::fill_form("template.pdf", &MyData { name: "Alice".into() })
    .save("filled.pdf")?;
# Ok::<(), easypdf::PdfError>(())

9-Crate Overview

PDF Creation (Builder Pattern)

The writer supports text, images, shapes, custom fonts, and metadata:

use easypdf::prelude::*;

let writer = EasyPdf::writer("My Report")
    .backend(WriteBackend::auto(10 * 1024 * 1024))  // 10 MB threshold
    .build()?;

// WriteBackend::InMemory -- default, fast for small docs
// WriteBackend::Spill  -- page-level temp files, constant memory
// WriteBackend::Auto   -- auto-select by threshold
# Ok::<(), easypdf::PdfError>(())

PDF Reading (3 Strategies)

PdfReader automatically selects the optimal strategy based on file size:

Session reuse parses the document once and reuses the in-memory representation -- ~129x faster than re-opening for repeated access.

Markdown Conversion

PDF to Markdown with profiles, table detection, and OCR fallback:

use easypdf::prelude::*;

EasyPdf::export_markdown("input.pdf", "output.md")
    .pages(0..20)
    .profile(MarkdownProfile::Llm)
    .tables(TablePolicy::Detect)
    .ocr(OcrPolicy::Auto)
    .do_export()?;
# Ok::<(), easypdf::PdfError>(())

Pipeline flow: PDF -> PdfReader -> PdfDocumentModel -> ProcessorPipeline -> MarkdownRenderer -> String

Encryption and Signing

AES-128/256 encryption with permission control:

use easypdf::prelude::*;

let enc = PdfEncryption::new("user_pass", "owner_pass")
    .with_algorithm(PdfEncryptionAlgorithm::Aes256)
    .with_permissions(PdfPermissions::PRINT | PdfPermissions::COPY);

let encrypted = encrypt_pdf(&pdf_bytes, &enc)?;
# Ok::<(), easypdf::PdfError>(())

PKCS#7 digital signatures with RSA-PKCS#1v1.5 + SHA-256 (via ring):

use easypdf::prelude::*;

let signer = PdfSigner::new(cert_pem, key_pem)
    .with_reason("Document approval")
    .with_location("Beijing");

let signed = sign_pdf(&pdf_bytes, &signer)?;
let info = verify_pdf_signature(&signed)?;
# Ok::<(), easypdf::PdfError>(())

Resident Daemon and MCP Server

Resident daemon keeps PDF sessions in memory across requests:

use easypdf::EasyPdf;

// Start daemon (blocks):
EasyPdf::serve(None)?;

// Attach from another process:
if let Some(client) = EasyPdf::attach() {
    // use client to interact with the daemon
}

MCP server exposes 7 tools for LLM agent integration:

use easypdf::EasyPdf;

let server = EasyPdf::mcp_server();
server.run()?;

Performance

Benchmarked against pdftotext (Poppler) on Apple M4 Pro:

Test Coverage

Cargo Features

# Default: markdown enabled
easypdf = "0.1.1"

# Minimal build (no markdown)
easypdf = { version = "0.1.1", default-features = false }

# Enable everything
easypdf = { version = "0.1.1", features = ["full"] }

Toolchain

Documentation

Roadmap

详见 docs/superpowers/version-plan.md。

Contributing

Before submitting, run all quality gates:

cargo check -p easypdf --no-default-features
cargo check -p easypdf --all-features
cargo test --workspace --quiet
cargo doc --workspace --no-deps

New public API must include docs, examples, tests, and SemVer impact notes.

License

Licensed under Apache-2.0.

Related Projects

• easyexcel-rs -- Rust port of Alibaba EasyExcel
• easyexcel -- Original Java library
• lopdf -- Pure Rust PDF manipulation
• printpdf -- Pure Rust PDF generation

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