kobako 0.29.0 → 0.30.0

data/crates/kobako-runtime/src/filesystem/overlay/stack.rs

@@ -1,117 +1,142 @@
 //! The Layers of an Overlay and the rules that make them one view: which
-//! Layer shows a path, how a change lands in a writable Layer, and the
-//! markers that hide what a read-only Layer still holds.
+//! Layer shows a name, how a change lands in the upper, and the marks that
+//! hide what a lower Layer still holds. The calls on the view are split
+//! as overlayfs splits them: finding a name in `namei`, copying up in
+//! `copy_up`, listing in `readdir`, and changing a directory in `dir`.
 //!
-//! Each change that touches more than one entry writes its marker or its
-//! replacement before it takes the old one away, as overlayfs builds a
-//! copy before it swaps it in, so a change that fails part way leaves the
-//! view as it was or as it was meant to become.
+//! Every Layer is asked about a single name in a directory already held, as
+//! overlayfs looks a name up in each layer's directory. A Layer's directory
+//! merges into the view only beneath a directory it also holds.
+//!
+//! The upper Tmpfs holds the view's changes in `upper` and builds each one
+//! in `work` first, as overlayfs's upperdir and workdir share one mount.
+//! A change that replaces an entry is made whole in `work` and exchanged
+//! into place, so a change that fails part way leaves the view as it was.
+
+mod copy_up;
+mod dir;
+mod namei;
+mod readdir;
 
-use std::collections::HashSet;
+use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Arc;
 
-use super::super::path::{ancestors, beneath_itself, is_beneath, join, name, parent};
-use super::super::{
-    Access, DirEntry, File, FileType, Filesystem, FilesystemError, Hold, Metadata, OpenOptions,
-    Rename,
-};
+use super::inode::OverlayDirInode;
+use super::path::OverlayPath;
+
+use super::super::{FileOperations, FileType, Filesystem, FilesystemError, Kiocb};
+use crate::vfs::{Cred, Dentry, Identity};
 
-/// The prefix of a whiteout, and of every name reserved for a marker.
-const WHITEOUT: &str = ".wh.";
-/// The marker hiding every lower Layer's entries of its directory.
-const OPAQUE: &str = ".wh..wh..opq";
+/// The directories of the upper Tmpfs holding the view's changes and the
+/// changes being built, as overlayfs's `upperdir` and `workdir`.
+const UPPERDIR: &str = "upper";
+const WORKDIR: &str = "work";
 
-/// How a Layer is asked what a path names: following a link there, or not.
-type Lookup = fn(&(dyn Filesystem + 'static), &str) -> Result<Metadata, FilesystemError>;
+/// Where the upper stands among the Layers, topmost first, holding nothing where
+/// an Overlay has none, as `ovl_inode` keeps `__upperdentry` apart from its lower
+/// stack. Every change lands there.
+pub(super) const UPPER: usize = 0;
 
+/// Each Layer's directory at one directory of the view, topmost first;
+/// `None` where that Layer holds no directory the view merges there.
+pub(super) type Level = Vec<Option<OverlayPath>>;
+
+/// One directory of the view: the dentry the runtime holds for it and the
+/// state kept there, as overlayfs reaches a directory by its dentry and
+/// the `ovl_inode` behind it.
 #[derive(Clone)]
-struct Layer {
-    filesystem: Arc<dyn Filesystem>,
-    access: Access,
+pub(super) struct ViewDir {
+    dentry: Arc<Dentry>,
+    inode: Arc<OverlayDirInode>,
 }
 
-impl Layer {
-    fn writable(&self) -> bool {
-        self.access == Access::ReadWrite
+impl ViewDir {
+    /// Each Layer's directory this one stands for.
+    pub(super) fn level(&self) -> Level {
+        self.inode.level()
     }
+}
 
-    fn find(&self, path: &str) -> Result<Option<Metadata>, FilesystemError> {
-        self.find_by(path, <dyn Filesystem>::metadata)
-    }
+/// What a Layer shows at a name, as `ovl_lookup_single` tells a whiteout from an
+/// entry.
+enum Presence {
+    /// Nothing, and a name too long for that Layer to hold is nothing either, as
+    /// `ovl_lookup_single` answers ENOENT and ENAMETOOLONG by moving on.
+    Nothing,
+    /// A whiteout, which hides the Layers below.
+    Whiteout,
+    /// An entry, a link reported as itself.
+    Entry(LayerEntry),
+}
 
-    /// What this Layer holds at `path` as one of the Layers merged beneath
-    /// a directory shown: a file standing above `path` here ends the merge
-    /// as a file at `path` does, rather than failing it.
-    fn find_below(&self, path: &str) -> Result<Option<Metadata>, FilesystemError> {
-        match self.find(path) {
-            Err(FilesystemError::NotADirectory) => Ok(Some(Metadata::new(FileType::File, 0))),
-            found => found,
-        }
+/// An entry a Layer holds: its name as the Layer stores it, and its dentry there.
+pub(super) struct LayerEntry {
+    stored_name: String,
+    dentry: Arc<Dentry>,
+}
+
+impl LayerEntry {
+    /// The name as the Layer stores it.
+    pub(super) fn stored_name(&self) -> &str {
+        &self.stored_name
     }
 
-    fn find_by(&self, path: &str, lookup: Lookup) -> Result<Option<Metadata>, FilesystemError> {
-        match lookup(self.filesystem.as_ref(), path) {
-            Ok(metadata) => Ok(Some(metadata)),
-            Err(FilesystemError::NotFound) => Ok(None),
-            Err(err) => Err(err),
-        }
+    /// What kind of entry it is, as its lookup recorded it.
+    fn kind(&self) -> Result<FileType, FilesystemError> {
+        self.dentry.kind()
     }
+}
 
-    /// Whether this Layer has an entry at `path`, a link pointing at
-    /// nothing among them. A Layer that cannot answer fails the call, so a
-    /// marker it could not read never lets a lower entry show.
-    fn holds(&self, path: &str) -> Result<bool, FilesystemError> {
-        match self.filesystem.symlink_metadata(path) {
-            Ok(_) => Ok(true),
-            Err(FilesystemError::NotFound | FilesystemError::NotADirectory) => Ok(false),
-            Err(err) => Err(err),
-        }
+impl Presence {
+    fn is_directory(&self) -> bool {
+        matches!(self, Self::Entry(found) if found.kind() == Ok(FileType::Dir))
     }
+}
 
-    /// Whether this Layer hides `path` in every Layer below it: a whiteout
-    /// of it or of a directory above it, an opaque marker in one of those
-    /// directories or in `path` itself, or a file or link standing at it
-    /// or above it, as overlayfs merges only directories. A marker lives
-    /// in a directory, so the walk ends at the first directory above
-    /// `path` this Layer lacks.
-    fn hides(&self, path: &str) -> Result<bool, FilesystemError> {
-        if self.holds(&join(path, OPAQUE))? {
-            return Ok(true);
+/// What `dir` shows at `name`, read from one lookup, as `ovl_lookup_single` reads
+/// `ovl_is_whiteout` and `d_is_dir` from the dentry it found.
+fn entry(dir: &OverlayPath, name: &str) -> Result<Presence, FilesystemError> {
+    match dir.lookup_single(name) {
+        Ok(Some((_, dentry))) if dir.is_whiteout_dentry(&dentry) => Ok(Presence::Whiteout),
+        Ok(Some((stored_name, dentry))) => Ok(Presence::Entry(LayerEntry {
+            stored_name,
+            dentry,
+        })),
+        Ok(None) | Err(FilesystemError::NotFound | FilesystemError::InvalidFilename) => {
+            Ok(Presence::Nothing)
         }
-        for name in ancestors(path).chain(std::iter::once(path)) {
-            if self.holds(&whiteout(name))? || self.holds(&join(parent(name), OPAQUE))? {
-                return Ok(true);
-            }
-            match self.filesystem.symlink_metadata(name) {
-                Ok(metadata) if metadata.file_type != FileType::Directory => return Ok(true),
-                Ok(_) => {}
-                Err(FilesystemError::NotFound | FilesystemError::NotADirectory) if name != path => {
-                    return Ok(false)
-                }
-                Err(FilesystemError::NotFound | FilesystemError::NotADirectory) => {}
-                Err(err) => return Err(err),
-            }
-        }
-        Ok(false)
+        Err(err) => Err(err),
     }
 }
 
-/// The whiteout hiding `path`, beside it in its directory.
-fn whiteout(path: &str) -> String {
-    join(parent(path), &format!("{WHITEOUT}{}", name(path)))
+/// Whether a Layer below the upper shows `name` in `level`, as
+/// `ovl_lower_positive` finds out whether a removal must leave a whiteout. A Layer
+/// that cannot answer is taken to hold something, so nothing below shows through.
+fn ovl_lower_positive(level: &Level, name: &str) -> bool {
+    for dir in level.iter().skip(UPPER + 1).flatten() {
+        match entry(dir, name) {
+            Ok(Presence::Nothing) => {}
+            Ok(Presence::Whiteout) => return false,
+            Ok(Presence::Entry(_)) | Err(_) => return true,
+        }
+    }
+    false
 }
 
-fn copy_whole(source: &mut dyn File, target: &mut dyn File) -> Result<(), FilesystemError> {
+fn copy_whole(
+    source: &mut dyn FileOperations,
+    target: &mut dyn FileOperations,
+) -> Result<(), FilesystemError> {
     let mut buf = vec![0; 64 * 1024];
-    let mut offset = 0;
+    let (mut from, mut to) = (Kiocb::at(0), Kiocb::at(0));
     loop {
-        let read = source.read_at(&mut buf, offset)?;
+        let read = source.read_iter(&mut from, &mut buf)?;
         if read == 0 {
             return Ok(());
         }
         let mut written = 0;
         while written < read {
-            match target.write_at(&buf[written..read], offset + written as u64)? {
+            match target.write_iter(&mut to, &buf[written..read])? {
                 0 => {
                     return Err(FilesystemError::Other(
                         "a copy up's write wrote nothing".to_string(),
@@ -120,689 +145,157 @@ fn copy_whole(source: &mut dyn File, target: &mut dyn File) -> Result<(), Filesy
                 wrote => written += wrote,
             }
         }
-        offset += read as u64;
-    }
-}
-
-/// Take every marker out of a writable Layer's copy of the directory
-/// `path`, which the view shows empty, for `act` to change it; any other
-/// entry there means it is not. When `act` fails, or a marker will not
-/// go, the markers taken out are put back, so the view stays as it was.
-fn without_markers(
-    filesystem: &dyn Filesystem,
-    path: &str,
-    act: impl FnOnce() -> Result<(), FilesystemError>,
-) -> Result<(), FilesystemError> {
-    let markers: Vec<String> = filesystem
-        .read_dir(path)?
-        .into_iter()
-        .map(|entry| entry.name)
-        .collect();
-    if markers.iter().any(|name| !name.starts_with(WHITEOUT)) {
-        return Err(FilesystemError::DirectoryNotEmpty);
-    }
-    let mut cleared = Vec::new();
-    let changed = markers
-        .iter()
-        .try_for_each(|name| {
-            let marker = join(path, name);
-            filesystem.remove_file(&marker)?;
-            cleared.push(marker);
-            Ok(())
-        })
-        .and_then(|()| act());
-    if changed.is_err() {
-        for marker in cleared {
-            let _ = put_marker(filesystem, &marker);
-        }
     }
-    changed
 }
 
-/// An empty file at `path`, as every marker is.
-fn put_marker(filesystem: &dyn Filesystem, path: &str) -> Result<(), FilesystemError> {
-    filesystem
-        .open(
-            path,
-            &OpenOptions {
-                write: true,
-                create: true,
-                ..OpenOptions::default()
-            },
-        )?
-        .close()
+/// The Layer's directory a level holds, which it holds wherever it shows
+/// a name.
+fn layer_dir(dir: &Option<OverlayPath>) -> Result<&OverlayPath, FilesystemError> {
+    dir.as_ref().ok_or(FilesystemError::NotFound)
 }
 
-/// Refuse a path naming an entry reserved for the Overlay's markers, in
-/// any case, since a Layer that folds case would hold `.WH.name` as one.
-fn refuse_reserved(path: &str) -> Result<(), FilesystemError> {
-    let marker = |name: &str| {
-        name.get(..WHITEOUT.len())
-            .is_some_and(|start| start.eq_ignore_ascii_case(WHITEOUT))
-    };
-    if path.split('/').any(marker) {
-        return Err(FilesystemError::InvalidInput);
+/// The directory `name` in `root`, made there first if it stands nowhere, as
+/// overlayfs's `ovl_workdir_create` makes its upperdir's sibling.
+fn ovl_workdir_create(root: &OverlayPath, name: &str) -> Result<OverlayPath, FilesystemError> {
+    match root.do_mkdir(name) {
+        Ok(()) | Err(FilesystemError::AlreadyExists) => root.open_dir(name),
+        Err(err) => Err(err),
     }
-    Ok(())
-}
-
-/// Layers stacked into one view, the first added on top.
-#[derive(Clone, Default)]
-pub(super) struct Stack {
-    layers: Vec<Layer>,
 }
 
-impl Stack {
-    pub(super) fn push(&mut self, filesystem: Arc<dyn Filesystem>, access: Access) {
-        self.layers.push(Layer { filesystem, access });
-    }
-
-    /// The Layers a new Invocation starts from, or `None` when every Layer
-    /// is shared.
-    pub(super) fn for_invocation(&self) -> Option<Self> {
-        self.with_each_layer(|filesystem| filesystem.for_invocation())
-    }
-
-    /// The Layers a Mount with a Policy reaches, or `None` when no Layer
-    /// holds a link.
-    pub(super) fn for_policy(&self) -> Option<Self> {
-        self.with_each_layer(|filesystem| filesystem.for_policy())
-    }
-
-    /// The Layers with each Filesystem `next` answers in its place, or
-    /// `None` when it answers none.
-    fn with_each_layer(
-        &self,
-        next: impl Fn(&Arc<dyn Filesystem>) -> Option<Arc<dyn Filesystem>>,
-    ) -> Option<Self> {
-        let next: Vec<_> = self
-            .layers
-            .iter()
-            .map(|layer| next(&layer.filesystem))
-            .collect();
-        if next.iter().all(Option::is_none) {
-            return None;
-        }
-        let layers = self
-            .layers
-            .iter()
-            .zip(next)
-            .map(|(layer, next)| Layer {
-                filesystem: next.unwrap_or_else(|| layer.filesystem.clone()),
-                access: layer.access,
-            })
-            .collect();
-        Some(Self { layers })
-    }
-
-    /// The topmost Layer holding `path` and what it holds there, a link
-    /// followed within that Layer, or `None` when no Layer shows it or the
-    /// link shown points at nothing.
-    fn locate(&self, path: &str) -> Result<Option<(usize, Metadata)>, FilesystemError> {
-        match self.locate_by(path, <dyn Filesystem>::symlink_metadata)? {
-            Some((index, metadata)) if metadata.file_type == FileType::Symlink => Ok(self.layers
-                [index]
-                .find(path)?
-                .map(|metadata| (index, metadata))),
-            found => Ok(found),
-        }
-    }
-
-    fn locate_by(
-        &self,
-        path: &str,
-        lookup: Lookup,
-    ) -> Result<Option<(usize, Metadata)>, FilesystemError> {
-        for (index, layer) in self.layers.iter().enumerate() {
-            if let Some(metadata) = layer.find_by(path, lookup)? {
-                return Ok(Some((index, metadata)));
-            }
-            if layer.hides(path)? {
-                break;
-            }
-        }
-        Ok(None)
-    }
-
-    /// Every Layer still showing `path`, topmost first, and the topmost
-    /// Layer below them whose entry there a file or link above shadows.
-    fn holders(&self, path: &str) -> Result<(Vec<usize>, Option<usize>), FilesystemError> {
-        let mut holders = Vec::new();
-        for (index, layer) in self.layers.iter().enumerate() {
-            let holds = layer.holds(path)?;
-            if holds {
-                holders.push(index);
-            }
-            if layer.hides(path)? {
-                let shadowed = if holds {
-                    self.beneath(index, path)?
-                } else {
-                    None
-                };
-                return Ok((holders, shadowed));
-            }
-        }
-        Ok((holders, None))
-    }
-
-    /// The topmost Layer below `above` holding `path` in sight.
-    fn beneath(&self, above: usize, path: &str) -> Result<Option<usize>, FilesystemError> {
-        for (index, layer) in self.layers.iter().enumerate().skip(above + 1) {
-            if layer.holds(path)? {
-                return Ok(Some(index));
-            }
-            if layer.hides(path)? {
-                return Ok(None);
-            }
-        }
-        Ok(None)
-    }
-
-    /// The topmost writable Layer, where every change that is not in place
-    /// lands.
-    fn upper(&self) -> Result<usize, FilesystemError> {
-        self.layers
-            .iter()
-            .position(Layer::writable)
-            .ok_or(FilesystemError::ReadOnlyFilesystem)
-    }
-
-    /// Refuse as read-only a change landing at `path` in Layer `into` that
-    /// a read-only Layer above it would cover, holding or hiding `path`, so
-    /// no change succeeds out of sight.
-    fn refuse_covered(&self, path: &str, into: usize) -> Result<(), FilesystemError> {
-        for layer in &self.layers[..into] {
-            if layer.holds(path)? || layer.hides(path)? {
-                return Err(FilesystemError::ReadOnlyFilesystem);
-            }
-        }
-        Ok(())
-    }
-
-    /// Create in Layer `into` each directory above `path` that so far shows
-    /// only from another Layer. A Layer holds no link it was not handed, so
-    /// a change reaching through a link another Layer holds is refused as
-    /// crossing devices rather than landing beside where the link points.
-    fn copy_up_directories(&self, path: &str, into: usize) -> Result<(), FilesystemError> {
-        let target = &self.layers[into];
-        for dir in ancestors(path) {
-            if target.holds(dir)? {
-                continue;
-            }
-            match self.locate_by(dir, <dyn Filesystem>::symlink_metadata)? {
-                Some((_, metadata)) => match metadata.file_type {
-                    FileType::Directory => target.filesystem.create_dir(dir)?,
-                    FileType::Symlink => return Err(FilesystemError::CrossesDevices),
-                    _ => return Err(FilesystemError::NotADirectory),
-                },
-                None => return Err(FilesystemError::NotFound),
-            }
-        }
-        Ok(())
-    }
-
-    /// Copy the file at `path` from Layer `from` into Layer `into` whole.
-    /// Layer `into` held nothing there, so a copy that fails part way is
-    /// taken away again rather than left to hide the whole file. A link
-    /// is not copied up, as no Layer is handed one to hold.
-    fn copy_up_file(&self, path: &str, from: usize, into: usize) -> Result<(), FilesystemError> {
-        if self.layers[from]
-            .filesystem
-            .symlink_metadata(path)?
-            .file_type
-            == FileType::Symlink
-        {
-            return Err(FilesystemError::CrossesDevices);
-        }
-        self.copy_up_directories(path, into)?;
-        let mut source = self.layers[from].filesystem.open(
-            path,
-            &OpenOptions {
-                read: true,
-                ..OpenOptions::default()
-            },
-        )?;
-        let target = &self.layers[into].filesystem;
-        let mut copy = target.open(
-            path,
-            &OpenOptions {
-                write: true,
-                create: true,
-                truncate: true,
-                ..OpenOptions::default()
-            },
-        )?;
-        let copied = copy_whole(source.as_mut(), copy.as_mut()).and(copy.close());
-        if copied.is_err() {
-            let _ = target.remove_file(path);
-        }
-        copied
-    }
-
-    /// Clear the whiteout of `path` in Layer `into` once an entry has
-    /// landed there. A whiteout left beside the entry hides only what lies
-    /// below, which the entry replaced, so failing to clear it fails
-    /// nothing.
-    fn unhide(&self, path: &str, into: usize) {
-        let _ = self.layers[into].filesystem.remove_file(&whiteout(path));
-    }
-
-    fn mark(&self, path: &str, into: usize) -> Result<(), FilesystemError> {
-        self.copy_up_directories(path, into)?;
-        put_marker(self.layers[into].filesystem.as_ref(), path)
-    }
-
-    /// The Layer a whiteout over the Layer at `shown` lands in, or `None`
-    /// when nothing below needs one; refused as read-only when no writable
-    /// Layer sits above it.
-    fn whiteout_layer(&self, shown: Option<usize>) -> Result<Option<usize>, FilesystemError> {
-        match shown {
-            Some(shown) => match self.upper()? {
-                upper if upper < shown => Ok(Some(upper)),
-                _ => Err(FilesystemError::ReadOnlyFilesystem),
-            },
-            None => Ok(None),
-        }
-    }
-
-    /// Take `path` out of the view: a whiteout over any Layer that keeps it
-    /// first, then out of every other Layer holding it. A read-only Layer
-    /// keeps it, and so does a writable one `keeps` answers for, so no
-    /// Layer changes before each is known to go; `remove` takes it out of
-    /// one Layer.
-    fn withdraw(
-        &self,
-        path: &str,
-        keeps: impl Fn(&dyn Filesystem) -> Result<bool, FilesystemError>,
-        remove: impl Fn(&dyn Filesystem, &str) -> Result<(), FilesystemError>,
-    ) -> Result<(), FilesystemError> {
-        let (holders, shadowed) = self.holders(path)?;
-        let mut kept = Vec::new();
-        for &index in &holders {
-            let layer = &self.layers[index];
-            if !layer.writable() || keeps(layer.filesystem.as_ref())? {
-                kept.push(index);
-            }
-        }
-        let shown = kept.first().copied().into_iter().chain(shadowed).min();
-        if let Some(upper) = self.whiteout_layer(shown)? {
-            self.mark(&whiteout(path), upper)?;
-        }
-        for &index in &holders {
-            if !kept.contains(&index) {
-                remove(self.layers[index].filesystem.as_ref(), path)?;
-            }
-        }
-        Ok(())
-    }
-
-    pub(super) fn open(
-        &self,
-        path: &str,
-        options: &OpenOptions,
-    ) -> Result<Box<dyn File>, FilesystemError> {
-        refuse_reserved(path)?;
-        let changes = options.write || options.truncate;
-        match self.locate(path)? {
-            Some((
-                _,
-                Metadata {
-                    file_type: FileType::Directory,
-                    ..
-                },
-            )) => Err(FilesystemError::IsADirectory),
-            Some(_) if options.create_new => Err(FilesystemError::AlreadyExists),
-            Some((index, _)) if !changes || self.layers[index].writable() => {
-                self.layers[index].filesystem.open(path, options)
-            }
-            Some((index, _)) => {
-                let into = self.layers[..index]
-                    .iter()
-                    .rposition(Layer::writable)
-                    .ok_or(FilesystemError::ReadOnlyFilesystem)?;
-                self.copy_up_file(path, index, into)?;
-                self.layers[into].filesystem.open(path, options)
-            }
-            None if options.create || options.create_new => self.create_file(path, options),
-            None => Err(FilesystemError::NotFound),
-        }
-    }
-
-    /// A link pointing at nothing still names an entry, so an exclusive
-    /// create finds it there; any other create reaches through it, which
-    /// only the Layer holding the link may answer. The new file shadows
-    /// whatever the whiteout hid before the whiteout goes, so nothing
-    /// shows through in between.
-    fn create_file(
-        &self,
-        path: &str,
-        options: &OpenOptions,
-    ) -> Result<Box<dyn File>, FilesystemError> {
-        match self.locate_by(path, <dyn Filesystem>::symlink_metadata)? {
-            Some(_) if options.create_new => Err(FilesystemError::AlreadyExists),
-            Some((index, _)) if self.layers[index].writable() => {
-                self.layers[index].filesystem.open(path, options)
-            }
-            Some(_) => Err(FilesystemError::CrossesDevices),
-            None => {
-                let upper = self.upper()?;
-                self.refuse_covered(path, upper)?;
-                self.copy_up_directories(path, upper)?;
-                let file = self.layers[upper].filesystem.open(path, options)?;
-                self.unhide(path, upper);
-                Ok(file)
-            }
-        }
-    }
-
-    pub(super) fn metadata(&self, path: &str) -> Result<Metadata, FilesystemError> {
-        refuse_reserved(path)?;
-        let (index, metadata) = self.locate(path)?.ok_or(FilesystemError::NotFound)?;
-        self.merge_identity(path, index, metadata)
+/// Take `name` out of `dir`, a directory only once it is empty, as
+/// overlayfs's `ovl_cleanup` takes away what a change left in its
+/// workdir, so whatever another writer made in it meanwhile stays.
+fn ovl_cleanup(dir: &OverlayPath, name: &str) -> Result<(), FilesystemError> {
+    match dir.getattr_at(name)?.file_type {
+        FileType::Dir => dir.do_rmdir(name),
+        _ => dir.do_unlink(name),
     }
+}
 
-    /// What the Layer showing `path` holds there, a link it holds
-    /// reported as one even where it points at nothing.
-    pub(super) fn symlink_metadata(&self, path: &str) -> Result<Metadata, FilesystemError> {
-        refuse_reserved(path)?;
-        let (index, metadata) = self
-            .locate_by(path, <dyn Filesystem>::symlink_metadata)?
-            .ok_or(FilesystemError::NotFound)?;
-        self.merge_identity(path, index, metadata)
+/// Take the whiteouts out of the directory `name` in `dir`, and nothing
+/// else, as overlayfs's `ovl_cleanup_whiteouts` does before it removes
+/// one; anything else stands there leaves it holding that.
+fn ovl_cleanup_whiteouts(dir: &OverlayPath, name: &str) -> Result<(), FilesystemError> {
+    if dir.getattr_at(name)?.file_type != FileType::Dir {
+        return Ok(());
     }
-
-    /// `path` spelled as the topmost Layer showing it stores it; a name
-    /// no Layer shows keeps its spelling, beneath its directory's.
-    pub(super) fn stored_path(&self, path: &str) -> Result<String, FilesystemError> {
-        if path.is_empty() {
-            return Ok(String::new());
-        }
-        match self.locate_by(path, <dyn Filesystem>::symlink_metadata) {
-            Ok(Some((index, _))) => self.layers[index].filesystem.stored_path(path),
-            Ok(None) | Err(FilesystemError::NotFound | FilesystemError::NotADirectory) => {
-                Ok(join(&self.stored_path(parent(path))?, name(path)))
-            }
-            Err(err) => Err(err),
+    let inner = dir.open_dir(name)?;
+    for entry in inner.entries()? {
+        if inner.is_whiteout(&entry.name) {
+            inner.do_unlink(&entry.name)?;
         }
     }
+    Ok(())
+}
 
-    /// `path` beneath `base` with its links followed by the Layer showing
-    /// the first of them, as a link is followed within the Layer holding
-    /// it; a path the merged view shows no link on answers as given.
-    pub(super) fn canonicalize_beneath(
-        &self,
-        base: &str,
-        path: &str,
-    ) -> Result<String, FilesystemError> {
-        if path.is_empty() {
-            return Ok(String::new());
+/// Take `name` out of the workdir with all it holds, as overlayfs's
+/// `ovl_workdir_cleanup` empties it of what an earlier mount left.
+fn ovl_workdir_cleanup(dir: &OverlayPath, name: &str) -> Result<(), FilesystemError> {
+    let mut pending = vec![(dir.clone(), name.to_string())];
+    while let Some((dir, name)) = pending.last().cloned() {
+        if dir.getattr_at(&name)?.file_type != FileType::Dir {
+            dir.do_unlink(&name)?;
+            pending.pop();
+            continue;
         }
-        let full = join(base, path);
-        let start = full.len() - path.len();
-        let ends = full[start..]
-            .match_indices('/')
-            .map(|(end, _)| start + end)
-            .chain([full.len()]);
-        for end in ends {
-            match self.locate_by(&full[..end], <dyn Filesystem>::symlink_metadata) {
-                Ok(Some((index, metadata))) if metadata.file_type == FileType::Symlink => {
-                    return self.layers[index]
-                        .filesystem
-                        .canonicalize_beneath(base, path)
-                }
-                Ok(Some(_)) => {}
-                Ok(None) | Err(FilesystemError::NotFound | FilesystemError::NotADirectory) => break,
-                Err(err) => return Err(err),
-            }
+        let inner = dir.open_dir(&name)?;
+        let entries = inner.entries()?;
+        if entries.is_empty() {
+            dir.do_rmdir(&name)?;
+            pending.pop();
         }
-        Ok(path.to_string())
+        pending.extend(entries.into_iter().map(|entry| (inner.clone(), entry.name)));
     }
+    Ok(())
+}
 
-    /// `metadata`, found at `path` in the Layer at `index`, as the merged
-    /// view reports it: a directory takes the identity of the lowest Layer
-    /// still showing it, so copying it up into a writable Layer leaves the
-    /// identity as it was.
-    fn merge_identity(
-        &self,
-        path: &str,
-        index: usize,
-        metadata: Metadata,
-    ) -> Result<Metadata, FilesystemError> {
-        if metadata.file_type != FileType::Directory {
-            return Ok(metadata);
-        }
-        let (_, lowest) = self.lowest_directory(path, index, metadata)?;
-        Ok(metadata.with_identity(lowest.dev, lowest.ino))
-    }
+/// Layers stacked into one view, topmost first, the upper among them on
+/// top, as overlayfs's `ovl_fs` holds a mount's layers.
+#[derive(Clone)]
+pub(super) struct OverlayFs {
+    /// Each Layer's root, the upper's `upper` at `UPPER` where there is one, and
+    /// the lower Layers beneath it, topmost first.
+    roots: Level,
+    /// Where a change is built before it lands, with an upper only.
+    work: Option<OverlayPath>,
+    /// The next name a change built in `work` takes.
+    temp: Arc<AtomicU64>,
+}
 
-    /// The lowest Layer at or below `index` still showing the directory
-    /// `path`, found there as `metadata`, and what it holds there.
-    fn lowest_directory(
-        &self,
-        path: &str,
-        index: usize,
-        metadata: Metadata,
-    ) -> Result<(usize, Metadata), FilesystemError> {
-        let mut lowest = (index, metadata);
-        for (at, layer) in self.layers.iter().enumerate().skip(index) {
-            match layer.find_below(path)? {
-                Some(found) if found.file_type == FileType::Directory => lowest = (at, found),
-                Some(_) => break,
-                None => {}
-            }
-            if layer.hides(path)? {
-                break;
-            }
-        }
-        Ok(lowest)
+impl OverlayFs {
+    /// The view of `lower` under `upper`, its `upper` and `work` made where
+    /// they stand nowhere and `work` emptied of what a change left, as
+    /// overlayfs's mount does with its workdir.
+    pub(super) fn new(
+        lower: Vec<Arc<Filesystem>>,
+        upper: Option<Arc<Filesystem>>,
+    ) -> Result<Self, FilesystemError> {
+        let mut roots = vec![None];
+        let mut work = None;
+        let creator_cred = Cred::new(Vec::new());
+        if let Some(upper) = upper {
+            let root = OverlayPath::root(&upper, &creator_cred);
+            roots[UPPER] = Some(ovl_workdir_create(&root, UPPERDIR)?);
+            let made = ovl_workdir_create(&root, WORKDIR)?;
+            for entry in made.entries()? {
+                ovl_workdir_cleanup(&made, &entry.name)?;
+            }
+            work = Some(made);
+        }
+        roots.extend(
+            lower
+                .iter()
+                .map(|layer| Some(OverlayPath::root(layer, &creator_cred))),
+        );
+        Ok(Self {
+            roots,
+            work,
+            temp: Arc::default(),
+        })
     }
 
-    /// The Hold of the Layer whose directory gives `path` its identity.
-    pub(super) fn hold_directory(&self, path: &str) -> Result<Option<Hold>, FilesystemError> {
-        let (index, metadata) = self.locate(path)?.ok_or(FilesystemError::NotFound)?;
-        if metadata.file_type != FileType::Directory {
-            return Err(FilesystemError::NotADirectory);
-        }
-        let (lowest, _) = self.lowest_directory(path, index, metadata)?;
-        self.layers[lowest].filesystem.hold_directory(path)
+    /// Whether changes have an upper to land in, as `ovl_upper_mnt` answers.
+    pub(super) fn has_upper(&self) -> bool {
+        self.work.is_some()
     }
 
-    pub(super) fn read_dir(&self, path: &str) -> Result<Vec<DirEntry>, FilesystemError> {
-        if self.metadata(path)?.file_type != FileType::Directory {
-            return Err(FilesystemError::NotADirectory);
-        }
-        let mut entries: Vec<DirEntry> = Vec::new();
-        let mut taken: HashSet<String> = HashSet::new();
-        for layer in &self.layers {
-            match layer.find_below(path)? {
-                Some(Metadata {
-                    file_type: FileType::Directory,
-                    ..
-                }) => {
-                    let listed = layer.filesystem.read_dir(path)?;
-                    for entry in &listed {
-                        if !entry.name.starts_with(WHITEOUT) && taken.insert(entry.name.clone()) {
-                            entries.push(entry.clone());
-                        }
-                    }
-                    taken.extend(
-                        listed
-                            .iter()
-                            .filter_map(|entry| entry.name.strip_prefix(WHITEOUT))
-                            .map(str::to_string),
-                    );
-                    if listed.iter().any(|entry| entry.name == OPAQUE) {
-                        break;
-                    }
-                }
-                Some(_) => break,
-                None => {}
-            }
-            if layer.hides(path)? {
-                break;
-            }
-        }
-        Ok(entries)
+    /// What the topmost Layer's root recorded it stands for.
+    pub(super) fn root_identity(&self) -> Option<Identity> {
+        let topmost = self.roots.iter().flatten().next()?;
+        topmost.dentry().inode()?.identity()
     }
 
-    /// A directory made where a whiteout hid one is marked opaque before
-    /// the whiteout goes, so the lower Layers' entries never show in it.
-    pub(super) fn create_dir(&self, path: &str) -> Result<(), FilesystemError> {
-        refuse_reserved(path)?;
-        if self
-            .locate_by(path, <dyn Filesystem>::symlink_metadata)?
-            .is_some()
-        {
-            return Err(FilesystemError::AlreadyExists);
-        }
-        let upper = self.upper()?;
-        self.refuse_covered(path, upper)?;
-        self.copy_up_directories(path, upper)?;
-        let layer = &self.layers[upper];
-        let hid = layer.holds(&whiteout(path))?;
-        layer.filesystem.create_dir(path)?;
-        if hid {
-            if let Err(err) = self.mark(&join(path, OPAQUE), upper) {
-                let _ = layer.filesystem.remove_dir(path);
-                return Err(err);
-            }
-            self.unhide(path, upper);
-        }
-        Ok(())
+    /// The state of the root, which stands for every Layer's root, as overlayfs's
+    /// `ovl_get_root` keeps it on the root's inode as it mounts.
+    pub(super) fn root_dir(&self) -> OverlayDirInode {
+        OverlayDirInode::new(self.roots.clone())
     }
 
-    /// A writable Layer's copy of the directory may hold only markers; any
-    /// other entry there means the view is not what was found empty. A
-    /// copy still holding what a Layer above hides stays, beneath the
-    /// whiteout.
-    pub(super) fn remove_dir(&self, path: &str) -> Result<(), FilesystemError> {
-        if self.symlink_metadata(path)?.file_type != FileType::Directory {
-            return Err(FilesystemError::NotADirectory);
-        }
-        if !self.read_dir(path)?.is_empty() {
-            return Err(FilesystemError::DirectoryNotEmpty);
-        }
-        self.withdraw(
-            path,
-            |filesystem| {
-                Ok(filesystem
-                    .read_dir(path)?
-                    .iter()
-                    .any(|entry| !entry.name.starts_with(WHITEOUT)))
-            },
-            |filesystem, path| without_markers(filesystem, path, || filesystem.remove_dir(path)),
-        )
+    /// The directory of the view `dentry` names, its state found on the inode
+    /// its lookup, or the mount for the root, recorded.
+    pub(super) fn dir(&self, dentry: &Dentry) -> Result<ViewDir, FilesystemError> {
+        let inode = dentry.inode().ok_or(FilesystemError::NotFound)?;
+        let inode = OverlayDirInode::of(&inode).ok_or(FilesystemError::NotADirectory)?;
+        Ok(ViewDir {
+            dentry: dentry.get(),
+            inode,
+        })
     }
 
-    /// A link is removed as itself, wherever it points.
-    pub(super) fn remove_file(&self, path: &str) -> Result<(), FilesystemError> {
-        if self.symlink_metadata(path)?.file_type == FileType::Directory {
-            return Err(FilesystemError::IsADirectory);
-        }
-        self.withdraw(
-            path,
-            |_| Ok(false),
-            |filesystem, path| filesystem.remove_file(path),
-        )
+    /// The directory holding the entry `dentry` names.
+    pub(super) fn parent(&self, dentry: &Dentry) -> Result<ViewDir, FilesystemError> {
+        self.dir(&dentry.parent())
     }
 
-    /// A directory moves only when the topmost writable Layer alone holds
-    /// it; moving one out of another would mean copying up everything
-    /// beneath it, so it is refused as crossing devices, as overlayfs
-    /// refuses it without `redirect_dir`; so is a link or another kind a
-    /// lower Layer holds, which no copy up can make. What the view holds
-    /// at `to` is checked as rename(2) checks it, and a directory moved
-    /// over one a lower Layer holds is marked opaque before it moves, so
-    /// it never lands without the marker. The source is whited out before
-    /// it moves, so it never shows from a read-only Layer once moved. What
-    /// a lower writable Layer holds is refused as crossing devices, as
-    /// unionfs-fuse refuses a rename across writable branches, since moving
-    /// it would change two Layers that could fail apart.
-    pub(super) fn rename(
-        &self,
-        from: &str,
-        to: &str,
-        rename: Rename,
-    ) -> Result<(), FilesystemError> {
-        refuse_reserved(to)?;
-        let moving = self.symlink_metadata(from)?;
-        if from == to {
-            return Ok(());
-        }
-        rename.check(moving.file_type)?;
-        if is_beneath(to, from) {
-            return Err(beneath_itself(moving.file_type));
-        }
-        let replaced = self
-            .locate_by(to, <dyn Filesystem>::symlink_metadata)?
-            .map(|(_, metadata)| metadata.file_type);
-        // Only a directory replaces a directory, and only an empty one.
-        match (moving.file_type == FileType::Directory, replaced) {
-            (false, Some(FileType::Directory)) => return Err(FilesystemError::IsADirectory),
-            (true, Some(FileType::Directory)) if !self.read_dir(to)?.is_empty() => {
-                return Err(FilesystemError::DirectoryNotEmpty)
-            }
-            (true, Some(found)) if found != FileType::Directory => {
-                return Err(FilesystemError::NotADirectory)
-            }
-            _ => {}
-        }
-        let upper = self.upper()?;
-        self.refuse_covered(to, upper)?;
-        let mut replaces_below = false;
-        if moving.file_type == FileType::Directory {
-            for (index, layer) in self.layers.iter().enumerate() {
-                replaces_below |= index != upper && layer.holds(to)?;
-            }
-        }
-        let (holders, shadowed) = self.holders(from)?;
-        if holders
-            .iter()
-            .any(|&index| index != upper && self.layers[index].writable())
-        {
-            return Err(FilesystemError::CrossesDevices);
-        }
-        let read_only = holders
-            .iter()
-            .copied()
-            .find(|&index| !self.layers[index].writable());
-        let shown_below = self.whiteout_layer(read_only.into_iter().chain(shadowed).min())?;
-        match moving.file_type {
-            FileType::Directory if holders != [upper] => {
-                return Err(FilesystemError::CrossesDevices)
-            }
-            FileType::File if holders.first() != Some(&upper) => {
-                let shown = holders.first().ok_or(FilesystemError::NotFound)?;
-                self.copy_up_file(from, *shown, upper)?
-            }
-            FileType::Symlink | FileType::Unknown if holders.first() != Some(&upper) => {
-                return Err(FilesystemError::CrossesDevices)
-            }
-            _ => {}
-        }
-        self.copy_up_directories(to, upper)?;
-        if let Some(upper) = shown_below {
-            self.mark(&whiteout(from), upper)?;
-        }
-        let filesystem = self.layers[upper].filesystem.as_ref();
-        let opaque = join(from, OPAQUE);
-        let marks = replaces_below && !self.layers[upper].holds(&opaque)?;
-        if marks {
-            put_marker(filesystem, &opaque)?;
-        }
-        let moved = || filesystem.rename(from, to, rename);
-        let moved = if replaced == Some(FileType::Directory) && self.layers[upper].holds(to)? {
-            without_markers(filesystem, to, moved)
-        } else {
-            moved()
-        };
-        if let Err(err) = moved {
-            if marks {
-                let _ = filesystem.remove_file(&opaque);
-            }
-            return Err(err);
-        }
-        self.unhide(to, upper);
-        Ok(())
+    /// The workdir and a name in it no change has taken, as overlayfs's
+    /// `ovl_tempname` names one.
+    fn tempname(&self) -> Result<(&OverlayPath, String), FilesystemError> {
+        let work = self
+            .work
+            .as_ref()
+            .ok_or(FilesystemError::ReadOnlyFilesystem)?;
+        let next = self.temp.fetch_add(1, Ordering::Relaxed);
+        Ok((work, format!("#{next:x}")))
     }
 }