filesystem

Documentation

Overview

Package filesystem provides a Disk abstraction modelled on Laravel's Storage facade.

The Disk interface is intentionally small so a Local driver can ship in-box (no external deps) while S3/GCS/Azure drivers live in sub-packages once they are needed.

Path safety is enforced by the Local driver: any path that would resolve outside the configured root (via .., absolute paths, or symlinks pointing outside) is rejected with ErrPathTraversal. The driver never opens, writes, or deletes outside its root.

Usage:

disk, err := filesystem.NewLocal("/var/app/storage")
if err != nil { return err }
_ = disk.Put(ctx, "users/42/avatar.png", data)
r, err := disk.Reader(ctx, "users/42/avatar.png")

Index

• Variables
• type Disk
• type FileInfo
• type Local
  • func NewLocal(root string) (*Local, error)
  • func (l *Local) Copy(ctx context.Context, src, dst string) error
  • func (l *Local) Delete(_ context.Context, path string) error
  • func (l *Local) Exists(_ context.Context, path string) (bool, error)
  • func (l *Local) Files(_ context.Context, dir string) ([]FileInfo, error)
  • func (l *Local) Get(_ context.Context, path string) ([]byte, error)
  • func (l *Local) Move(_ context.Context, src, dst string) error
  • func (l *Local) Put(_ context.Context, path string, data []byte) error
  • func (l *Local) PutStream(_ context.Context, path string, r io.Reader) error
  • func (l *Local) Reader(_ context.Context, path string) (io.ReadCloser, error)
  • func (l *Local) Root() string
  • func (l *Local) Stat(_ context.Context, path string) (FileInfo, error)

Variables

var ErrNotFound = errors.New("filesystem: not found")

ErrNotFound is returned when a file does not exist on the disk.

var ErrPathTraversal = errors.New("filesystem: path escapes root")

ErrPathTraversal is returned when the requested path would escape the disk root.

Types

type Disk

type Disk interface {
	// Put writes data atomically to path, replacing any existing file.
	Put(ctx context.Context, path string, data []byte) error
	// PutStream copies r into path. Larger payloads should prefer this
	// over Put to avoid loading the whole body into memory.
	PutStream(ctx context.Context, path string, r io.Reader) error
	// Get returns the file's content.
	Get(ctx context.Context, path string) ([]byte, error)
	// Reader returns an open reader; caller must Close it.
	Reader(ctx context.Context, path string) (io.ReadCloser, error)
	// Exists reports whether path exists.
	Exists(ctx context.Context, path string) (bool, error)
	// Delete removes path (no error if missing).
	Delete(ctx context.Context, path string) error
	// Copy duplicates src to dst within the same disk.
	Copy(ctx context.Context, src, dst string) error
	// Move renames src to dst.
	Move(ctx context.Context, src, dst string) error
	// Files lists non-directory entries directly under dir (no recursion).
	Files(ctx context.Context, dir string) ([]FileInfo, error)
	// Stat returns metadata for path.
	Stat(ctx context.Context, path string) (FileInfo, error)
}

Disk is the storage abstraction. Implementations must be safe for concurrent use; the Local driver is.

type FileInfo

type FileInfo struct {
	Path    string
	Size    int64
	ModTime time.Time
	IsDir   bool
}

FileInfo describes a file on the disk. Modelled after the parts of os.FileInfo callers actually use.

type Local

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

Local is a Disk that stores files on the host filesystem under a fixed root directory. Safe for concurrent use.

func NewLocal

func NewLocal(root string) (*Local, error)

NewLocal returns a Local disk rooted at the given absolute path. The root is created with 0o755 if missing.

func (*Local) Copy

func (l *Local) Copy(ctx context.Context, src, dst string) error

func (*Local) Delete

func (l *Local) Delete(_ context.Context, path string) error

func (*Local) Exists

func (l *Local) Exists(_ context.Context, path string) (bool, error)

func (*Local) Files

func (l *Local) Files(_ context.Context, dir string) ([]FileInfo, error)

func (*Local) Get

func (l *Local) Get(_ context.Context, path string) ([]byte, error)

func (*Local) Move

func (l *Local) Move(_ context.Context, src, dst string) error

func (*Local) Put

func (l *Local) Put(_ context.Context, path string, data []byte) error

func (*Local) PutStream

func (l *Local) PutStream(_ context.Context, path string, r io.Reader) error

func (*Local) Reader

func (l *Local) Reader(_ context.Context, path string) (io.ReadCloser, error)

func (*Local) Root

func (l *Local) Root() string

Root returns the absolute filesystem root the Local disk uses.

func (*Local) Stat

func (l *Local) Stat(_ context.Context, path string) (FileInfo, error)