paths

Documentation

Overview

Package paths provides various functions and types related to processing paths in the filesystem, often for the purpose of identifying files older or larger than specified thresholds.

Index

• Variables
• func AgeExceeded(file os.FileInfo, days int) bool
• func Exists(path string) (bool, error)
• func Process(ctx context.Context, path string, ignoreList []string, recurse bool, ...)
• func ResolveIDs(mr *MetaRecord) error
• type ID
  • func LookupIDs(fi os.FileInfo) (ID, error)
• type MetaRecord
  • func AssertNotExists(list []string) (MetaRecord, error)
  • func Info(path string) (MetaRecord, error)
  • func (mr MetaRecord) SizeHR() string
• type MetaRecords
  • func (mr MetaRecords) SortByModTimeAsc()
  • func (mr MetaRecords) SortByModTimeDesc()
  • func (mr MetaRecords) SortBySizeAsc()
  • func (mr MetaRecords) SortBySizeDesc()
  • func (mr MetaRecords) TotalFileSize() int64
  • func (mr MetaRecords) TotalFileSizeHR() string
• type ProcessResult

Variables

var (
	ErrPathExists           = errors.New("path exists")
	ErrPathDoesNotExist     = errors.New("path does not exist")
	ErrPathEmptyString      = errors.New("specified path is empty string")
	ErrPathCheckFailed      = errors.New("failed to check path")
	ErrPathCheckCanceled    = errors.New("path check canceled")
	ErrPathOldFilesFound    = errors.New("old files found in path")
	ErrPathIgnored          = errors.New("path ignored per request")
	ErrSizeOfFilesTooLarge  = errors.New("evaluated files in specified path too large")
	ErrSizeOfFilesTooSmall  = errors.New("evaluated files in specified path too small")
	ErrPathMissingUsername  = errors.New("requested username not set on file/directory")
	ErrPathMissingGroupName = errors.New("requested group name not set on file/directory")
)

Application-specific errors for common path checks.

Functions

func AgeExceeded

func AgeExceeded(file os.FileInfo, days int) bool

AgeExceeded indicates whether a path is older than the specified threshold in days. If the path age is younger or equal to the specified number of days then the threshold is considered uncrossed.

func Exists

func Exists(path string) (bool, error)

Exists is a helper function used to quickly determine whether a specified path exists.

func Process

func Process(ctx context.Context, path string, ignoreList []string, recurse bool, results chan<- ProcessResult)

Process evalutes the specified path, either at a flat level or if specified, recursively. ProcessResult values are sent back by way of a results channel.

func ResolveIDs

func ResolveIDs(mr *MetaRecord) error

ResolveIDs accepts a MetaRecord pointer and if supported, resolves the uid and gid values from the underlying syscall.Stat_t and sets the values directly using the provided MetaRecord pointer. For unsupported operating systems, this function is effectively a NOOP.

Types

type ID

type ID struct {
	Username  string
	UID       int
	UIDStr    string
	GroupName string
	GID       int
	GIDStr    string
}

ID is a collection of username and group name values, associated with a specific os.FileInfo value.

func LookupIDs

func LookupIDs(fi os.FileInfo) (ID, error)

LookupIDs accepts a os.FileInfo and if supported, resolves the uid and gid values from the underlying syscall.Stat_t and returns those resolved values as an instance of the ID type for further processing. For unsupported operating systems, this function is effectively a NOOP.

type MetaRecord

type MetaRecord struct {

	// Size, name and other common details for the associated path.
	os.FileInfo

	// Permissions for the associated path.
	Permissions permbits.PermissionBits

	// Username and group values.
	ID

	// FQPath is the original, fully-qualified path.
	FQPath string

	// ParentDir is the parent directory for the path.
	ParentDir string
}

MetaRecord represents a superset of statistics for a file. This includes os.FileInfo, the fully-qualified path to the file and potentially user/group information.

func AssertNotExists

func AssertNotExists(list []string) (MetaRecord, error)

AssertNotExists accepts a list of paths to process and returns the specific error if unable to check the path, a set MetaRecord value and a package specific associated error for a path that is found or an empty MetaRecord and nil if all paths do not exist.

func Info

func Info(path string) (MetaRecord, error)

Info is a helper function used to quickly gather details on a specified path. A MetaRecord value and nil is returned for successful path evaluation, otherwise an empty MetaRecord value and appropriate error is returned.

func (MetaRecord) SizeHR

func (mr MetaRecord) SizeHR() string

SizeHR returns a human-readable string of the size of a MetaRecord object. Unless filtered later, this also applies to directories.

type MetaRecords

type MetaRecords []MetaRecord

MetaRecords is a slice of MetaRecord objects intended for bulk processing.

func (MetaRecords) SortByModTimeAsc

func (mr MetaRecords) SortByModTimeAsc()

SortByModTimeAsc sorts slice of MetaRecord objects in ascending order with older values listed first.

func (MetaRecords) SortByModTimeDesc

func (mr MetaRecords) SortByModTimeDesc()

SortByModTimeDesc sorts slice of MetaRecord objects in descending order with newer values listed first.

func (MetaRecords) SortBySizeAsc

func (mr MetaRecords) SortBySizeAsc()

SortBySizeAsc sorts slice of MetaRecord objects in ascending order with smaller values listed first.

func (MetaRecords) SortBySizeDesc

func (mr MetaRecords) SortBySizeDesc()

SortBySizeDesc sorts slice of MetaRecord objects in descending order with larger values listed first.

func (MetaRecords) TotalFileSize

func (mr MetaRecords) TotalFileSize() int64

TotalFileSize returns the cumulative size of all MetaRecord objects in the slice in bytes. Since this would also apply to directories, those objects are filtered out in an effort to provide a more accurate value.

func (MetaRecords) TotalFileSizeHR

func (mr MetaRecords) TotalFileSizeHR() string

TotalFileSizeHR returns a human-readable string of the cumulative size of all files in the slice of bytes.

type ProcessResult

type ProcessResult struct {
	MetaRecord
	Error error
}

ProcessResult is a superset of a MetaRecord and any associated error encountered while processing a path.