fsx

package
v0.20.0 Latest Latest
Warning

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

 Go to latest Published: Mar 9, 2025 License: GPL-3.0 Imports: 9 Imported by: 6

Documentation

Overview

Package fsx allows abstracting the file system.

This package is derived from afero.

In addition to afero, we also implement support for dialing and listening unix domain sockets, and for Lstat.

Unix Domain Sockets Portability Note

Beware that Unix domain sockets have path length limitations ranging around ~100 chars (e.g., 108 on Linux, 104 on macOS) for historical reasons (see, e.g., https://unix.stackexchange.com/q/367008). When using Unix domain sockets, therefore, it is possible to get `EINVAL` errors in `bind` or `connect`, which occur when the combined path is too long. If possible, consider using a relative base path (if you know you'll never chdir elsewhere), or possibly use secure temporary directories.

Index

Constants

View Source 
const (
	O_CREATE = fsmodel.O_CREATE
	O_RDONLY = fsmodel.O_RDONLY
	O_RDWR   = fsmodel.O_RDWR
	O_TRUNC  = fsmodel.O_TRUNC
	O_WRONLY = fsmodel.O_WRONLY
	O_APPEND = fsmodel.O_APPEND
)

Forward file system constants.

Variables

View Source 
var NewAbsoluteChdirPathMapper = NewAbsolutePrefixDirPathMapper

NewAbsoluteChdirPathMapper is a deprecated alias for NewAbsolutePrefixDirPathMapper.

View Source 
var NewRelativeChdirPathMapper = NewRelativePrefixDirPathMapper

NewRelativeChdirPathMapper is a deprecated alias for NewRelativePrefixDirPathMapper.

View Source 
var NewRelativeFS = NewContainedFS

NewRelativeFS is a deprecated alias for NewContainedFS.

Deprecated: use NewContainedFS instead.

Functions

func IsNotExist 

func IsNotExist(err error) bool

IsNotExist combines the os.IsNotExist check with checking for the fs.ErrNotExist error.

Types

type ChdirFS deprecated 

type ChdirFS struct {
	*OverlayFS
}

ChdirFS is the FS type returned by NewChdirFS.

The zero value IS NOT ready to use; construct using NewChdirFS.

Deprecated: use NewOverlayFS with NewRelativePrefixDirPathMapper instead.

func NewChdirFS deprecated 

func NewChdirFS(dep FS, path string) *ChdirFS

NewChdirFS creates a new FS where each file name is prefixed with the given directory path.

Deprecated: use NewOverlayFS with NewRelativePrefixDirPathMapper instead.

type ChdirPathMapper added in v0.15.0 

type ChdirPathMapper = PrefixDirPathMapper

ChdirPathMapper is a deprecated alias for PrefixDirPathMapper.

type ContainedDirPathMapper added in v0.15.0 

type ContainedDirPathMapper struct {
	// contains filtered or unexported fields
}

ContainedDirPathMapper is a RealPathMapper that prevents accessing file names outside of a given base directory.

Any file name (after filepath.Clean) outside this base path will be treated as a non-existing file.

Any absolute file name will be treated as a non-existing file.

We return fs.ErrNotExist in these cases.

Note: This implementation cannot prevent symlink traversal attacks. The caller must ensure the base directory does not contain symlinks if this is a security requirement.

The zero value is invalid. Use NewRelativeContainedDirPathMapper or NewAbsoluteContainedDirPathMapper to construct a new instance.

func NewAbsoluteContainedDirPathMapper added in v0.15.0 

func NewAbsoluteContainedDirPathMapper(baseDir string) (*ContainedDirPathMapper, error)

NewAbsoluteContainedDirPathMapper converts the given directory to an absolute path and, on success, returns a new *ContainedDirPathMapper instance. On failure, it returns and error.

Usage Considerations

Use this constructor when you want your *ContainedDirPathMapper to be robust against concurrent invocations of os.Chdir.

func NewRelativeContainedDirPathMapper added in v0.15.0 

func NewRelativeContainedDirPathMapper(baseDir string) *ContainedDirPathMapper

NewRelativeContainedDirPathMapper returns a new *ContainedDirPathMapper instance without bothering to check if the given directory is relative or absolute.

Usage Considerations

Use this constructor when you know your program is not going to invoke os.Chdir so you can avoid building potentially long paths that could break Unix domain sockets as documented in the top-level package documentation.

func (*ContainedDirPathMapper) RealPath added in v0.15.0 

func (c *ContainedDirPathMapper) RealPath(virtualPath string) (realPath string, err error)

RealPath implements RealPathMapper.

type ContainedFS deprecated added in v0.15.0 

type ContainedFS struct {
	*OverlayFS
}

ContainedFS is the FS type returned by NewContainedFS.

The zero value IS NOT ready to use; construct using NewContainedFS.

Deprecated: use NewOverlayFS with NewRelativeContainedDirPathMapper instead.

func NewContainedFS deprecated added in v0.15.0 

func NewContainedFS(dep FS, path string) *ContainedFS

NewContainedFS creates a new FS rooted at the given path using the given child FS as the dependency.

Any file name (after filepath.Clean) outside this base path will be treated as a non-existing file.

Any absolute file name will be treated as a non-existing file.

We return fs.ErrNotExist in these cases.

Note: This implementation cannot prevent symlink traversal attacks. The caller must ensure the base directory does not contain symlinks if this is a security requirement.

Deprecated: use NewOverlayFS with NewRelativeContainedDirPathMapper instead.

type FS 

type FS = fsmodel.FS

FS is an alias for fsmodel.FS.

type File 

type File = fsmodel.File

File is an alias for fsmodel.File.

type OsFS 

type OsFS struct{}

OsFS implements FS using the standard os package.

The zero value is ready to use.

func (OsFS) Chmod 

func (OsFS) Chmod(name string, mode fs.FileMode) error

Chmod implements FS.

func (OsFS) Chown 

func (OsFS) Chown(name string, uid, gid int) error

Chown implements FS.

func (OsFS) Chtimes 

func (OsFS) Chtimes(name string, atime, mtime time.Time) error

Chtimes implements FS.

func (OsFS) Create 

func (OsFS) Create(name string) (File, error)

Create implements FS.

func (OsFS) DialUnix 

func (OsFS) DialUnix(name string) (net.Conn, error)

DialUnix implements FS.

See also the limitations documented in the top-level package docs.

func (OsFS) ListenUnix 

func (OsFS) ListenUnix(name string) (net.Listener, error)

ListenUnix implements FS.

See also the limitations documented in the top-level package docs.

func (OsFS) Lstat 

func (OsFS) Lstat(name string) (fs.FileInfo, error)

Lstat implements FS.

func (OsFS) Mkdir 

func (OsFS) Mkdir(name string, mode fs.FileMode) error

Mkdir implements FS.

func (OsFS) MkdirAll 

func (OsFS) MkdirAll(name string, mode fs.FileMode) error

MkdirAll implements FS.

func (OsFS) Open 

func (OsFS) Open(name string) (File, error)

Open implements FS.

func (OsFS) OpenFile 

func (OsFS) OpenFile(name string, flag int, mode fs.FileMode) (File, error)

OpenFile implements FS.

func (OsFS) ReadDir 

func (OsFS) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir implements FS.

func (OsFS) Remove 

func (OsFS) Remove(name string) error

Remove implements FS.

func (OsFS) RemoveAll 

func (OsFS) RemoveAll(name string) error

RemoveAll implements FS.

func (OsFS) Rename 

func (OsFS) Rename(oldname, newname string) error

Rename implements FS.

func (OsFS) Stat 

func (OsFS) Stat(name string) (os.FileInfo, error)

Stat implements FS.

type OverlayFS added in v0.15.0 

type OverlayFS struct {
	// contains filtered or unexported fields
}

OverlayFS overlays a path manipulation function implemented by RealPathMapper on top of another FS.

The zero value is invalid. Construct using NewOverlayFS.

func NewOverlayFS added in v0.15.0 

func NewOverlayFS(fs FS, rpm RealPathMapper) *OverlayFS

NewOverlayFS creates a new FS that uses RealPathMapper to map virtual paths to real paths on top of the given FS.

func (*OverlayFS) Chmod added in v0.15.0 

func (rfs *OverlayFS) Chmod(name string, mode fs.FileMode) error

Chmod implements FS.

func (*OverlayFS) Chown added in v0.15.0 

func (rfs *OverlayFS) Chown(name string, uid, gid int) error

Chown implements FS.

func (*OverlayFS) Chtimes added in v0.15.0 

func (rfs *OverlayFS) Chtimes(name string, atime, mtime time.Time) error

Chtimes implements FS.

func (*OverlayFS) Create added in v0.15.0 

func (rfs *OverlayFS) Create(name string) (File, error)

Create implements FS.

func (*OverlayFS) DialUnix added in v0.15.0 

func (rfs *OverlayFS) DialUnix(name string) (net.Conn, error)

DialUnix implements FS.

See also the limitations documented in the top-level package docs.

func (*OverlayFS) ListenUnix added in v0.15.0 

func (rfs *OverlayFS) ListenUnix(name string) (net.Listener, error)

ListenUnix implements FS.

See also the limitations documented in the top-level package docs.

func (*OverlayFS) Lstat added in v0.15.0 

func (rfs *OverlayFS) Lstat(name string) (fs.FileInfo, error)

Lstat implements FS.

func (*OverlayFS) Mkdir added in v0.15.0 

func (rfs *OverlayFS) Mkdir(name string, mode fs.FileMode) error

Mkdir implements FS.

func (*OverlayFS) MkdirAll added in v0.15.0 

func (rfs *OverlayFS) MkdirAll(name string, mode fs.FileMode) error

MkdirAll implements FS.

func (*OverlayFS) Open added in v0.15.0 

func (rfs *OverlayFS) Open(name string) (File, error)

Open implements FS.

func (*OverlayFS) OpenFile added in v0.15.0 

func (rfs *OverlayFS) OpenFile(name string, flag int, mode fs.FileMode) (File, error)

OpenFile implements FS.

func (*OverlayFS) ReadDir added in v0.15.0 

func (rfs *OverlayFS) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir implements FS.

func (*OverlayFS) Remove added in v0.15.0 

func (rfs *OverlayFS) Remove(name string) error

Remove implements FS.

func (*OverlayFS) RemoveAll added in v0.15.0 

func (rfs *OverlayFS) RemoveAll(name string) error

RemoveAll implements FS.

func (*OverlayFS) Rename added in v0.15.0 

func (rfs *OverlayFS) Rename(oldname, newname string) error

Rename implements FS.

func (*OverlayFS) Stat added in v0.15.0 

func (rfs *OverlayFS) Stat(name string) (fs.FileInfo, error)

Stat implements FS.

type PrefixDirPathMapper added in v0.16.0 

type PrefixDirPathMapper struct {
	// contains filtered or unexported fields
}

PrefixDirPathMapper is a RealPathMapper that prepends a base directory to the virtual path.

The zero value is invalid. Use NewRelativePrefixDirPathMapper, NewRelativeToCwdPrefixDirPathMapper or NewAbsolutePrefixDirPathMapper to construct a new instance.

func NewAbsolutePrefixDirPathMapper added in v0.16.0 

func NewAbsolutePrefixDirPathMapper(baseDir string) (*PrefixDirPathMapper, error)

NewAbsolutePrefixDirPathMapper converts the given directory to an absolute path and, on success, returns a new *PrefixDirPathMapper instance. On failure, it returns and error.

Usage Considerations

Use this constructor when you want your *PrefixDirPathMapper to be robust against concurrent invocations of os.Chdir.

func NewRelativePrefixDirPathMapper added in v0.16.0 

func NewRelativePrefixDirPathMapper(baseDir string) *PrefixDirPathMapper

NewRelativePrefixDirPathMapper returns a new *PrefixDirPathMapper instance without bothering to check if the given directory is relative or absolute.

Usage Considerations

Use this constructor when you know your program is not going to invoke os.Chdir so you can avoid building potentially long paths that could break Unix domain sockets as documented in the top-level package documentation.

func NewRelativeToCwdPrefixDirPathMapper added in v0.16.0 

func NewRelativeToCwdPrefixDirPathMapper(path string) (*PrefixDirPathMapper, error)

NewRelativeToCwdPrefixDirPathMapper returns a *PrefixDirPathMapper in which the given base directory is made relative to the current working directory obtained using os.Getwd at the time of the call. On failure, it returns an error.

Usage Considerations

Use this constructor when you know your program is not going to invoke os.Chdir so you can avoid building potentially long paths that could break Unix domain sockets as documented in the top-level package documentation.

This constructor explicitly addresses the `rbmk sh` use case where mvdan.cc/sh/v3/interp provides us with the absolute path of the current working directory, subcommands run as goroutines, we cannot chdir because we're still in the same process, and we want to minimise the length of paths because of Unix domain sockets path limitations.

func (*PrefixDirPathMapper) RealPath added in v0.16.0 

func (b *PrefixDirPathMapper) RealPath(virtualPath string) (realPath string, err error)

RealPath implements RealPathMapper.

type RealPathMapper added in v0.15.0 

type RealPathMapper interface {
	RealPath(virtualPath string) (realPath string, err error)
}

RealPathMapper maps a virtual file name to its real path name.

type RealPathMapperFunc added in v0.15.0 

type RealPathMapperFunc func(virtualPath string) (realPath string, err error)

RealPathMapperFunc is a function type that implements RealPathMapper.

func (RealPathMapperFunc) RealPath added in v0.15.0 

func (fx RealPathMapperFunc) RealPath(virtualPath string) (realPath string, err error)

RealPath implements RealPathMapper.

type RelativeFS deprecated 

type RelativeFS = ContainedFS

RelativeFS is a deprecated alias for ContainedFS.

Deprecated: use ContainedFS instead.

Source Files

View all Source files

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.