@threadedstack/wmd-web 0.0.0-stage → 0.1.13

package/src/fs/overlay.js

@@ -0,0 +1,1018 @@
+// A container root file system: read-only pack layers (lowers) under a
+// writable in-memory upper, with the layering rules of wmd's internal/union
+// and internal/memfs (Docker's overlay storage):
+//
+// - Layers are given top first. In a directory, the topmost layer that has a
+//   name decides what it is. A whiteout entry hides the name in the layers
+//   below its own; an opaque directory hides everything the layers below hold
+//   in it; a non-directory hides any directory of that name below it. The
+//   directories of one path merge, top first, until one of them is opaque or
+//   a lower layer has a non-directory there.
+// - Names starting ".wh." are the layers' bookkeeping, never entries.
+// - A change to a lower entry "copies it up": its inode, metadata included,
+//   is already in memory, and a regular file's contents become an upper
+//   Content whose unwritten parts still read from the pack.
+// - A removed lower name is recorded as a whiteout of its directory; a
+//   directory made again over it is opaque.
+//
+// The tree is inode based: an Inode object is one file, whatever its names
+// (a lower hard-link group is one Inode, nlink its group size), so 9P fids
+// survive renames of their names or directories, and a directory moved with
+// lower contents keeps showing them (overlayfs' redirect_dir; memfs says
+// EXDEV there instead).
+//
+// Inode numbers are memfs's: a lower entry's is 1<<62 | layer<<40 | index
+// of the first entry of its hard-link group in that layer's pack; upper
+// entries count from 1<<46; a copied-up entry keeps its number.
+//
+// Names and paths are byte strings (see pack.js). Errors are FsError with a
+// Linux errno. No permissions are checked: the guest kernel checks its own
+// processes.
+
+import {
+  EEXIST, EFBIG, EINVAL, EISDIR, ELOOP, ENAMETOOLONG, ENODATA, ENOENT, ENOSPC,
+  ENOTDIR, ENOTEMPTY, ENXIO, EOPNOTSUPP, EPERM, fail,
+} from './errno.js'
+import { S_IFBLK, S_IFCHR, S_IFDIR, S_IFIFO, S_IFLNK, S_IFMT, S_IFREG, S_IFSOCK, bytesOf, strOf } from './pack.js'
+
+export const NAME_MAX = 255
+export const PATH_MAX = 4096
+export const MAX_SYMLINKS = 40
+export const WHITEOUT_PREFIX = '.wh.'
+/** The first inode number of the upper layer (memfs.UpperInos). */
+export const UPPER_INOS = 1n << 46n
+/** Upper file contents are kept in chunks of this many bytes, only those written. */
+export const CHUNK = 65536
+/** Largest file size: offsets stay exact in a JavaScript number. */
+export const MAX_FILE_SIZE = 2 ** 52
+
+export const XATTR_CREATE = 1
+export const XATTR_REPLACE = 2
+
+export const QTDIR = 0x80
+export const QTSYMLINK = 0x02
+export const QTFILE = 0
+
+const EMPTY = new Uint8Array(0)
+
+/** Wall clock in Unix nanoseconds, as a BigInt. */
+export function nowNs() {
+  const us = Math.round((performance.timeOrigin + performance.now()) * 1000)
+  return BigInt(us) * 1000n
+}
+
+const LOWER_INOS = 1n << 62n
+
+// A lower inode number, kept as a Number (layer << 40 | index, under 2^53)
+// until asked for: Inode.ino makes the BigInt.
+function lowerIno(layer, index) {
+  return layer * 2 ** 40 + index
+}
+
+/**
+ * A regular file's contents in the upper, over an optional pack base.
+ *
+ * The file is cut into CHUNK-sized chunks; only chunks written hold memory.
+ * A chunk is a Uint8Array that covers the first c.length bytes of its range,
+ * no more than were written there (or copied from the base below a write):
+ * its first allocation is exactly the bytes needed, later growth doubles up
+ * to CHUNK so appends stay linear. Bytes of a chunk's range past c.length
+ * read from the base below baseLen and as zeros above it. So a 6-byte file
+ * holds 6 bytes, and a big sparse file only the chunks written.
+ *
+ * Invariant: no byte at or past size is anything but zero in a chunk, so
+ * extending the size (truncate up) shows zeros. Writes and truncates keep it.
+ *
+ * Memory held is `allocated`, charged to the overlay (maxUpperBytes) as it
+ * grows and given back as it shrinks or by free() when the file is gone.
+ */
+export class Content {
+  constructor(fs, base, size) {
+    this.fs = fs
+    this.base = base // {pack, off, size}: the pack entry's contents, or null
+    this.baseLen = base ? size : 0
+    this.size = size
+    // Chunk 0 (all of a small file) in c0; the others in a Map made when needed.
+    this.c0 = null // Uint8Array (length <= CHUNK)
+    this.chunks = null // Map chunk index (>= 1) -> Uint8Array (length <= CHUNK)
+    this.allocated = 0 // bytes the chunks hold, charged to fs
+  }
+
+  read(off, len) {
+    if (off >= this.size || len <= 0) return EMPTY
+    const n = Math.min(len, this.size - off)
+    const out = new Uint8Array(n)
+    const end = off + n
+    let pos = off
+    while (pos < end) {
+      const ci = Math.floor(pos / CHUNK)
+      const cs = ci * CHUNK
+      const stop = Math.min(end, cs + CHUNK)
+      const c = this.#get(ci)
+      let p = pos
+      if (c && p < cs + c.length) {
+        const s = Math.min(stop, cs + c.length)
+        out.set(c.subarray(p - cs, s - cs), p - off)
+        p = s
+      }
+      if (p < stop && p < this.baseLen) {
+        const bs = Math.min(stop, this.baseLen)
+        out.set(this.base.pack.read(this.base, p, bs - p), p - off)
+      }
+      // else: a hole, zeros.
+      pos = stop
+    }
+    return out
+  }
+
+  #get(ci) {
+    if (ci === 0) return this.c0
+    return this.chunks ? this.chunks.get(ci) : undefined
+  }
+
+  // Sets chunk ci to c, or removes it (c null).
+  #put(ci, c) {
+    if (ci === 0) {
+      this.c0 = c
+    } else if (c) {
+      if (!this.chunks) this.chunks = new Map()
+      this.chunks.set(ci, c)
+    } else if (this.chunks) {
+      this.chunks.delete(ci)
+      if (this.chunks.size === 0) this.chunks = null
+    }
+  }
+
+  // The length chunk ci (now have bytes) grows to so it covers need bytes.
+  static #grown(have, need) {
+    if (have === 0) return need
+    return Math.max(need, Math.min(CHUNK, have * 2))
+  }
+
+  // Makes chunk ci cover len bytes (charging the growth), filling new bytes
+  // from the base where there is one.
+  #grow(ci, c, len) {
+    const have = c ? c.length : 0
+    this.fs.charge(len - have)
+    const g = new Uint8Array(len)
+    if (c) g.set(c)
+    const cs = ci * CHUNK
+    const from = cs + have
+    const to = Math.min(cs + len, this.baseLen)
+    if (from < to) g.set(this.base.pack.read(this.base, from, to - from), have)
+    this.#put(ci, g)
+    this.allocated += len - have
+    return g
+  }
+
+  // The bytes the chunks must grow by for a write of [off, end), with the
+  // doubling slack (slack) or exactly.
+  #cost(off, end, slack) {
+    let cost = 0
+    for (let ci = Math.floor(off / CHUNK); ci * CHUNK < end; ci++) {
+      const cs = ci * CHUNK
+      const c = this.#get(ci)
+      const have = c ? c.length : 0
+      const need = Math.min(end, cs + CHUNK) - cs
+      if (need > have) cost += (slack ? Content.#grown(have, need) : need) - have
+    }
+    return cost
+  }
+
+  /**
+   * Writes data at off, all of it or (ENOSPC, nothing changed) none: the
+   * room is checked before any byte is stored. A guest write(2) larger than
+   * one Twrite still comes out short, as POSIX has it: v9fs returns the
+   * bytes of the Twrites that succeeded before the one that got ENOSPC.
+   */
+  write(off, data) {
+    const end = off + data.length
+    if (end > MAX_FILE_SIZE) fail(EFBIG)
+    if (data.length === 0) return 0
+    const room = this.fs.room()
+    if (this.#cost(off, end, false) > room) this.fs.full()
+    // Doubling slack only when it fits too.
+    const slack = this.#cost(off, end, true) <= room
+    let pos = off
+    while (pos < end) {
+      const ci = Math.floor(pos / CHUNK)
+      const cs = ci * CHUNK
+      const stop = Math.min(end, cs + CHUNK)
+      let c = this.#get(ci)
+      const have = c ? c.length : 0
+      if (stop - cs > have) c = this.#grow(ci, c, slack ? Content.#grown(have, stop - cs) : stop - cs)
+      c.set(data.subarray(pos - off, stop - off), pos - cs)
+      // Size follows each chunk: should a later allocation throw, no byte
+      // stored is past EOF (a truncate up must show zeros).
+      if (stop > this.size) this.size = stop
+      pos = stop
+    }
+    return data.length
+  }
+
+  truncate(size) {
+    if (size > MAX_FILE_SIZE) fail(EFBIG)
+    if (size < this.size) {
+      const all = this.chunks ? [...this.chunks] : []
+      if (this.c0) all.push([0, this.c0])
+      for (const [ci, c] of all) {
+        const cs = ci * CHUNK
+        if (cs >= size) {
+          this.#put(ci, null)
+          this.#uncharge(c.length)
+        } else if (cs + c.length > size) {
+          // The chunk with the new end: drop what lies past it.
+          const keep = size - cs
+          this.#put(ci, c.slice(0, keep))
+          this.#uncharge(c.length - keep)
+        }
+      }
+    }
+    if (this.baseLen > size) this.baseLen = size
+    this.size = size
+  }
+
+  #uncharge(n) {
+    this.allocated -= n
+    this.fs.charge(-n)
+  }
+
+  /** Gives all the memory back: the file is gone (no names, no fids). */
+  free() {
+    if (this.allocated > 0) this.#uncharge(this.allocated)
+    this.c0 = null
+    this.chunks = null
+    this.size = 0
+    this.baseLen = 0
+    this.base = null
+  }
+}
+
+/**
+ * One file of the tree. Directories are DirInode. Lower entries' inodes are
+ * made when their directory is first read, so they are kept small: a few
+ * dozen bytes of fields, the pack's times shared, and the inode number
+ * kept as a Number until asked for.
+ */
+export class Inode {
+  constructor(ino, mode) {
+    this.lino = ino // the qid path: a BigInt, or a lower one as lowerIno's Number
+    this.mode = mode
+    this.uid = 0
+    this.gid = 0
+    this.nlink = 1
+    this.rdev = 0
+    this.atime = 0n
+    this.mtime = 0n
+    this.ctime = 0n
+    this.xattrs = null // Map name -> Uint8Array
+    this.upper = false // changed or made in the upper
+    this.refs = 0 // holders other than names (9P fids)
+    // Symlink.
+    this.target = ''
+    // Regular file: the pack entry's contents it shows until written (see
+    // low), data the upper contents.
+    this.lowPack = null
+    this.lowOff = 0
+    this.lowSize = 0
+    this.data = null
+  }
+
+  /** A lower regular file's pack contents, {pack, off, size}, or null. */
+  get low() {
+    return this.lowPack ? { pack: this.lowPack, off: this.lowOff, size: this.lowSize } : null
+  }
+
+  /** The inode number (qid path), a BigInt. */
+  get ino() {
+    const v = this.lino
+    return typeof v === 'number' ? LOWER_INOS | BigInt(v) : v
+  }
+
+  set ino(v) {
+    this.lino = v
+  }
+
+  get type() {
+    return this.mode & S_IFMT
+  }
+
+  isDir() {
+    return (this.mode & S_IFMT) === S_IFDIR
+  }
+
+  get qtype() {
+    const t = this.mode & S_IFMT
+    return t === S_IFDIR ? QTDIR : t === S_IFLNK ? QTSYMLINK : QTFILE
+  }
+}
+
+/** A directory. */
+export class DirInode extends Inode {
+  constructor(ino, mode) {
+    super(ino, mode)
+    // kids is null until the lower layers are read.
+    this.kids = null
+    this.lowerDirs = null // [{layer, path}] the lower directories merged here, top first
+    this.whiteouts = null // lower names removed here
+    this.opaque = false
+    this.parent = null
+    this.removed = false
+  }
+}
+
+function checkName(name) {
+  if (name === '' || name === '.' || name === '..' || name.includes('/') || name.includes('\0')) fail(EINVAL)
+  if (name.length > NAME_MAX) fail(ENAMETOOLONG)
+  if (name.startsWith(WHITEOUT_PREFIX)) fail(EPERM)
+}
+
+function xattrNamespace(name) {
+  if (name.startsWith('security.') || name.startsWith('trusted.') || name.startsWith('user.')) return
+  fail(EOPNOTSUPP)
+}
+
+export class Overlay {
+  /**
+   * @param {object} o
+   * @param {import('./pack.js').Pack[]} [o.layers] lower packs, top first
+   * @param {string} [o.at] where the layers show: '' for the root, or a path
+   *   such as 'rootfs' under an upper-only root (the guest init's layout).
+   * @param {number} [o.maxUpperBytes] bytes of file contents the upper may hold
+   * @param {(fs: Overlay) => void} [o.onFull] called whenever a write is refused for it
+   * @param {() => bigint} [o.now] clock, Unix ns
+   */
+  constructor({ layers = [], at = '', maxUpperBytes = Infinity, now = nowNs, onFull = null } = {}) {
+    this.layers = layers
+    this.now = now
+    this.maxUpperBytes = maxUpperBytes
+    this.used = 0
+    this.fullHits = 0 // ENOSPC answers because of maxUpperBytes
+    this.onFull = onFull // called on each of them (the host tells the user)
+    this.nextIno = UPPER_INOS
+    this.linkInodes = new Map() // `${layer}:${first}` -> Inode
+    const lroot = this.#lowerRoot()
+    const parts = at.split('/').filter((s) => s !== '' && s !== '.')
+    if (parts.length === 0) {
+      this.root = lroot
+    } else {
+      // An upper-only root, qid path 1 as wmd's Go server's synthetic root.
+      this.root = this.#newInode(S_IFDIR | 0o755, 0, 0)
+      this.root.ino = 1n
+      this.nextIno = UPPER_INOS
+      let dir = this.root
+      for (let i = 0; i < parts.length - 1; i++) dir = this.mkdir(dir, parts[i], 0o755, 0, 0)
+      checkName(parts.at(-1))
+      this.#insert(dir, parts.at(-1), lroot, false)
+    }
+    this.root.parent = null
+  }
+
+  /** Accounts n more (or fewer) bytes of upper contents. */
+  charge(n) {
+    if (n > 0 && this.used + n > this.maxUpperBytes) this.full()
+    this.used += n
+  }
+
+  /** Refuses with ENOSPC: the upper is at maxUpperBytes. */
+  full() {
+    this.fullHits++
+    this.onFull?.(this)
+    fail(ENOSPC)
+  }
+
+  /** The bytes of contents the upper can still take (Infinity without a cap). */
+  room() {
+    return Math.max(0, this.maxUpperBytes - this.used)
+  }
+
+  /**
+   * Counts a holder of n other than its names (a 9P fid). A file with no
+   * names left keeps its contents until the last holder lets go (unref).
+   */
+  ref(n) {
+    n.refs++
+  }
+
+  unref(n) {
+    if (n.refs > 0) n.refs--
+    this.#release(n)
+  }
+
+  // Gives back a file's contents once it has neither names nor holders.
+  #release(n) {
+    if (n.nlink === 0 && n.refs === 0 && n.data) n.data.free()
+  }
+
+  #newIno() {
+    this.nextIno += 1n
+    return this.nextIno
+  }
+
+  #newInode(mode, uid, gid) {
+    const n = (mode & S_IFMT) === S_IFDIR ? new DirInode(this.#newIno(), mode) : new Inode(this.#newIno(), mode)
+    n.uid = uid >>> 0
+    n.gid = gid >>> 0
+    const t = this.now()
+    n.atime = n.mtime = n.ctime = t
+    n.upper = true
+    switch (mode & S_IFMT) {
+      case S_IFDIR:
+        n.nlink = 2
+        n.kids = new Map()
+        n.lowerDirs = []
+        n.whiteouts = new Set()
+        break
+      case S_IFREG:
+        n.data = new Content(this, null, 0)
+        break
+    }
+    return n
+  }
+
+  #lowerRoot() {
+    if (this.layers.length === 0) return this.#newInode(S_IFDIR | 0o755, 0, 0)
+    const dirs = []
+    for (let i = 0; i < this.layers.length; i++) {
+      dirs.push({ layer: i, path: '' })
+      const r = this.layers[i].lookup('')
+      if (r && r.opaque) break
+    }
+    const top = this.layers[0]
+    const idx = top.index('')
+    const n = new DirInode(lowerIno(0, idx < 0 ? 0 : idx), S_IFDIR | 0o755)
+    if (idx >= 0) this.#copyAttrs(n, top.entry(idx))
+    n.nlink = 2 // memfs's root
+    n.lowerDirs = dirs
+    return n
+  }
+
+  #copyAttrs(n, e) {
+    n.mode = e.mode
+    n.uid = e.uid
+    n.gid = e.gid
+    n.rdev = e.rdev
+    n.atime = e.atime
+    n.mtime = e.mtime
+    n.ctime = e.ctime
+    if (e.xattrs) n.xattrs = new Map(e.xattrs)
+  }
+
+  // The inode of lower entry e (index i of layer `layer`'s pack).
+  #fromEntry(layer, i, e, parent, dirs) {
+    if (dirs) {
+      const n = new DirInode(lowerIno(layer, i), e.mode)
+      this.#copyAttrs(n, e)
+      n.lowerDirs = dirs
+      n.parent = parent
+      return n
+    }
+    let first = i
+    let nlink = 1
+    let key = null
+    if (e.link) {
+      const g = this.layers[layer].linkGroup(e.link)
+      first = g.first
+      nlink = g.n
+      key = `${layer}:${first}`
+      const had = this.linkInodes.get(key)
+      if (had) return had
+    }
+    const n = new Inode(lowerIno(layer, first), e.mode)
+    this.#copyAttrs(n, e)
+    n.nlink = nlink
+    switch (e.mode & S_IFMT) {
+      case S_IFREG:
+        n.lowPack = this.layers[layer]
+        n.lowOff = e.off
+        n.lowSize = e.size
+        break
+      case S_IFLNK:
+        n.target = e.target
+        break
+    }
+    if (key) this.linkInodes.set(key, n)
+    return n
+  }
+
+  // Reads directory dir's lower layers once: its merged entries.
+  #load(dir) {
+    if (dir.kids) return dir.kids
+    if (dir.lowerDirs.length === 1) return this.#loadOne(dir)
+    const pend = new Map()
+    const hidden = new Set()
+    for (const { layer, path } of dir.lowerDirs) {
+      const p = this.layers[layer]
+      const wh = []
+      for (const i of p.children(path)) {
+        const e = p.entry(i)
+        const name = e.name
+        if (name.startsWith(WHITEOUT_PREFIX)) continue
+        if (e.whiteout) {
+          wh.push(name)
+          continue
+        }
+        if (hidden.has(name)) continue
+        const isDir = (e.mode & S_IFMT) === S_IFDIR
+        const c = pend.get(name)
+        if (!c) {
+          pend.set(name, { layer, i, e, dirs: isDir ? [{ layer, path: e.path }] : null, stop: !isDir || e.opaque })
+        } else if (!c.stop) {
+          if (isDir && c.dirs) {
+            c.dirs.push({ layer, path: e.path })
+            if (e.opaque) c.stop = true
+          } else {
+            c.stop = true
+          }
+        }
+      }
+      // A layer's whiteouts hide only what is below it.
+      for (const w of wh) hidden.add(w)
+    }
+    const kids = new Map()
+    for (const [name, c] of pend) kids.set(name, this.#fromEntry(c.layer, c.i, c.e, dir, c.dirs))
+    dir.kids = kids
+    if (!dir.whiteouts) dir.whiteouts = new Set()
+    return kids
+  }
+
+  // #load of a directory from one lower layer (most are): nothing to merge,
+  // so no per-name bookkeeping (a million-entry directory makes no garbage
+  // beyond the decoded entries).
+  #loadOne(dir) {
+    const { layer, path } = dir.lowerDirs[0]
+    const p = this.layers[layer]
+    const kids = new Map()
+    for (const i of p.children(path)) {
+      const e = p.entry(i)
+      if (e.whiteout || e.name.startsWith(WHITEOUT_PREFIX)) continue
+      const dirs = (e.mode & S_IFMT) === S_IFDIR ? [{ layer, path: e.path }] : null
+      kids.set(e.name, this.#fromEntry(layer, i, e, dir, dirs))
+    }
+    dir.kids = kids
+    if (!dir.whiteouts) dir.whiteouts = new Set()
+    return kids
+  }
+
+  // Whether the lower layers show name in dir (as #load merges them: the
+  // topmost layer that has the name decides).
+  #lowerHas(dir, name) {
+    for (const { layer, path } of dir.lowerDirs) {
+      const p = this.layers[layer]
+      const i = p.index(path === '' ? name : path + '/' + name)
+      if (i >= 0) return !p.entry(i).whiteout
+    }
+    return false
+  }
+
+  // ---- lookups -----------------------------------------------------------
+
+  /** The entry name in directory dir. */
+  lookup(dir, name) {
+    if (!dir.isDir()) fail(ENOTDIR)
+    if (name.length > NAME_MAX) fail(ENAMETOOLONG)
+    if (name.startsWith(WHITEOUT_PREFIX)) fail(ENOENT)
+    const n = this.#load(dir).get(name)
+    if (!n) fail(ENOENT)
+    return n
+  }
+
+  /** Directory dir's entries, [name, inode] sorted by name (byte order). */
+  list(dir) {
+    const { names, nodes } = this.listing(dir)
+    return names.map((name, i) => [name, nodes[i]])
+  }
+
+  /**
+   * Directory dir's entries sorted by name (byte order) as two arrays,
+   * names and their inodes: what a 9P readdir keeps, cheaper than pairs in
+   * a directory of a million.
+   */
+  listing(dir) {
+    if (!dir.isDir()) fail(ENOTDIR)
+    const kids = this.#load(dir)
+    const names = new Array(kids.size)
+    const nodes = new Array(kids.size)
+    let i = 0
+    let sorted = true
+    for (const [name, n] of kids) {
+      if (i > 0 && names[i - 1] >= name) sorted = false
+      names[i] = name
+      nodes[i++] = n
+    }
+    if (!sorted) {
+      names.sort() // code unit order: byte order for byte strings
+      for (let k = 0; k < names.length; k++) nodes[k] = kids.get(names[k])
+    }
+    return { names, nodes }
+  }
+
+  /** The number of entries of directory dir. */
+  count(dir) {
+    return this.#load(dir).size
+  }
+
+  /**
+   * The inode path leads to from the root, following symlinks inside the
+   * root as a process chrooted to it would (the final one only when follow
+   * is set): ELOOP after 40 links, ENOTDIR through a non-directory.
+   */
+  resolve(path, follow = true) {
+    let links = 0
+    let cur = this.root
+    let parts = path.split('/').filter((s) => s !== '')
+    let i = 0
+    while (i < parts.length) {
+      const name = parts[i]
+      const last = i === parts.length - 1
+      if (name === '.') {
+        if (!cur.isDir()) fail(ENOTDIR)
+        i++
+        continue
+      }
+      if (name === '..') {
+        if (!cur.isDir()) fail(ENOTDIR)
+        cur = cur.parent || this.root
+        i++
+        continue
+      }
+      const c = this.lookup(cur, name)
+      if (c.type === S_IFLNK && (!last || follow)) {
+        if (++links > MAX_SYMLINKS) fail(ELOOP)
+        if (c.target.startsWith('/')) cur = this.root
+        parts = c.target.split('/').filter((s) => s !== '').concat(parts.slice(i + 1))
+        i = 0
+        if (parts.length === 0) return cur
+        continue
+      }
+      if (last) return c
+      cur = c
+      i++
+    }
+    return cur
+  }
+
+  /** The directory path's parent resolves to, and its last name. */
+  resolveParent(path) {
+    const parts = path.split('/').filter((s) => s !== '')
+    if (parts.length === 0) fail(EINVAL)
+    const dir = this.resolve(parts.slice(0, -1).join('/'), true)
+    if (!dir.isDir()) fail(ENOTDIR)
+    return [dir, parts.at(-1)]
+  }
+
+  // ---- attributes --------------------------------------------------------
+
+  size(n) {
+    switch (n.type) {
+      case S_IFREG:
+        return n.data ? n.data.size : n.lowPack ? n.lowSize : 0
+      case S_IFLNK:
+        return n.target.length
+      case S_IFDIR:
+        return 4096
+    }
+    return 0
+  }
+
+  blocks(n) {
+    switch (n.type) {
+      case S_IFREG: {
+        const size = this.size(n)
+        if (!n.data) return Math.ceil(size / 512)
+        return Math.ceil(Math.min(size, n.data.allocated + n.data.baseLen) / 512)
+      }
+      case S_IFLNK:
+        return Math.ceil(n.target.length / 512)
+      case S_IFDIR:
+        return 8
+    }
+    return 0
+  }
+
+  /** stat(2)'s view of n. Times are BigInt ns. */
+  getattr(n) {
+    return {
+      ino: n.ino, qtype: n.qtype, mode: n.mode, uid: n.uid, gid: n.gid, nlink: n.nlink,
+      rdev: n.rdev, size: this.size(n), blksize: 4096, blocks: this.blocks(n),
+      atime: n.atime, mtime: n.mtime, ctime: n.ctime,
+    }
+  }
+
+  #ensureData(n) {
+    if (!n.data) n.data = new Content(this, n.low, n.lowSize)
+    n.upper = true
+    return n.data
+  }
+
+  /**
+   * Changes n: {mode (permission bits), uid, gid, size, atime, mtime (BigInt
+   * ns)}; undefined fields stay. ctime becomes now.
+   */
+  setattr(n, s) {
+    if (s.size !== undefined) {
+      if (n.isDir()) fail(EISDIR)
+      if (n.type !== S_IFREG) fail(EINVAL)
+      if (s.size < 0) fail(EINVAL)
+      if (s.size > MAX_FILE_SIZE) fail(EFBIG)
+    }
+    const t = this.now()
+    n.upper = true
+    if (s.mode !== undefined) n.mode = (n.mode & S_IFMT) | (s.mode & 0o7777)
+    if (s.uid !== undefined) n.uid = s.uid >>> 0
+    if (s.gid !== undefined) n.gid = s.gid >>> 0
+    if (s.size !== undefined) {
+      this.#ensureData(n).truncate(s.size)
+      n.mtime = t
+    }
+    if (s.atime !== undefined) n.atime = s.atime
+    if (s.mtime !== undefined) n.mtime = s.mtime
+    n.ctime = t
+  }
+
+  // ---- contents ----------------------------------------------------------
+
+  /** Opens n: {write, trunc}. Checks the type; truncates. */
+  open(n, { write = false, trunc = false } = {}) {
+    switch (n.type) {
+      case S_IFLNK:
+        fail(ELOOP)
+      case S_IFDIR:
+        if (write || trunc) fail(EISDIR)
+        return
+      case S_IFREG:
+        if (trunc && this.size(n) > 0) {
+          this.#ensureData(n).truncate(0)
+          n.mtime = n.ctime = this.now()
+        }
+        return
+    }
+    // Devices, fifos and sockets are the guest kernel's to run.
+    fail(ENXIO)
+  }
+
+  read(n, off, len) {
+    if (n.isDir()) fail(EISDIR)
+    if (n.type !== S_IFREG) fail(EINVAL)
+    if (n.data) return n.data.read(off, len)
+    if (n.lowPack) return n.lowPack.read({ off: n.lowOff, size: n.lowSize }, off, len)
+    return EMPTY
+  }
+
+  write(n, off, bytes) {
+    if (n.isDir()) fail(EISDIR)
+    if (n.type !== S_IFREG) fail(EINVAL)
+    const w = this.#ensureData(n).write(off, bytes)
+    if (w > 0) n.mtime = n.ctime = this.now()
+    return w
+  }
+
+  readlink(n) {
+    if (n.type !== S_IFLNK) fail(EINVAL)
+    return n.target
+  }
+
+  // ---- changes to directories --------------------------------------------
+
+  #checkNew(dir, name) {
+    if (!dir.isDir()) fail(ENOTDIR)
+    if (dir.removed) fail(ENOENT)
+    checkName(name)
+    if (this.#load(dir).has(name)) fail(EEXIST)
+  }
+
+  #touch(n) {
+    n.mtime = n.ctime = this.now()
+    n.upper = true
+  }
+
+  // Makes name in dir be n. made: n is new here (not a rename), so a
+  // directory made over a removed lower name must not merge with it.
+  #insert(dir, name, n, made) {
+    const kids = this.#load(dir)
+    if (made && n.isDir() && this.#lowerHas(dir, name)) n.opaque = true
+    dir.whiteouts.delete(name)
+    kids.set(name, n)
+    if (n.isDir()) {
+      n.parent = dir
+      if (dir.nlink >= 2) dir.nlink++
+    }
+    this.#touch(dir)
+  }
+
+  #detach(dir, name, n) {
+    dir.kids.delete(name)
+    if (this.#lowerHas(dir, name)) dir.whiteouts.add(name)
+    if (n.isDir() && dir.nlink > 2) dir.nlink--
+    this.#touch(dir)
+  }
+
+  create(dir, name, perm, uid, gid) {
+    this.#checkNew(dir, name)
+    const n = this.#newInode(S_IFREG | (perm & 0o7777), uid, gid)
+    this.#insert(dir, name, n, true)
+    return n
+  }
+
+  mkdir(dir, name, perm, uid, gid) {
+    this.#checkNew(dir, name)
+    const n = this.#newInode(S_IFDIR | (perm & 0o7777), uid, gid)
+    this.#insert(dir, name, n, true)
+    return n
+  }
+
+  symlink(dir, name, target, uid, gid) {
+    this.#checkNew(dir, name)
+    if (target.length >= PATH_MAX) fail(ENAMETOOLONG)
+    const n = this.#newInode(S_IFLNK | 0o777, uid, gid)
+    n.target = target
+    this.#insert(dir, name, n, true)
+    return n
+  }
+
+  mknod(dir, name, mode, rdev, uid, gid) {
+    switch (mode & S_IFMT) {
+      case S_IFIFO: case S_IFSOCK: case S_IFCHR: case S_IFBLK: case S_IFREG:
+        break
+      case 0:
+        mode |= S_IFREG
+        break
+      default:
+        fail(EINVAL)
+    }
+    this.#checkNew(dir, name)
+    const n = this.#newInode(mode & (S_IFMT | 0o7777), uid, gid)
+    n.rdev = rdev
+    this.#insert(dir, name, n, true)
+    return n
+  }
+
+  /** Makes name in dir another name of n. */
+  link(dir, name, n) {
+    if (n.isDir()) fail(EPERM)
+    if (n.nlink === 0) fail(ENOENT)
+    this.#checkNew(dir, name)
+    this.#insert(dir, name, n, true)
+    n.nlink++
+    n.ctime = this.now()
+    n.upper = true
+  }
+
+  /** Removes name from dir: a directory (empty) when rmdir is set, else anything else. */
+  unlink(dir, name, rmdir = false) {
+    if (dir.removed) fail(ENOENT)
+    const n = this.lookup(dir, name)
+    if (rmdir) {
+      if (!n.isDir()) fail(ENOTDIR)
+      if (this.#load(n).size > 0) fail(ENOTEMPTY)
+    } else if (n.isDir()) {
+      fail(EISDIR)
+    }
+    this.#detach(dir, name, n)
+    if (n.isDir()) {
+      n.removed = true
+      n.nlink = 0
+    } else {
+      n.nlink--
+      n.ctime = this.now()
+      this.#release(n)
+    }
+  }
+
+  /** Moves odir/oname to ndir/nname, replacing what is there as rename(2) does. */
+  rename(odir, oname, ndir, nname) {
+    if (odir.removed) fail(ENOENT)
+    const src = this.lookup(odir, oname)
+    if (!ndir.isDir()) fail(ENOTDIR)
+    if (ndir.removed) fail(ENOENT)
+    checkName(nname)
+    if (odir === ndir && oname === nname) return
+    if (src.isDir()) {
+      for (let p = ndir; p; p = p.parent) if (p === src) fail(EINVAL)
+    }
+    const t = this.#load(ndir).get(nname)
+    if (t) {
+      if (t === src) return // two names of one file: nothing, as Linux
+      if (src.isDir()) {
+        if (!t.isDir()) fail(ENOTDIR)
+        if (this.#load(t).size > 0) fail(ENOTEMPTY)
+      } else if (t.isDir()) {
+        fail(EISDIR)
+      }
+    }
+    this.#detach(odir, oname, src)
+    if (t) {
+      this.#detach(ndir, nname, t)
+      if (t.isDir()) {
+        t.removed = true
+        t.nlink = 0
+      } else {
+        t.nlink--
+        t.ctime = this.now()
+        this.#release(t)
+      }
+    }
+    this.#insert(ndir, nname, src, false)
+    src.ctime = this.now()
+    src.upper = true
+  }
+
+  // ---- extended attributes -----------------------------------------------
+
+  getxattr(n, name) {
+    xattrNamespace(name)
+    const v = n.xattrs && n.xattrs.get(name)
+    if (!v) fail(ENODATA)
+    return v
+  }
+
+  listxattr(n) {
+    return n.xattrs ? [...n.xattrs.keys()].sort() : []
+  }
+
+  setxattr(n, name, value, flags = 0) {
+    xattrNamespace(name)
+    const has = !!(n.xattrs && n.xattrs.has(name))
+    if (flags & XATTR_CREATE && has) fail(EEXIST)
+    if (flags & XATTR_REPLACE && !has) fail(ENODATA)
+    n.xattrs = new Map(n.xattrs || [])
+    n.xattrs.set(name, value.slice())
+    n.ctime = this.now()
+    n.upper = true
+  }
+
+  removexattr(n, name) {
+    xattrNamespace(name)
+    if (!n.xattrs || !n.xattrs.has(name)) fail(ENODATA)
+    n.xattrs = new Map(n.xattrs)
+    n.xattrs.delete(name)
+    n.ctime = this.now()
+    n.upper = true
+  }
+
+  /**
+   * statfs(2): with maxUpperBytes the size is the cap and free what is left
+   * of it. Without one, wmd's Go server's numbers (8 GiB, 4 GiB free), free
+   * shrinking once the upper holds more than the other 4 GiB.
+   */
+  statfs() {
+    const bs = 4096
+    const capped = Number.isFinite(this.maxUpperBytes)
+    const blocks = capped ? Math.floor(this.maxUpperBytes / bs) : 1 << 21
+    const left = Math.max(0, blocks - Math.ceil(this.used / bs))
+    const free = capped ? left : Math.min(1 << 20, left)
+    return {
+      fstype: 0x01021997, bsize: bs, blocks, bfree: free, bavail: free,
+      files: 1 << 20, ffree: 1 << 19, fsid: 0, namelen: NAME_MAX,
+    }
+  }
+
+  // ---- path helpers for the host (bundle files, tests) -------------------
+
+  /** mkdir -p (following symlinks); returns the directory. */
+  mkdirp(path, perm = 0o755) {
+    const parts = path.split('/').filter((s) => s !== '')
+    let dir = this.root
+    for (let i = 0; i < parts.length; i++) {
+      let c
+      try {
+        c = this.resolve(parts.slice(0, i + 1).join('/'), true)
+      } catch (e) {
+        if (e.errno !== ENOENT) throw e
+        c = this.mkdir(dir, parts[i], perm, 0, 0)
+      }
+      if (!c.isDir()) fail(ENOTDIR)
+      dir = c
+    }
+    return dir
+  }
+
+  /** Writes a whole file (made or replaced), data a Uint8Array or byte string. */
+  writeFile(path, data, { mode = 0o644, uid = 0, gid = 0 } = {}) {
+    const bytes = typeof data === 'string' ? bytesOf(data) : data
+    const [dir, name] = this.resolveParent(path)
+    let n
+    try {
+      n = this.resolve(path, true)
+    } catch (e) {
+      if (e.errno !== ENOENT) throw e
+      n = this.create(dir, name, mode, uid, gid)
+    }
+    this.open(n, { write: true, trunc: true })
+    this.write(n, 0, bytes)
+    return n
+  }
+
+  /** A whole file's bytes. */
+  readFile(path) {
+    const n = this.resolve(path, true)
+    return this.read(n, 0, this.size(n))
+  }
+
+  /** stat(2) (lstat when follow is false) of path. */
+  stat(path, follow = true) {
+    return this.getattr(this.resolve(path, follow))
+  }
+}
+
+export { strOf, bytesOf }