am-fs-core 0.2.0

Pure-Rust block-device framework — BlockRead/BlockDevice traits + FileDevice + CallbackDevice + LRU cache. Foundation crate for fs-* drivers and img-* containers.
Documentation
  • Coverage
  • 67.96%
    70 out of 103 items documented0 out of 57 items with examples
  • Size
  • Source code size: 130.76 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 2.09 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 8s Average build duration of successful builds.
  • all releases: 9s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • antimatter-studios/rust-fs-core
    0 0 0
  • crates.io
  • Dependencies
    • —
  • Versions
  • Owners
  • christhomas

fs-core

Pure-Rust block-device framework. The shared substrate every filesystem driver and disk-image reader plugs into.

What it gives you

  • BlockRead — read-only random-access block device (read_at + size_bytes)
  • BlockDevice: BlockRead — adds optional write_at / flush / is_writable
  • FileDevice — backed by a regular file, optional read-only
  • CallbackDevice — backed by host-process-owned callbacks (FFI from Swift / Go / C++)
  • CachingDevice — LRU read-cache decorator wrapping any BlockDevice
  • A unified Error type with a Custom(String) escape hatch so each driver can lift its own internal errors to the trait boundary

Intended consumers

Filesystem drivers — fs-ext4, fs-ntfs, future am-fs-exfat, am-fs-hfsplus, am-fs-apfs, am-fs-fat32, am-fs-fat16, am-fs-squashfs, am-fs-iso9660. Each only writes format-specific code; the block plumbing comes from here.

Disk-image readers — am-img-qcow2, am-img-vhd, am-img-vhdx, am-img-vmdk; future am-img-vdi, am-img-raw. Same pattern: format-specific container logic, shared block I/O.

Block-layer utilities — am-partitions (GPT/MBR probe), future am-block-luks, am-block-lvm, am-block-mdraid. Same trait, opposite direction: consumes a BlockRead to expose slices of it.

Layout

src/
  lib.rs              public re-exports
  error.rs            Error / Result
  block.rs            BlockRead + BlockDevice traits
  file_device.rs      FileDevice (backed by std::fs::File)
  callback_device.rs  CallbackDevice (FFI-friendly)
  caching_device.rs   CachingDevice (LRU decorator)
tests/
  cache.rs            CachingDevice + interop tests

Roadmap

Planned additions (not yet implemented):

  • SliceReader — currently lives in am-partitions, but slicing is a generic block-layer concern. Will move here so any BlockRead consumer (not just partition users) can grab it. am-partitions will keep a re-export for backwards compatibility.
  • ReadOnlyDevice<T> — wrapper that takes any BlockRead / BlockDevice and rejects writes regardless of the inner type's capabilities. Useful for type-level "give me this image strictly read-only" guarantees.
  • Logger hook — pluggable set_logger(callback) so consuming crates can route diagnostics to a host-provided sink without each crate hard-coding a logging dependency.
  • IoStats hook — counters for reads/writes, bytes-read/bytes-written, cache hit rate. CachingDevice already exposes some of these internally; the plan is to generalise across every adapter.

License

MIT.