io

type BulkRemovableIO interface {
	IO

	// DeleteFiles deletes all named files. Implementations should make a
	// best-effort attempt to delete as many files as possible, returning
	// the list of successfully deleted paths and a joined error
	// (via [errors.Join]) for any individual failures.
	//
	// Missing files are not considered errors — if a path does not exist,
	// it should be treated as a successful deletion.
	//
	// An empty paths slice is a no-op and must not error.
	DeleteFiles(ctx context.Context, paths []string) (deleted []string, err error)
}

type File interface {
	fs.File
	io.ReadSeekCloser
	io.ReaderAt
}

type FileWriter interface {
	io.WriteCloser
	io.ReaderFrom
}

type IO interface {
	// Open opens the named file.
	//
	// When Open returns an error, it should be of type *PathError
	// with the Op field set to "open", the Path field set to name,
	// and the Err field describing the problem.
	//
	// Open should reject attempts to open names that do not satisfy
	// fs.ValidPath(name), returning a *PathError with Err set to
	// ErrInvalid or ErrNotExist.
	Open(name string) (File, error)

	// Remove removes the named file or (empty) directory.
	//
	// If there is an error, it will be of type *PathError.
	// Implementations must be safe for concurrent use by multiple goroutines.
	Remove(name string) error
}

type ListableIO interface {
	IO

	// WalkDir walks the file tree rooted at root, calling fn for each
	// file or directory in the tree, including root. Paths passed to fn
	// are full URIs consistent with the root's scheme and authority.
	WalkDir(root string, fn fs.WalkDirFunc) error
}

type LocalFS struct{}

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

type MkdirAllIO interface {
	IO

	// MkdirAll should not raise an error if the directory already exists,
	// and should create any parent directories in the path if they
	// do not already exist.
	MkdirAll(path string) error
}

type ReadDirFile interface {
	File

	// ReadDir read the contents of the directory and returns a slice
	// of up to n DirEntry values in directory order. Subsequent calls
	// on the same file will yield further DirEntry values.
	//
	// If n > 0, ReadDir returns at most n DirEntry structures. In this
	// case, if ReadDir returns an empty slice, it will return a non-nil
	// error explaining why.
	//
	// At the end of a directory, the error is io.EOF. (ReadDir must return
	// io.EOF itself, not an error wrapping io.EOF.)
	//
	// If n <= 0, ReadDir returns all the DirEntry values from the directory
	// in a single slice. In this case, if ReadDir succeeds (reads all the way
	// to the end of the directory), it returns the slice and a nil error.
	// If it encounters an error before the end of the directory, ReadDir
	// returns the DirEntry list read until that point and a non-nil error.
	ReadDir(n int) ([]fs.DirEntry, error)
}

type ReadFileIO interface {
	IO

	// ReadFile reads the named file and returns its contents.
	// A successful call returns a nil error, not io.EOF.
	// (Because ReadFile reads the whole file, the expected EOF
	// from the final Read is not treated as an error to be reported.)
	//
	// The caller is permitted to modify the returned byte slice.
	// This method should return a copy of the underlying data.
	ReadFile(name string) ([]byte, error)
}

type RemoveAllIO interface {
	IO

	RemoveAll(name string) error
}

type RenameIO interface {
	IO

	Rename(oldpath, newpath string) error
}

type RenameNoReplaceIO interface {
	IO

	RenameNoReplace(oldpath, newpath string) error
}

type SchemeFactory func(ctx context.Context, parsed *url.URL, props map[string]string) (IO, error)

type StatIO interface {
	IO

	// The Stat method returns a FileInfo describing the named file or directory,
	// or an error satisfying errors.Is(err, fs.ErrNotExist) if the file does not exist
	Stat(path string) (fs.FileInfo, error)
}

type WriteFileIO interface {
	IO

	// Create attempts to create the named file and return a writer
	// for it.
	Create(name string) (FileWriter, error)

	// WriteFile writes p to the named file.
	WriteFile(name string, p []byte) error
}