github.com/avfs/avfs@v0.33.1-0.20240303173310-c6ba67c33eb7/vfs.go

//
//  Copyright 2021 The AVFS authors
//
//  Licensed under the Apache License, Version 2.0 (the "License");
//  you may not use this file except in compliance with the License.
//  You may obtain a copy of the License at
//
//  	http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//

package avfs

import (
	"errors"
	"io"
	"io/fs"
	"os"
	"path/filepath"
	"sort"
	"strings"
	_ "unsafe" // for go:linkname only.
)

// cleanGlobPath prepares path for glob matching.
func cleanGlobPath[T VFSBase](vfs T, path string) string {
	pathSeparator := vfs.PathSeparator()

	switch path {
	case "":
		return "."
	case string(pathSeparator):
		// do nothing to the path
		return path
	default:
		return path[0 : len(path)-1] // chop off trailing separator
	}
}

// cleanGlobPathWindows is Windows version of cleanGlobPath.
func cleanGlobPathWindows[T VFSBase](vfs T, path string) (prefixLen int, cleaned string) {
	vollen := VolumeNameLen(vfs, path)

	switch {
	case path == "":
		return 0, "."
	case vollen+1 == len(path) && IsPathSeparator(vfs, path[len(path)-1]): // /, \, C:\ and C:/
		// do nothing to the path
		return vollen + 1, path
	case vollen == len(path) && len(path) == 2: // C:
		return vollen, path + "." // convert C: into C:.
	default:
		if vollen >= len(path) {
			vollen = len(path) - 1
		}

		return vollen, path[0 : len(path)-1] // chop off trailing separator
	}
}

// Create creates or truncates the named file. If the file already exists,
// it is truncated. If the file does not exist, it is created with mode 0666
// (before umask). If successful, methods on the returned DummyFile can
// be used for I/O; the associated file descriptor has mode O_RDWR.
// If there is an error, it will be of type *PathError.
func Create[T VFSBase](vfs T, name string) (File, error) {
	return vfs.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_TRUNC, DefaultFilePerm)
}

// CreateTemp creates a new temporary file in the directory dir,
// opens the file for reading and writing, and returns the resulting file.
// The filename is generated by taking pattern and adding a random string to the end.
// If pattern includes a "*", the random string replaces the last "*".
// If dir is the empty string, CreateTemp uses the default directory for temporary files, as returned by TempDir.
// Multiple programs or goroutines calling CreateTemp simultaneously will not choose the same file.
// The caller can use the file's Name method to find the pathname of the file.
// It is the caller's responsibility to remove the file when it is no longer needed.
func CreateTemp[T VFSBase](vfs T, dir, pattern string) (File, error) {
	const op = "createtemp"

	if dir == "" {
		dir = TempDir(vfs)
	}

	prefix, suffix, err := prefixAndSuffix(vfs, pattern)
	if err != nil {
		return nil, &fs.PathError{Op: op, Path: pattern, Err: err}
	}

	prefix = joinPath(vfs, dir, prefix)

	try := 0

	for {
		name := prefix + nextRandom() + suffix

		f, err := vfs.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0o600)
		if IsExist(err) {
			try++
			if try < 10000 {
				continue
			}

			return nil, &fs.PathError{Op: op, Path: dir + string(vfs.PathSeparator()) + prefix + "*" + suffix, Err: fs.ErrExist}
		}

		return f, err
	}
}

// FromUnixPath returns valid path for Unix or Windows from a unix path.
// For Windows systems, absolute paths are prefixed with the default volume
// and relative paths are preserved.
func FromUnixPath[T VFSBase](vfs T, path string) string {
	if vfs.OSType() != OsWindows {
		return path
	}

	if path[0] != '/' {
		return FromSlash(vfs, path)
	}

	return Join(vfs, DefaultVolume, FromSlash(vfs, path))
}

// Glob returns the names of all files matching pattern or nil
// if there is no matching file. The syntax of patterns is the same
// as in Match. The pattern may describe hierarchical names such as
// /usr/*/bin/ed (assuming the Separator is '/').
//
// Glob ignores file system errors such as I/O errors reading directories.
// The only possible returned error is ErrBadPattern, when pattern
// is malformed.
func Glob[T VFSBase](vfs T, pattern string) (matches []string, err error) {
	// Check pattern is well-formed.
	if _, err = Match(vfs, pattern, ""); err != nil {
		return nil, err
	}

	if !hasMeta(vfs, pattern) {
		if _, err = vfs.Lstat(pattern); err != nil {
			return nil, nil
		}

		return []string{pattern}, nil
	}

	dir, file := Split(vfs, pattern)
	volumeLen := 0

	if vfs.OSType() == OsWindows {
		volumeLen, dir = cleanGlobPathWindows(vfs, dir)
	} else {
		dir = cleanGlobPath(vfs, dir)
	}

	if !hasMeta(vfs, dir[volumeLen:]) {
		return glob(vfs, dir, file, nil)
	}

	// Prevent infinite recursion. See issue 15879.
	if dir == pattern {
		return nil, filepath.ErrBadPattern
	}

	var m []string

	m, err = Glob(vfs, dir)
	if err != nil {
		return
	}

	for _, d := range m {
		matches, err = glob(vfs, d, file, matches)
		if err != nil {
			return
		}
	}

	return //nolint:nakedret // Adapted from standard library.
}

// glob searches for files matching pattern in the directory dir
// and appends them to matches. If the directory cannot be
// opened, it returns the existing matches. New matches are
// added in lexicographical order.
func glob[T VFSBase](vfs T, dir, pattern string, matches []string) (m []string, e error) {
	m = matches

	fi, err := vfs.Stat(dir)
	if err != nil {
		return // ignore I/O error
	}

	if !fi.IsDir() {
		return // ignore I/O error
	}

	d, err := vfs.OpenFile(dir, os.O_RDONLY, 0)
	if err != nil {
		return // ignore I/O error
	}

	defer d.Close()

	names, _ := d.Readdirnames(-1)
	sort.Strings(names)

	for _, n := range names {
		matched, err := Match(vfs, pattern, n)
		if err != nil {
			return m, err
		}

		if matched {
			m = append(m, Join(vfs, dir, n))
		}
	}

	return //nolint:nakedret // Adapted from standard library.
}

// hasMeta reports whether path contains any of the magic characters
// recognized by Match.
func hasMeta[T VFSBase](vfs T, path string) bool {
	magicChars := `*?[`

	if vfs.OSType() != OsWindows {
		magicChars = `*?[\`
	}

	return strings.ContainsAny(path, magicChars)
}

// HomeDir returns the home directory of the file system.
func HomeDir[T VFSBase](vfs T, basePath string) string {
	switch vfs.OSType() {
	case OsWindows:
		return Join(vfs, basePath, `\Users`)
	default:
		return Join(vfs, "/home")
	}
}

// HomeDirUser returns the home directory of the user.
// If the file system does not have an identity manager, the root directory is returned.
func HomeDirUser[T VFSBase](vfs T, basePath string, u UserReader) string {
	name := u.Name()
	if vfs.OSType() == OsWindows {
		return Join(vfs, HomeDir(vfs, basePath), name)
	}

	if name == AdminUserName(vfs.OSType()) {
		return "/root"
	}

	return Join(vfs, HomeDir(vfs, basePath), name)
}

// HomeDirPerm return the default permission for home directories.
func HomeDirPerm() fs.FileMode {
	return 0o700
}

// IsExist returns a boolean indicating whether the error is known to report
// that a file or directory already exists. It is satisfied by ErrExist as
// well as some syscall errors.
//
// This function predates errors.Is. It only supports errors returned by
// the os package. New code should use errors.Is(err, fs.ErrExist).
func IsExist(err error) bool {
	return errors.Is(err, fs.ErrExist)
}

// IsNotExist returns a boolean indicating whether the error is known to
// report that a file or directory does not exist. It is satisfied by
// ErrNotExist as well as some syscall errors.
//
// This function predates errors.Is. It only supports errors returned by
// the os package. New code should use errors.Is(err, fs.ErrNotExist).
func IsNotExist(err error) bool {
	return errors.Is(err, fs.ErrNotExist)
}

func joinPath[T VFSBase](vfs T, dir, name string) string {
	if dir != "" && IsPathSeparator(vfs, dir[len(dir)-1]) {
		return dir + name
	}

	return dir + string(vfs.PathSeparator()) + name
}

// MkdirTemp creates a new temporary directory in the directory dir
// and returns the pathname of the new directory.
// The new directory's name is generated by adding a random string to the end of pattern.
// If pattern includes a "*", the random string replaces the last "*" instead.
// If dir is the empty string, MkdirTemp uses the default directory for temporary files, as returned by TempDir.
// Multiple programs or goroutines calling MkdirTemp simultaneously will not choose the same directory.
// It is the caller's responsibility to remove the directory when it is no longer needed.
func MkdirTemp[T VFSBase](vfs T, dir, pattern string) (string, error) {
	const op = "mkdirtemp"

	if dir == "" {
		dir = vfs.TempDir()
	}

	prefix, suffix, err := prefixAndSuffix(vfs, pattern)
	if err != nil {
		return "", &fs.PathError{Op: op, Path: pattern, Err: err}
	}

	prefix = joinPath(vfs, dir, prefix)
	try := 0

	for {
		name := prefix + nextRandom() + suffix

		err := vfs.Mkdir(name, 0o700)
		if err == nil {
			return name, nil
		}

		if IsExist(err) {
			try++
			if try < 10000 {
				continue
			}

			return "", &fs.PathError{Op: op, Path: dir + string(vfs.PathSeparator()) + prefix + "*" + suffix, Err: fs.ErrExist}
		}

		if IsNotExist(err) {
			_, err := vfs.Stat(dir) //nolint:govet // declaration of "err" shadows declaration
			if IsNotExist(err) {
				return "", err
			}
		}

		return "", err
	}
}

// MkHomeDir creates and returns the home directory of a user.
// If there is an error, it will be of type *PathError.
func MkHomeDir[T VFSBase](vfs T, basePath string, u UserReader) (string, error) {
	userDir := HomeDirUser(vfs, basePath, u)

	err := vfs.Mkdir(userDir, HomeDirPerm())
	if err != nil {
		return "", err
	}

	switch vfs.OSType() {
	case OsWindows:
		err = vfs.MkdirAll(TempDirUser(vfs, basePath, u.Name()), DefaultDirPerm)
	default:
		err = vfs.Chown(userDir, u.Uid(), u.Gid())
	}

	if err != nil {
		return "", err
	}

	return userDir, nil
}

// MkSystemDirs creates the system directories of a file system.
func MkSystemDirs[T VFSBase](vfs T, dirs []DirInfo) error {
	for _, dir := range dirs {
		err := vfs.MkdirAll(dir.Path, dir.Perm)
		if err != nil {
			return err
		}

		if vfs.OSType() != OsWindows {
			err = vfs.Chmod(dir.Path, dir.Perm)
			if err != nil {
				return err
			}
		}
	}

	return nil
}

// nextRandom is used in Utils.CreateTemp and Utils.MkdirTemp.
//
//go:linkname nextRandom os.nextRandom
func nextRandom() string

// prefixAndSuffix splits pattern by the last wildcard "*", if applicable,
// returning prefix as the part before "*" and suffix as the part after "*".
func prefixAndSuffix[T VFSBase](vfs T, pattern string) (prefix, suffix string, err error) {
	for i := 0; i < len(pattern); i++ {
		if IsPathSeparator(vfs, pattern[i]) {
			return "", "", ErrPatternHasSeparator
		}
	}

	if pos := strings.LastIndexByte(pattern, '*'); pos != -1 {
		prefix, suffix = pattern[:pos], pattern[pos+1:]
	} else {
		prefix = pattern
	}

	return prefix, suffix, nil
}

// ReadDir reads the named directory,
// returning all its directory entries sorted by filename.
// If an error occurs reading the directory,
// ReadDir returns the entries it was able to read before the error,
// along with the error.
func ReadDir[T VFSBase](vfs T, name string) ([]fs.DirEntry, error) {
	f, err := vfs.OpenFile(name, os.O_RDONLY, 0)
	if err != nil {
		return nil, err
	}

	defer f.Close()

	dirs, err := f.ReadDir(-1)

	sort.Slice(dirs, func(i, j int) bool { return dirs[i].Name() < dirs[j].Name() })

	return dirs, err
}

// ReadFile reads the named file and returns the contents.
// A successful call returns err == nil, not err == EOF.
// Because ReadFile reads the whole file, it does not treat an EOF from Read
// as an error to be reported.
func ReadFile[T VFSBase](vfs T, name string) ([]byte, error) {
	f, err := vfs.OpenFile(name, os.O_RDONLY, 0)
	if err != nil {
		return nil, err
	}

	defer f.Close()

	var size int

	if info, err := f.Stat(); err == nil {
		size64 := info.Size()
		if int64(int(size64)) == size64 {
			size = int(size64)
		}
	}

	size++ // one byte for final read at EOF

	// If a file claims a small size, read at least 512 bytes.
	// In particular, files in Linux's /proc claim size 0 but
	// then do not work right if read in small pieces,
	// so an initial read of 1 byte would not work correctly.
	if size < 512 {
		size = 512
	}

	data := make([]byte, 0, size)

	for {
		if len(data) >= cap(data) {
			d := append(data[:cap(data)], 0) //nolint:gocritic // append result not assigned to the same slice
			data = d[:len(data)]
		}

		n, err := f.Read(data[len(data):cap(data)])
		data = data[:len(data)+n]

		if err != nil {
			if err == io.EOF {
				err = nil
			}

			return data, err
		}
	}
}

// SetUserByName sets the current user by name.
// If the user is not found, the returned error is of type UnknownUserError.
func SetUserByName[T VFSBase](vfs T, name string) error {
	if !vfs.HasFeature(FeatIdentityMgr) {
		return ErrPermDenied
	}

	if vfs.User().Name() == name {
		return nil
	}

	u, err := vfs.Idm().LookupUser(name)
	if err != nil {
		return err
	}

	err = vfs.SetUser(u)

	return err
}

// SplitAbs splits an absolute path immediately preceding the final Separator,
// separating it into a directory and file name component.
// If there is no Separator in path, splitPath returns an empty dir
// and file set to path.
// The returned values have the property that path = dir + PathSeparator + file.
func SplitAbs[T VFSBase](vfs T, path string) (dir, file string) {
	l := VolumeNameLen(vfs, path)

	i := len(path) - 1
	for i >= l && !IsPathSeparator(vfs, path[i]) {
		i--
	}

	return path[:i], path[i+1:]
}

// SystemDirs returns an array of system directories always present in the file system.
func SystemDirs[T VFSBase](vfs T, basePath string) []DirInfo {
	switch vfs.OSType() {
	case OsWindows:
		if basePath == "" {
			basePath = DefaultVolume
		}

		return []DirInfo{
			{Path: HomeDir(vfs, basePath), Perm: DefaultDirPerm},
			{Path: TempDirUser(vfs, basePath, AdminUserName(vfs.OSType())), Perm: DefaultDirPerm},
			{Path: TempDirUser(vfs, basePath, DefaultName), Perm: DefaultDirPerm},
			{Path: Join(vfs, basePath, `\Windows`), Perm: DefaultDirPerm},
		}
	default:
		return []DirInfo{
			{Path: HomeDir(vfs, basePath), Perm: HomeDirPerm()},
			{Path: Join(vfs, basePath, "/root"), Perm: 0o700},
			{Path: Join(vfs, basePath, "/tmp"), Perm: 0o777},
		}
	}
}

// TempDir returns the default directory to use for temporary files.
//
// On Unix systems, it returns $TMPDIR if non-empty, else /tmp.
// On Windows, it uses GetTempPath, returning the first non-empty
// value from %TMP%, %TEMP%, %USERPROFILE%, or the Windows directory.
// On Plan 9, it returns /tmp.
//
// The directory is neither guaranteed to exist nor have accessible
// permissions.
func TempDir[T VFSBase](vfs T) string {
	return TempDirUser(vfs, "", vfs.User().Name())
}

// TempDirUser returns the default directory to use for temporary files with for a specific user.
func TempDirUser[T VFSBase](vfs T, basePath, username string) string {
	if vfs.OSType() != OsWindows {
		return Join(vfs, basePath, "/tmp")
	}

	if basePath == "" {
		basePath = DefaultVolume
	}

	dir := Join(vfs, basePath, `\Users\`, username, `\AppData\Local\Temp`)

	return dir
}

// ToOpenMode returns the open mode from the input flags.
func ToOpenMode(flag int) OpenMode {
	var om OpenMode

	// Mask flags that can be used in read only mode (syscall.O_DIRECT for example)
	if flag&0xFFF == os.O_RDONLY {
		return OpenRead
	}

	if flag&os.O_RDWR != 0 {
		om = OpenRead | OpenWrite
	}

	if flag&(os.O_EXCL|os.O_CREATE) == (os.O_EXCL | os.O_CREATE) {
		om |= OpenCreate | OpenCreateExcl | OpenWrite
	}

	if flag&os.O_CREATE != 0 {
		om |= OpenCreate | OpenWrite
	}

	if flag&os.O_APPEND != 0 {
		om |= OpenAppend | OpenWrite
	}

	if flag&os.O_TRUNC != 0 {
		om |= OpenTruncate | OpenWrite
	}

	if flag&os.O_WRONLY != 0 {
		om |= OpenWrite
	}

	return om
}

// VolumeName returns leading volume name.
// Given "C:\foo\bar" it returns "C:" on Windows.
// Given "\\host\share\foo" it returns "\\host\share".
// On other platforms it returns "".
func VolumeName[T VFSBase](vfs T, path string) string {
	return FromSlash(vfs, path[:VolumeNameLen(vfs, path)])
}

//go:linkname volumeNameLen path/filepath.volumeNameLen
func volumeNameLen(path string) int

// WalkDir walks the file tree rooted at root, calling fn for each file or
// directory in the tree, including root.
//
// All errors that arise visiting files and directories are filtered by fn:
// see the fs.WalkDirFunc documentation for details.
//
// The files are walked in lexical order, which makes the output deterministic
// but requires WalkDir to read an entire directory into memory before proceeding
// to walk that directory.
//
// WalkDir does not follow symbolic links.
func WalkDir[T VFSBase](vfs T, root string, fn fs.WalkDirFunc) error {
	info, err := vfs.Lstat(root)
	if err != nil {
		err = fn(root, nil, err)
	} else {
		err = walkDir(vfs, root, &statDirEntry{info}, fn)
	}

	if err == filepath.SkipDir {
		return nil
	}

	return err
}

// walkDir recursively descends path, calling walkDirFn.
func walkDir[T VFSBase](vfs T, path string, d fs.DirEntry, walkDirFn fs.WalkDirFunc) error {
	if err := walkDirFn(path, d, nil); err != nil || !d.IsDir() {
		if err == filepath.SkipDir && d.IsDir() {
			// Successfully skipped directory.
			err = nil
		}

		return err
	}

	dirs, err := ReadDir(vfs, path)
	if err != nil {
		// Second call, to report ReadDir error.
		err = walkDirFn(path, d, err)
		if err != nil {
			return err
		}
	}

	for _, d1 := range dirs {
		path1 := Join(vfs, path, d1.Name())
		if err := walkDir(vfs, path1, d1, walkDirFn); err != nil {
			if err == filepath.SkipDir {
				break
			}

			return err
		}
	}

	return nil
}

type statDirEntry struct {
	info fs.FileInfo
}

func (d *statDirEntry) Name() string               { return d.info.Name() }
func (d *statDirEntry) IsDir() bool                { return d.info.IsDir() }
func (d *statDirEntry) Type() fs.FileMode          { return d.info.Mode().Type() }
func (d *statDirEntry) Info() (fs.FileInfo, error) { return d.info, nil }

// WriteFile writes data to the named file, creating it if necessary.
// If the file does not exist, WriteFile creates it with permissions perm (before umask);
// otherwise WriteFile truncates it before writing, without changing permissions.
func WriteFile[T VFSBase](vfs T, name string, data []byte, perm fs.FileMode) error {
	f, err := vfs.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, perm)
	if err != nil {
		return err
	}

	_, err = f.Write(data)
	if err1 := f.Close(); err1 != nil && err == nil {
		err = err1
	}

	return err
}