vfs

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package vfs defines the file system abstraction that lets the UI browse and transfer between local and remote locations with the same code.

Index

Constants

This section is empty.

Variables

View Source
var ErrUnsafeName = errors.New("unsafe file name")

ErrUnsafeName is returned for names that could escape their directory or that the local system can't store.

Functions

func CheckName

func CheckName(name string) error

CheckName validates a single path element, as listed by a (possibly hostile) server or typed by the user. It rejects anything that could traverse directories ("..", separators), NUL bytes, and control characters.

func LooksBinary

func LooksBinary(data []byte) bool

LooksBinary guesses whether data is binary rather than text.

func ReadHead

func ReadHead(fsys FS, path string, n int) (data []byte, truncated bool, err error)

ReadHead reads up to n bytes from the start of a file, reporting whether the file was longer.

func RemoveAll

func RemoveAll(fsys FS, path string) error

RemoveAll deletes path and, for directories, everything inside it. Directory symlinks are removed as links, never followed.

func RemoveAllFunc added in v0.2.0

func RemoveAllFunc(fsys FS, path string, removed func(path string)) error

RemoveAllFunc is RemoveAll, calling removed (if not nil) with the path of each file and directory after it is deleted, so callers can show progress.

func Sanitize

func Sanitize(s string) string

Sanitize makes untrusted text safe to print to a terminal: control characters (which could carry escape sequences) are replaced with a visible placeholder, and invalid UTF-8 is repaired. Tabs become spaces.

Types

type Entry

type Entry struct {
	Name    string
	Size    int64
	Mode    fs.FileMode
	ModTime time.Time
	// IsDir is true for directories and for symlinks that point to one, so
	// links to directories can be navigated into.
	IsDir  bool
	IsLink bool
}

Entry describes one item in a directory listing.

func FromFileInfo

func FromFileInfo(info fs.FileInfo, fullPath string, stat func(string) (fs.FileInfo, error)) Entry

FromFileInfo converts info (from an lstat-style call) into an Entry. For symlinks, stat is used to resolve the target so IsDir and Size describe what the link points to; a broken link is reported as a non-directory.

func (Entry) Executable

func (e Entry) Executable() bool

Executable reports whether any execute bit is set on a regular file.

func (Entry) Hidden

func (e Entry) Hidden() bool

Hidden reports whether the entry is a dotfile.

type FS

type FS interface {
	// Label is a short human-readable name, e.g. "Local" or "jsd@nas".
	Label() string
	// Home returns the starting directory for this file system.
	Home() (string, error)

	ReadDir(path string) ([]Entry, error)
	// Stat describes path without following a final symlink, except to
	// fill in IsDir for links to directories.
	Stat(path string) (Entry, error)

	Open(path string) (io.ReadCloser, error)
	// Create creates or truncates a file for writing.
	Create(path string) (io.WriteCloser, error)
	Mkdir(path string) error
	// Remove deletes a file or an empty directory.
	Remove(path string) error
	Rename(oldPath, newPath string) error
	// Chtimes sets the modification (and access) time.
	Chtimes(path string, mtime time.Time) error
	// Chmod sets permission bits.
	Chmod(path string, mode fs.FileMode) error

	Join(elem ...string) string
	Dir(path string) string
	Base(path string) string
	IsRoot(path string) bool
}

FS is a browsable file system. Paths are absolute and use the file system's own conventions (local paths on Windows use backslashes, SFTP paths always use forward slashes), so callers must use the FS's path helpers rather than path or path/filepath directly.

type Local

type Local struct{}

Local is the machine's own file system.

func NewLocal

func NewLocal() Local

NewLocal returns the local file system.

func (Local) Base

func (Local) Base(path string) string

Base implements FS.

func (Local) Chmod

func (Local) Chmod(path string, mode fs.FileMode) error

Chmod implements FS.

func (Local) Chtimes

func (Local) Chtimes(path string, mtime time.Time) error

Chtimes implements FS.

func (Local) Create

func (Local) Create(path string) (io.WriteCloser, error)

Create implements FS.

func (Local) Dir

func (Local) Dir(path string) string

Dir implements FS.

func (Local) Home

func (Local) Home() (string, error)

Home implements FS.

func (Local) IsRoot

func (Local) IsRoot(path string) bool

IsRoot implements FS.

func (Local) Join

func (Local) Join(elem ...string) string

Join implements FS.

func (Local) Label

func (Local) Label() string

Label implements FS.

func (Local) Mkdir

func (Local) Mkdir(path string) error

Mkdir implements FS.

func (Local) Open

func (Local) Open(path string) (io.ReadCloser, error)

Open implements FS.

func (Local) ReadDir

func (Local) ReadDir(path string) ([]Entry, error)

ReadDir implements FS. Entries that vanish while listing are skipped.

func (Local) Remove

func (Local) Remove(path string) error

Remove implements FS.

func (Local) Rename

func (Local) Rename(oldPath, newPath string) error

Rename implements FS.

func (Local) Stat

func (Local) Stat(path string) (Entry, error)

Stat implements FS.

type SFTP

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

SFTP is a remote file system over an SFTP session. Paths always use forward slashes.

func NewSFTP

func NewSFTP(c *sftp.Client, label string) (*SFTP, error)

NewSFTP wraps an SFTP client. The label is shown in the pane title, e.g. "jsd@nas".

func (*SFTP) Base

func (*SFTP) Base(p string) string

Base implements FS.

func (*SFTP) Chmod

func (s *SFTP) Chmod(p string, mode fs.FileMode) error

Chmod implements FS.

func (*SFTP) Chtimes

func (s *SFTP) Chtimes(p string, mtime time.Time) error

Chtimes implements FS.

func (*SFTP) Create

func (s *SFTP) Create(p string) (io.WriteCloser, error)

Create implements FS.

func (*SFTP) Dir

func (*SFTP) Dir(p string) string

Dir implements FS.

func (*SFTP) Home

func (s *SFTP) Home() (string, error)

Home implements FS. It is the directory the server starts sessions in.

func (*SFTP) IsRoot

func (*SFTP) IsRoot(p string) bool

IsRoot implements FS.

func (*SFTP) Join

func (*SFTP) Join(elem ...string) string

Join implements FS.

func (*SFTP) Label

func (s *SFTP) Label() string

Label implements FS.

func (*SFTP) Mkdir

func (s *SFTP) Mkdir(p string) error

Mkdir implements FS.

func (*SFTP) Open

func (s *SFTP) Open(p string) (io.ReadCloser, error)

Open implements FS.

func (*SFTP) ReadDir

func (s *SFTP) ReadDir(p string) ([]Entry, error)

ReadDir implements FS.

func (*SFTP) Remove

func (s *SFTP) Remove(p string) error

Remove implements FS.

func (*SFTP) Rename

func (s *SFTP) Rename(oldPath, newPath string) error

Rename implements FS. It prefers the POSIX rename extension, which replaces an existing target atomically like a local rename does.

func (*SFTP) Stat

func (s *SFTP) Stat(p string) (Entry, error)

Stat implements FS.

Directories

Path Synopsis
Package vfstest provides an in-memory vfs.FS for deterministic tests.
Package vfstest provides an in-memory vfs.FS for deterministic tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址