vfs

package module
v0.0.28 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 2, 2026 License: BSD-3-Clause Imports: 19 Imported by: 4

README

Virtual File System abstraction layer

This project entails just another virtual file system abstraction layer. The main aim is to describe file system functionality using a number of interfaces, while keeping the effort to implement them minimal. There is also special attention for setting and reading extended attributes.

Documentation

Index

Constants

View Source 
const ListBufSize = 512
View Source 
const ReadDirBufSize = 512
View Source 
const Separator = '/'

Variables

View Source 
var (
	SkipDir     = filepath.SkipDir //nolint:errname
	SkipAll     = filepath.SkipAll //nolint:errname
	SkipSubDirs = api.SkipSubDirs  //nolint:errname
)
View Source 
var (
	// Log context key to specify which logger.
	// Set a context value either to a *logrus.Logger or a *logrus.Entry to use a custom logger.
	// Defaults to logrus.StandardLogger
	Log = ContextKey("logger")

	// Boolean indicating whether List and Walk methods should return extended attributes.
	// If false, implementations may choose to not include them if Extended() is called on the returned file infos.
	ListWithXattrs = ContextKey("list-with-xattrs")

	// String indicating which local storage can be used as persistent storage for the inode handle database.
	PersistentStorage = ContextKey("persistent-storage")

	// Boolean indicating whether or not the inode handle database should be persisted.
	DisablePersistentHandleDB = ContextKey("disable-persistent-handle-db")

	// Boolean indicating whether or not server inodes should be used when exposing a native posix file system.
	UseServerInodes = ContextKey("use-serverino")

	// Boolean indicating whether or not chown is supported when exposing a native posix file system.
	AllowServerChown = ContextKey("allow-chown")
)
View Source 
var ErrInvalidHandle = fmt.Errorf("%w: invalid handle", syscall.EINVAL)
View Source 
var ErrNotImplemented = fmt.Errorf("%w: not implemented", syscall.EPERM)
View Source 
var ErrNotSupported = syscall.EOPNOTSUPP

Functions

func Base 

func Base(path string) string

Base returns the last element of path. If the path is empty or root, Base returns ".".

func Bool 

func Bool(ctx context.Context, key ContextKey) bool

Bool returns the boolean value associated with the given context key. If the key is not present in the context, it returns false.

func Checksum added in v0.0.25 

func Checksum(fs ReadFS, path string, algorithm crypto.Hash) ([]byte, error)

func Clean 

func Clean(path string) string

Clean strips trailing separators from the path, except for the root directory, which will never be stripped. It also removes ./ and ../ elements.

func Dir 

func Dir(path string) string

Dir returns all but the last element of path, typically the path's directory. On the root directory, Dir returns "" and prints a warning.

func Duration 

func Duration(ctx context.Context, key ContextKey) time.Duration

Duration returns the time.Duration value associated with the given context key. If the key is not present in the context, it returns 0.

func FileReadSeekCloser 

func FileReadSeekCloser(fs FS, path string) (io.ReadSeekCloser, error)

func FileWriteCloser 

func FileWriteCloser(fs FS, path string, flags int) (io.WriteCloser, error)

func Int 

func Int(ctx context.Context, key ContextKey) int

Int returns the int value associated with the given context key. If the key is not present in the context, it returns 0.

func IsAbs 

func IsAbs(path string) bool

IsAbs reports whether the path is absolute.

func IsPathSeparator 

func IsPathSeparator(c uint8) bool

func Iterate added in v0.0.12 

func Iterate(lister ListerAt, batchSize int) iter.Seq[FileInfo]

func Join 

func Join(paths ...string) string

Join joins any number of path elements into a single path, separating them with slashes.

func Logger 

func Logger(ctx context.Context) *logrus.Entry

func MkdirAll 

func MkdirAll(fs MkdirFS, path string, perm os.FileMode) error

func ReadFile 

func ReadFile(fs FS, path string) ([]byte, error)

func RemoveAll 

func RemoveAll(fs WalkRemoveFS, path string) error

func RunTestSuiteRO 

func RunTestSuiteRO(t *testing.T, fs FS)

RunTestSuiteRO runs comprehensive read-only tests for FS implementations

func RunTestSuiteRW 

func RunTestSuiteRW(t *testing.T, fs FS)

RunTestSuiteRW runs comprehensive read-write tests for FS implementations

func SetExtendedAttrs 

func SetExtendedAttrs(fs SetExtendedAttrFS, path string, attrs Attributes) error

func Split 

func Split(path string) (string, string)

func String 

func String(ctx context.Context, key ContextKey) string

String returns the string value associated with the given context key. If the key is not present in the context, it returns an empty string.

func Walk 

func Walk(fs WalkableFS, root string, fn WalkFunc) error

func WriteFile 

func WriteFile(fs FS, path string, data []byte, flags int) error

Types

type AdvancedFS 

type AdvancedFS interface {
	OpenFileFS
	HandleResolveFS
	SetExtendedAttrsFS
	ChecksumFS
}

type AdvancedLinkFS 

type AdvancedLinkFS interface {
	AdvancedFS
	SymlinkFS
	LinkFS
	RealPath(path string) (string, error)
}

type Attributes 

type Attributes map[string][]byte

func (Attributes) Delete 

func (a Attributes) Delete(name string)

func (Attributes) Get 

func (a Attributes) Get(name string) ([]byte, bool)

func (Attributes) GetString 

func (a Attributes) GetString(name string) (string, bool)

func (Attributes) Set 

func (a Attributes) Set(name string, value []byte)

func (Attributes) SetString 

func (a Attributes) SetString(name, value string)

type ChecksumFS added in v0.0.25 

type ChecksumFS interface {
	FS
	Checksum(path string, algorithm crypto.Hash) ([]byte, error)
}

type ContextKey 

type ContextKey string

type FS 

type FS interface {
	Stat(path string) (FileInfo, error)
	List(path string) (ListerAt, error)
	FileRead(path string) (ReaderAt, error)
	FileWrite(path string, flags int) (WriterAt, error)
	Chmod(path string, mode os.FileMode) error
	Chown(path string, uid, gid int) error
	Chtimes(path string, atime, mtime time.Time) error
	Truncate(path string, size int64) error
	SetExtendedAttr(path string, name string, value []byte) error
	UnsetExtendedAttr(path string, name string) error
	Rename(oldpath, newpath string) error
	Rmdir(path string) error
	Remove(path string) error
	Mkdir(path string, perm os.FileMode) error
	Close() error
}

FS interface Implementing file systems should implement all methods.

type File 

type File interface {
	Name() string
	Stat() (FileInfo, error)
	Truncate(size int64) error
	Readdir(count int) ([]FileInfo, error)
	io.ReadWriteCloser
	WriterAtReaderAt
	io.Seeker
}

func Open 

func Open(fs OpenableFS, path string) (File, error)

type FileInfo 

type FileInfo interface {
	os.FileInfo
	Uid() uint32
	Gid() uint32
	NumLinks() uint64
	Extended() (Attributes, error)
	Permissions() (*Permissions, error) // Returns an indicative permission set to indicate which permissions the client has
}

func ListAll 

func ListAll(lister ListerAt) ([]FileInfo, error)

func ReadDir 

func ReadDir(fs WalkableFS, dirname string) ([]FileInfo, error)

ReadDir reads the directory named by dirname and returns a sorted list of directory entries.

type FileInfoListerAt 

type FileInfoListerAt []FileInfo

func (FileInfoListerAt) Close 

func (f FileInfoListerAt) Close() error

func (FileInfoListerAt) ListAt 

func (f FileInfoListerAt) ListAt(ls []FileInfo, offset int64) (int, error)

Modeled after strings.Reader's ReadAt() implementation

type HandleFS 

type HandleFS interface {
	FS
	Handle(path string) ([]byte, error)
}

type HandleFileInfo added in v0.0.24 

type HandleFileInfo interface {
	FileInfo
	Handle() ([]byte, error)
}

type HandleResolveFS 

type HandleResolveFS interface {
	HandleFS
	Path(handle []byte) (string, error)
}

type LinkFS 

type LinkFS interface {
	FS
	Link(oldname, newname string) error
}

type ListerAt 

type ListerAt interface {
	ListAt(buf []FileInfo, offset int64) (int, error)
	Close() error
}

type MkdirFS 

type MkdirFS interface {
	Stat(path string) (FileInfo, error)
	Mkdir(path string, perm os.FileMode) error
}

type NotImplementedAdvancedFS 

type NotImplementedAdvancedFS struct {
	NotImplementedFS
}

func (NotImplementedAdvancedFS) Checksum added in v0.0.25 

func (n NotImplementedAdvancedFS) Checksum(path string, algorithm crypto.Hash) ([]byte, error)

func (NotImplementedAdvancedFS) Handle 

func (n NotImplementedAdvancedFS) Handle(path string) ([]byte, error)

func (NotImplementedAdvancedFS) Open 

func (n NotImplementedAdvancedFS) Open(path string) (File, error)

func (NotImplementedAdvancedFS) OpenFile 

func (n NotImplementedAdvancedFS) OpenFile(path string, mode int, perm os.FileMode) (File, error)

func (NotImplementedAdvancedFS) Path 

func (n NotImplementedAdvancedFS) Path(handle []byte) (string, error)

func (NotImplementedAdvancedFS) Walk 

func (n NotImplementedAdvancedFS) Walk(path string, fn WalkFunc) error

type NotImplementedFS 

type NotImplementedFS struct{}

Base for partial implementations

func (NotImplementedFS) Chmod 

func (n NotImplementedFS) Chmod(path string, mode os.FileMode) error

func (NotImplementedFS) Chown 

func (n NotImplementedFS) Chown(path string, uid, gid int) error

func (NotImplementedFS) Chtimes 

func (n NotImplementedFS) Chtimes(path string, atime, mtime time.Time) error

func (NotImplementedFS) Close 

func (n NotImplementedFS) Close() error

func (NotImplementedFS) FileRead 

func (n NotImplementedFS) FileRead(path string) (ReaderAt, error)

func (NotImplementedFS) FileWrite 

func (n NotImplementedFS) FileWrite(path string, flag int) (WriterAt, error)

func (NotImplementedFS) List 

func (n NotImplementedFS) List(path string) (ListerAt, error)

func (NotImplementedFS) Mkdir 

func (n NotImplementedFS) Mkdir(path string, perm os.FileMode) error

func (NotImplementedFS) Remove 

func (n NotImplementedFS) Remove(path string) error

func (NotImplementedFS) Rename 

func (n NotImplementedFS) Rename(oldpath, newpath string) error

func (NotImplementedFS) Rmdir 

func (n NotImplementedFS) Rmdir(path string) error

func (NotImplementedFS) SetExtendedAttr 

func (n NotImplementedFS) SetExtendedAttr(path, name string, value []byte) error

func (NotImplementedFS) SetExtendedAttrs 

func (n NotImplementedFS) SetExtendedAttrs(path string, attrs Attributes) error

func (NotImplementedFS) Stat 

func (n NotImplementedFS) Stat(path string) (FileInfo, error)

func (NotImplementedFS) Truncate 

func (n NotImplementedFS) Truncate(path string, size int64) error

func (NotImplementedFS) UnsetExtendedAttr 

func (n NotImplementedFS) UnsetExtendedAttr(path, name string) error

type NotImplementedRootFS 

type NotImplementedRootFS struct {
	NotImplementedAdvancedFS
}
func (n NotImplementedRootFS) Link(path, target string) error

func (NotImplementedRootFS) Lstat 

func (n NotImplementedRootFS) Lstat(path string) (FileInfo, error)

func (NotImplementedRootFS) Mount 

func (n NotImplementedRootFS) Mount(path string, fs FS, index byte) error
func (n NotImplementedRootFS) Readlink(path string) (string, error)

func (NotImplementedRootFS) RealPath 

func (n NotImplementedRootFS) RealPath(path string) (string, error)
func (n NotImplementedRootFS) Symlink(path, target string) error

type OpenFS added in v0.0.19 

type OpenFS interface {
	FS
	Open(path string) (File, error)
}

type OpenFileFS 

type OpenFileFS interface {
	FS
	OpenFile(path string, flag int, perm os.FileMode) (File, error)
}

type OpenableFS 

type OpenableFS interface {
	Stat(path string) (FileInfo, error)
	FileRead(path string) (ReaderAt, error)
	List(path string) (ListerAt, error)
}

type Permissions 

type Permissions struct {
	Read             bool // List, FileRead
	Write            bool // FileWrite, Chtimes, Truncate
	Delete           bool // Rmdir, Remove
	Own              bool // Chmod, Chown (depends on target user/group), Chtimes
	GetExtendedAttrs bool // Stat returns extended attributes
	SetExtendedAttrs bool // SetExtendedAttrs
}

type ReadFS added in v0.0.25 

type ReadFS interface {
	FileRead(path string) (ReaderAt, error)
}

type ReaderAt 

type ReaderAt interface {
	io.ReaderAt
	io.Closer
}

type RootFS 

type RootFS interface {
	AdvancedLinkFS
	WalkFS
	Open(path string) (File, error)
	Mount(path string, fs FS, index byte) error
}

type SetExtendedAttrFS 

type SetExtendedAttrFS interface {
	Stat(path string) (FileInfo, error)
	SetExtendedAttr(path string, name string, value []byte) error
	UnsetExtendedAttr(path string, name string) error
}

type SetExtendedAttrsFS 

type SetExtendedAttrsFS interface {
	FS
	SetExtendedAttrs(path string, attrs Attributes) error
}

type SymlinkFS 

type SymlinkFS interface {
	FS
	Lstat(path string) (FileInfo, error)
	Symlink(target, link string) error
	Readlink(path string) (string, error)
}

type WalkFS 

type WalkFS interface {
	FS
	Walk(path string, walkFn WalkFunc) error
}

type WalkFunc 

type WalkFunc func(path string, info FileInfo, err error) error

type WalkRemoveFS 

type WalkRemoveFS interface {
	WalkableFS
	Remove(path string) error
	Rmdir(path string) error
}

type WalkableFS 

type WalkableFS interface {
	Stat(path string) (FileInfo, error)
	List(path string) (ListerAt, error)
}

type WriterAt 

type WriterAt interface {
	io.WriterAt
	io.Closer
}

type WriterAtReaderAt 

type WriterAtReaderAt interface {
	io.WriterAt
	io.ReaderAt
	io.Closer
}

Source Files

View all Source files

Directories

Path Synopsis
fs
emptyfs
errorfs
iofs
irodsfs
nativefs
rootfs
rootfs/handledb
sftpfs
sysfs
wrapfs
writeonlyfs
io
buffered
readerat
writerat

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.