filesystem

Documentation

Overview

Package filesystem provides the interface for inventory extraction plugins.

Index

• Variables
• func ExtractorErrorToFileExtractedResult(err error) stats.FileExtractedResult
• func InitWalkContext(ctx context.Context, config *Config, absScanRoots []string) (*walkContext, error)
• func Run(ctx context.Context, config *Config) ([]*extractor.Inventory, []*plugin.Status, error)
• func RunFS(ctx context.Context, config *Config, wc *walkContext) ([]*extractor.Inventory, []*plugin.Status, error)
• type Config
• type Extractor
• type ScanInput

Variables

var (
	// ErrExtractorMemoryLimitExceeded is returned when an extractor skips a file
	// due to the extraction process exceeding a configured memory limit.
	ErrExtractorMemoryLimitExceeded = errors.New("extraction failed due to extractor exceeding the configured memory limit")
)

var (
	// ErrNotRelativeToScanRoots is returned when one of the file or directory to be retrieved or
	// skipped is not relative to any of the scan roots.
	ErrNotRelativeToScanRoots = fmt.Errorf("path not relative to any of the scan roots")
)

Functions

func ExtractorErrorToFileExtractedResult

func ExtractorErrorToFileExtractedResult(err error) stats.FileExtractedResult

ExtractorErrorToFileExtractedResult converts an error returned by an extractor to a FileExtractedResult for stats collection. Converting the error to a result minimizes the memory used for reporting stats.

func InitWalkContext

func InitWalkContext(ctx context.Context, config *Config, absScanRoots []string) (*walkContext, error)

InitWalkContext initializes the walk context for a filesystem walk. It strips all the paths that are expected to be relative to the scan root. This function is exported for TESTS ONLY.

func Run

func Run(ctx context.Context, config *Config) ([]*extractor.Inventory, []*plugin.Status, error)

Run runs the specified extractors and returns their extraction results, as well as info about whether the plugin runs completed successfully.

func RunFS

func RunFS(ctx context.Context, config *Config, wc *walkContext) ([]*extractor.Inventory, []*plugin.Status, error)

RunFS runs the specified extractors and returns their extraction results, as well as info about whether the plugin runs completed successfully. scanRoot is the location of fsys. This method is for testing, use Run() to avoid confusion with scanRoot vs fsys.

Types

type Config

type Config struct {
	Extractors []Extractor
	ScanRoots  []string
	FS         fs.FS
	// Optional: Individual files to extract inventory from. If specified, the
	// extractors will only look at these files during the filesystem traversal.
	// Note that these are not relative to the ScanRoots and thus need to be
	// sub-directories of one of the ScanRoots.
	FilesToExtract []string
	// Optional: Directories that the file system walk should ignore.
	// Note that these are not relative to the ScanRoots and thus need to be
	// sub-directories of one of the ScanRoots.
	// TODO(b/279413691): Also skip local paths, e.g. "Skip all .git dirs"
	DirsToSkip []string
	// Optional: If the regex matches a directory, it will be skipped.
	SkipDirRegex *regexp.Regexp
	// Optional: stats allows to enter a metric hook. If left nil, no metrics will be recorded.
	Stats stats.Collector
	// Optional: Whether to read symlinks.
	ReadSymlinks bool
	// Optional: Limit for visited inodes. If 0, no limit is applied.
	MaxInodes int
	// Optional: By default, inventories stores a path relative to the scan root. If StoreAbsolutePath
	// is set, the absolute path is stored instead.
	StoreAbsolutePath bool
}

Config stores the config settings for an extraction run.

type Extractor

type Extractor interface {
	extractor.Extractor
	// FileRequired should return true if the file described by path and file info is
	// relevant for the extractor.
	// Note that the plugin doesn't traverse the filesystem itself but relies on the core
	// library for that.
	FileRequired(path string, fileinfo fs.FileInfo) bool
	// Extract extracts inventory data relevant for the extractor from a given file.
	Extract(ctx context.Context, input *ScanInput) ([]*extractor.Inventory, error)
}

Extractor is the filesystem-based inventory extraction plugin, used to extract inventory data from the filesystem such as OS and language packages.

type ScanInput

type ScanInput struct {
	// The path of the file to extract, relative to ScanRoot.
	Path string
	// The root directory where the extraction file walking started from.
	ScanRoot string
	Info     fs.FileInfo
	// A reader for accessing contents of the file.
	// Note that the file is closed by the core library, not the plugin.
	Reader io.Reader
}

ScanInput describes one file to extract from.