This is a fork and extension of the vfs mock file system test affordance from Pebble by Cockroach Labs.

https://github.com/cockroachdb/pebble/

The original lacked the Truncate method necessary to test write-ahead-logs that are truncated to a specific size on recovery.

LICENSE: see the LICENSE files herein.

(parts are MIT licensed, parts are Apache 2 licensed, and the top level is BSD 3-clause licensed)

This fork adds several methods to support dual-mode testing (real FS and in-memory FS; via dev created build tags).

• Truncate(size int64) error -- Truncate a file to a given size. Required for testing write-ahead-log recovery, where a WAL must be truncated to a specific size after a simulated crash.

• Name() string -- Return the name/path of an open file handle.

• ReadDir(dirname string) ([]os.DirEntry, error) -- Read a directory and return sorted os.DirEntry entries. Complements the existing List() (which returns only name strings) by providing type and metadata information for each entry.

• WalkDir(path string, fn fs.WalkDirFunc) error -- Recursive directory traversal following the io/fs.WalkDirFunc convention. Walks the tree in lexicographic order, supports fs.SkipDir. Implemented for both defaultFS (real disk) and MemFS (in-memory tree).

• IsReal() bool -- Returns true for the real OS filesystem (defaultFS or vfs.Default), false for MemFS. Lets test setup code branch on the filesystem type without type-asserting on unexported vfs types.

• MountReadOnlyRealDir(fromRealDir, mountPointInsideDir string) error -- Mount a real OS directory inside a MemFS at a chosen path, read-only. This allows tests running under a MemFS to access large test assets (e.g. reference databases, golden files) from the real filesystem without copying them into memory. Key properties:

  • Read-only: Open, Stat, List, ReadDir, and WalkDir fall through to the real directory. Write operations (Create, MkdirAll, Rename, etc.) targeting the mount point return an error.
  • Disjoint paths: The mount point must not already exist in the MemFS overlay. This prevents ambiguous ownership of paths.
  • Multiple mounts: Several real directories can be mounted at different MemFS paths on the same MemFS instance.
  • Zero overhead when unused: A plain NewMem() with no mounts has no extra allocations or method-dispatch overhead.
  • Propagated on CrashClone(): Mount configuration is carried forward so crash-recovery tests retain access to mounted assets.

  Only supported on MemFS; calling on defaultFS or wrapper filesystems returns an error.

• MemFS.Save method to durably persist a MemFS to actual, real disk file. The on-disk format is greenpack encoding followed by s2 compression.

• MemFS.Load method to reify the real file generated by Save back into an MemFS in memory. Useful to resume from a saved time point of interest, such as that generated by NewCrashableMem() and MemFS.CrashClone() during fsync durability/recovery-path testing.

Author: Jason E. Aten, Ph.D.

Copyright (C) 2026, Jason E. Aten, Ph.D. All rights reserved.

LICENSE: BSD 3-clause for the new aggregate; same as pebble. See the LICENSE files herein.