Crate rsfs_tokio

A generic filesystem with disk and in-memory implementations.

Reason for existence

The std::fs module provides functions to manipulate the filesytem, and these functions are good. However, if you have code that uses std::fs, it is difficult to ensure that your code handles errors properly because generally, you are not testing on an already broken machine. You could attempt to set up FUSE, which, although doable, is involved.

This crate provides a generic filesystem with various implementations. At the moment, only normal (non-injectable) disk and in-memory implementations are provided. In the future, an error-injectable shim around the in-memory file system will be provided to help trigger filesystem errors in unit tests.

The intent of this crate is for you to use the generic rsfs::GenFS everywhere where you use std::fs in your code. Your main.rs can use rsfs::disk::FS to get default disk behavior while your tests use rsfs::mem::test::FS (once it exists) to get an in-memory filesystem that can have errors injected.

An in-memory filesystem

There existed no complete in-process in-memory filesystem when I wrote this crate; the implementation in rsfs::mem should suffice most needs.

rsfs::mem is a platform specific module that pub uses the proper module based off the builder’s platform. To get a platform agnostic module, you need to use the in-memory platform you desire. Thus, if you use rsfs::mem::unix, you will get an in-memory system that follows Unix semantics. If you use rsfs::mem::windows, you will get an in-memory system that follows Windows semantics (however, you would have to write that module first).

This means that rsfs::mem aims to essentially be an in-memory drop in for std::fs and forces you to structure your code in a cross-platform way. rsfs::mem::unix aims to be a Unix specific drop in that buys you Unix semantics on all platforms.

Caveats

The current in-memory filesystems are only implemented for Unix. This means that the only cross-platform in-memory filesystem is specifically rsfs::mem::unix. Window’s users can help by implementing the in-memory analog for Windows.

The in-memory filesystem is implemented using some unsafe code. I deemed this necessary after working with the recursive data structure that is a filesystem through an Arc/RwLock for too long. The code is pretty well tested; there should be no problems. The usage of unsafe, in my opinion, makes the code much clearer, but it did require special care in some functions.

Documentation credit

This crate copies a lot of the documentation and examples that currently exist in std::fs. It not only makes it easier for people to migrate straight to this crate, but makes this crate much more understandable. This crate includes Rust’s MIT license in its repo for further attribution purposes.

Modules

• disk
  A zero cost wrapper around std::fs.
• mem
  An in-memory filesystem.
• unix_ext
  Unix specific traits that extend the traits in rsfs.

Traits

• DirBuilder
  A builder used to create directories.
• DirEntry
  Entries returned by the iterator returned from read_dir.
• File
  A reference to an open file on the filesystem.
• FileType
  Returned from Metadata::file_type, this trait represents the type of a file.
• GenFS
  The single filesystem underpinning all filesystem operations.
• Metadata
  Metadata information about a file.
• OpenOptions
  Options and flags which can be used to configure how a file is opened.
• Permissions
  Representation of the various permissions on a file.