archive

Documentation

Index

• Constants
• func AddMountInclusionsExclusions(currentMount string, filter *FilterSpec, mounts []string, copyTarget string) error
• func CanonicalTarNameForPath(p string) (string, error)
• func Clean(path string, leading bool) string
• func Diff(op trace.Operation, newDir, oldDir string, spec *FilterSpec, data bool, ...) (io.ReadCloser, error)
• func DockerUnpack(op trace.Operation, root string, tarStream io.Reader) (int64, error)
• func EncodeFilterSpec(op trace.Operation, spec *FilterSpec) (*string, error)
• func MultiReader(readers ...io.Reader) io.ReadCloser
• func OfflineUnpack(op trace.Operation, tarStream io.Reader, filter *FilterSpec, root string) error
• func OnlineUnpack(op trace.Operation, tarStream io.Reader, filter *FilterSpec, root string) (*exec.Cmd, error)
• func Tar(op trace.Operation, dir string, changes []docker.Change, spec *FilterSpec, ...) (io.ReadCloser, error)
• func UnpackNoChroot(op trace.Operation, tarStream io.Reader, filter *FilterSpec, root string) error
• type Archiver
• type CancelNotifyKey
• type FilterSpec
  • func CreateFilterSpec(op trace.Operation, spec map[string]FilterType) (*FilterSpec, error)
  • func DecodeFilterSpec(op trace.Operation, spec *string) (*FilterSpec, error)
  • func GenerateFilterSpec(copyPath string, mountPoint string, primaryTarget bool, direction bool) FilterSpec
  • func (spec *FilterSpec) Excludes(op trace.Operation, filePath string) bool
• type FilterType
• type Stripper
  • func NewStripper(op trace.Operation, reader *tar.Reader, close func() error) *Stripper
  • func (s *Stripper) Close() error
  • func (s *Stripper) Read(b []byte) (int, error)
  • func (s *Stripper) WriteTo(w io.Writer) (sum int64, err error)

Constants

const (
	// Include specifies a path inclusion.
	// Note: An included path that sits under an excluded path should be included.
	// Example: if / is excluded, and /files is included, /files should  be added to the archive.
	Include = iota
	// Exclude specifies a path exclusion.
	Exclude
	// Rebase specifies a path rebase.
	// The rebase path is prepended to the path in the archive header.
	// for an Export this will ensure proper headers on the way out.
	// for an Import it will ensure that the tar unpacking occurs in
	// right location
	Rebase
	// Strip specifies a path strip.
	// The inverse of a rebase, the path is stripped from the header path
	// before writing to disk.
	Strip
)

const (
	// CopyTo is used to indicate that the desired filter spec is for a CopyTo direction
	CopyTo = true

	// CopyFrom is used to indicate that the desired filter spec is for the CopyFrom direction
	CopyFrom = false
)

const (
	// ChangeTypeKey defines the key for the type of diff change stored in the tar Xattrs header
	ChangeTypeKey = "change_type"
)

Functions

func AddMountInclusionsExclusions

func AddMountInclusionsExclusions(currentMount string, filter *FilterSpec, mounts []string, copyTarget string) error

func CanonicalTarNameForPath

func CanonicalTarNameForPath(p string) (string, error)

CanonicalTarNameForPath returns platform-specific filepath to canonical posix-style path for tar archival. p is relative path.

func Clean

func Clean(path string, leading bool) string

Clean run filepath.Clean on the target and will remove leading and trailing slashes from the target path corresponding to supplied booleans

func Diff

func Diff(op trace.Operation, newDir, oldDir string, spec *FilterSpec, data bool, xattr bool) (io.ReadCloser, error)

Diff produces a tar archive containing the differences between two filesystems

func DockerUnpack

func DockerUnpack(op trace.Operation, root string, tarStream io.Reader) (int64, error)

func EncodeFilterSpec

func EncodeFilterSpec(op trace.Operation, spec *FilterSpec) (*string, error)

Encode the filter spec

func MultiReader

func MultiReader(readers ...io.Reader) io.ReadCloser

MultiReader is based off the io.MultiReader but will make use of WriteTo or ReadFrom delegation and ONLY supports usage via the WriteTo method on itself. It is specifically intended to be passed to io.Copy

func OfflineUnpack

func OfflineUnpack(op trace.Operation, tarStream io.Reader, filter *FilterSpec, root string) error

OfflineUnpack wraps Unpack for usage in contexts without a childReaper, namely when copying to an offline container with docker cp

func OnlineUnpack

func OnlineUnpack(op trace.Operation, tarStream io.Reader, filter *FilterSpec, root string) (*exec.Cmd, error)

OnlineUnpack will extract a tar stream tarStream to folder root inside of a running container

func Tar

func Tar(op trace.Operation, dir string, changes []docker.Change, spec *FilterSpec, data bool, xattr bool) (io.ReadCloser, error)

func UnpackNoChroot

func UnpackNoChroot(op trace.Operation, tarStream io.Reader, filter *FilterSpec, root string) error

UnpackNoChroot will unpack the given tarstream(if it is a tar stream) on the local filesystem based on the specified root combined with any rebase from the path spec

the pathSpec will include the following elements - include : any tar entry that has a path below(after stripping) the include path will be written - strip : The strip string will indicate the - exlude : marks paths that are to be excluded from the write - rebase : marks the the write path that will be tacked onto (appended or prepended? TODO improve this comment) the "root". e.g /tmp/unpack + /my/target/path = /tmp/unpack/my/target/path N.B. tarStream MUST BE TERMINATED WITH EOF or this function will hang forever!

Types

type Archiver

type Archiver interface {

	// Export reads the delta between child and ancestor layers, returning
	// the difference as a tar archive.
	//
	// store - the store containing the two layers
	// id - must inherit from ancestor if ancestor is specified
	// ancestor - the old layer against which to diff. If omitted, the entire filesystem will be included
	// spec - describes filters on paths found in the data (include, exclude, rebase, strip)
	// data - include file data in the tar archive if true, headers only otherwise
	Export(op trace.Operation, store *url.URL, id, ancestor string, spec *FilterSpec, data bool) (io.ReadCloser, error)

	// Import will process the input tar stream based on the supplied path spec and write the stream to the
	// target device.
	//
	// store - the device store containing the target device
	// id - the id for the device that is contained within the store
	// spec - describes filters on paths found in the data (include, exclude, rebase, strip)
	// tarstream - the tar stream that is to be written to the target on the device
	Import(op trace.Operation, store *url.URL, id string, spec *FilterSpec, tarstream io.ReadCloser) error
}

Archiver defines an API for creating archives consisting of data that exist between a child and parent layer, as well as unpacking archives to container filesystems

type CancelNotifyKey

type CancelNotifyKey struct{}

CancelNotifyKey allows for a notification when cancelation is complete

type FilterSpec

type FilterSpec struct {
	Inclusions map[string]struct{}
	Exclusions map[string]struct{}
	RebasePath string
	StripPath  string
}

FilterSpec describes rules for handling specified paths during archival

func CreateFilterSpec

func CreateFilterSpec(op trace.Operation, spec map[string]FilterType) (*FilterSpec, error)

CreateFilterSpec creates a FilterSpec from a supplied map

func DecodeFilterSpec

func DecodeFilterSpec(op trace.Operation, spec *string) (*FilterSpec, error)

Decodes a base64 encoded string from EncodeFilterSpec into a FilterSpec

func GenerateFilterSpec

func GenerateFilterSpec(copyPath string, mountPoint string, primaryTarget bool, direction bool) FilterSpec

GenerateFilterSpec will populate the appropriate relative Rebase and Strip paths based on the supplied scenarios. Inclusion/Exclusion should be constructed separately. Please also note that any mount that exists before the copy target that is not primary and comes before the primary target will have a bogus filterspec, since it would not be written or read to.

func (*FilterSpec) Excludes

func (spec *FilterSpec) Excludes(op trace.Operation, filePath string) bool

Excludes returns true if the provided filter excludes the provided filepath If the spec is completely empty it will include everything. If an inclusion is set, but not exclusion, then we'll only return matches for the inclusions.

type FilterType

type FilterType int

FilterType specifies what type of filter to apply in a FilterSpec

type Stripper

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

Stripper strips the end-of-archive entries from a tar stream

func NewStripper

func NewStripper(op trace.Operation, reader *tar.Reader, close func() error) *Stripper

NewStripper returns a WriterTo that will strip the trailing end-of-archive bytes from the supplied tar stream. It implements io.Reader only so that it can be passed to io.Copy

func (*Stripper) Close

func (s *Stripper) Close() error

Close allows us to proxy a close on the stripper to the wrapped input

func (*Stripper) Read

func (s *Stripper) Read(b []byte) (int, error)

Read is implemented solely so this can be provided to io.Copy as an io.Reader. This works on the assumption of io.Copy making use of the WriterTo implementation.

func (*Stripper) WriteTo

func (s *Stripper) WriteTo(w io.Writer) (sum int64, err error)

WriteTo is the primary function, allowing easy use of the underlying tar stream without requiring chunking and assocated tracking to another buffer size. Of note is that this returns the number of DATA bytes written, excluding the header bytes.