treehouse/crates/treehouse/src/vfs.rs

//! The treehouse virtual file system.
//!
//! Unlike traditional file systems, there is no separation between directories and files.
//! Instead, our file system is based on _entries_, which may have specific, optional, well-typed
//! metadata attached to them.
//! A directory is formed by returning a list of paths from [`dir`][Dir::dir], and a file is
//! formed by returning `Some` from [`content`][Dir::content].
//!
//! This makes using the file system simpler, as you do not have to differentiate between different
//! entry kinds. All paths act as if they _could_ return byte content, and all paths act as if they
//! _could_ have children.
//!
//! # Composability
//!
//! [`Dir`]s are composable. The [`Dir`] itself starts off with the root path ([`VPath::ROOT`]),
//! which may contain further [`dir`][Dir::dir] entries, or content by itself.
//! This makes it possible to nest a [`Dir`] under another [`Dir`].
//!
//! Additionally, there's also the inverse operation, [`Cd`] (named after the `cd`
//! _change directory_ shell command), which returns a [`Dir`] viewing a subpath within another
//! [`Dir`].
//!
//! # Building directories
//!
//! In-memory directories can be composed using the following primitives:
//!
//! - [`EmptyEntry`] - has no metadata whatsoever.
//! - [`BufferedFile`] - root path content is the provided byte vector.
//! - [`MemDir`] - a [`Dir`] containing a single level of other [`Dir`]s inside.
//!
//! Additionally, for interfacing with the OS file system, [`PhysicalDir`] is available,
//! representing a directory stored on the disk.
//!
//! # Virtual paths
//!
//! Entries within directories are referenced using [`VPath`]s (**v**irtual **path**s).
//! A virtual path is composed out of any amount of `/`-separated components.
//!
//! There are no special directories like `.` and `..` (those are just normal entries, though using
//! them is discouraged). [`VPath`]s are always relative to the root of the [`Dir`] you're querying.
//!
//! A leading or trailing slash is not allowed, because they would have no meaning.
//!
//! [`VPath`] also has an owned version, [`VPathBuf`].

use std::{
    fmt::{self, Debug},
    ops::{ControlFlow, Deref},
    sync::Arc,
};

mod anchored;
pub mod asynch;
mod cd;
mod content_version_cache;
mod edit;
mod empty;
mod file;
mod mem_dir;
mod overlay;
mod path;
mod physical;

pub use anchored::*;
pub use cd::*;
pub use content_version_cache::*;
pub use edit::*;
pub use empty::*;
pub use file::*;
pub use mem_dir::*;
pub use overlay::*;
pub use path::*;
pub use physical::*;

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct DirEntry {
    pub path: VPathBuf,
}

pub trait Dir: Debug {
    /// List all entries under the provided path.
    fn dir(&self, path: &VPath) -> Vec<DirEntry>;

    /// Return the byte content of the entry at the given path.
    fn content(&self, path: &VPath) -> Option<Vec<u8>>;

    /// Get a string signifying the current version of the provided path's content.
    /// If the content changes, the version must also change.
    ///
    /// Returns None if there is no content or no version string is available.
    fn content_version(&self, path: &VPath) -> Option<String>;

    /// Returns a path relative to `config.site` indicating where the file will be available
    /// once served.
    ///
    /// May return `None` if the file is not served.
    fn anchor(&self, _path: &VPath) -> Option<VPathBuf> {
        None
    }

    /// If a file can be written persistently, returns an [`EditPath`] representing the file in
    /// persistent storage.
    ///
    /// An edit path can then be made into an [`Edit`].
    fn edit_path(&self, _path: &VPath) -> Option<EditPath> {
        None
    }
}

impl<T> Dir for &T
where
    T: Dir,
{
    fn dir(&self, path: &VPath) -> Vec<DirEntry> {
        (**self).dir(path)
    }

    fn content(&self, path: &VPath) -> Option<Vec<u8>> {
        (**self).content(path)
    }

    fn content_version(&self, path: &VPath) -> Option<String> {
        (**self).content_version(path)
    }

    fn anchor(&self, path: &VPath) -> Option<VPathBuf> {
        (**self).anchor(path)
    }

    fn edit_path(&self, path: &VPath) -> Option<EditPath> {
        (**self).edit_path(path)
    }
}

#[derive(Clone)]
pub struct DynDir {
    arc: Arc<dyn Dir + Send + Sync>,
}

impl Dir for DynDir {
    fn dir(&self, path: &VPath) -> Vec<DirEntry> {
        self.arc.dir(path)
    }

    fn content(&self, path: &VPath) -> Option<Vec<u8>> {
        self.arc.content(path)
    }

    fn content_version(&self, path: &VPath) -> Option<String> {
        self.arc.content_version(path)
    }

    fn anchor(&self, path: &VPath) -> Option<VPathBuf> {
        self.arc.anchor(path)
    }

    fn edit_path(&self, path: &VPath) -> Option<EditPath> {
        self.arc.edit_path(path)
    }
}

impl fmt::Debug for DynDir {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Debug::fmt(&*self.arc, f)
    }
}

impl Deref for DynDir {
    type Target = dyn Dir + Send + Sync;

    fn deref(&self) -> &Self::Target {
        &*self.arc
    }
}

pub trait ToDynDir {
    fn to_dyn(self) -> DynDir;
}

impl<T> ToDynDir for T
where
    T: Dir + Send + Sync + 'static,
{
    fn to_dyn(self) -> DynDir {
        DynDir {
            arc: Arc::new(self),
        }
    }
}

pub trait AnchoredAtExt {
    fn anchored_at(self, at: VPathBuf) -> Anchored<Self>
    where
        Self: Sized;
}

impl<T> AnchoredAtExt for T
where
    T: Dir,
{
    fn anchored_at(self, at: VPathBuf) -> Anchored<Self> {
        Anchored::new(self, at)
    }
}

pub fn walk_dir_rec(dir: &dyn Dir, path: &VPath, f: &mut dyn FnMut(&VPath) -> ControlFlow<(), ()>) {
    for entry in dir.dir(path) {
        match f(&entry.path) {
            ControlFlow::Continue(_) => (),
            ControlFlow::Break(_) => return,
        }
        walk_dir_rec(dir, &entry.path, f);
    }
}

pub fn url(site: &str, dir: &dyn Dir, path: &VPath) -> Option<String> {
    let anchor = dir.anchor(path)?;
    if let Some(version) = dir.content_version(path) {
        Some(format!("{}/{anchor}?v={version}", site))
    } else {
        Some(format!("{}/{anchor}", site))
    }
}