blockworx_opfs/

lib.rs

//! A `.bwx` container in origin-private storage.
//!
//! The container's layout — which file, in what order, written before what
//! — is [`blockworx_store`]'s and is not repeated here. What this crate
//! answers is the trait under it: where the bytes of one container go in a
//! browser, and who holds the right to write them.
//!
//! Two values, and the [`Root`] is where a session starts:
//!
//! ```text
//! navigator.storage.getDirectory()   Root        the origin's own directory
//!   doc.bwx/                         Opfs        one container's storage
//!     manifest.jsonl  revs/  assets/ Entry       what the store names
//! ```
//!
//! **Everything here really is asynchronous.** Origin-private storage on
//! the main thread is promises all the way down, so [`Opfs::residency`] is
//! [`Residency::Resident`]: the store reads the container in when it opens
//! it and owes its writes back
//! ([`Container::drain`](blockworx_store::container::Container::drain)),
//! and nothing may resolve a future here by polling it.
//!
//! **What a browser has to be given room for.** Only Chromium has
//! `FileSystemHandle.move()`, so a rename copies and removes rather than
//! moving. Safari has no `createWritable` outside a worker, which is what
//! every write here is made of, so this storage is Chromium and Firefox
//! for now; Safari's way in is the kernel in a worker, over
//! `createSyncAccessHandle`. The lock is the origin's lock manager rather than a `lock`
//! entry, because nothing in a browser can be asked whether the tab that
//! wrote an entry is still open — see [`locks`].

pub mod directory;
pub mod fault;
pub mod file;
pub mod locks;

use std::cell::RefCell;

use wasm_bindgen::JsCast as _;
use web_sys::FileSystemDirectoryHandle;

use blockworx_store::container::MANIFEST;
use blockworx_store::lock::{Claim, Holding};
use blockworx_store::record::WallTime;
use blockworx_store::storage::{Entry, Name, Residency, Storage};

use crate::directory::Depth;
use crate::fault::{mistaken, settled};

pub use crate::directory::Missing;

/// The origin's private directory: where a browser keeps this app's
/// containers, and the only place it keeps them.
#[derive(Clone)]
pub struct Root(FileSystemDirectoryHandle);

impl Root {
    /// # Errors
    /// A page with no origin-private storage — which is every page that is
    /// not a secure context.
    pub async fn open() -> std::io::Result<Self> {
        let origin = web_sys::window()
            .ok_or_else(|| {
                std::io::Error::other(
                    "origin-private storage is reached from a page, and there is none",
                )
            })?
            .navigator()
            .storage();
        let root = settled(origin.get_directory()).await?;
        Ok(Self(
            root.dyn_into().map_err(mistaken("the origin's root"))?,
        ))
    }

    /// The container called `name`, made if it is not there and `missing`
    /// says so.
    ///
    /// A directory, not a document: whether what stands there is a
    /// container is what [`Store::opening`](blockworx_store::handle::Store)
    /// answers.
    ///
    /// # Errors
    /// [`std::io::ErrorKind::NotFound`] for a name nothing stands under and
    /// nothing is to be made, or the browser's refusal.
    pub async fn container(&self, name: &Name, missing: Missing) -> std::io::Result<Opfs> {
        Ok(Opfs {
            dir: directory::directory(&self.0, name.as_str(), missing).await?,
            root: self.0.clone(),
            name: name.clone(),
            held: RefCell::default(),
        })
    }

    /// Every container in the origin, by name and in name order — the
    /// library's list.
    ///
    /// A directory holding a manifest is what counts as one, so a folder
    /// something else in the origin made is not offered as a document.
    ///
    /// # Errors
    /// The browser's refusal.
    pub async fn containers(&self) -> std::io::Result<Vec<Name>> {
        let mut containers = Vec::new();
        for held in directory::directories(&self.0).await? {
            let Some(name) = Name::new(&held) else {
                continue;
            };
            let dir = directory::directory(&self.0, name.as_str(), Missing::IsNothing).await?;
            if directory::holds(&dir, MANIFEST.as_str()).await? {
                containers.push(name);
            }
        }
        containers.sort();
        Ok(containers)
    }

    /// Whether anything already stands under `name` — what a new document
    /// and a rename each ask before they take one.
    ///
    /// # Errors
    /// The browser's refusal.
    pub async fn holds(&self, name: &Name) -> std::io::Result<bool> {
        directory::holds(&self.0, name.as_str()).await
    }

    /// Remove a container and everything in it — the library's delete,
    /// where [`Opfs::discard`] is the store's own and takes only an
    /// emptied one.
    ///
    /// # Errors
    /// [`std::io::ErrorKind::NotFound`] for a name nothing stands under,
    /// or the browser's refusal.
    pub async fn remove(&self, name: &Name) -> std::io::Result<()> {
        directory::remove(&self.0, name.as_str(), Depth::Everything).await
    }

    /// Remove a container no view holds. Its lock is claimed first and kept
    /// until the directory is gone, so a container open in another tab is
    /// refused rather than pulled out from under the session writing it.
    ///
    /// # Errors
    /// [`std::io::ErrorKind::ResourceBusy`] for a container another view
    /// holds, and otherwise as [`Self::remove`].
    pub async fn remove_unheld(&self, name: &Name) -> std::io::Result<()> {
        let Some(_held) = locks::request(&Opfs::lock_name(name)).await? else {
            return Err(std::io::Error::new(
                std::io::ErrorKind::ResourceBusy,
                format!("{name} is open in another tab"),
            ));
        };
        self.remove(name).await
    }
}

/// One container's directory in origin-private storage.
pub struct Opfs {
    /// The origin's root, which a rename and a discard reach the container
    /// through rather than reaching into it.
    root: FileSystemDirectoryHandle,
    dir: FileSystemDirectoryHandle,
    name: Name,
    held: RefCell<Option<locks::Held>>,
}

impl Opfs {
    /// The directory `at` is held in — made along the way where a write is
    /// what asked — and the name it is held under.
    async fn within(
        &self,
        at: &Entry,
        missing: Missing,
    ) -> std::io::Result<(FileSystemDirectoryHandle, String)> {
        let path = segments(at);
        let Some((name, holding)) = path.split_last() else {
            return Err(std::io::Error::new(
                std::io::ErrorKind::InvalidInput,
                format!("{} is the container itself, not an entry in it", self.name),
            ));
        };
        Ok((self.walk(holding, missing).await?, (*name).to_owned()))
    }

    async fn entry(
        &self,
        at: &Entry,
        missing: Missing,
    ) -> std::io::Result<web_sys::FileSystemFileHandle> {
        let (dir, name) = self.within(at, missing).await?;
        directory::file(&dir, &name, missing).await
    }

    async fn walk(
        &self,
        path: &[&str],
        missing: Missing,
    ) -> std::io::Result<FileSystemDirectoryHandle> {
        let mut at = self.dir.clone();
        for segment in path {
            at = directory::directory(&at, segment, missing).await?;
        }
        Ok(at)
    }

    fn lock_name(name: &Name) -> String {
        format!("blockworx/{name}")
    }
}

impl std::fmt::Debug for Opfs {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{} in origin-private storage", self.name)
    }
}

impl Storage for Opfs {
    fn name(&self) -> Name {
        self.name.clone()
    }

    fn names(&self, at: &Entry) -> String {
        if at.as_str().is_empty() {
            return self.name.to_string();
        }
        format!("{}/{at}", self.name)
    }

    fn residency(&self) -> Residency {
        Residency::Resident
    }

    async fn read<'a>(&'a self, at: &'a Entry) -> std::io::Result<Option<Vec<u8>>> {
        let Some(handle) = nothing_there(self.entry(at, Missing::IsNothing).await)? else {
            return Ok(None);
        };
        file::read(&handle).await.map(Some)
    }

    /// A name a *directory* stands under answers `false` rather than the
    /// browser's refusal, which is what a map answers too: this is asked
    /// about entries, and the container's own directories are laid out
    /// rather than looked for.
    async fn exists<'a>(&'a self, at: &'a Entry) -> std::io::Result<bool> {
        match self.entry(at, Missing::IsNothing).await {
            Ok(_) => Ok(true),
            Err(why) if not_an_entry(&why) => Ok(false),
            Err(why) => Err(why),
        }
    }

    async fn write<'a>(&'a self, at: &'a Entry, bytes: &'a [u8]) -> std::io::Result<()> {
        file::write(&self.entry(at, Missing::IsMade).await?, bytes).await
    }

    async fn append<'a>(&'a self, at: &'a Entry, bytes: &'a [u8]) -> std::io::Result<()> {
        file::append(&self.entry(at, Missing::IsMade).await?, bytes).await
    }

    async fn truncate<'a>(&'a self, at: &'a Entry, len: u64) -> std::io::Result<()> {
        file::truncate(&self.entry(at, Missing::IsMade).await?, len).await
    }

    async fn list<'a>(&'a self, dir: &'a Entry) -> std::io::Result<Vec<String>> {
        let within = self.walk(&segments(dir), Missing::IsNothing).await?;
        directory::names(&within).await
    }

    async fn remove<'a>(&'a self, at: &'a Entry) -> std::io::Result<()> {
        let (dir, name) = self.within(at, Missing::IsNothing).await?;
        directory::remove(&dir, &name, Depth::Entry).await
    }

    async fn create_dir<'a>(&'a self, dir: &'a Entry) -> std::io::Result<()> {
        self.walk(&segments(dir), Missing::IsMade).await?;
        Ok(())
    }

    /// The bytes travel, since only Chromium has `move()`, and the lock
    /// goes with them: it is named after the container, so a rename must
    /// take the new name's lock as well as the new name.
    ///
    /// Both are taken before anything moves. A view claiming a name whose
    /// directory it has not laid down yet holds that lock and nothing else,
    /// so a rename that copied first and asked afterwards would find the
    /// lock gone and carry on writing a container it no longer holds.
    async fn rename<'a>(&'a mut self, to: &'a Name) -> std::io::Result<()> {
        if directory::holds(&self.root, to.as_str()).await? {
            return Err(taken(to));
        }
        let holding = self.held.borrow().is_some();
        let relocked = if holding {
            Some(
                locks::request(&Self::lock_name(to))
                    .await?
                    .ok_or_else(|| taken(to))?,
            )
        } else {
            None
        };

        let moved = directory::directory(&self.root, to.as_str(), Missing::IsMade).await?;
        directory::copy(&self.dir, &moved).await?;
        directory::remove(&self.root, self.name.as_str(), Depth::Everything).await?;

        if let Some(relocked) = relocked {
            *self.held.borrow_mut() = Some(relocked);
        }
        self.dir = moved;
        self.name = to.clone();
        Ok(())
    }

    async fn discard(&self) -> std::io::Result<()> {
        directory::remove(&self.root, self.name.as_str(), Depth::Entry).await
    }

    /// `now` names nobody here: the origin's lock manager records no
    /// holder, only that the lock is held, which is why a refusal is
    /// [`Holding::Elsewhere`].
    async fn claim(&self, _now: WallTime) -> std::io::Result<Claim> {
        let Some(held) = locks::request(&Self::lock_name(&self.name)).await? else {
            return Ok(Claim::Held(Holding::Elsewhere));
        };
        *self.held.borrow_mut() = Some(held);
        Ok(Claim::Taken)
    }

    fn release(&self) {
        drop(self.held.borrow_mut().take());
    }
}

/// The path `at` names, as the directories to walk and the entry at the
/// end. Empty for [`Entry::ROOT`], which is the container itself.
fn segments(at: &Entry) -> Vec<&str> {
    at.as_str().split('/').filter(|of| !of.is_empty()).collect()
}

/// A missing entry is nothing rather than a failure — the one refusal the
/// container reads as an answer.
fn nothing_there<T>(got: std::io::Result<T>) -> std::io::Result<Option<T>> {
    match got {
        Ok(found) => Ok(Some(found)),
        Err(why) if why.kind() == std::io::ErrorKind::NotFound => Ok(None),
        Err(why) => Err(why),
    }
}

/// A name that is not this container's to take: something already stands
/// under it, or another view has claimed it and not laid it down yet.
fn taken(name: &Name) -> std::io::Error {
    std::io::Error::new(
        std::io::ErrorKind::AlreadyExists,
        format!("{name} already exists"),
    )
}

/// Nothing the container would call an entry stands where this was asked:
/// no such name, or a name something that is not a file stands under.
fn not_an_entry(why: &std::io::Error) -> bool {
    matches!(
        why.kind(),
        std::io::ErrorKind::NotFound | std::io::ErrorKind::InvalidInput
    )
}