store-io 0.6.0

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, 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::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 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 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, 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

[dependencies]
store-io = "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.