Documentation
¶
Overview ¶
Package fs provides filesystem abstractions for testability and fault injection.
The package defines two key interfaces:
- File: Represents an open file with read/write/sync capabilities
- FileSystem: Abstracts filesystem operations (open, remove, rename, etc.)
Implementations ¶
- LocalFS: Production implementation using standard os package
- FaultyFS: Test utility for fault injection (simulate I/O errors)
Usage ¶
Production code should use fs.Default (which is LocalFS):
file, err := fs.Default.OpenFile(path, os.O_RDWR|os.O_CREATE, 0644)
Tests can inject FaultyFS to simulate failures:
ffs := fs.NewFaultyFS(nil) ffs.SetLimit(1024) // Fail after 1KB written // inject ffs into component under test
Design Notes ¶
This package intentionally does NOT include context.Context parameters. Filesystem operations are typically fast (microseconds for local NVMe) and non-interruptible at the syscall level. Adding context would add overhead without meaningful cancellation capability.
For slow operations (e.g., S3), use [blobstore.Blob] which has context support.
Index ¶
- type Fault
- type FaultyFS
- func (f *FaultyFS) AddRule(pattern string, fault Fault)
- func (f *FaultyFS) GetWritten() int64
- func (f *FaultyFS) MkdirAll(path string, perm os.FileMode) error
- func (f *FaultyFS) OpenFile(name string, flag int, perm os.FileMode) (File, error)
- func (f *FaultyFS) ReadDir(name string) ([]os.DirEntry, error)
- func (f *FaultyFS) Remove(name string) error
- func (f *FaultyFS) Rename(oldpath, newpath string) error
- func (f *FaultyFS) Reset()
- func (f *FaultyFS) SetError(err error)
- func (f *FaultyFS) SetLimit(limit int64)
- func (f *FaultyFS) Stat(name string) (os.FileInfo, error)
- func (f *FaultyFS) Truncate(name string, size int64) error
- type File
- type FileSystem
- type LocalFS
- func (LocalFS) MkdirAll(path string, perm os.FileMode) error
- func (LocalFS) OpenFile(name string, flag int, perm os.FileMode) (File, error)
- func (LocalFS) ReadDir(name string) ([]os.DirEntry, error)
- func (LocalFS) Remove(name string) error
- func (LocalFS) Rename(oldpath, newpath string) error
- func (LocalFS) Stat(name string) (os.FileInfo, error)
- func (LocalFS) Truncate(name string, size int64) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Fault ¶
type Fault struct {
// FailAfterBytes fails writes after this many bytes written to this file.
// -1 disables the per-file limit.
FailAfterBytes int64
// FailOnSync causes Sync() to return an error.
FailOnSync bool
// FailOnClose causes Close() to return an error (file is still closed).
FailOnClose bool
// Err is the error to return. If nil, a default error is used.
Err error
}
Fault defines specific failure behavior for a file.
type FaultyFS ¶
type FaultyFS struct {
FS FileSystem
// contains filtered or unexported fields
}
FaultyFS is a FileSystem wrapper that injects errors for testing. It supports both global write limits and per-file fault rules.
func NewFaultyFS ¶
func NewFaultyFS(fs FileSystem) *FaultyFS
NewFaultyFS creates a new FaultyFS wrapping the provided FS. If fs is nil, Default (LocalFS) is used.
func (*FaultyFS) AddRule ¶
AddRule adds a fault injection rule for files matching the pattern. Pattern matching uses strings.Contains (substring match). Later rules for the same pattern override earlier ones.
func (*FaultyFS) GetWritten ¶
GetWritten returns the total bytes written across all files.
type File ¶
type File interface {
io.ReadWriteCloser
io.ReaderAt
io.WriterAt
io.Seeker
Sync() error
Stat() (os.FileInfo, error)
}
File represents an open file with random-access read/write capabilities. It embeds standard io interfaces for composability.
type FileSystem ¶
type FileSystem interface {
// OpenFile opens a file with the specified flags and permissions.
// Flags are the same as os.OpenFile (O_RDONLY, O_WRONLY, O_RDWR, O_CREATE, etc.).
OpenFile(name string, flag int, perm os.FileMode) (File, error)
// Remove deletes the named file or empty directory.
Remove(name string) error
// Rename renames (moves) oldpath to newpath.
// If newpath exists, it is replaced.
Rename(oldpath, newpath string) error
// Stat returns file info for the named file.
Stat(name string) (os.FileInfo, error)
// MkdirAll creates a directory and all parent directories.
MkdirAll(path string, perm os.FileMode) error
// ReadDir reads the named directory and returns directory entries.
ReadDir(name string) ([]os.DirEntry, error)
// Truncate changes the size of the named file.
Truncate(name string, size int64) error
}
FileSystem abstracts filesystem operations for testability. All methods mirror the standard os package with identical semantics.
var Default FileSystem = LocalFS{}
Default is the default local file system implementation.
Source Files