vfs

Documentation

Overview

a paranoic layer to assure internal implementation consistency

Package vfs provides a virtual filesystem which can be written to. vfs.FS is a superset of io/fs.FS.

Index

• Constants
• func DirFS(root string, allowsymlinks bool) *dirfs
• func ExclusiveEmptyFileFuzzy(fsys FS, name0 string) (string, error)
• func Find(fsys FS, allowhidden bool, allowdirname, allowfilename func(string) bool) ([]string, error)
• func OpenFileRDONLY[T ReadWriteSyncCloser](openFile func(name string, flag int, perm fs.FileMode) (T, error), name string) (io.ReadCloser, error)
• func ReadFile(fsys FS, name string) ([]byte, error)
• func Tempfile(fsys FS, dirname string, content []byte) (string, func(), error)
• func WriteFile(fsys FS, name string, data []byte, perm fs.FileMode) error
• func WriteFileTRUNC(fsys FS, name string, data []byte, perm fs.FileMode) error
• type FS
  • func Restrict(fsys FS) FS
  • func Sub(fsys FS, name string, allowsymlinks bool) FS
• type ReadWriteSyncCloser
• type WriteSyncCloser
  • func OpenFileWRONLY[T ReadWriteSyncCloser](mkdirall func(name string, perm fs.FileMode) error, ...) (WriteSyncCloser, error)

Constants

const (
	O_RDONLY = os.O_RDONLY
	O_WRONLY = os.O_WRONLY
	O_CREATE = os.O_CREATE
	O_EXCL   = os.O_EXCL
)

Functions

func DirFS

func DirFS(root string, allowsymlinks bool) *dirfs

*dirfs implements FS

TODO Implement a blacklisting facility so that ".brief" is not only ignored by sacks/fssacks due to it being a hidden folder but it is fully invisible to the sacks/fssacks implementation.

DirFS' names are slash-delimited.

root is of path/filepath style

func ExclusiveEmptyFileFuzzy

func ExclusiveEmptyFileFuzzy(fsys FS, name0 string) (string, error)

ExclusiveEmptyFile creates an empty file named similiarly to name0. It is used to atomically reserve a filename.

ExclusiveEmptyFileFuzzy cannot fail unless fsys is degraded, at full capacity or contains more than INT64_MAX entries.

func Find

func Find(fsys FS, allowhidden bool, allowdirname, allowfilename func(string) bool) ([]string, error)

Find implements "$ find . -type f" for PWD=((fsys)).

func OpenFileRDONLY

func OpenFileRDONLY[T ReadWriteSyncCloser](openFile func(name string, flag int, perm fs.FileMode) (T, error), name string) (io.ReadCloser, error)

func ReadFile

func ReadFile(fsys FS, name string) ([]byte, error)

func Tempfile

func Tempfile(fsys FS, dirname string, content []byte) (string, func(), error)

Tempfile writes content to an exclusive, hidden filename.

Tempfile should not fail (uuid entropy is 24 bytes) unless fsys is degraded or at full capacity.

func WriteFile

func WriteFile(fsys FS, name string, data []byte, perm fs.FileMode) error

WriteFile is a Rename-based atomic wrapper.

func WriteFileTRUNC

func WriteFileTRUNC(fsys FS, name string, data []byte, perm fs.FileMode) error

WriteFileTRUNC is a Rename-based atomic wrapper. WriteFileTRUNC simulates an os.O_TRUNC write call by

Types

type FS

type FS interface {
	// Lstat may be implemented using os.Stat, offering all symlinks and the
	// resulting possibly wider filesystem reach to sacks/fssacks.
	Lstat(name string) (fs.FileInfo, error)

	// sacks/fssacks will always call Chmod with perm==0444.
	Chmod(name string, perm fs.FileMode) error

	// sacks/fssacks will always call MkdirAll with perm==0755
	MkdirAll(name string, perm fs.FileMode) error

	// sacks/fssacks will only ever call Remove on directories (meaning paths
	// it reasonably thinks are directories: an (exotic) filesystem may for
	// example both resolve "a.tar/b.eml" and "a.tar" to files; in this case,
	// "a.tar" may be considered a directory since it appears as non-leaf in
	// a valid path).
	// NOTE (internal): Specialising this to "Rmdir" does not by itself
	// guarantee sack monotonicity (meaning the impossibility to lose data)
	// as Rename could be used to stamp the empty file onto everything.
	Remove(name string) error

	// NOTE: ReadDir(".") is the correct root-level call.
	ReadDir(name string) ([]fs.DirEntry, error)

	// Rename is expected to be atomic.
	Rename(oldname, newname string) error

	// sacks/fssacks will always call OpenFile with
	// flag==os.O_WRONLY|os.O_CREATE|os.O_EXCL and perm==0444 or
	// flag==os.O_RDONLY and perm==0.
	// The returned io.ReadWriteCloser MUST error either on Read or Write.
	OpenFile(name string, flag int, perm fs.FileMode) (ReadWriteSyncCloser, error)
}

FS represents sacks/fssacks' minimal view of a filesystem. Names are interpreted as in io/fs: no leading slash, the entire namespace may be edited by sacks/fssacks to provide sacks.Sack facilities. Names are slash-separated. Use "path" instead of "path/filepath".

Currently, sacks/fssacks only accesses its FS synchronously. There is no guarantee for this to stay that way, however.

func Restrict

func Restrict(fsys FS) FS

func Sub

func Sub(fsys FS, name string, allowsymlinks bool) FS

[2023-12-09, jfrech] TODO implement

type ReadWriteSyncCloser

type ReadWriteSyncCloser interface {
	io.Reader
	WriteSyncCloser
}

type WriteSyncCloser

type WriteSyncCloser interface {
	io.Writer
	Sync() error

	// must be idempotent
	io.Closer
}

func OpenFileWRONLY

func OpenFileWRONLY[T ReadWriteSyncCloser](mkdirall func(name string, perm fs.FileMode) error, openFile func(name string, flag int, perm fs.FileMode) (T, error), name string) (WriteSyncCloser, error)