An async virtual filesystem interface in Rust.
Lunchbox provides a common interface that can be used to interact with any filesystem (e.g. a local FS, in-memory FS, zip filesystem, etc). This interface closely matches tokio::fs::
so it's easy to get started with.
High level features:
- Support for read only filesystems and read/write filesystems
- A built-in implementation for local filesystems
- An async interface
- WASM support
Getting started
Add lunchbox to your Cargo.toml:
[]
= "0.1"
Step 1: Load a filesystem
At its core, Lunchbox provides a ReadableFileSystem
and a WritableFileSystem
trait. These traits provide analogues for all the functions available in tokio::fs
.
We'll use the built in LocalFS
, but you can use anything that implements one of the filesystem traits above.
use ReadableFileSystem;
use LocalFS;
// Create a lunchbox filesystem that uses the root of your local filesystem as its root
let local_fs = new?;
// Create a lunchbox filesystem that uses `/tmp` as its root.
// `/some/path` inside the filesystem would be translated to `/tmp/some/path`
// on your local filesystem
let local_fs = with_base_dir.await?;
Note: using LocalFS
requires the localfs
feature
Step 2: Use it instead of tokio::fs::...
Instead of
.await
canonicalize
you'd write
local_fs.canonicalize.await
Details
Path
s
We can't use std::path::Path
directly because it contains methods that directly access the filesystem (e.g. exists
) and is not portable across OSs (e.g. a path on Windows is different than a path on Unix).
As an alternative, we use the relative_path crate to give us platform-independent paths. We also provide an extension trait (LunchboxPathUtils
) to add methods like exists
. This is available as lunchbox::path::Path
and lunchbox::path::PathBuf
.
Methods in the lunchbox traits generally accept anything that implements AsRef<lunchbox::path::Path>
. This means you can use str
or String
directly as you would with standard library paths. See the relative_path docs for more details.
Trait methods
In the below methods, note that PathType
is just an alias for AsRef<lunchbox::path::Path> + Send
.
ReadableFileSystem
contains the following methods
// Open a file
async
WritableFileSystem
contains
// Create a file
async
These work with ReadableFile
s and WritableFile
s respectively:
/// A readable file
/// A file that supports both reads and writes
Note that all WritableFile
s must be ReadableFile
s and all WritableFileSystem
s must be ReadableFileSystem
s as well.
WASM
For WASM builds, the Send
and Sync
bounds are removed from all parts of the interface.