Overview
Werunos provides high-performance ext4 and btrfs read-write support in userspace. It mounts volumes directly as native Windows drives via WinFsp, utilizing structured B-tree walks, logical-to-physical chunk translation, native circular JBD2 journaling, B-tree Copy-on-Write (CoW) commits, and transparent compression segment decoding without any kernel modules. With the completion of all three core engineering phases, the driver is now fully complete, stable, and ready for production use.
Werunos features a complete userspace Btrfs engine. It decodes the superblock system chunk array, resolves complex chunk trees, performs native Copy-on-Write (CoW) root commits, and supports transparent on-the-fly decompressions for zlib, LZO, and ZSTD extents.
Internal Topology
Phased Roadmap
Core Performance, Tooling & Btrfs
- SafeDevice sector LRU block cache
- Real Btrfs ZSTD decompression integration
- Btrfs transparent Zlib write compression
- Multi-tree Btrfs FSCK verifier
Advanced Trees & Allocation
- Btrfs recursive multi-level index splits
- Ext4 multi-depth extent trees (Depth > 0)
- Ext4 in-inode and external block EA writes
- Complete xattr read-modify-write engine
Native Transactions
- Btrfs leaf and node Copy-on-Write updates
- Btrfs superblock root pointer serialization
- Btrfs superblock CRC32c checksum verification
- Ext4 active transaction memory write buffering
- Ext4 circular JBD2 descriptor and commit blocks
- Standard FUSE named-return commit propagation
- Read-Only Safety Switch (--ro) for mounts
- Dynamic partition superblock filesystem probing
Capabilities
Ext4 & Btrfs Feature Comparison Matrix
| Operation | Ext4 Support | Btrfs Support | Technical Implementation / Detail |
|---|---|---|---|
| File Reading | ✔ Yes | ✔ Yes | Ext4: extent B-tree walk, block caching. Btrfs: inline/regular extents, chunk tree logical maps. |
| File Writing | ✔ Yes | ✔ Yes | Ext4: full block allocator, extent appending. Btrfs: inline/regular extents, dynamic block allocator with recursive multi-level B-tree node/leaf splitting. |
| Directory Ops | ✔ Yes | ✔ Yes | Creating directories (with ./..), readdir traversal, directory entry unlinking. |
| File Creation / Deletion | ✔ Yes | ✔ Yes | Ext4: inode allocation, group block reclaim. Btrfs: inode generation, leaf deletion of index/item keys. |
| Chmod / Chown | ✔ Yes | ✔ Yes | Mutates permission mode, uid, and gid bits, recalculating CRCs/checksums dynamically. |
| File Truncation | ✔ Yes | ✔ Yes | Supports resizing files (grow / shrink). Ext4: extent tree splitting. Btrfs: Copy-on-Write leaf updates. |
| Links (Hard & Sym) | ✔ Yes | ✔ Yes | Symlinks (fast/slow pathways). Hard links update link counts and references. |
| Filesystem FSCK | ✔ Yes | ✔ Yes | Ext4: 5-phase validation and auto-repairs. Btrfs: superblock, chunk map, and recursive node CRC32c verifications. |
| Compression Support | ✘ No | ✔ Yes | Btrfs: transparent decompression of zlib, LZO, and ZSTD extents, with dynamic Zlib write compression. |
Crash Safety
- jbd2 journal replay & native commits (ext4)
- orphan inode cleanup (ext4)
- external redo log fallback (ext4)
- native Copy-on-Write root updates (btrfs)
- superblock flush & checksum updates (both)
- graceful fallback on replay failure (ext4)
- recovery flag auto-clear (ext4)
- read-only safety mount option (--ro)
Integrity & Partitions
- 5-phase fsck (ext4)
- bitmap & block verification (ext4)
- auto-repair with
--fixflag (ext4) - B-tree CRC32c checksum validation (btrfs)
- GPT & MBR partition tables
- raw disk images (both
.imgfiles) - sector-aligned physical disk I/O
- dynamic superblock filesystem auto-detection
Source Structure
. ├── main.go CLI entry point, mount/fsck dispatch ├── install.go WinFsp installer ├── block/ │ ├── device.go PartitionReader, wraps disk I/O │ ├── aligned.go sector-aligned reads/writes │ ├── gpt.go GPT parser │ ├── mbr.go MBR parser │ └── enum_windows.go Windows disk enumeration ├── host/ │ ├── bridge.go WinFsp FUSE bridge (16 ops) │ └── handles.go file/dir handle tables ├── fs/ │ └── fs.go unified FileSystem interface ├── ext4/ │ └── fs.go ext4 FileSystem adapter wrapper ├── btrfs/ │ ├── super.go superblock & sys chunk parsing │ ├── tree.go B-tree walks & logical translation │ ├── types.go node, key, leaf structures │ ├── compress.go zlib & LZO decompression segment decoding │ ├── writer.go leaf insert/update/delete primitives │ └── fs.go btrfs FileSystem adapter (16 ops) ├── vfs/ │ ├── core.go ext4 Walk, core mapping │ ├── super.go Superblock definitions │ ├── bgdesc.go Block group descriptors │ ├── inodes.go Inode read/write │ ├── extents.go Extent B-tree walks │ ├── directory.go Directory reading │ ├── dirent.go Entry add/remove │ ├── allocate.go Block/inode allocator │ ├── reclaim.go Block/inode freeing │ ├── writer.go File writing, extent append │ ├── reader.go File reading, extent walk │ ├── jbd2.go Journal replay engine │ ├── redolog.go Crash-safe redo log │ ├── symlinks.go Fast/slow symlink resolution │ └── health.go fsck implementation └── docs/ └── ext4/ (28 files) ext4 on-disk reference
Usage
werunos devices
List all physical disks, partition tables, and auto-detected filesystems.
werunos mount <letter> <disk> <part> [--ro]
Mount an ext4 or btrfs physical partition as a Windows drive letter. Pass --ro for read-only safety.
werunos mount G: 0 4 --ro
werunos mount <letter> <imagePath>
Mount a raw ext4 or btrfs disk image file directly as a Windows drive letter.
werunos mount Z: btrfs_test.img
werunos fsck [--fix] <device> [<part>]
5-phase integrity check across block bitmaps, inode bitmaps, inode structures, superblock counts, and directory entries (ext4 only). Pass --fix to auto-correct mismatched counts.
werunos fsck --fix \\.\PhysicalDrive0 4
werunos install [--force]
Download, verify, and silently install WinFsp directly from the CLI with a live percentage status bar. Pass --force or -f to force a clean re-installation. Requires Administrator privileges.
werunos <device> [<part>]
Without a subcommand, probe partitions on a device or list the root directory of an ext4/btrfs volume.
werunos testfs.img
Known Boundaries
| Limitation | Impact | Rationale |
|---|---|---|
| No encryption | EXT4_ENCRYPT_FL / encrypted files skipped | Requires kernel keyring integration |
| No metadata checksums | metadata_csum not verified or updated | Checksum verification would add ~200 lines |