filehealth

package module
v0.0.0-...-be26a82 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 30, 2022 License: MIT Imports: 15 Imported by: 0

README

filehealth Go Reference

The filehealth package provides a library and command line tool for scanning files for invalid names, timestamps and other attributes. It was written for use on Windows file systems but it may be of use on other platforms in the future.

Command Line Tool

For information about the filehealth command line tool specifically, please take a look at its documentation.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrDryRun = errors.New("dry run")

ErrDryRun is reported as the outcome for fixes when an operation was created as a dry run.

View Source 
var ErrFileChanged = errors.New("the file has changed since the file was examined")

ErrFileChanged is returned by some issue handlers when they detect that a file changed between the time it was examined and the time that a fix was requested.

View Source 
var ErrScanCancelled = errors.New("the scan has been cancelled")

ErrScanCancelled is reported by FileIter.Err() if it's been cancelled.

Functions

This section is empty.

Types

type AttrHandler 

type AttrHandler struct {
	Unwanted fileattr.Value
}

AttrHandler handles file attribute issues.

func (AttrHandler) Examine 

func (h AttrHandler) Examine(ctx context.Context, exam *Examination) []Issue

Examine checks the file under examination for issues. It returns nil if no issues are identified.

func (AttrHandler) Name 

func (h AttrHandler) Name() string

Name returns the name of the handler.

type AttrIssue 

type AttrIssue struct {
	Original fileattr.Value
	Matched  fileattr.Value

	AttrHandler
}

NameIssue describes a file name issue.

func (AttrIssue) Description 

func (issue AttrIssue) Description() string

Description returns a description of the issue. It may return an empty string if the information provided by the summary is sufficient.

func (AttrIssue) FileOpenFlags 

func (issue AttrIssue) FileOpenFlags() int

FileOpenFlags returns the set of file permission flags required to fix the issue.

func (AttrIssue) Fix 

func (issue AttrIssue) Fix(ctx context.Context, op *Operation) Outcome

Fix attempts to correct the issue with the file.

func (AttrIssue) Handler 

func (issue AttrIssue) Handler() IssueHandler

Handler returns the Handler that's responsible for handling the name issue.

func (AttrIssue) Resolution 

func (issue AttrIssue) Resolution() string

Resolution returns a string describing a proposed resolution to the issue.

func (AttrIssue) Summary 

func (issue AttrIssue) Summary() string

Summary returns a short summary of the issue.

type AttrOutcome 

type AttrOutcome struct {
	OldAttributes fileattr.Value
	NewAttributes fileattr.Value
	// contains filtered or unexported fields
}

AttrOutcome records the outcome of an attempted fix for a file name issue.

func (AttrOutcome) Err 

func (outcome AttrOutcome) Err() error

Err returns an error if one was encountered during the operation.

func (AttrOutcome) Issue 

func (outcome AttrOutcome) Issue() Issue

Issue returns the issue this outcome pertains to.

func (AttrOutcome) String 

func (outcome AttrOutcome) String() string

String returns a string representation of the issue.

type Dir 

type Dir string

Dir is a file directory path accessible via operating system API acalls.

func (Dir) FilePath 

func (dir Dir) FilePath(name string) string

FilePath returns the full path of the given file name by joining it with dir.

func (Dir) Open 

func (dir Dir) Open(name string) (fs.File, error)

Open opens the named file.

func (Dir) OpenFile 

func (dir Dir) OpenFile(name string, flag int, mode fs.FileMode) (fs.File, error)

Open opens the named file with the given flags and mode.

func (Dir) Stat 

func (dir Dir) Stat(name string) (fs.FileInfo, error)

Stat returns a FileInfo describing the file.

type Examination 

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

Operation is an operation on a file that has been scanned.

func (*Examination) FileInfo 

func (op *Examination) FileInfo() fs.FileInfo

Index returns the index of the file when it was scanned.

func (*Examination) Index 

func (op *Examination) Index() int

Index returns the index of the file when it was scanned.

func (*Examination) Path 

func (op *Examination) Path() string

Path returns the path of the file within its file system.

type ExaminationFunc 

type ExaminationFunc func(*Examination) error

ExaminationFunc is a function that runs within the context of an examination.

type File 

type File struct {
	// Scanned file location
	Root    Dir
	Path    string
	Index   int
	Skipped bool

	// FileInfo values collected during a scan (may be empty)
	Name    string
	Size    int64
	Mode    fs.FileMode
	ModTime time.Time
	Issues  []Issue
}

File describes a file that has been scanned.

func (File) Description 

func (f File) Description() string

Description returns a multiline string of the file's issues. It returns an empty string if the file has no issue.

func (File) DryOperation 

func (f File) DryOperation(fn OperationFunc) error

DryOperation executes an operation for the file as a dry run.

func (File) DryRun 

func (f File) DryRun(ctx context.Context) ([]Outcome, error)

DryRun performs a dry run of attempted fixes for each of the file's issues.

func (File) Fix 

func (f File) Fix(ctx context.Context) ([]Outcome, error)

Fix attemtps to fix each of the issues with the given file.

func (File) Operation 

func (f File) Operation(fn OperationFunc) error

Operation executes an operation for the file.

func (File) String 

func (f File) String() string

String returns a string representation of f, including its index and path.

type FileFunc 

type FileFunc func(fs.File) error

FileFunc is a function that can operate on a file.

type FileIter 

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

FileIter is a file iterator returned by a Scanner. It's used to step through the results of a Scanner as they're produced.

func ScanDir 

func ScanDir(ctx context.Context, root Dir, handlers ...IssueHandler) *FileIter

ScanDir scans the given file system directory for issues.

func (*FileIter) Close 

func (iter *FileIter) Close() error

Close causes the iterator's job to stop running. It always returns nil.

func (*FileIter) Duration 

func (iter *FileIter) Duration() time.Duration

Duration returns the duration of the iterator's job.

func (*FileIter) Err 

func (iter *FileIter) Err() error

Err returns a non-nil error if the iterator's job encountered an error and stopped. It should be called after Scan() returns false. It returns nil if the job completed successfully.

func (*FileIter) File 

func (iter *FileIter) File() File

File returns the most recently matched file. It is updated each time Scan() returns true. Scan() must be called at least once before calling this funcion.

func (*FileIter) Scan 

func (iter *FileIter) Scan(ctx context.Context) bool

Scan waits for the next file to become available from the iterator. It returns false if the context is cancelled, the scanner encounters an error, or the end of the stream is reached.

When Scan returns false, check iter.Err() for a non-nil error to understand the cause.

func (*FileIter) Stats 

func (iter *FileIter) Stats() JobStats

Stats returns the statistics for the iterator's job.

type FileTimeType 

type FileTimeType int

FileTimeType identifies a type of file timestamp. 

const (
	FileTimeCreation FileTimeType = iota
	FileTimeAccess
	FileTimeLastWrite
	FileTimeChange
)

Timestamp types.

func (FileTimeType) String 

func (t FileTimeType) String() string

String returns a string representation of the timestamp type.

type Issue 

type Issue interface {
	// Handler returns the Handler that's responsible for handling the issue.
	Handler() IssueHandler

	// Summary returns a short summary of the issue.
	Summary() string

	// Description returns a description of the issue. It may return an empty
	// string if the information provided by the summary is sufficient.
	Description() string

	// Resolution returns a string describing the fix. It returns an empty
	// string if no resolution is possible.
	Resolution() string

	// FileOpenFlags returns the set of file permission flags required to fix
	// the issue.
	FileOpenFlags() int

	// Fix attempts to fix the issue.
	Fix(context.Context, *Operation) Outcome
}

Issue describes a problem with a file.

type IssueHandler 

type IssueHandler interface {
	// Name returns the name of the handler.
	Name() string

	// Examine checks the file under examination for issues. It returns nil if no
	// issues are identified.
	Examine(context.Context, *Examination) []Issue
}

IssueHandler handles file issues of a particular type.

type JobStats 

type JobStats struct {
	// Skipped is the number of files not scanned due to filters.
	Skipped int

	// Scanned is the number of files scanned.
	Scanned int

	// Healthy is the number of scanned files that had no issues.
	Healthy int

	// Unhealthy is the number of scanned files that had at least one issue.
	Unhealthy int

	// Issues is the total number of issues detected in scanned files.
	Issues int
}

JobStats report scanning tallies during and at the completion of scanning.

func (JobStats) String 

func (s JobStats) String() string

String returns a string representation of the job statistics.

type NameHandler 

type NameHandler struct {
	TrimSpace bool
}

NameHandler handles file name issues.

func (NameHandler) Examine 

func (h NameHandler) Examine(ctx context.Context, exam *Examination) []Issue

Examine checks the file under examination for issues. It returns nil if no issues are identified.

func (NameHandler) Name 

func (h NameHandler) Name() string

Name returns the name of the handler.

type NameIssue 

type NameIssue struct {
	OriginalName string
	NewName      string

	NameHandler
}

NameIssue describes a file name issue.

func (NameIssue) Description 

func (issue NameIssue) Description() string

Description returns a description of the issue. It may return an empty string if the information provided by the summary is sufficient.

func (NameIssue) FileOpenFlags 

func (issue NameIssue) FileOpenFlags() int

FileOpenFlags returns the set of file permission flags required to fix the issue.

func (NameIssue) Fix 

func (issue NameIssue) Fix(ctx context.Context, op *Operation) Outcome

Fix attempts to correct the issue a file.

func (NameIssue) Handler 

func (issue NameIssue) Handler() IssueHandler

Handler returns the Handler that's responsible for handling the name issue.

func (NameIssue) Resolution 

func (issue NameIssue) Resolution() string

Resolution returns a string describing a proposed resolution to the issue.

func (NameIssue) Summary 

func (issue NameIssue) Summary() string

Summary returns a short summary of the issue.

type NameOutcome 

type NameOutcome struct {
	OldFilePath string
	NewFilePath string
	// contains filtered or unexported fields
}

NameOutcome records the outcome of an attempted fix for a file name issue.

func (NameOutcome) Err 

func (outcome NameOutcome) Err() error

Err returns an error if one was encountered during the operation.

func (NameOutcome) Issue 

func (outcome NameOutcome) Issue() Issue

Issue returns the issue this outcome pertains to.

func (NameOutcome) String 

func (outcome NameOutcome) String() string

String returns a string representation of the issue.

type Operation 

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

Operation is an operation on a file that has been scanned.

func (*Operation) Close 

func (op *Operation) Close() error

Close closes any file handles that the operation may have open.

func (*Operation) DryRun 

func (op *Operation) DryRun() bool

DryRun returns true if the operation is a dry run.

func (*Operation) FileChanged 

func (op *Operation) FileChanged() (bool, error)

FileChanged reports whether the file's basic attributes were changed between the time it was scanned and the first time this function is called on the operation.

func (*Operation) Index 

func (op *Operation) Index() int

Index returns the index of the file when it was examined.

func (*Operation) OriginalModTime 

func (op *Operation) OriginalModTime() time.Time

OriginalModTime returns the modification time of the file at the time it was examined.

func (*Operation) OriginalMode 

func (op *Operation) OriginalMode() fs.FileMode

OriginalMode returns the mode of the file at the time it was examined.

func (*Operation) OriginalName 

func (op *Operation) OriginalName() string

OriginalName returns the name of the file when it was examined.

func (*Operation) OriginalPath 

func (op *Operation) OriginalPath() string

OriginalPath returns the path of the file within its file system.

func (*Operation) OriginalSize 

func (op *Operation) OriginalSize() int64

OriginalSize returns the size of the file at the time it was examined.

func (*Operation) Root 

func (op *Operation) Root() Dir

Root returns the root directory to which the files's paths is relative.

func (*Operation) WithFile 

func (op *Operation) WithFile(fn FileFunc) error

WithFile opens the operation's file and invokes the given function on it.

If the file cannot be opened, an error is returned. Otherwise, the result of fn() is returned.

If called more than once, the same fs.File will be returned to each call. Callers should not use this function to read from or write to the file, because the file's position will not be reset between calls.

func (*Operation) WithFileExclusive 

func (op *Operation) WithFileExclusive(fn FileFunc) error

WithFileExclusive opens the operation's file and invokes the given function on it.

If the file cannot be opened, an error is returned. Otherwise, the result of fn() is returned.

A unique fs.File will be returned for each call. It is safe to read from and write to the file.

type OperationFunc 

type OperationFunc func(*Operation) error

OperationFunc is a function that runs within the context of an operation.

type Outcome 

type Outcome interface {
	Issue() Issue
	String() string
	Err() error
}

Outcome records the outcome of an attempted fix for an issue.

type Pattern 

type Pattern struct {
	Expression *regexp.Regexp
}

Pattern is a file matching pattern based on regular expressions.

func (Pattern) String 

func (p Pattern) String() string

String returns a string representation of the pattern.

func (*Pattern) UnmarshalText 

func (p *Pattern) UnmarshalText(text []byte) error

UnmarshalText unmarshals the given text as a pattern in p.

type ScanIssue 

type ScanIssue struct {
	Err error
}

ScanIssue describes an issue encounterd by a scanner.

func (ScanIssue) Description 

func (issue ScanIssue) Description() string

Description returns a description of the issue. It may return an empty string if the information provided by the summary is sufficient.

func (ScanIssue) FileOpenFlags 

func (issue ScanIssue) FileOpenFlags() int

FileOpenFlags returns the set of file permission flags required to fix the issue.

func (ScanIssue) Fix 

func (issue ScanIssue) Fix(ctx context.Context, op *Operation) Outcome

Fix attempts to fix the issue.

func (ScanIssue) Handler 

func (issue ScanIssue) Handler() IssueHandler

Handler returns the Handler that's responsible for handling the issue.

func (ScanIssue) Resolution 

func (issue ScanIssue) Resolution() string

Resolution returns a string describing the fix. It returns an empty string if no resolution is possible.

func (ScanIssue) Summary 

func (issue ScanIssue) Summary() string

Summary returns a short summary of the issue.

type Scanner 

type Scanner struct {
	// Handlers examine each file passing through the scanner's filters and
	// determine whether they have issues. They determine what constitutes an "issue".
	Handlers []IssueHandler

	// Include is a filter that limits the number of files scanned. If
	// provided, only files with names matching at least one pattern will
	// be scanned.
	Include []Pattern

	// Exclude is a filter that limits the number of files scanned. If
	// provided, only files with names that don't match any of its patterns
	// will be scanned.
	Exclude []Pattern

	// SendSkipped requests that skipped files, those that don't pass the
	// inclusion and exclusion filters, be sent to the iterator.
	SendSkipped bool

	// SendHealthy requests that healthy files, those without any issues, be
	// sent to the iterator.
	SendHealthy bool
}

Scanner scans a set of files for issues identified by its issue handlers.

func (Scanner) ScanDir 

func (s Scanner) ScanDir(root Dir) *FileIter

ScanDir causes the scanner to scan the given file system directory.

type Summary 

type Summary struct {
	Scanned    int
	Matched    int
	Issues     int
	Start, End time.Time
}

Summary is a summary of a file system scan.

func (Summary) String 

func (s Summary) String() string

String returns a string representation of the summary.

type TimeHandler 

type TimeHandler struct {
	// Min is the minimum timestamp permitted. Optional.
	Min time.Time

	// Max is the maximum timestamp permitted. Optional.
	Max time.Time

	// Reference is used to compensate for the passage of time during
	// long-running operations. Optional.
	//
	// When specified, the current time will be compared to the reference
	// time, and the difference will be added to Min and Max.
	Reference time.Time

	// Lenience is used to compensate for inaccurate and unsynchronized.
	// clocks. Optional.
	//
	// Timestamps that are close to Min or Max will be accepted if the
	// delta is less than lenience.
	Lenience time.Duration
}

TimeHandler handles file timestamp issues.

func (TimeHandler) Examine 

func (h TimeHandler) Examine(ctx context.Context, exam *Examination) []Issue

Examine checks the file under examination for issues. It returns nil if no issues are identified.

func (TimeHandler) Name 

func (h TimeHandler) Name() string

Name returns the name of the handler.

func (TimeHandler) NewTime 

func (h TimeHandler) NewTime(t, fallback time.Time) time.Time

NewTime returns the given time, constrained to the bounds of Min and Max.

type TimeIssue 

type TimeIssue struct {
	Type     FileTimeType
	Time     time.Time
	Fallback time.Time

	TimeHandler
}

TimeIssue describes a file modification time issue.

func (TimeIssue) Description 

func (issue TimeIssue) Description() string

Description returns a description of the issue. It may return an empty string if the information provided by the summary is sufficient.

func (TimeIssue) FileOpenFlags 

func (issue TimeIssue) FileOpenFlags() int

FileOpenFlags returns the set of file permission flags required to fix the issue.

func (TimeIssue) Fix 

func (issue TimeIssue) Fix(ctx context.Context, op *Operation) Outcome

Fix attempts to correct the issue a file.

func (TimeIssue) Handler 

func (issue TimeIssue) Handler() IssueHandler

Handler returns the Handler that's responsible for handling the name issue.

func (TimeIssue) Resolution 

func (issue TimeIssue) Resolution() string

Resolution returns a string describing a proposed resolution to the issue.

func (TimeIssue) Summary 

func (issue TimeIssue) Summary() string

Summary returns a short summary of the issue.

type TimeOutcome 

type TimeOutcome struct {
	OldTime time.Time
	NewTime time.Time
	// contains filtered or unexported fields
}

TimeOutcome records the outcome of an attempted fix for a file name issue.

func (TimeOutcome) Err 

func (outcome TimeOutcome) Err() error

Err returns an error if one was encountered during the operation.

func (TimeOutcome) Issue 

func (outcome TimeOutcome) Issue() Issue

Issue returns the issue this outcome pertains to.

func (TimeOutcome) String 

func (outcome TimeOutcome) String() string

String returns a string representation of the issue.

Source Files

View all Source files

Directories

Path Synopsis
cmd
filehealth

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.