Crate async_fs_io 

async-fs-io

Async-first filesystem primitives for Tokio applications that must keep file I/O centralized, bounded, and observable.

The crate provides:

• AsyncFile, an async low-level file handle for sequential and random-access operations;
• bounded whole-file reads that require an explicit byte ceiling;
• streaming directory traversal with one directory entry in flight;
• atomic writes that stream through a temporary file;
• explicit asynchronous temporary-directory cleanup;
• typed filesystem errors with path and operation context.

Large files and directories are never implicitly loaded into memory. Use AsyncFile or the streaming helpers for unbounded data and use bounded reads only when the caller has an explicit size contract.

Enforcing the filesystem boundary

The crate is designed to be the single filesystem boundary for an application. Do not call std::fs, tokio::fs, blocking filesystem APIs, or private wrappers around them anywhere else in the repository.

Run the repository lint with:

./.scripts/lint-fs-io.sh --allow-path src

Copy that command into CI and the repository’s pre-commit hook (this repository runs it in both). In a consuming repository, omit --allow-path src; the consumer has no filesystem backend allowlist. The lint scans production code, tests, benchmarks, and private helpers, and it matches both fully-qualified paths (std::fs::read) and the import statements themselves (use std::fs;, use tokio::fs as t;), so aliasing cannot slip a call past it. Its only allowlist in this repository is the audited backend implementation under src.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE);
• MIT License (LICENSE-MIT). Async-first filesystem primitives with explicit memory bounds.

Structs

AsyncFile

A file handle whose open, read, write, seek, flush, and metadata operations are all asynchronous.

DirectoryEntry

One directory entry. A reader holds at most one entry in addition to the operating system’s own directory stream buffer.

DirectoryReader

An asynchronous directory reader. Call Self::next repeatedly instead of collecting the directory into memory.

ExclusiveLock

An acquired non-blocking exclusive advisory lock.

FileMetadata

Metadata needed without exposing filesystem-specific read helpers.

TempDir

An asynchronously created temporary directory.

TempFile

An asynchronously created temporary file with explicit cleanup.

Enums

DirectoryEntryKind

The kind of an asynchronously inspected directory entry.

FsError

Error from an asynchronous filesystem operation.

Operation

The filesystem operation that failed.

Functions

acquire_exclusive_lock

Acquire a non-blocking exclusive advisory lock on path.

atomic_copy

Atomically copy one existing file to another path.

atomic_write

Stream reader into a temporary sibling file and atomically rename it over target.

atomic_write_string

Atomically replace a file with UTF-8 text.

canonicalize

Canonicalize a path through the asynchronous filesystem boundary.

ensure_dir

Create a directory and all missing parents.

metadata

Return metadata through the async filesystem boundary.

read_bounded

Read a file only when its complete contents fit under max_bytes.

read_string_bounded

Read UTF-8 text only when its complete contents fit under max_bytes.

read_string_bounded_if_exists

Read UTF-8 text only when its complete contents fit under max_bytes, returning None when the file does not exist.

remove_dir_all

Remove a directory tree if it exists.

remove_file

Remove a file, reporting a missing file as an error.

remove_if_exists

Remove a file if it exists.

rename

Rename a file or directory.

set_permissions

Set filesystem permissions through the asynchronous filesystem boundary.

symlink_metadata

Return operating-system metadata without following a symbolic link.

try_exists

Return whether a path exists, preserving errors other than not-found.

write_bytes

Write a bounded caller-owned byte slice to a file, replacing its contents.