fs

Documentation

Index

• Constants
• func Copy(ctx context.Context, s Interface, dst string, src string) (n int64, err error)
• func CopyAll(ctx context.Context, s Interface, dst string, src string) error
• func CopyTo(ctx context.Context, s Interface, p string, r io.Reader) (n int64, err error)
• func Exists(ctx context.Context, s Interface, p string) (bool, error)
• func Hash(ctx context.Context, s Interface, p string, h crypto.Hash) ([]byte, error)
• func IsDir(ctx context.Context, s Interface, p string) (bool, error)
• func IsDirEmpty(ctx context.Context, s Interface, p string) (bool, error)
• func IsFile(ctx context.Context, s Interface, p string) (bool, error)
• func MkdirRecursive(ctx context.Context, s Interface, p string) error
• func RemoveAll(ctx context.Context, s Interface, p string) error
• func RemoveFile(ctx context.Context, s Interface, p string) error
• func Rmdir(ctx context.Context, s Interface, p string) error
• func ValidatePath(p string) (string, error)
• type DirIterator
• type Interface
• type Metadata
  • func (mt *Metadata) CopyTo(dst *Metadata) error
  • func (mt *Metadata) String() string
• type Reader
• type Writer
  • func ReplaceFile(ctx context.Context, s Interface, p string) (Writer, error)

Constants

const (
	MaxPathLength          = 32767
	MaxPathComponentLength = 255
	ValidPathComponent     = "[[:word:]-.,]+"
)

Constants used to determine when a path is valid.

Functions

func Copy

func Copy(ctx context.Context, s Interface, dst string, src string) (n int64, err error)

Copy copies the contents of the file at src in s to dst in s. If src does not exist or is not a file, then errors.NotFile is returned. If dst's parent directory does not exist, an errors.NotExist error is returned; if the parent exists but is not a directory then an errors.NotDirectory error is returned; an errors.Exist error is returned if a file or directory with path dst already exists. Returns the number of bytes copied. If s satisfies the interface:

type Copier interface {
	Copy(ctx context.Context, dst string, src string) (int64, error)
}

then its Copy method will be used.

func CopyAll

func CopyAll(ctx context.Context, s Interface, dst string, src string) error

CopyAll recursively copies the file or directory structure rooted at path src to path dst. If src does not exist, then errors.NotExist is returned. If dst's parent directory does not exist, an errors.NotExist error is returned; an errors.Exist error is returned if a file or directory with path dst already exists. If s satisfies the interface:

type CopyAller interface {
	CopyAll(ctx context.Context, dst string, src string) error
}

then its CopyAll method will be used.

func CopyTo

func CopyTo(ctx context.Context, s Interface, p string, r io.Reader) (n int64, err error)

CopyTo copies the contents of r to p in s. If p's parent directory does not exist, an errors.NotExist error is returned; if the parent exists but is not a directory then an errors.NotDirectory error is returned; an errors.Exist error is returned if a file or directory with path p already exists. Returns the number of bytes copied. If s satisfies the interface:

type CopyToer interface {
	CopyTo(ctx context.Context, p string, r io.Reader) (int64, error)
}

then its CopyTo method will be used.

func Exists

func Exists(ctx context.Context, s Interface, p string) (bool, error)

Exists returns true if and only if path p exists in s. If s satisfies the interface:

type Existser interface {
	Exists(ctx context.Context, p string) (bool, error)
}

then its Exists method will be used.

func Hash

func Hash(ctx context.Context, s Interface, p string, h crypto.Hash) ([]byte, error)

Hash returns the hash of the file with path p on s, using the hash h. If the hash is not available (as determined by crypto.Hash.Available) then an errors.HashNotAvailable error will be returned. If the path does not exist, or is a directory, an errors.NotFile error is returned. If s satisfies the interface:

type Hasher interface {
	Hash(ctx context.Context, p string, h crypto.Hash) ([]byte, error)
}

then its Hash method will be tried first.

func IsDir

func IsDir(ctx context.Context, s Interface, p string) (bool, error)

IsDir returns true if and only if path p exists in s and is a directory. If s satisfies the interface:

type IsDirer interface {
	IsDir(ctx context.Context, p string) (bool, error)
}

then its IsDir method will be used.

func IsDirEmpty

func IsDirEmpty(ctx context.Context, s Interface, p string) (bool, error)

IsDirEmpty returns true if and only if path p exists in s and is an empty directory. If the path is not a directory, returns errors.NotDirectory. If s satisfies the interface:

type IsDirEmptyer interface {
	IsDirEmpty(ctx context.Context, p string) (bool, error)
}

then its IsDirEmpty method will be used.

func IsFile

func IsFile(ctx context.Context, s Interface, p string) (bool, error)

IsFile returns true if and only if path p exists in s and is a file. If s satisfies the interface:

type IsFiler interface {
	IsFile(ctx context.Context, p string) (bool, error)
}

then its IsFile method will be used.

func MkdirRecursive

func MkdirRecursive(ctx context.Context, s Interface, p string) error

MkdirRecursive creates the directory with the given path p, along with any intermediate directories as necessary. An errors.Exist error is returned if a file or directory with that path already exists, or if a file already exists with an intermediate path. If s satisfies the interface:

type MkdirRecursiver interface {
	MkdirRecursive(ctx context.Context, p string) error
}

then its MkdirRecursive method will be used.

func RemoveAll

func RemoveAll(ctx context.Context, s Interface, p string) error

RemoveAll removes path p from s if p is a file, and removes p and all its contents from s if p is a directory. If the path does not exist, RemoveAll returns nil (no error). If s satisfies the interface:

type RemoveAller interface {
	RemoveAll(ctx context.Context, p string) error
}

then its RemoveAll method will be used.

func RemoveFile

func RemoveFile(ctx context.Context, s Interface, p string) error

RemoveFile attempts to delete the file with path p in s. If p does not exist or is not a file, then the error errors.NotFile will be returned. If s satisfies the interface:

type RemoveFiler interface {
	RemoveFile(ctx context.Context, p string) error
}

then its RemoveFile method will be used.

func Rmdir

func Rmdir(ctx context.Context, s Interface, p string) error

Rmdir removes the path p from s, if p is an empty directory. If the path is not a directory, returns errors.NotDirectory; if the directory is not empty or is "/", returns errors.DirNotEmpty. If s satisfies the interface:

type Rmdirer interface {
	Rmdir(ctx context.Context, p string) error
}

then its Rmdir method will be used.

func ValidatePath

func ValidatePath(p string) (string, error)

ValidatePath checks that the path validates and returns its canonical form. Note that success says nothing about the path actually existing -- it means that the format of the path is sensible.

The canonical form of any path is the result of path.Clean applied to that path. Two valid paths are considered to be equivalent if they have the same canonical form. A valid path is one such that its canonical form satisfies the following:

• the path is at most MaxPathLength characters long in total;
• the path is divided by '/' into path components;
• no path component exceeds MaxPathComponentLength characters in length;
• each path component contains only the characters satisfying the regular expression ValidPathComponent;
• it begins with a '/'.

Types

type DirIterator

type DirIterator interface {
	io.Closer
	// Err returns the last error, if any, encountered during iteration. Err
	// may be called after Close.
	Err() error
	// Next advances the iterator. Returns true on successful advance of the
	// iterator; false otherwise. Next or NextContext must be called before
	// the first call to Scan.
	Next() bool
	// NextContext advances the iterator. Returns true on successful advance
	// of the iterator; false otherwise. Next or NextContext must be called
	// before the first call to Scan.
	NextContext(ctx context.Context) (bool, error)
	// Scan copies the current entry in the iterator to dst, which must be
	// non-nil.
	Scan(dst *Metadata) error
}

DirIterator is an interface satisfied by an iterator containing the files and directories within a directory.

type Interface

type Interface interface {
	// Upload returns a Writer writing to the path p. If p's parent
	// directory does not exist, an errors.NotExist error is returned;
	// if the parent exists but is not a directory then an
	// errors.NotDirectory error is returned; if a file or directory with
	// path p already exists then an errors.Exist error is returned. It is
	// the caller's responsibility to call Close on the returned Writer,
	// otherwise resources may leak.
	Upload(ctx context.Context, p string) (Writer, error)
	// Download returns a Reader reading from contents of the file with the
	// path p. If no file with path p exists, an errors.NotFile is returned.
	// It is the caller's responsibility to call Close on the returned
	// Reader, otherwise resources may leak.
	Download(ctx context.Context, p string) (Reader, error)
	// DownloadMetadata returns the metadata for the file or directory with
	// the path p. If a file or directory with this path does not exist, an
	// errors.NotExist error is returned.
	DownloadMetadata(ctx context.Context, p string) (*Metadata, error)
	// Mkdir creates the directory with the path p. If p's parent directory
	// does not exist, an errors.NotExist error is returned; if the parent
	// exists but is not a directory then an errors.NotDirectory error is
	// returned; if a file or directory with that path already exists then
	// an errors.Exist error is returned.
	Mkdir(ctx context.Context, p string) error
	// Remove attempts to remove the file or directory with the path p. If
	// the path does not exist, an errors.NotExist error is returned. If the
	// path is a directory and is non-empty or is "/", an errors.DirNotEmpty
	// error is returned.
	Remove(ctx context.Context, p string) error
	// Dir returns an iterator containing metadata for the files and
	// directories within the directory with path p. If the path p does not
	// exist then an errors.NotExist error is returned; if the path p exists
	// but is not a directory then an errors.NotDirectory error will be
	// returned. It is the caller's responsibility to call Close on the
	// returned DirIterator, otherwise resources may leak.
	Dir(ctx context.Context, p string) (DirIterator, error)
}

Interface is the interface satisfied by storage systems.

type Metadata

type Metadata struct {
	Path    string    `json:",omitempty"` // The path of the file
	Size    int64     `json:",omitempty"` // The size of the file contents
	ModTime time.Time `json:",omitempty"` // The modification time
	IsDir   bool      `json:",omitempty"` // True if and only if the file represents a directory
}

Metadata describes file metadata.

func (*Metadata) CopyTo

func (mt *Metadata) CopyTo(dst *Metadata) error

CopyTo copies mt to dst.

func (*Metadata) String

func (mt *Metadata) String() string

String returns a string description of the metadata.

type Reader

type Reader interface {
	io.ReadCloser
	// Name returns the name of the file as presented to Download.
	Name() string
	// SetReadDeadline sets the deadline for future Read calls and any
	// currently-blocked Read call. A zero value for t means Read will not
	// time out.
	SetReadDeadline(t time.Time) error
	// SetDeadline is an alias for SetReadDeadline.
	SetDeadline(t time.Time) error
}

Reader is the interface describing a reader.

type Writer

type Writer interface {
	io.WriteCloser
	// Name returns the name of the file as presented to Upload.
	Name() string
	// SetWriteDeadline sets the deadline for future Write calls and any
	// currently-blocked Write call. Even if write times out, it may return
	// n > 0, indicating that some of the data was successfully written. A
	// zero value for t means Write will not time out.
	SetWriteDeadline(t time.Time) error
	// SetDeadline is an alias for SetWriteDeadline.
	SetDeadline(t time.Time) error
}

Writer is the interface describing a writer.

func ReplaceFile

func ReplaceFile(ctx context.Context, s Interface, p string) (Writer, error)

ReplaceFile attempts to create or replace the file with path p in s. If p's parent directory does not exist, an errors.NotExist error is returned; if the parent exists but is not a directory then an errors.NotDirectory error is returned; if p exists but is not a file, then the error errors.NotFile will be returned. It is the caller's responsibility to call Close on the returned Writer, otherwise resources may leak. If s satisfies the interface:

type ReplaceFiler interface {
	ReplaceFile(ctx context.Context, p string) (Writer, error)
}

then its ReplaceFile method will be used.