fsops

type Backend interface {

	// Stat returns metadata for a single path, following symlinks — FileID
	// and Nlinks describe the target, so symlinked torrent data keeps its
	// identity. Returns a non-nil error wrapping fs.ErrNotExist if the path
	// does not exist. A failure to resolve identity is reported in
	// LstatInfo.FileIDErr, not as a Stat error, so one identity-opaque file
	// cannot fail callers that only need metadata.
	Stat(ctx context.Context, path string) (*LstatInfo, error)

	// Lstat is like Stat but does not follow symlinks.
	Lstat(ctx context.Context, path string) (*LstatInfo, error)

	// ReadDir returns directory entries.
	ReadDir(ctx context.Context, path string) ([]DirEntry, error)

	// WalkDir walks a directory tree and streams entries on the returned channel.
	// Entries within one directory arrive in lexical order and a directory's
	// own entry precedes everything beneath it; nothing more is promised about
	// order, as a backend may list sibling directories concurrently. The
	// channel is closed when the walk completes, is cancelled via ctx, or
	// hits an unrecoverable error. Callers must drain the channel or cancel
	// ctx; abandoning it leaks the walk goroutine. Entries whose metadata
	// cannot be read are skipped, not emitted — WalkEntry.Err carries only
	// enumeration-level walk failures. Setting opts.EmitStatErrors emits
	// those entries instead, with WalkEntry.StatErr set and only Path/RelPath
	// valid, so delete preflights can fail closed on unverifiable paths.
	WalkDir(ctx context.Context, root string, opts WalkOptions) (<-chan WalkEntry, error)

	// Statfs returns free/total bytes for the filesystem containing path.
	Statfs(ctx context.Context, path string) (*StatfsResult, error)

	// SameFilesystem returns true if both paths reside on the same filesystem
	// (same device ID on Unix, same volume serial on Windows).
	SameFilesystem(ctx context.Context, p1, p2 string) (bool, error)

	// MkdirAll creates a directory and all parents. Equivalent to os.MkdirAll.
	// For torrent content and link-tree dirs, pass fsutil.ContentDirMode /
	// fsutil.LinkTreeBaseDirMode rather than a hand-typed mode (#1704, #2086).
	MkdirAll(ctx context.Context, path string, perm fs.FileMode) error

	// Mkdir creates one directory, like os.Mkdir. The error wraps fs.ErrExist
	// when path already exists, so of two calls for one path only one
	// succeeds. Link trees use it to reserve a folder name.
	Mkdir(ctx context.Context, path string, perm fs.FileMode) error

	// Remove removes a file or directory. If opts.Recursive is true, removes
	// the entire tree (like os.RemoveAll).
	Remove(ctx context.Context, path string, opts RemoveOptions) error

	// HardlinkTree creates a hardlink tree from plan. Rolls back what it
	// created on partial failure. The result records the files and dirs this
	// call made, for a later RemoveTree.
	//
	// Every implementation owes the same answer to a target that already
	// exists: skip it when it is provably the same file as its source, and
	// refuse the whole plan with hardlinktree.ErrTargetExists otherwise. A
	// skipped target is counted in SkippedExists and never recorded in Files,
	// because it belongs to whoever made it first; see
	// TestHardlinkTree_ExecTierSkippedLinkSurvivesLaterFailure. A backend that
	// cannot prove identity refuses.
	HardlinkTree(ctx context.Context, plan *hardlinktree.TreePlan) (*TreeCreateResult, error)

	// ReflinkTree creates a reflink (CoW) tree from plan. Rolls back what it
	// created on partial failure. The result records the files and dirs this
	// call made, for a later RemoveTree.
	ReflinkTree(ctx context.Context, plan *hardlinktree.TreePlan) (*TreeCreateResult, error)

	// RemoveTree removes exactly the files and dirs recorded in created —
	// never the whole plan, which could delete links shared with sibling
	// torrents (discussion #2282). A plan root that already existed before
	// the create is therefore NOT removed; callers own pruning it. Safe to
	// call with a nil result.
	RemoveTree(ctx context.Context, created *TreeCreateResult) error

	// Paths is the dialect of this backend's filesystem. Every Join, Dir,
	// IsAbs or Rel on a path that goes to or comes from this backend uses it.
	Paths() PathDialect

	// SupportsReflink returns whether the filesystem at path supports CoW
	// reflinks. The string return is a human-readable reason when unsupported.
	SupportsReflink(ctx context.Context, path string) (bool, string, error)
}

type BatchStater interface {
	// StatBatch is Stat for each path: infos[i] and errs[i] answer paths[i].
	StatBatch(ctx context.Context, paths []string) (infos []*LstatInfo, errs []error)
	// LstatBatch is Lstat for each path: infos[i] and errs[i] answer paths[i].
	LstatBatch(ctx context.Context, paths []string) (infos []*LstatInfo, errs []error)
}

type DirEntry struct {
	Name      string
	IsDir     bool
	IsSymlink bool
	// Mode contains only the entry's type bits, without following links.
	Mode fs.FileMode
}

type FileInfo struct {
	Path      string
	Size      int64
	ModTime   time.Time
	IsDir     bool
	IsSymlink bool
	Mode      fs.FileMode
}

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

type LstatInfo struct {
	FileInfo
	FileID hardlink.FileID
	Nlinks uint64
	// FileIDErr is set when FileID/Nlinks could not be resolved (e.g. a
	// Windows ACL denial on an otherwise statable file). The rest of the
	// struct is still valid; callers that need identity must check this
	// instead of treating the whole stat as failed.
	FileIDErr error
}

type PathDialect interface {
	// Join takes two parts, which is every backend-path join in qui; a
	// variadic slice would escape through the interface call on each file.
	Join(base, name string) string
	Dir(p string) string
	Base(p string) string
	Clean(p string) string
	IsAbs(p string) bool
	Rel(base, target string) (string, error)
	// FromSlash and ToSlash convert between slash-delimited names, which is
	// how qBittorrent reports every file, and the dialect's own form.
	FromSlash(p string) string
	ToSlash(p string) string
	Separator() string
}

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

type RemoveOptions struct {
	Recursive bool
}

type StatfsResult struct {
	BytesAvailable int64
	BytesTotal     int64
}

type TreeCreateResult struct {
	Created       int
	SkippedExists int
	Files         []string
	Dirs          []string
}

type WalkEntry struct {
	LstatInfo
	RelPath string
	Err     error
	// StatErr is set when the entry was enumerated but its metadata lookup
	// failed; only Path and RelPath are valid then. Such entries are emitted
	// only when WalkOptions.EmitStatErrors is set and skipped otherwise.
	StatErr error
}

type WalkOptions struct {
	SkipHidden bool
	// IgnoreDirNames are directory basenames to skip, matched case-insensitively
	// (OS/NAS metadata dirs like $RECYCLE.BIN and @eaDir vary in on-disk case).
	IgnoreDirNames []string
	// IgnoreDirNamePrefixes are matched case-insensitively.
	IgnoreDirNamePrefixes []string
	IgnorePaths           []string
	// WantFileID populates FileID and Nlinks on regular-file entries.
	WantFileID bool
	// EmitStatErrors emits entries whose metadata lookup failed with StatErr
	// set instead of silently skipping them. Consumers that delete based on
	// walk results use this to fail closed on paths they cannot verify.
	EmitStatErrors bool
	// FollowRoot walks a root that is a symlink to a directory as that
	// directory. Entries are reported under the root as given, and symlinks
	// below the root are still not followed.
	FollowRoot bool
}