Documentation
¶
Overview ¶
Package fs defines the virtual filesystem interface used by go-bash and utility functions for path manipulation.
All paths exchanged with FileSystem implementations are POSIX-style forward-slash paths. Paths containing a NUL byte ("\x00") are rejected at the API boundary — this matches POSIX and bash semantics and closes a class of injection attacks that exploit C-string truncation in lower layers.
Index ¶
- Constants
- Variables
- func Basename(path string) string
- func Clean(path string) string
- func Dirname(path string) string
- func IsWithinRoot(root, path string) bool
- func Join(parts ...string) string
- func PathError(op, path string, err error) error
- func Resolve(base, path string) string
- func SplitParts(path string) []string
- func Validate(path string) error
- type File
- type FileInit
- type FileSystem
Constants ¶
const ( SeekStart = io.SeekStart SeekCurrent = io.SeekCurrent SeekEnd = io.SeekEnd )
Seek-whence constants re-exported so users of the fs package do not need a separate io import when constructing File operations. Matches io.SeekStart, io.SeekCurrent, io.SeekEnd values exactly.
const MaxSymlinkDepth = 40
MaxSymlinkDepth bounds the number of symlink hops any resolver in the FileSystem layer will follow before returning a loop error. Matches the Linux kernel's MAXSYMLINKS / ELOOP threshold.
Variables ¶
var ( ErrNotImplemented = errors.New("operation not implemented") ErrReadOnly = errors.New("read-only filesystem") ErrSymlinkLoop = errors.New("too many levels of symbolic links") ErrNotDirectory = errors.New("not a directory") ErrIsDirectory = errors.New("is a directory") )
Helper sentinels exposed for cross-package error matching. Implementations should return wrapped *os.PathError values so callers can use errors.Is/As.
var ErrEmptyPath = errors.New("empty path")
ErrEmptyPath is returned by Validate when the input is the empty string.
var ErrNullByte = errors.New("path contains null byte")
ErrNullByte is returned by Validate when the input path contains a NUL byte. Callers should not unwrap this — match via errors.Is.
Functions ¶
func Basename ¶
Basename returns the final path component of path. For "/" it returns "/"; for "/a/b" it returns "b"; for "a" it returns "a".
func Clean ¶
Clean is a POSIX-style path cleaner. It collapses repeated slashes, resolves "." and ".." textually (without touching the filesystem), and removes a trailing slash except on the root path "/".
Empty input returns ".". A purely-relative path that resolves to the empty string after cleaning returns ".".
func Dirname ¶
Dirname returns everything up to (but not including) the last "/" in path. For "/a/b" it returns "/a"; for "a" it returns "."; for "/" it returns "/".
func IsWithinRoot ¶
IsWithinRoot reports whether path lies inside root (after cleaning), treating root as a prefix boundary. Both inputs are Cleaned before comparison so the answer is purely lexical — callers that need a symlink-resolved check must canonicalize first.
func Join ¶
Join concatenates path elements with "/" and Cleans the result. Empty elements are skipped. Join() == ".".
func PathError ¶
PathError builds an *os.PathError with the supplied op/path/err triple. Centralized so implementations stay consistent and so the type can be swapped without churn.
func Resolve ¶
Resolve returns the cleaned absolute form of path against base. If path is already absolute, base is ignored. If base is empty and path is relative, the result is just Clean(path).
func SplitParts ¶
SplitParts returns the cleaned path's components (without any leading slash). For "/a/b/c" it returns ["a", "b", "c"]; for "/" it returns nil. Helper used by tree-walking implementations.
Types ¶
type File ¶
File is a handle to an open file. It satisfies io/fs.File and adds the writer/seeker/truncate operations needed by shell redirection.
type FileInit ¶
type FileInit struct {
Content []byte
Lazy func(ctx context.Context) ([]byte, error)
Mode os.FileMode
// Dir signals that the entry is a directory rather than a file.
// The directory is created (recursively) with Mode (0o755 if zero).
Dir bool
// Symlink, when non-empty, marks the entry as a symbolic link
// pointing at the named target. Content/Lazy are ignored.
Symlink string
}
FileInit describes a single file passed via BashOptions.Files. Exactly one of Content or Lazy must be non-nil for a file entry; both nil produces an empty file. Directory entries (Dir=true) ignore Content and Lazy.
When Lazy is set, the underlying memfs creates a placeholder node that invokes the provider on first read, then memoizes the result. If a write occurs before any read, the provider is never called.
type FileSystem ¶
type FileSystem interface {
iofs.FS
iofs.StatFS
iofs.ReadDirFS
OpenFile(name string, flag int, perm os.FileMode) (File, error)
Create(name string) (File, error)
Mkdir(name string, perm os.FileMode) error
MkdirAll(name string, perm os.FileMode) error
Remove(name string) error
RemoveAll(name string) error
Rename(oldpath, newpath string) error
Symlink(target, linkpath string) error
Link(oldpath, newpath string) error
Readlink(name string) (string, error)
Lstat(name string) (os.FileInfo, error)
Realpath(name string) (string, error)
Chmod(name string, mode os.FileMode) error
Chtimes(name string, atime, mtime time.Time) error
ReadFile(name string) ([]byte, error)
WriteFile(name string, data []byte, perm os.FileMode) error
AppendFile(name string, data []byte, perm os.FileMode) error
// AllPaths returns every regular-file path the implementation can
// enumerate cheaply. Used by glob expansion against in-memory
// filesystems. Implementations that would have to do unbounded I/O
// (e.g. recursive disk scans) may return nil.
AllPaths() []string
}
FileSystem is the writable virtual filesystem interface implemented by memfs, overlayfs, rwfs, and mountfs. It embeds the read-only stdlib interfaces so callers can use io/fs helpers (fs.WalkDir, fs.ReadFile) against the sandbox.
Every path argument is a forward-slash POSIX path; implementations MUST call Validate(path) (or equivalent) at every public entry point and reject null bytes and empty paths before any I/O.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package fstest provides a contract test suite shared by every FileSystem implementation in go-bash.
|
Package fstest provides a contract test suite shared by every FileSystem implementation in go-bash. |
|
Package memfs implements an in-memory FileSystem suitable for use as the default backing store of a Bash sandbox.
|
Package memfs implements an in-memory FileSystem suitable for use as the default backing store of a Bash sandbox. |
|
Package mountfs implements a mount-table FileSystem composed of one or more child FileSystems mounted at virtual paths over a base FS.
|
Package mountfs implements a mount-table FileSystem composed of one or more child FileSystems mounted at virtual paths over a base FS. |
|
Package overlayfs implements an overlay FileSystem where writes land in an in-memory overlay and reads come from the overlay-or-real-disk union.
|
Package overlayfs implements an overlay FileSystem where writes land in an in-memory overlay and reads come from the overlay-or-real-disk union. |
|
Package realfs holds the security helpers shared by the read-write and overlay filesystems.
|
Package realfs holds the security helpers shared by the read-write and overlay filesystems. |
|
Package rwfs implements a read-write FileSystem that maps virtual paths under a sandbox root onto the host filesystem.
|
Package rwfs implements a read-write FileSystem that maps virtual paths under a sandbox root onto the host filesystem. |