What it is
store-io replaces fsys as the only code in a database stack that touches files and devices. It is built for:
- Write-ahead logs and commit layers: small, sector-aligned, positioned writes at low queue depth, durable on completion on power-safe devices and with the minimum barrier cost on volatile-cache devices; exact receipts with out-of-order completion; raw, uninterpreted recovery reads.
- Columnar and page stores: large vectored writes, dependent writes across files and devices with at most one flush per device, release on compaction, and clone for backup (planned for a 0.6.x release).
- Buffer pools: batched direct reads into caller-owned aligned frames, explicit cancellable prefetch, per-range errors.
- Backup and replication shipping: streaming direct-read copies with bounded memory.
- Embedded deployments: one portable container file, unprivileged, with zero idle wakeups.
What it is not
- Not a general-purpose file manager. It does not replace
std::fsfor ordinary files. - Not a log or a database. It has no frames, sequence numbers, payload checksums, commit windows or recovery policy: those belong to the caller.
- Not an async runtime. The core has none; async adapters live in separate crates.
Design rules
- Durability classes from evidence. Power-safe, flush-required, unverified or unsafe, decided per path and per device. Operating-system cache toggles and vendor tables never promote a device.
- Unforgeable receipts. Positions, write tickets and receipts are distinct opaque types. A sequence number never type-checks as a byte position, and a barrier is never a silent no-op.
- Fail-stop. A failed write or flush poisons the device's barrier domain. A flush is never retried, and success is never reported after a failed one.
- Opens never touch caller data. A read-only open, a scan and a lock acquisition change nothing: no byte, size, timestamp or directory entry. A writable open writes the volume record (the next owner generation) and may heal one torn metadata write before it returns, so the container's bytes and modification time change; caller data is never modified.
- No hidden latency. No timers, no polling threads, no group-commit windows, no idle wakeups.
- Measured, not claimed. Every performance number names the device, durability class, filesystem, OS and kernel, and fsync status, and is measured against fio on the same box: gated, or published where its gate is not yet set.
Quick start
use ;
// First run: create (the device is probed; unsafe devices are refused).
let store = create?;
let wal = store.provision_append_region?;
// Durable when this returns: one write, one flush.
let = wal.append_durable?;
println!;
// Many records: packed into the device's own buffers, one write, one flush.
let mut batch = wal.batch;
batch.append?;
batch.append?;
let = batch.commit?;
Documentation
| Document | What it covers |
|---|---|
docs/GUIDE.md |
A walk through store-io: receipts, regions, batches, many writers, small objects, recovery, the device report, errors, space, recycling, tuning. |
docs/API.md |
Every public item, grouped by purpose. |
docs/DURABILITY.md |
The durability model: classes, evidence, trust, receipts, flush sharing, fail-stop. |
docs/PLATFORMS.md |
What store-io does on Windows, Linux and macOS, and the known limits of each. |
docs/FORMAT.md |
The on-disk formats: format 2 (made by 0.5 and later), format 1 (made by 0.4 and earlier, read-only from 0.5), and the export record (Part III). |
CHANGELOG.md |
Every change. |
Installation
[]
= "0.6"
The store-io command-line tool (store-io probe <dir>, store-io info <store>, store-io copy <old> <new>) is behind the cli feature.
Contributing
See dev/DIRECTIVES.md for engineering standards and the definition of done, and REPS.md for the Rust Efficiency & Performance Standards. Before a PR: cargo fmt --all, cargo clippy --workspace --all-targets --all-features -- -D warnings, and cargo test --workspace --all-features must be clean.