store-io 0.3.1

Durable storage I/O for Rust databases: evidence-based durability classes, unforgeable receipts, direct I/O, io_uring and IOCP.
Documentation

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, clone for backup.
  • 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::fs for 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 modify nothing. No open, scan or lock acquisition ever changes caller bytes, sizes, timestamps or directory entries.
  • 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 gated against fio on the same box.

Quick start

use store_io::{Store, StoreOptions};

// First run: create (the device is probed; unsafe devices are refused).
let store = Store::create("data/orders", StoreOptions::default())?;
let wal = store.provision_append_region("wal", 256 << 20)?;

// Durable when this returns: one write, one flush.
let (pos, receipt) = wal.append_durable(b"order 1001: 3 widgets")?;
println!("durable through {} at class {}", receipt.durable_through(), receipt.class());

// Many records: packed into the device's own buffers, one write, one flush.
let mut batch = wal.batch();
batch.append(b"order 1002")?;
batch.append(b"order 1003")?;
let (start, receipt) = 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 and Linux, and the known limits of each.
docs/FORMAT.md The on-disk format of a store.
CHANGELOG.md Every change.

Installation

[dependencies]
store-io = "0.3"

The store-io command-line tool (store-io probe <dir>, store-io info <store>) 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.