fsys 0.1.0

Adaptive file and directory IO for Rust — fast, hardware-aware, multi-strategy.
Documentation

FSYS (fsys-rs) is a low-level filesystem abstraction for Rust, designed for storage engines, databases, and any application that needs predictable, high-performance file IO with explicit control over durability.

It exists because the standard library's file IO is general-purpose by design, it has to work everywhere, behave reasonably on every platform, and never surprise a casual user. Storage engines need the opposite: they need to know exactly what's happening, pick the fastest strategy their hardware allows, and pay zero cost for features they don't use.

Status: Early development. The public API is not yet stable. Expect breaking changes until 0.8.0.

 

Design goals

  • Hardware-aware. Detect drive type (NVMe, SSD, HDD) and capabilities (Power Loss Protection, queue depth, optimal block size) at startup. Pick defaults that match the device.
  • Multi-strategy durability. Support fsync, fdatasync, NVMe passthrough flush, and Phantom Buffer modes. The caller picks the tradeoff; fsys doesn't decide for them.
  • Adaptive dispatch. Route single writes through a low-latency solo lane and bulk writes through a group-commit lane. The dispatcher switches automatically based on load.
  • Cross-platform. Linux, macOS, Windows. Best available path on each, with honest fallbacks where the OS doesn't expose the primitive.
  • Zero magic. Every strategy is explicit. No hidden buffering, no unexpected flushes, no surprises in the latency tail.

Non-goals

  • High-level filesystem features (locking semantics, watch APIs, path manipulation).
  • Replacing std::fs for general use.
  • Async-runtime integration in the core. Async wrappers may live in a separate crate.

Status & roadmap

Current state: scaffolding only. The crate compiles; the API surface is empty. Active development is targeting:

  • 0.1.x — [DEV]: Initial Setup - Project planning and basic setup.
  • 0.2.x — [DEV]: Scaffolding - Structure, configuration, and system information.
  • 0.3.x — [DEV]: Foundation - Module libraries and base functionality.
  • 0.4.x — [DEV]: Construction - IO Pipelines, directory control, and file access.
  • 0.5.x — [DEV]: Development - Advanced API and final features.
  • 0.6.x — [DEV]: Optimization - Testing, performance tuning, and error hardening.
  • 0.7.x — [ALPHA]: Completion - Final adjustments, optimizations, and polishing.
  • 0.8.x — [BETA]: Public Testing - Issue tracking, performance monitoring,and patches.
  • 0.9.x — [RC]: Release Candidate - Production-ready (pending further issues).
  • 1.0.0 — Stable API - public release.

The roadmap is aspirational, not a schedule. Versions ship when they're right, not when the calendar agrees.

Installation

[dependencies]
fsys = "0.1.0"

The crate is published to reserve the name. Do not depend on it for production work until at least 0.8.0.

Minimum supported Rust version

1.75. The MSRV may be raised in any minor version before 1.0.0. After 1.0.0, MSRV bumps require a minor version bump.

Coming Soon

LICENSE

Licensed under the Apache License version 2.0 [ LICENSE-APACHE ], or the MIT License [ LICENSE-MIT ]; otherwise known as the ("License Agreement"); you are permitted to use this software, its source code, documentation, concepts, and any of the associated contents, within the limitations defined by the "License Agreement".