filesystem

package
v1.5.0 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// MaxIgnoreLength is the maximum size, in bytes, of a pattern list.
	MaxIgnoreLength = 32 * 1024
	// MaxIgnorePatterns is the maximum number of non-blank, non-comment lines in a list.
	MaxIgnorePatterns = 256
	// MaxIgnorePatternWildcards is the maximum number of unescaped "*" characters in a pattern.
	MaxIgnorePatternWildcards = 16
)

Limits applied to the gitignore-style pattern lists used by an Archive, whether they come from the Panel with a backup request or from a server's ignore file.

View Source 
const MaxArchiveExtractFiles = 10000

MaxArchiveExtractFiles is the maximum number of files that can be extracted in one request.

View Source 
const MaxArchiveListEntries = 2500

MaxArchiveListEntries caps how many names are returned from ListArchiveContents to keep responses bounded.

View Source 
const TrashDirName = ".featherpanel-trash"

Variables

View Source 
var SkipThis = errors.New("skip this")

Functions

func IsErrorCode 

func IsErrorCode(err error, code ErrorCode) bool

IsErrorCode checks if "err" is a filesystem Error type. If so, it will then drop in and check that the error code is the same as the provided ErrorCode passed in "code".

func IsFilesystemError 

func IsFilesystemError(err error) bool

IsFilesystemError checks if the given error is one of the Filesystem errors.

func NewBadPathResolution 

func NewBadPathResolution(path string, resolved string) error

NewBadPathResolution returns a new BadPathResolution error.

func NewTrashEntryNotFound added in v1.4.0 

func NewTrashEntryNotFound() error

NewTrashEntryNotFound reports that a trash index entry does not exist.

func NewTrashItemTooLarge added in v1.4.0 

func NewTrashItemTooLarge(name string) error

NewTrashItemTooLarge reports that an item exceeds the configured trash size limit.

func NewTrashRestoreConflict added in v1.4.0 

func NewTrashRestoreConflict(name string) error

NewTrashRestoreConflict reports that the restore target path already exists.

func ValidateIgnore added in v1.4.0 

func ValidateIgnore(s string) error

ValidateIgnore checks a pattern list against the limits above. The returned error describes the first limit exceeded and is safe to display to the user.

Types

type Archive 

type Archive struct {
	// Filesystem to create the archive with.
	Filesystem *Filesystem

	// Ignore is a gitignore string (most likely read from a file) of files to ignore
	// from the archive.
	Ignore string

	// BaseDirectory .
	BaseDirectory string

	// Files specifies the files to archive, this takes priority over the Ignore
	// option, if unspecified, all files in the BaseDirectory will be archived
	// unless Ignore is set.
	Files []string

	// Progress wraps the writer of the archive to pass through the progress tracker.
	Progress *progress.Progress
	// contains filtered or unexported fields
}

func (*Archive) Create 

func (a *Archive) Create(ctx context.Context, dst string) error

Create creates an archive at dst with all the files defined in the included Files array.

THIS IS UNSAFE TO USE IF `dst` IS PROVIDED BY A USER! ONLY USE THIS WITH CONTROLLED PATHS!

func (*Archive) Stream 

func (a *Archive) Stream(ctx context.Context, w io.Writer) error

Stream streams the creation of the archive to the given writer.

type ArchiveListEntry added in v1.4.0 

type ArchiveListEntry struct {
	Name      string `json:"name"`
	Path      string `json:"path"`
	Size      int64  `json:"size"`
	Directory bool   `json:"directory"`
	Modified  string `json:"modified,omitempty"`
}

ArchiveListEntry describes one file or directory inside an on-disk archive (zip, tar, etc.).

type Error 

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

func (*Error) Code 

func (e *Error) Code() ErrorCode

Code returns the ErrorCode for this specific error instance.

func (*Error) ConflictName added in v1.4.0 

func (e *Error) ConflictName() string

ConflictName returns the conflicting file name for a trash restore conflict error.

func (*Error) Error 

func (e *Error) Error() string

Returns a human-readable error string to identify the Error by.

func (*Error) ItemName added in v1.4.0 

func (e *Error) ItemName() string

ItemName returns the file or folder name attached to a trash-related error.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap returns the underlying cause of this filesystem error. In some causes there may not be a cause present, in which case nil will be returned.

type ErrorCode 

type ErrorCode string
const (
	ErrCodeIsDirectory          ErrorCode = "E_ISDIR"
	ErrCodeDiskSpace            ErrorCode = "E_NODISK"
	ErrCodeUnknownArchive       ErrorCode = "E_UNKNFMT"
	ErrCodePathResolution       ErrorCode = "E_BADPATH"
	ErrCodeDenylistFile         ErrorCode = "E_DENYLIST"
	ErrCodeTrashRestoreConflict ErrorCode = "E_TRASHRESTORE"
	ErrCodeTrashEntryNotFound   ErrorCode = "E_TRASHMISSING"
	ErrCodeTrashItemTooLarge    ErrorCode = "E_TRASHLARGE"
	ErrCodeUnknownError         ErrorCode = "E_UNKNOWN"
	ErrNotExist                 ErrorCode = "E_NOTEXIST"
)

type Filesystem 

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

func New 

func New(root string, size int64, denylist []string) (*Filesystem, error)

New creates a new Filesystem instance for a given server.

func (*Filesystem) CachedUsage 

func (fs *Filesystem) CachedUsage() int64

Returns the cached value for the amount of disk space used by the filesystem. Do not rely on this function for critical logical checks. It should only be used in areas where the actual disk usage does not need to be perfect, e.g. API responses for server resource usage.

func (*Filesystem) Chmod 

func (fs *Filesystem) Chmod(path string, mode ufs.FileMode) error

func (*Filesystem) Chown 

func (fs *Filesystem) Chown(p string) error

Chown recursively iterates over a file or directory and sets the permissions on all of the underlying files. Iterate over all of the files and directories. If it is a file just go ahead and perform the chown operation. Otherwise dig deeper into the directory until we've run out of directories to dig into.

func (*Filesystem) Chtimes 

func (fs *Filesystem) Chtimes(path string, atime, mtime time.Time) error

func (*Filesystem) CompressFiles 

func (fs *Filesystem) CompressFiles(ctx context.Context, dir string, name string, paths []string, extension string) (ufs.FileInfo, string, error)

CompressFiles compresses all the files matching the given paths in the specified directory. This function also supports passing nested paths to only compress certain files and folders when working in a larger directory. This effectively creates a local backup, but rather than ignoring specific files and folders, it takes an allow-list of files and folders.

All paths are relative to the dir that is passed in as the first argument, and the compressed file will be placed at that location named `archive-{date}.tar.gz`.

func (*Filesystem) Copy 

func (fs *Filesystem) Copy(p string) error

Copy copies a given file or directory to the same location and appends a suffix.

func (*Filesystem) CreateDirectory 

func (fs *Filesystem) CreateDirectory(name string, p string) error

CreateDirectory creates a new directory (name) at a specified path (p) for the server.

func (*Filesystem) DecompressFile 

func (fs *Filesystem) DecompressFile(ctx context.Context, dir string, file string) error

DecompressFile will decompress a file in a given directory by using the archiver tool to infer the file type and go from there. This will walk over all the files within the given archive and ensure that there is not a zip-slip attack being attempted by validating that the final path is within the server data directory.

func (*Filesystem) Delete 

func (fs *Filesystem) Delete(p string) error

Delete removes a file or folder from the system. Prevents the user from accidentally (or maliciously) removing their root server data directory.

func (*Filesystem) DeletePath added in v1.4.0 

func (fs *Filesystem) DeletePath(p string, limits TrashLimits, useTrash bool) error

MoveFilesToTrash moves files from the server tree into the trash bin. DeletePath removes a file or directory, optionally moving it to trash first.

func (*Filesystem) DeleteTrashEntries added in v1.4.0 

func (fs *Filesystem) DeleteTrashEntries(ids []string) error

DeleteTrashEntries permanently removes selected trash items.

func (*Filesystem) DirectorySize 

func (fs *Filesystem) DirectorySize(root string) (int64, error)

DirectorySize calculates the size of a directory and its descendants.

func (*Filesystem) DiskUsage 

func (fs *Filesystem) DiskUsage(allowStaleValue bool) (int64, error)

Internal helper function to allow other parts of the codebase to check the total used disk space as needed without overly taxing the system. This will prioritize the value from the cache to avoid excessive IO usage. We will only walk the filesystem and determine the size of the directory if there is no longer a cached value.

If "allowStaleValue" is set to true, a stale value MAY be returned to the caller if there is an expired cache value AND there is currently another lookup in progress. If there is no cached value but no other lookup is in progress, a fresh disk space response will be returned to the caller.

This is primarily to avoid a bunch of I/O operations from piling up on the server, especially on servers with a large amount of files.

func (*Filesystem) EmptyTrash added in v1.4.0 

func (fs *Filesystem) EmptyTrash() error

EmptyTrash permanently deletes all trashed items.

func (*Filesystem) Ext 

func (fs *Filesystem) Ext(n string) string

func (*Filesystem) ExtractArchiveMembers added in v1.4.0 

func (fs *Filesystem) ExtractArchiveMembers(ctx context.Context, root, archiveFile, destination string, entries []string) error

ExtractArchiveMembers writes given files and/or directory trees from an on-disk archive into the server filesystem. root and archiveFile identify the archive (same as decompress). destination is the directory on the server to write under. entries are paths inside the archive (files or directories).

func (*Filesystem) ExtractTransfer added in v1.4.3 

func (fs *Filesystem) ExtractTransfer(ctx context.Context, r io.Reader) error

ExtractTransfer extracts the archive of a server that is being transferred to this node into the server's directory. Every file is kept, including ones the denylist would refuse, since they are the server's own files.

func (*Filesystem) File 

func (fs *Filesystem) File(p string) (ufs.File, Stat, error)

File returns a reader for a file instance as well as the stat information.

func (*Filesystem) HasSpaceAvailable 

func (fs *Filesystem) HasSpaceAvailable(allowStaleValue bool) bool

Determines if the directory a file is trying to be added to has enough space available for the file to be written to.

Because determining the amount of space being used by a server is a taxing operation we will load it all up into a cache and pull from that as long as the key is not expired.

This operation will potentially block unless allowStaleValue is set to true. See the documentation on DiskUsage for how this affects the call.

func (*Filesystem) HasSpaceErr 

func (fs *Filesystem) HasSpaceErr(allowStaleValue bool) error

The same concept as HasSpaceAvailable however this will return an error if there is no space, rather than a boolean value.

func (*Filesystem) HasSpaceFor 

func (fs *Filesystem) HasSpaceFor(size int64) error

func (*Filesystem) IsIgnored 

func (fs *Filesystem) IsIgnored(paths ...string) error

Checks if the given file or path is in the server's file denylist. If so, an Error is returned, otherwise nil is returned.

func (*Filesystem) ListArchiveContents added in v1.4.0 

func (fs *Filesystem) ListArchiveContents(ctx context.Context, root, archiveFile, innerPath string) ([]ArchiveListEntry, bool, error)

ListArchiveContents lists one directory level inside an archive at archivePath = join(root, archiveFile) without extracting it. innerPath is a path inside the archive ("." for root).

func (*Filesystem) ListDirectory 

func (fs *Filesystem) ListDirectory(p string, includeDirectorySizes bool) ([]Stat, error)

ListDirectory lists the contents of a given directory and returns stat information about each file and folder within it. When includeDirectorySizes is true, each subdirectory includes directory_size (total bytes of regular files under that folder, with hard-link deduplication) from a TTL cache; stale or missing entries are refreshed asynchronously so the HTTP handler returns promptly.

func (*Filesystem) ListTrash added in v1.4.0 

func (fs *Filesystem) ListTrash(limits TrashLimits) ([]TrashEntry, int64, error)

ListTrash returns trash entries and total bytes used by trashed items.

func (*Filesystem) MaxDisk 

func (fs *Filesystem) MaxDisk() int64

MaxDisk returns the maximum amount of disk space that this Filesystem instance is allowed to use.

func (*Filesystem) MoveFilesToTrash added in v1.4.0 

func (fs *Filesystem) MoveFilesToTrash(root string, files []string, limits TrashLimits) error

func (*Filesystem) Path 

func (fs *Filesystem) Path() string

Path returns the root path for the Filesystem instance.

func (*Filesystem) ReadDir 

func (fs *Filesystem) ReadDir(path string) ([]ufs.DirEntry, error)

ReadDir reads directory entries.

func (*Filesystem) ReadDirStat 

func (fs *Filesystem) ReadDirStat(path string) ([]ufs.FileInfo, error)

ReadDirStat is like ReadDir except that it returns FileInfo for each entry instead of just a DirEntry.

func (*Filesystem) Rename 

func (fs *Filesystem) Rename(oldpath, newpath string) error

func (*Filesystem) RestoreTrashEntries added in v1.4.0 

func (fs *Filesystem) RestoreTrashEntries(ids []string, overwrite bool) error

RestoreTrashEntries moves items from trash back to their original location. When overwrite is true, an existing file or folder at the destination is removed first.

func (*Filesystem) SafeDeleteRecursively added in v1.0.5 

func (fs *Filesystem) SafeDeleteRecursively(p string) error

SafeDeleteRecursively deletes a file or directory while respecting the denylist. For files, deletion is skipped if the file matches the denylist. For directories, it recursively deletes all non-denylisted files and subdirectories. Empty directories are removed automatically, but directories containing denylisted files are preserved.

func (*Filesystem) SetDiskLimit 

func (fs *Filesystem) SetDiskLimit(i int64)

SetDiskLimit sets the disk space limit for this Filesystem instance.

func (*Filesystem) SpaceAvailableForDecompression 

func (fs *Filesystem) SpaceAvailableForDecompression(ctx context.Context, dir string, file string) error

SpaceAvailableForDecompression looks through a given archive and determines if decompressing it would put the server over its allocated disk space limit.

The entries are read one at a time rather than opening the archive as a file system, which is much faster for large archives.

func (*Filesystem) Stat 

func (fs *Filesystem) Stat(p string) (Stat, error)

Stat stats a file or folder and returns the base stat object from go along with the MIME data that can be used for editing files. 

func (fs *Filesystem) Symlink(oldpath, newpath string) error

func (*Filesystem) Touch 

func (fs *Filesystem) Touch(p string, flag int) (ufs.File, error)

Touch acts by creating the given file and path on the disk if it is not present already. If it is present, the file is opened using the defaults which will truncate the contents. The opened file is then returned to the caller.

func (*Filesystem) TruncateRootDirectory 

func (fs *Filesystem) TruncateRootDirectory() error

TruncateRootDirectory removes _all_ files and directories from a server's data directory and resets the used disk space to zero. The directory itself is kept, since it is mounted into the server's container.

func (*Filesystem) UnixFS 

func (fs *Filesystem) UnixFS() *ufs.UnixFS

func (*Filesystem) Write 

func (fs *Filesystem) Write(p string, r io.Reader, newSize int64, mode ufs.FileMode) error

func (*Filesystem) WriteFrom added in v1.4.3 

func (fs *Filesystem) WriteFrom(p string, r io.Reader) (int64, error)

WriteFrom writes the contents of r to p, creating the file or truncating it if it exists, and returns the number of bytes written. Unlike Write, the size of the contents does not need to be known ahead of time: each write is counted against the disk limit as it happens. If writing fails the file is removed.

type SpaceCheckingOpts 

type SpaceCheckingOpts struct {
	AllowStaleResponse bool
}

type Stat 

type Stat struct {
	ufs.FileInfo
	Mimetype string
	// DirectorySize is the recursive size of a directory's contents (regular files, hard-link aware).
	// Only set when listing with directory sizes enabled and a cached or computed value exists.
	DirectorySize *int64 `json:"-"`
}

func (*Stat) CTime added in v1.4.0 

func (s *Stat) CTime() time.Time

CTime returns the time that the file/folder was created.

TODO: remove. Ctim is not actually ever been correct and doesn't actually return the creation time.

func (*Stat) MarshalJSON 

func (s *Stat) MarshalJSON() ([]byte, error)

type TarProgress 

type TarProgress struct {
	*tar.Writer
	// contains filtered or unexported fields
}

TarProgress .

func NewTarProgress 

func NewTarProgress(w *tar.Writer, p *progress.Progress) *TarProgress

NewTarProgress .

func (*TarProgress) Write 

func (p *TarProgress) Write(v []byte) (int, error)

Write .

type TrashEntry added in v1.4.0 

type TrashEntry struct {
	ID           string    `json:"id"`
	OriginalRoot string    `json:"original_root"`
	OriginalName string    `json:"original_name"`
	DeletedAt    time.Time `json:"deleted_at"`
	Size         int64     `json:"size"`
	IsDirectory  bool      `json:"is_directory"`
}

type TrashLimits added in v1.4.0 

type TrashLimits struct {
	MaxSizeBytes  int64 `json:"max_size_bytes"`
	RetentionDays int   `json:"retention_days"`
}

Source Files

View all Source files

Directories

Path Synopsis

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.
⌂ 换网址