Flesh out crate

Cargo.lock

@@ -2362,6 +2362,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 name = "vfs"
 version = "0.1.0"
 dependencies = [
+ "crossbeam-channel 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "notify 4.0.15 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 

vfs/Cargo.toml

@@ -3,8 +3,12 @@ name = "vfs"
 version = "0.1.0"
 authors = ["Lucien Greathouse <me@lpghatguy.com>"]
 edition = "2018"
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/rojo-rbx/rojo"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
 notify = "4.0.15"
+crossbeam-channel = "0.4.0"

vfs/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2020 The Rojo Developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

vfs/README.md

@@ -0,0 +1,5 @@
+# [vfs]
+Name pending. Implementation of a virtual filesystem with a configurable backend and file watching.
+
+## License
+[vfs] is available under the terms of the MIT license. See [LICENSE.txt](LICENSE.txt) or <https://opensource.org/licenses/MIT> for more details.

vfs/src/lib.rs

@@ -17,12 +17,16 @@ mod sealed {
     impl Sealed for StdBackend {}
 }
 
+/// Backend that can be used to create a
+///
+/// This trait is sealed and cannot not be implemented outside this crate.
 pub trait VfsBackend: sealed::Sealed {
     fn read(&mut self, path: &Path) -> io::Result<Vec<u8>>;
     fn write(&mut self, path: &Path, data: &[u8]) -> io::Result<()>;
     fn read_dir(&mut self, path: &Path) -> io::Result<ReadDir>;
     fn metadata(&mut self, path: &Path) -> io::Result<Metadata>;
 
+    fn event_receiver(&mut self) -> crossbeam_channel::Receiver<VfsEvent>;
     fn watch(&mut self, path: &Path) -> io::Result<()>;
     fn unwatch(&mut self, path: &Path) -> io::Result<()>;
 }
@@ -49,6 +53,7 @@ impl Iterator for ReadDir {
     }
 }
 
+#[derive(Debug)]
 pub struct Metadata {
     is_file: bool,
 }
@@ -63,6 +68,14 @@ impl Metadata {
     }
 }
 
+#[derive(Debug)]
+#[non_exhaustive]
+pub enum VfsEvent {
+    Create(PathBuf),
+    Write(PathBuf),
+    Remove(PathBuf),
+}
+
 struct VfsLock {
     backend: Box<dyn VfsBackend>,
 }
@@ -90,11 +103,18 @@ impl VfsLock {
     }
 }
 
+/// A virtual filesystem with a configurable backend.
 pub struct Vfs {
     inner: Mutex<VfsLock>,
 }
 
 impl Vfs {
+    /// Creates a new `Vfs` with the default backend, `StdBackend`.
+    pub fn new_default() -> Self {
+        Self::new(StdBackend::new())
+    }
+
+    /// Creates a new `Vfs` with the given backend.
     pub fn new<B: VfsBackend + 'static>(backend: B) -> Self {
         let lock = VfsLock {
             backend: Box::new(backend),
@@ -105,12 +125,23 @@ impl Vfs {
         }
     }
 
+    /// Read a file from the VFS, or the underlying backend if it isn't
+    /// resident.
+    ///
+    /// Roughly equivalent to [`std::fs::read`][std::fs::read].
+    ///
+    /// [std::fs::read]: https://doc.rust-lang.org/stable/std/fs/fn.read.html
     pub fn read<P: AsRef<Path>>(&self, path: P) -> io::Result<Arc<Vec<u8>>> {
         let path = path.as_ref();
         let mut inner = self.inner.lock().unwrap();
         inner.read(path)
     }
 
+    /// Write a file to the VFS and the underlying backend.
+    ///
+    /// Roughly equivalent to [`std::fs::write`][std::fs::write].
+    ///
+    /// [std::fs::write]: https://doc.rust-lang.org/stable/std/fs/fn.write.html
     pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(&self, path: P, contents: C) -> io::Result<()> {
         let path = path.as_ref();
         let contents = contents.as_ref();
@@ -118,6 +149,11 @@ impl Vfs {
         inner.write(path, contents)
     }
 
+    /// Read all of the children of a directory.
+    ///
+    /// Roughly equivalent to [`std::fs::read_dir`][std::fs::read_dir].
+    ///
+    /// [std::fs::read_dir]: https://doc.rust-lang.org/stable/std/fs/fn.read_dir.html
     pub fn read_dir<P: AsRef<Path>>(&self, path: P) -> io::Result<ReadDir> {
         let path = path.as_ref();
         let mut inner = self.inner.lock().unwrap();

vfs/src/noop_backend.rs

@@ -1,8 +1,9 @@
 use std::io;
 use std::path::Path;
 
-use crate::{Metadata, ReadDir, VfsBackend};
+use crate::{Metadata, ReadDir, VfsBackend, VfsEvent};
 
+/// `VfsBackend` that returns an error on every operation.
 #[non_exhaustive]
 pub struct NoopBackend;
 
@@ -41,6 +42,10 @@ impl VfsBackend for NoopBackend {
         ))
     }
 
+    fn event_receiver(&mut self) -> crossbeam_channel::Receiver<VfsEvent> {
+        crossbeam_channel::never()
+    }
+
     fn watch(&mut self, _path: &Path) -> io::Result<()> {
         Err(io::Error::new(
             io::ErrorKind::Other,

vfs/src/std_backend.rs

@@ -2,21 +2,49 @@ use std::fs;
 use std::io;
 use std::path::Path;
 use std::sync::mpsc;
+use std::thread;
 use std::time::Duration;
 
+use crossbeam_channel::Receiver;
 use notify::{watcher, DebouncedEvent, RecommendedWatcher, RecursiveMode, Watcher};
 
-use crate::{DirEntry, Metadata, ReadDir, VfsBackend};
+use crate::{DirEntry, Metadata, ReadDir, VfsBackend, VfsEvent};
 
+/// `VfsBackend` that uses `std::fs` and the `notify` crate.
 pub struct StdBackend {
     watcher: RecommendedWatcher,
-    watcher_receiver: mpsc::Receiver<DebouncedEvent>,
+    watcher_receiver: Receiver<VfsEvent>,
 }
 
 impl StdBackend {
     pub fn new() -> StdBackend {
-        let (tx, rx) = mpsc::channel();
-        let watcher = watcher(tx, Duration::from_millis(50)).unwrap();
+        let (notify_tx, notify_rx) = mpsc::channel();
+        let watcher = watcher(notify_tx, Duration::from_millis(50)).unwrap();
+
+        let (tx, rx) = crossbeam_channel::unbounded();
+
+        thread::spawn(move || {
+            for event in notify_rx {
+                match event {
+                    DebouncedEvent::Create(path) => {
+                        tx.send(VfsEvent::Create(path))?;
+                    }
+                    DebouncedEvent::Write(path) => {
+                        tx.send(VfsEvent::Write(path))?;
+                    }
+                    DebouncedEvent::Remove(path) => {
+                        tx.send(VfsEvent::Remove(path))?;
+                    }
+                    DebouncedEvent::Rename(from, to) => {
+                        tx.send(VfsEvent::Remove(from))?;
+                        tx.send(VfsEvent::Create(to))?;
+                    }
+                    _ => {}
+                }
+            }
+
+            Result::<(), crossbeam_channel::SendError<VfsEvent>>::Ok(())
+        });
 
         Self {
             watcher,
@@ -54,6 +82,10 @@ impl VfsBackend for StdBackend {
         })
     }
 
+    fn event_receiver(&mut self) -> crossbeam_channel::Receiver<VfsEvent> {
+        self.watcher_receiver.clone()
+    }
+
     fn watch(&mut self, path: &Path) -> io::Result<()> {
         self.watcher
             .watch(path, RecursiveMode::NonRecursive)