go-mtree – github.com/vbatts/go-mtree Index | Examples | Files | Directories

package mtree

import "github.com/vbatts/go-mtree"

Index

Examples

Constants 

const DefaultVisFlags govis.VisFlag = govis.VisWhite | govis.VisOctal | govis.VisGlob

DefaultVisFlags is the set of Vis flags used when encoding filenames and other similar entries.

Variables 

var (
	// DefaultKeywords has the several default keyword producers (uid, gid,
	// mode, nlink, type, size, mtime)
	DefaultKeywords = []Keyword{
		"size",
		"type",
		"uid",
		"gid",
		"mode",
		"link",
		"nlink",
		"time",
	}

	// DefaultTarKeywords has keywords that should be used when creating a manifest from
	// an archive. Currently, evaluating the # of hardlinks has not been implemented yet
	DefaultTarKeywords = []Keyword{
		"size",
		"type",
		"uid",
		"gid",
		"mode",
		"link",
		"tar_time",
	}

	// BsdKeywords is the set of keywords that is only in the upstream FreeBSD mtree
	BsdKeywords = []Keyword{
		"cksum",
		"flags",
		"ignore",
		"gid",
		"gname",
		"link",
		"md5",
		"md5digest",
		"mode",
		"nlink",
		"nochange",
		"optional",
		"ripemd160digest",
		"rmd160",
		"rmd160digest",
		"sha1",
		"sha1digest",
		"sha256",
		"sha256digest",
		"sha384",
		"sha384digest",
		"sha512",
		"sha512digest",
		"size",
		"tags",
		"time",
		"type",
		"uid",
		"uname",
	}

	// SetKeywords is the default set of keywords calculated for a `/set` SpecialType
	SetKeywords = []Keyword{
		"uid",
		"gid",
	}
)
var DefaultUpdateKeywords = []Keyword{
	"uid",
	"gid",
	"mode",
	"xattr",
	"link",
	"time",
}

DefaultUpdateKeywords is the default set of keywords that can take updates to the files on disk 

var ExcludeNonDirectories = func(path string, info os.FileInfo) bool {
	return !info.IsDir()
}

ExcludeNonDirectories is an ExcludeFunc for excluding all paths that are not directories 

var (
	// KeywordFuncs is the map of all keywords (and the functions to produce them)
	KeywordFuncs = map[Keyword]KeywordFunc{
		"size":            sizeKeywordFunc,
		"type":            typeKeywordFunc,
		"time":            timeKeywordFunc,
		"link":            linkKeywordFunc,
		"uid":             uidKeywordFunc,
		"gid":             gidKeywordFunc,
		"nlink":           nlinkKeywordFunc,
		"uname":           unameKeywordFunc,
		"gname":           gnameKeywordFunc,
		"mode":            modeKeywordFunc,
		"cksum":           cksumKeywordFunc,
		"md5":             hasherKeywordFunc("md5digest", md5.New),
		"md5digest":       hasherKeywordFunc("md5digest", md5.New),
		"rmd160":          hasherKeywordFunc("ripemd160digest", ripemd160.New),
		"rmd160digest":    hasherKeywordFunc("ripemd160digest", ripemd160.New),
		"ripemd160digest": hasherKeywordFunc("ripemd160digest", ripemd160.New),
		"sha1":            hasherKeywordFunc("sha1digest", sha1.New),
		"sha1digest":      hasherKeywordFunc("sha1digest", sha1.New),
		"sha256":          hasherKeywordFunc("sha256digest", sha256.New),
		"sha256digest":    hasherKeywordFunc("sha256digest", sha256.New),
		"sha384":          hasherKeywordFunc("sha384digest", sha512.New384),
		"sha384digest":    hasherKeywordFunc("sha384digest", sha512.New384),
		"sha512":          hasherKeywordFunc("sha512digest", sha512.New),
		"sha512digest":    hasherKeywordFunc("sha512digest", sha512.New),
		"sha512256":       hasherKeywordFunc("sha512digest", sha512.New512_256),
		"sha512256digest": hasherKeywordFunc("sha512digest", sha512.New512_256),

		"flags": flagsKeywordFunc,

		"tar_time": tartimeKeywordFunc,

		"xattr":  xattrKeywordFunc,
		"xattrs": xattrKeywordFunc,
	}
)
var UpdateKeywordFuncs = map[Keyword]UpdateKeywordFunc{
	"mode":     modeUpdateKeywordFunc,
	"time":     timeUpdateKeywordFunc,
	"tar_time": tartimeUpdateKeywordFunc,
	"uid":      uidUpdateKeywordFunc,
	"gid":      gidUpdateKeywordFunc,
	"xattr":    xattrUpdateKeywordFunc,
	"link":     linkUpdateKeywordFunc,
}

UpdateKeywordFuncs is the registered list of functions to update file attributes. Keyed by the keyword as it would show up in the manifest

Functions

func CleanPath 

func CleanPath(path string) string

CleanPath makes a path safe for use with filepath.Join. This is done by not only cleaning the path, but also (if the path is relative) adding a leading '/' and cleaning it (then removing the leading '/'). This ensures that a path resulting from prepending another path will always resolve to lexically be a subdirectory of the prefixed path. This is all done lexically, so paths that include symlinks won't be safe as a result of using CleanPath.

This code was copied from runc/libcontainer/utils/utils.go. It was originally written by myself, so I am dual-licensing it for the purpose of this project.

func FromKeywords 

func FromKeywords(list []Keyword) []string

FromKeywords makes a list of string from a list of Keyword

func InKeywordSlice 

func InKeywordSlice(a Keyword, list []Keyword) bool

InKeywordSlice checks for the presence of `a` in `list`

func KeyValToString 

func KeyValToString(list []KeyVal) []string

KeyValToString constructs a list of string from the list of KeyVal

Types

type DefaultFsEval 

type DefaultFsEval struct{}

DefaultFsEval is the default implementation of FsEval (and is the default used if a nil interface is passed to any mtree function). It does not modify or wrap any of the methods (they all just call out to os.*).

func (DefaultFsEval) KeywordFunc 

func (fs DefaultFsEval) KeywordFunc(fn KeywordFunc) KeywordFunc

KeywordFunc must return a wrapper around the provided function (in other words, the returned function must refer to the same keyword).

func (DefaultFsEval) Lstat 

func (fs DefaultFsEval) Lstat(path string) (os.FileInfo, error)

Lstat must have the same semantics as os.Lstat.

func (DefaultFsEval) Open 

func (fs DefaultFsEval) Open(path string) (*os.File, error)

Open must have the same semantics as os.Open.

func (DefaultFsEval) Readdir 

func (fs DefaultFsEval) Readdir(path string) ([]os.FileInfo, error)

Readdir must have the same semantics as calling os.Open on the given path and then returning the result of (*os.File).Readdir(-1).

type DifferenceType 

type DifferenceType string

DifferenceType represents the type of a discrepancy encountered for an object. This is also used to represent discrepancies between keys for objects. 

const (
	// Missing represents a discrepancy where the object is present in
	// the @old manifest but is not present in the @new manifest.
	Missing DifferenceType = "missing"

	// Extra represents a discrepancy where the object is not present in
	// the @old manifest but is present in the @new manifest.
	Extra DifferenceType = "extra"

	// Modified represents a discrepancy where the object is present in
	// both the @old and @new manifests, but one or more of the keys
	// have different values (or have not been set in one of the
	// manifests).
	Modified DifferenceType = "modified"

	// Same represents the case where two files are the same. These are
	// only generated from CompareSame().
	Same DifferenceType = "same"

	// ErrorDifference represents an attempted update to the values of
	// a keyword that failed
	ErrorDifference DifferenceType = "errored"
)

type DirectoryHierarchy 

type DirectoryHierarchy struct {
	Entries []Entry
}

DirectoryHierarchy is the mapped structure for an mtree directory hierarchy spec

func ParseSpec 

func ParseSpec(r io.Reader) (*DirectoryHierarchy, error)

ParseSpec reads a stream of an mtree specification, and returns the DirectoryHierarchy

func Walk 

func Walk(root string, excludes []ExcludeFunc, keywords []Keyword, fsEval FsEval) (*DirectoryHierarchy, error)

Walk from root directory and assemble the DirectoryHierarchy * `excludes` provided are used to skip paths * `keywords` are the set to collect from the walked paths. The recommended default list is DefaultKeywords. * `fsEval` is the interface to use in evaluating files. If `nil`, then DefaultFsEval is used.

func (DirectoryHierarchy) UsedKeywords 

func (dh DirectoryHierarchy) UsedKeywords() []Keyword

UsedKeywords collects and returns all the keywords used in a a DirectoryHierarchy

func (DirectoryHierarchy) WriteTo 

func (dh DirectoryHierarchy) WriteTo(w io.Writer) (n int64, err error)

WriteTo simplifies the output of the resulting hierarchy spec

type Entry 

type Entry struct {
	Parent     *Entry   // up
	Children   []*Entry // down
	Prev, Next *Entry   // left, right
	Set        *Entry   // current `/set` for additional keywords
	Pos        int      // order in the spec
	Raw        string   // file or directory name
	Name       string   // file or directory name
	Keywords   []KeyVal // TODO(vbatts) maybe a keyword typed set of values?
	Type       EntryType
}

Entry is each component of content in the mtree spec file

func (Entry) AllKeys 

func (e Entry) AllKeys() []KeyVal

AllKeys returns the full set of KeyVal for the given entry, based on the /set keys as well as the entry-local keys. Entry-local keys always take precedence.

func (Entry) Ascend 

func (e Entry) Ascend() *Entry

Ascend gets the parent of an Entry. Serves mainly to maintain readability when traversing up and down an Entry tree

func (Entry) Descend 

func (e Entry) Descend(filename string) *Entry

Descend searches thru an Entry's children to find the Entry associated with `filename`. Directories are stored at the end of an Entry's children so do a traverse backwards. If you descend to a "."

func (Entry) Find 

func (e Entry) Find(filepath string) *Entry

Find is a wrapper around Descend that takes in a whole string path and tries to find that Entry

func (Entry) IsDir 

func (e Entry) IsDir() bool

IsDir checks the type= value for this entry on whether it is a directory

func (Entry) Path 

func (e Entry) Path() (string, error)

Path provides the full path of the file, despite RelativeType or FullType. It will be in Unvis'd form.

func (Entry) String 

func (e Entry) String() string

String joins a file with its associated keywords. The file name will be the Vis'd encoded version so that it can be parsed appropriately when Check'd.

type EntryType 

type EntryType int

EntryType are the formats of lines in an mtree spec file 

const (
	SignatureType EntryType = iota // first line of the file, like `#mtree v2.0`
	BlankType                      // blank lines are ignored
	CommentType                    // Lines beginning with `#` are ignored
	SpecialType                    // line that has `/` prefix issue a "special" command (currently only /set and /unset)
	RelativeType                   // if the first white-space delimited word does not have a '/' in it. Options/keywords are applied.
	DotDotType                     // .. - A relative path step. keywords/options are ignored
	FullType                       // if the first word on the line has a `/` after the first character, it interpretted as a file pathname with options
)

The types of lines to be found in an mtree spec file

func (EntryType) String 

func (et EntryType) String() string

String returns the name of the EntryType

type ExcludeFunc 

type ExcludeFunc func(path string, info os.FileInfo) bool

ExcludeFunc is the type of function called on each path walked to determine whether to be excluded from the assembled DirectoryHierarchy. If the func returns true, then the path is not included in the spec.

type FsEval 

type FsEval interface {
	// Open must have the same semantics as os.Open.
	Open(path string) (*os.File, error)

	// Lstat must have the same semantics as os.Lstat.
	Lstat(path string) (os.FileInfo, error)

	// Readdir must have the same semantics as calling os.Open on the given
	// path and then returning the result of (*os.File).Readdir(-1).
	Readdir(path string) ([]os.FileInfo, error)

	// KeywordFunc must return a wrapper around the provided function (in other
	// words, the returned function must refer to the same keyword).
	KeywordFunc(fn KeywordFunc) KeywordFunc
}

FsEval is a mock-friendly method of specifying to go-mtree how to carry out filesystem operations such as opening files and the like. The semantics of all of these wrappers MUST be identical to the semantics described here.

type InodeDelta 

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

InodeDelta Represents a discrepancy in a filesystem object between two DirectoryHierarchy manifests. Discrepancies are caused by entries only present in one manifest [Missing, Extra], keys only present in one of the manifests Modified or a difference between the keys of the same object in both manifests Modified.

func Check 

func Check(root string, dh *DirectoryHierarchy, keywords []Keyword, fs FsEval) ([]InodeDelta, error)

Check a root directory path against the DirectoryHierarchy, regarding only the available keywords from the list and each entry in the hierarchy. If keywords is nil, the check all present in the DirectoryHierarchy

This is equivalent to creating a new DirectoryHierarchy with Walk(root, nil, keywords, fs) and then doing a Compare(dh, newDh, keywords).

Example

Code: 

{
	dh, err := Walk(".", nil, append(DefaultKeywords, "sha1"), nil)
	if err != nil {
		// handle error ...
	}

	res, err := Check(".", dh, nil, nil)
	if err != nil {
		// handle error ...
	}
	if len(res) > 0 {
		// handle failed validity ...
	}
}

func Compare 

func Compare(oldDh, newDh *DirectoryHierarchy, keys []Keyword) ([]InodeDelta, error)

Compare compares two directory hierarchy manifests, and returns the list of discrepancies between the two. All of the entries in the manifest are considered, with differences being generated for RelativeType and FullType entries. Differences in structure (such as the way /set and /unset are written) are not considered to be discrepancies. The list of differences are all filesystem objects.

keys controls which keys will be compared, but if keys is nil then all possible keys will be compared between the two manifests (allowing for missing entries and the like). A missing or extra key is treated as a Modified type.

If oldDh or newDh are empty, we assume they are a hierarchy that is completely empty. This is purely for helping callers create synthetic InodeDeltas.

NB: The order of the parameters matters (old, new) because Extra and 

Missing are considered as different discrepancy types.

func CompareSame 

func CompareSame(oldDh, newDh *DirectoryHierarchy, keys []Keyword) ([]InodeDelta, error)

CompareSame is the same as Compare, except it also includes the entries that are the same with a Same DifferenceType.

func Update 

func Update(root string, dh *DirectoryHierarchy, keywords []Keyword, fs FsEval) ([]InodeDelta, error)

Update attempts to set the attributes of root directory path, given the values of `keywords` in dh DirectoryHierarchy.

func (InodeDelta) Diff 

func (i InodeDelta) Diff() []KeyDelta

Diff returns the set of key discrepancies between the two manifests for the specific inode. If the DifferenceType of the inode is not Modified, then Diff returns nil.

func (InodeDelta) MarshalJSON 

func (i InodeDelta) MarshalJSON() ([]byte, error)

MarshalJSON creates a JSON-encoded version of InodeDelta.

func (InodeDelta) New 

func (i InodeDelta) New() *Entry

New returns the value of the inode Entry in the "new" DirectoryHierarchy (as determined by the ordering of parameters to Compare).

func (InodeDelta) Old 

func (i InodeDelta) Old() *Entry

Old returns the value of the inode Entry in the "old" DirectoryHierarchy (as determined by the ordering of parameters to Compare).

func (InodeDelta) Path 

func (i InodeDelta) Path() string

Path returns the path to the inode (relative to the root of the DirectoryHierarchy manifests).

func (InodeDelta) String 

func (i InodeDelta) String() string

String returns a "pretty" formatting for InodeDelta.

func (InodeDelta) Type 

func (i InodeDelta) Type() DifferenceType

Type returns the type of discrepancy encountered when comparing this inode between the two DirectoryHierarchy manifests.

type KeyDelta 

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

KeyDelta Represents a discrepancy in a key for a particular filesystem object between two DirectoryHierarchy manifests. Discrepancies are caused by keys only present in one manifest [Missing, Extra] or a difference between the keys of the same object in both manifests Modified. A set of these is returned with InodeDelta.Diff().

func (KeyDelta) MarshalJSON 

func (k KeyDelta) MarshalJSON() ([]byte, error)

MarshalJSON creates a JSON-encoded version of KeyDelta.

func (KeyDelta) Name 

func (k KeyDelta) Name() Keyword

Name returns the name (the key) of the KeyDeltaVal entry in the DirectoryHierarchy.

func (KeyDelta) New 

func (k KeyDelta) New() *string

New returns the value of the KeyDeltaVal entry in the "new" DirectoryHierarchy (as determined by the ordering of parameters to Compare). Returns nil if there was no entry in the "new" DirectoryHierarchy.

func (KeyDelta) Old 

func (k KeyDelta) Old() *string

Old returns the value of the KeyDeltaVal entry in the "old" DirectoryHierarchy (as determined by the ordering of parameters to Compare). Returns nil if there was no entry in the "old" DirectoryHierarchy.

func (KeyDelta) Type 

func (k KeyDelta) Type() DifferenceType

Type returns the type of discrepancy encountered when comparing this key between the two DirectoryHierarchy manifests' relevant inode entry.

type KeyVal 

type KeyVal string

KeyVal is a "keyword=value"

func Has 

func Has(keyvals []KeyVal, keyword string) []KeyVal

Has the "keyword" present in the list of KeyVal, and returns the corresponding KeyVal, else an empty string.

func HasKeyword 

func HasKeyword(keyvals []KeyVal, keyword Keyword) []KeyVal

HasKeyword the "keyword" present in the list of KeyVal, and returns the corresponding KeyVal, else an empty string. This match is done on the Prefix of the keyword only.

func MergeKeyValSet 

func MergeKeyValSet(setKeyVals, entryKeyVals []KeyVal) []KeyVal

MergeKeyValSet does a merge of the two sets of KeyVal, and the KeyVal of entryKeyVals win when there is a duplicate Keyword.

func MergeSet 

func MergeSet(setKeyVals, entryKeyVals []string) []KeyVal

MergeSet takes the current setKeyVals, and then applies the entryKeyVals such that the entry's values win. The union is returned.

func StringToKeyVals 

func StringToKeyVals(list []string) []KeyVal

StringToKeyVals constructs a list of KeyVal from the list of strings, like "keyword=value"

func (KeyVal) Equal 

func (kv KeyVal) Equal(b KeyVal) bool

Equal returns whether two KeyVal are equivalent. This takes care of certain odd cases such as tar_mtime, and should be used over using == comparisons directly unless you really know what you're doing.

func (KeyVal) Keyword 

func (kv KeyVal) Keyword() Keyword

Keyword is the mapping to the available keywords

func (KeyVal) NewValue 

func (kv KeyVal) NewValue(newval string) KeyVal

NewValue returns a new KeyVal with the newval

func (KeyVal) Value 

func (kv KeyVal) Value() string

Value is the data/value portion of "keyword=value"

type Keyword 

type Keyword string

Keyword is the string name of a keyword, with some convenience functions for determining whether it is a default or bsd standard keyword. It first portion before the "="

func KeywordSynonym 

func KeywordSynonym(name string) Keyword

KeywordSynonym returns the canonical name for keywords that have synonyms, and just returns the name provided if there is no synonym. In this way it ought to be safe to wrap any keyword name.

func ToKeywords 

func ToKeywords(list []string) []Keyword

ToKeywords makes a list of Keyword from a list of string

func (Keyword) Bsd 

func (k Keyword) Bsd() bool

Bsd returns whether this keyword is in the upstream FreeBSD mtree(8)

func (Keyword) Default 

func (k Keyword) Default() bool

Default returns whether this keyword is in the default set of keywords

func (Keyword) Prefix 

func (k Keyword) Prefix() Keyword

Prefix is the portion of the keyword before a first "." (if present).

Primarily for the xattr use-case, where the keyword `xattr.security.selinux` would have a Suffix of `security.selinux`.

func (Keyword) Suffix 

func (k Keyword) Suffix() string

Suffix is the portion of the keyword after a first ".". This is an option feature.

Primarily for the xattr use-case, where the keyword `xattr.security.selinux` would have a Suffix of `security.selinux`.

func (Keyword) Synonym 

func (k Keyword) Synonym() Keyword

Synonym returns the canonical name for this keyword. This is provides the same functionality as KeywordSynonym()

type KeywordFunc 

type KeywordFunc func(path string, info os.FileInfo, r io.Reader) ([]KeyVal, error)

KeywordFunc is the type of a function called on each file to be included in a DirectoryHierarchy, that will produce the string output of the keyword to be included for the file entry. Otherwise, empty string. io.Reader `r` is to the file stream for the file payload. While this function takes an io.Reader, the caller needs to reset it to the beginning for each new KeywordFunc

type Streamer 

type Streamer interface {
	io.ReadCloser
	Hierarchy() (*DirectoryHierarchy, error)
}

Streamer creates a file hierarchy out of a tar stream

Example

Code: 

{
	fh, err := os.Open("./testdata/test.tar")
	if err != nil {
		// handle error ...
	}
	str := NewTarStreamer(fh, nil, nil)
	if err := extractTar("/tmp/dir", str); err != nil {
		// handle error ...
	}

	dh, err := str.Hierarchy()
	if err != nil {
		// handle error ...
	}

	res, err := Check("/tmp/dir/", dh, nil, nil)
	if err != nil {
		// handle error ...
	}
	if len(res) > 0 {
		// handle validation issue ...
	}
}

func NewTarStreamer 

func NewTarStreamer(r io.Reader, excludes []ExcludeFunc, keywords []Keyword) Streamer

NewTarStreamer streams a tar archive and creates a file hierarchy based off of the tar metadata headers

type UpdateKeywordFunc 

type UpdateKeywordFunc func(path string, kv KeyVal) (os.FileInfo, error)

UpdateKeywordFunc is the signature for a function that will restore a file's attributes. Where path is relative path to the file, and value to be restored to.

Source Files

check.go cksum.go compare.go creator.go entry.go fseval.go hierarchy.go keywordfunc.go keywordfuncs_unsupported.go keywords.go lookup.go parse.go stat_unix.go tar.go update.go updatefuncs.go updatefuncs_unsupported.go walk.go

Directories

PathSynopsis
cmd
cmd/gomtree
cmd/gomtree/cmd
pkg
pkg/govis
test
test/cli-test
test/realpath
xattr
Version
v0.5.4 (latest)
Published
Jun 11, 2024
Platform
js/wasm
Imports
22 packages
Last checked
now –

Tools for package owners.