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 the same Edit read-ledger semantics as the osfs adapter, and performs Grep over the in-memory contents.
memfs has no shell, so its Workspace deliberately does NOT execute commands. For deterministic Bash-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) 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) ReadVersion(_ context.Context, p string) ([]byte, tool.FileVersion, error)
- func (w *Workspace) RecordRead(p string, version tool.FileVersion)
- func (w *Workspace) RecordedVersion(p string) (tool.FileVersion, bool)
- 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 Bash-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 Bash-tool stubbing, not real execution.
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 seam. It composes a FileSystem, performs Grep over in-memory contents, and carries the Edit read-ledger. Command execution is not part of the Workspace; use CommandRunner for that.
func NewWorkspace ¶
NewWorkspace returns an empty in-memory Workspace with the given logical root.
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) 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) 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) RecordRead ¶
func (w *Workspace) RecordRead(p string, version tool.FileVersion)
RecordRead stores the EXACT authoritative version for path under the session ledger. It performs NO I/O: it stores the FileVersion the caller supplies (the one ReadVersion minted), so a later RecordedVersion lookup compares against the recorded token without re-reading the file. The ledger key is the clean session-relative path (see cleanPath).
func (*Workspace) RecordedVersion ¶
func (w *Workspace) RecordedVersion(p string) (tool.FileVersion, bool)
RecordedVersion returns the version previously recorded for path via RecordRead, performing NO I/O. ok is false if path was never recorded. The lookup uses the same clean key as RecordRead.
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