cfb

cfb is a Rust library for reading and writing Compound File Binary (CFB) files — the Microsoft structured-storage format used by legacy Office documents, MSI installers, and many other binary containers. A CFB file behaves like a miniature filesystem inside a single file: a tree of storage objects (directories) that hold stream objects (files) or nested storages.

The crate exposes an ergonomic API for opening, creating, and mutating these compound files in place, including reading and writing streams with standard Read/Write/Seek traits and resizing objects without rewriting the whole file. It is widely depended on across the Rust ecosystem, with tens of millions of downloads.

What You Get

• open, open_rw, and create entry points for reading or mutating compound files
• A storage/stream tree API mirroring directories and files inside a single file
• Stream objects implementing Read, Write, and Seek for familiar I/O
• In-place resizing and mutation without rewriting the entire compound file

Common Use Cases

• Parsing legacy Microsoft Office (.doc/.xls/.msg) or MSI files stored as CFB containers
• Building or editing custom binary formats layered on structured storage
• Extracting embedded streams and metadata from OLE/compound documents

Under The Hood

Architecture - The public surface lives in src/lib.rs (~1,449 lines) exposing CompoundFile, Stream, storage/entry types, and the open/open_rw/create constructors. The real work is split across a rich src/internal/ module: header.rs, sector.rs, and chain.rs model the FAT sector chains; minialloc.rs/minichain.rs handle the mini-stream for small entries; directory.rs/direntry.rs manage the red-black directory tree; and alloc.rs, path.rs, validate.rs, and timestamp.rs round out allocation, path handling, validation, and time.

Tech Stack - Pure Rust (edition 2018, MSRV 1.74) with a tiny dependency set: fnv for fast hashing, uuid for CLSIDs, and web-time for timestamps. Dev/bench tooling uses criterion, clap, rand, and tempfile.

Code Quality - Quality is high: #![warn(missing_docs)] is enforced, and the tests/ directory covers basic, large, malformed, and set_len scenarios plus checked-in panics_fuzzed and infinite_loops_fuzzed corpora from fuzzing. A Criterion benchmark suite and a fuzz/ harness are included, and the module boundaries keep parsing logic well isolated.

API Design - The API is deliberately familiar: streams implement Read, Write, and Seek, and storage navigation mirrors filesystem paths (/foo/bar), so the README example gets you reading and writing streams in a handful of lines. In-place mutation is transparent to the caller.