fs

Documentation

Overview

Package fs defines virtual filesystem abstractions.

Index

• Constants
• Variables
• func IterateEntries(ctx context.Context, dir Directory, cb func(context.Context, Entry) error) error
• func Sort(entries []Entry)
• type DeviceInfo
• type Directory
• type DirectoryIterator
  • func StaticIterator(entries []Entry, err error) DirectoryIterator
• type DirectorySummary
  • func (s *DirectorySummary) Clone() DirectorySummary
• type DirectoryWithSummary
• type Entry
  • func FindByName(entries []Entry, n string) Entry
  • func GetAllEntries(ctx context.Context, d Directory) ([]Entry, error)
  • func IterateEntriesAndFindChild(ctx context.Context, d Directory, name string) (Entry, error)
• type EntryWithError
• type ErrorEntry
• type File
• type OwnerInfo
• type Reader
• type StreamingFile
• type Symlink
• type UTCTimestamp
  • func UTCTimestampFromTime(t time.Time) UTCTimestamp
  • func (u UTCTimestamp) Add(dur time.Duration) UTCTimestamp
  • func (u UTCTimestamp) After(other UTCTimestamp) bool
  • func (u UTCTimestamp) Before(other UTCTimestamp) bool
  • func (u UTCTimestamp) Equal(other UTCTimestamp) bool
  • func (u UTCTimestamp) Format(layout string) string
  • func (u UTCTimestamp) MarshalJSON() ([]byte, error)
  • func (u UTCTimestamp) Sub(u2 UTCTimestamp) time.Duration
  • func (u UTCTimestamp) ToTime() time.Time
  • func (u *UTCTimestamp) UnmarshalJSON(v []byte) error

Constants

const MaxFailedEntriesPerDirectorySummary = 10

MaxFailedEntriesPerDirectorySummary is the maximum number of failed entries per directory summary.

const ModBits = os.ModePerm | os.ModeSetgid | os.ModeSetuid | os.ModeSticky

ModBits is a bitmask representing the mode flags supported.

Variables

var ErrEntryNotFound = errors.New("entry not found")

ErrEntryNotFound is returned when an entry is not found.

var ErrUnknown = errors.Errorf("unknown or unsupported entry type")

ErrUnknown is returned by ErrorEntry.ErrorInfo() to indicate that type of an entry is unknown.

Functions

func IterateEntries

func IterateEntries(ctx context.Context, dir Directory, cb func(context.Context, Entry) error) error

IterateEntries iterates entries the provided directory and invokes given callback for each entry or until the callback returns an error.

func Sort

func Sort(entries []Entry)

Sort sorts the entries by name.

Types

type DeviceInfo

type DeviceInfo struct {
	Dev  uint64 `json:"dev"`
	Rdev uint64 `json:"rdev"`
}

DeviceInfo describes the device this filesystem entry is on.

type Directory

type Directory interface {
	Entry

	Child(ctx context.Context, name string) (Entry, error)
	Iterate(ctx context.Context) (DirectoryIterator, error)
	// SupportsMultipleIterations returns true if the Directory supports iterating
	// through the entries multiple times. Otherwise it returns false.
	SupportsMultipleIterations() bool
}

Directory represents contents of a directory.

type DirectoryIterator

type DirectoryIterator interface {
	Next(ctx context.Context) (Entry, error)
	Close()
}

DirectoryIterator iterates entries in a directory.

The client is expected to call Next() in a loop until it returns a nil entry to signal end of iteration or until an error has occurred.

Valid results:

(nil,nil) - end of iteration, success (entry,nil) - iteration in progress, success (nil,err) - iteration stopped, failure

The behavior of calling Next() after iteration has signaled its end is undefined.

To release any resources associated with iteration the client must call Close().

func StaticIterator

func StaticIterator(entries []Entry, err error) DirectoryIterator

StaticIterator returns a DirectoryIterator which returns the provided entries in order followed by a given final error. It is not safe to concurrently access directory iterator.

type DirectorySummary

type DirectorySummary struct {
	TotalFileSize     int64        `json:"size"`
	TotalFileCount    int64        `json:"files"`
	TotalSymlinkCount int64        `json:"symlinks"`
	TotalDirCount     int64        `json:"dirs"`
	MaxModTime        UTCTimestamp `json:"maxTime"`
	IncompleteReason  string       `json:"incomplete,omitempty"`

	// number of failed files
	FatalErrorCount   int `json:"numFailed"`
	IgnoredErrorCount int `json:"numIgnoredErrors,omitempty"`

	// first 10 failed entries
	FailedEntries []*EntryWithError `json:"errors,omitempty"`
}

DirectorySummary represents summary information about a directory.

func (*DirectorySummary) Clone

func (s *DirectorySummary) Clone() DirectorySummary

Clone clones given directory summary.

type DirectoryWithSummary

type DirectoryWithSummary interface {
	Summary(ctx context.Context) (*DirectorySummary, error)
}

DirectoryWithSummary is optionally implemented by Directory that provide summary.

type Entry

type Entry interface {
	os.FileInfo
	Owner() OwnerInfo
	Device() DeviceInfo
	LocalFilesystemPath() string // returns full local filesystem path or "" if not a local filesystem
	Close()                      // closes or recycles any resources associated with the entry, must be idempotent
}

Entry represents a filesystem entry, which can be Directory, File, or Symlink.

func FindByName

func FindByName(entries []Entry, n string) Entry

FindByName returns an entry with a given name, or nil if not found. Assumes the given slice of fs.Entry is sorted.

func GetAllEntries

func GetAllEntries(ctx context.Context, d Directory) ([]Entry, error)

GetAllEntries uses Iterate to return all entries in a Directory.

func IterateEntriesAndFindChild

func IterateEntriesAndFindChild(ctx context.Context, d Directory, name string) (Entry, error)

IterateEntriesAndFindChild iterates through entries from a directory and returns one by name. This is a convenience function that may be helpful in implementations of Directory.Child().

type EntryWithError

type EntryWithError struct {
	EntryPath string `json:"path"`
	Error     string `json:"error"`
}

EntryWithError describes error encountered when processing an entry.

type ErrorEntry

type ErrorEntry interface {
	Entry

	ErrorInfo() error
}

ErrorEntry represents entry in a Directory that had encountered an error or is unknown/unsupported (ErrUnknown).

type File

type File interface {
	Entry
	Open(ctx context.Context) (Reader, error)
}

File represents an entry that is a file.

type OwnerInfo

type OwnerInfo struct {
	UserID  uint32 `json:"uid"`
	GroupID uint32 `json:"gid"`
}

OwnerInfo describes owner of a filesystem entry.

type Reader

type Reader interface {
	io.ReadCloser
	io.Seeker

	Entry() (Entry, error)
}

Reader allows reading from a file and retrieving its up-to-date file info.

type StreamingFile

type StreamingFile interface {
	Entry
	GetReader(ctx context.Context) (io.ReadCloser, error)
}

StreamingFile represents an entry that is a stream.

type Symlink

type Symlink interface {
	Entry
	Readlink(ctx context.Context) (string, error)
}

Symlink represents a symbolic link entry.

type UTCTimestamp

type UTCTimestamp int64

UTCTimestamp stores the UTC timestamp in nanoseconds and provides JSON serializability.

func UTCTimestampFromTime

func UTCTimestampFromTime(t time.Time) UTCTimestamp

UTCTimestampFromTime converts time.Time to UTCTimestamp.

func (UTCTimestamp) Add

func (u UTCTimestamp) Add(dur time.Duration) UTCTimestamp

Add adds the specified duration to UTC time.

func (UTCTimestamp) After

func (u UTCTimestamp) After(other UTCTimestamp) bool

After returns true if the timestamp is after another timestamp.

func (UTCTimestamp) Before

func (u UTCTimestamp) Before(other UTCTimestamp) bool

Before returns true if the timestamp is before another timestamp.

func (UTCTimestamp) Equal

func (u UTCTimestamp) Equal(other UTCTimestamp) bool

Equal returns true if the timestamp is equal to another timestamp.

func (UTCTimestamp) Format

func (u UTCTimestamp) Format(layout string) string

Format formats the timestamp according to the provided layout.

func (UTCTimestamp) MarshalJSON

func (u UTCTimestamp) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (UTCTimestamp) Sub

func (u UTCTimestamp) Sub(u2 UTCTimestamp) time.Duration

Sub returns the difference between two specified durations.

func (UTCTimestamp) ToTime

func (u UTCTimestamp) ToTime() time.Time

ToTime returns time.Time representation of the time.

func (*UTCTimestamp) UnmarshalJSON

func (u *UTCTimestamp) UnmarshalJSON(v []byte) error

UnmarshalJSON implements json.Unmarshaler.