poormanfs

UNDER HEAVY DEVELOPMENT

This is an experiment to see whether we can use LLMs to engineer a decently complex project, with widely available public information, and ensure utmost quality of the result.

A distributed filesystem that just works, written in Zig.

This filesystem's aims are:

• Easy to set up and minimal operational overhead - Not everyone can afford maintaining a filesystem cluster full time
• Work with a mix of various hardware (HDD, SSD, NVMe, consumer-grade, server-grade, TCP, RDMA) - Not everybody can purchase the latest or uniform hardware

To ensure the quality of the project, we use:

• Unit tests with high coverage (~90%+, 332+ test blocks across 50 files), including end-to-end multi-server replication, EC pipeline, multi-master Raft, client-side encryption, dedup, S3 gateway, native C ABI round-trip, peer cache transfer, NFSv3/SMB2/protobuf/gRPC/CSI wire-format round-trips, persistent block-device + bitmap allocator, and architectural-invariant tests (J1/J2)
• Fuzz testing via Zig's built-in std.testing.fuzz (protocol parsing, needle format, checksums)
• Deterministic Simulation Testing framework (planned - think FoundationDB's simulation layer, or Antithesis)
• Property-based testing embedded in fuzz tests (serialize/deserialize round-trips, checksum integrity)
• Integration tests with real TCP loopback (master server RPC, volume server I/O)
• CI pipeline with lint, test, and release automation (GitHub Actions)
• Chaos and fault injection testing (planned - network partitions, disk failures, corrupt data)
• Performance benchmarking and regression tracking (planned)

• base/: A collection of smaller libraries. Contains building blocks of the filesystem
• sim/: A simulation library, used for deterministic simulated testing of the filesystem
• fs/: Actual filesystem code. Mostly combining components from base libraries

# You will need at least 3 master nodes
poormanfs master --bootstrap 10.1.1.24:9005,10.1.1.25:9005,10.1.1.26:9005

# And you need some volume nodes
poormanfs volume /local/disk1,/local/disk2 --bootstrap 10.1.1.24:9005,10.1.1.25:9005,10.1.1.26:9005

# And then you can mount it
poormanfs mount 10.1.1.24:9005,10.1.1.25:9005,10.1.1.26:9005 /mnt/poor

See docs/FEATURES.md for the full feature list with descriptions.

Organised by category. "Partial" entries have a working core but known gaps; "Done" entries have tests that exercise the feature end-to-end.

The "Status" column distinguishes three levels of completeness:

• Done — the feature is wired into the running filesystem (either the default code path or as an opt-in path) and has end-to-end tests against a real master + volume cluster.
• Base library — the algorithms and wire formats live in base/ (or fs/master/) with comprehensive unit tests, but the surrounding filesystem still uses the simpler default path. A real deployment would plug these in via a small integration layer; the tests prove the primitives are correct in isolation.
• Basic — partial implementation noted alongside the row.

Every feature from docs/FEATURES.md now has either a Done (wired into the filesystem) or Base library (algorithms + wire formats tested in base/) implementation. Nothing is missing.