Documentation
¶
Overview ¶
Package memfs implements an in-memory tool.FileSystem and tool.Workspace (map-backed) for fast, offline FS-tool tests. It enforces the same path-escape rejection and file-version protocol (content-hash versions, create-only and compare-and-swap writes) as the osfs adapter, and performs Grep over the in-memory contents. It keeps no read-before-edit evidence: that is the Environment's separately selected tool.ReadLedger (for example memledger).
memfs has no shell, so its Workspace deliberately does NOT execute commands. For deterministic Shell-tool stubbing it exposes a separate, programmable tool.CommandRunner (see CommandRunner / NewCommandRunner): by default Run returns ErrNoShell so tests cannot accidentally depend on shell behavior, and a canned result may be programmed via SetResult.
Index ¶
- Variables
- type CommandRunner
- type FileSystem
- func (f *FileSystem) Glob(_ context.Context, pattern string) ([]string, error)
- func (f *FileSystem) Read(_ context.Context, p string) ([]byte, error)
- func (f *FileSystem) Root() string
- func (f *FileSystem) Stat(_ context.Context, p string) (tool.FileInfo, error)
- func (f *FileSystem) Write(_ context.Context, p string, data []byte) error
- type Workspace
- func (w *Workspace) AuthorityResourcePath(p string) (target, workspace string, err error)
- func (w *Workspace) CopyFile(_ context.Context, source, destination string) (tool.FileVersion, error)
- func (w *Workspace) CreateFile(_ context.Context, p string, data []byte) (tool.FileVersion, error)
- func (w *Workspace) Glob(ctx context.Context, pattern string) ([]string, error)
- func (w *Workspace) Grep(ctx context.Context, pattern, pathGlob string) ([]tool.GrepMatch, error)
- func (w *Workspace) Read(ctx context.Context, p string) ([]byte, error)
- func (w *Workspace) ReadDir(_ context.Context, p string) ([]tool.FileInfo, error)
- func (w *Workspace) ReadVersion(_ context.Context, p string) ([]byte, tool.FileVersion, error)
- func (w *Workspace) ReadVersionBounded(_ context.Context, p string, maxBytes int64) ([]byte, tool.FileVersion, error)
- func (w *Workspace) ReadVersionRangeBounded(_ context.Context, p string, offset, maxBytes, totalLimit int64) ([]byte, tool.FileVersion, int64, error)
- func (w *Workspace) Remove(_ context.Context, p string) error
- func (w *Workspace) Rename(_ context.Context, oldPath, newPath string) error
- func (w *Workspace) ReplaceFile(_ context.Context, p string, old tool.FileVersion, data []byte) (tool.FileVersion, error)
- func (w *Workspace) Root() string
- func (w *Workspace) Stat(ctx context.Context, p string) (tool.FileInfo, error)
- func (w *Workspace) Write(ctx context.Context, p string, data []byte) error
Constants ¶
This section is empty.
Variables ¶
var ErrNoShell = fmt.Errorf("memfs: %w; program a result with SetResult", tool.ErrNoShell)
ErrNoShell is returned by CommandRunner.Run when no canned result has been programmed: memfs has no shell to run commands against. It wraps tool.ErrNoShell so callers can match either sentinel.
var ErrNotExist = fs.ErrNotExist
ErrNotExist is returned when a file is not present in the in-memory store.
var ErrPathEscape = errors.New("memfs: path escapes workspace root")
ErrPathEscape is returned when a session-relative path resolves outside the Workspace root.
Functions ¶
This section is empty.
Types ¶
type CommandRunner ¶
type CommandRunner struct {
// contains filtered or unexported fields
}
CommandRunner is a programmable, in-memory tool.CommandRunner for deterministic Shell-tool stubbing. memfs has no shell, so by default Run returns ErrNoShell; program a canned result (or error) with SetResult.
func NewCommandRunner ¶
func NewCommandRunner() *CommandRunner
NewCommandRunner returns a programmable in-memory CommandRunner. Until SetResult is called, Run returns ErrNoShell.
func (*CommandRunner) Run ¶
func (r *CommandRunner) Run(ctx context.Context, _ string) (tool.CommandResult, error)
Run returns the programmed canned result. memfs has no shell, so absent a programmed result it returns ErrNoShell. It honors ctx cancellation. The command string is ignored beyond being a marker; this method exists for deterministic Shell-tool stubbing, not real execution.
func (*CommandRunner) RunWithEnvironment ¶ added in v0.15.0
func (r *CommandRunner) RunWithEnvironment(ctx context.Context, _ string, _ tool.CommandEnvironmentOverlay) (tool.CommandResult, error)
RunWithEnvironment accepts the trusted overlay for CommandRunner conformance. The in-memory runner has no process environment, so it deliberately has no observable effect on its deterministic canned result.
func (*CommandRunner) SetResult ¶
func (r *CommandRunner) SetResult(res *tool.CommandResult, err error)
SetResult programs the deterministic result (and/or error) that the next and subsequent Run calls return. Passing a nil result with a nil error makes Run return an empty successful result; this is the only way to get a non-error Run from memfs, since it has no shell.
type FileSystem ¶
type FileSystem struct {
// contains filtered or unexported fields
}
FileSystem is an in-memory, map-backed tool.FileSystem. Paths are normalized to clean, slash-separated, root-relative keys. It is safe for concurrent use.
func NewFileSystem ¶
func NewFileSystem(root string) *FileSystem
NewFileSystem returns an empty in-memory FileSystem with the given (logical) root. The root is used only for Root() reporting and escape checks; no real directory is created.
func (*FileSystem) Glob ¶
Glob returns session-relative paths matching the glob pattern, in deterministic (sorted) order. The pattern supports the "**" globstar (matching across "/" recursively) in addition to "*", "?", "[…]" and "{…}". Matching uses doublestar.Match against each stored key. This mirrors the osfs adapter's globstar support so the in-memory test fabric and the real filesystem agree; the shared fsconformance suite pins both.
func (*FileSystem) Read ¶
Read returns the entire contents of the file at the session-relative path.
func (*FileSystem) Root ¶
func (f *FileSystem) Root() string
Root returns the logical workspace root.
type Workspace ¶
type Workspace struct {
// contains filtered or unexported fields
}
Workspace is the in-memory session-scoped content seam. Command execution and read-before-write evidence are carried separately by tool.Environment.
func NewWorkspace ¶
NewWorkspace returns an empty in-memory Workspace with the given logical root.
func NewWorkspaceOverFileSystem ¶ added in v0.14.0
func NewWorkspaceOverFileSystem(backend *FileSystem) *Workspace
NewWorkspaceOverFileSystem returns a Workspace over the given content backend.
func (*Workspace) AuthorityResourcePath ¶
AuthorityResourcePath derives memfs's confined logical path identity. memfs has no symlinks, so its cleaned key is already the physical identity it serves.
func (*Workspace) CopyFile ¶ added in v0.15.0
func (w *Workspace) CopyFile(_ context.Context, source, destination string) (tool.FileVersion, error)
CopyFile copies one regular file to a new destination without overwriting.
func (*Workspace) CreateFile ¶
CreateFile creates a NEW file at path with the given content, atomically. It fails (wrapping fs.ErrExist) if a file already exists. Parent directories are created as needed (memfs is flat — directories are implicit in the key). It returns the new file's FileVersion.
func (*Workspace) Grep ¶
Grep returns the matches of a regular expression across in-memory files selected by an optional path glob. When pathGlob is empty, all files are searched. Results are returned in deterministic order (by path, then line). The search honors ctx cancellation.
func (*Workspace) ReadDir ¶ added in v0.15.0
ReadDir returns the immediate children of a virtual directory. Directories are derived from file-path prefixes, so empty directories do not exist.
func (*Workspace) ReadVersion ¶
ReadVersion returns the contents of the file at the session-relative path AND the authoritative FileVersion (sha256 of the content). It reads under the FileSystem's lock so the content and the version are a consistent snapshot.
func (*Workspace) ReadVersionBounded ¶ added in v0.16.0
func (w *Workspace) ReadVersionBounded(_ context.Context, p string, maxBytes int64) ([]byte, tool.FileVersion, error)
ReadVersionBounded returns one consistent snapshot without allocating beyond the caller's byte limit.
func (*Workspace) ReadVersionRangeBounded ¶ added in v0.16.0
func (w *Workspace) ReadVersionRangeBounded(_ context.Context, p string, offset, maxBytes, totalLimit int64) ([]byte, tool.FileVersion, int64, error)
ReadVersionRangeBounded returns one page and the version/size of the same locked in-memory snapshot without copying the rest of the file.
func (*Workspace) Remove ¶ added in v0.15.0
Remove deletes a regular file. Prefix-derived directories are always non-empty, so removing one returns ErrDirectoryNotEmpty.
func (*Workspace) Rename ¶ added in v0.15.0
Rename moves a regular file or a prefix-derived directory without replacing an existing destination.
func (*Workspace) ReplaceFile ¶
func (w *Workspace) ReplaceFile(_ context.Context, p string, old tool.FileVersion, data []byte) (tool.FileVersion, error)
ReplaceFile conditionally replaces the contents of the file at path with data, only if the file's current authoritative version equals old. On a version mismatch it returns a *tool.VersionMismatchError; on a missing file it returns an error wrapping fs.ErrNotExist. It is atomic under the FileSystem's lock.
Source Files