reader

Documentation

Overview

Package reader implements reading contents of a CIPD package.

Index

• Variables
• func CalculatePin(ctx context.Context, src pkg.Source, algo api.HashAlgo) (common.Pin, error)
• func ExtractFiles(ctx context.Context, files []fs.File, dest fs.Destination, maxThreads int, ...) (extracted []pkg.FileInfo, err error)
• func ExtractFilesTxn(ctx context.Context, files []fs.File, dest fs.TransactionalDestination, ...) (extracted []pkg.FileInfo, err error)
• func IsCorruptionError(err error) bool
• func OpenInstance(ctx context.Context, r pkg.Source, opts OpenInstanceOpts) (pkg.Instance, error)
• func OpenInstanceFile(ctx context.Context, path string, opts OpenInstanceOpts) (pkg.Instance, error)
• type OpenInstanceOpts
• type VerificationMode
  • func (v VerificationMode) String() string

Variables

var ErrHashMismatch = errors.New("package hash mismatch", cipderr.HashMismatch)

ErrHashMismatch is an error when package hash doesn't match.

Functions

func CalculatePin

func CalculatePin(ctx context.Context, src pkg.Source, algo api.HashAlgo) (common.Pin, error)

CalculatePin returns a pin that represents the package.

It reads the package name from the manifest inside, and calculates package's hash to get instance ID.

func ExtractFiles

func ExtractFiles(ctx context.Context, files []fs.File, dest fs.Destination, maxThreads int, withManifest pkg.ManifestMode, overrideInstallMode pkg.InstallMode) (extracted []pkg.FileInfo, err error)

ExtractFiles extracts all given files into a destination, with a progress report.

This function has intimate understanding of specifics of CIPD packages, such as manifest files and .cipdpkg/* directory, thus it should be used only when extracting files from CIPD packages.

If withManifest is WithManifest, the manifest file is required to be among 'files'. It will be extended with information about extracted files and placed into the destination. Note that it will *not* be included into 'extracted' slice.

If withManifest is WithoutManifest, the function will fail if the manifest is among 'files' (as a precaution against unintended override of manifests).

func ExtractFilesTxn

func ExtractFilesTxn(ctx context.Context, files []fs.File, dest fs.TransactionalDestination, maxThreads int, withManifest pkg.ManifestMode, overrideInstallMode pkg.InstallMode) (extracted []pkg.FileInfo, err error)

ExtractFilesTxn is like ExtractFiles, but it also opens and closes the transaction over fs.TransactionalDestination object.

It guarantees that if extraction fails for some reason, there'll be no garbage laying around.

func IsCorruptionError

func IsCorruptionError(err error) bool

IsCorruptionError returns true iff err indicates corruption.

func OpenInstance

func OpenInstance(ctx context.Context, r pkg.Source, opts OpenInstanceOpts) (pkg.Instance, error)

OpenInstance opens a package instance by reading it from the given source.

The caller is responsible for closing the instance when done with it.

On success it takes ownership of the source, closing it when the instance itself is closed. On errors the source is left open. It's a responsibility of the caller to close it in this case.

func OpenInstanceFile

func OpenInstanceFile(ctx context.Context, path string, opts OpenInstanceOpts) (pkg.Instance, error)

OpenInstanceFile opens a package instance by reading it from a file on disk.

The caller is responsible for closing the instance when done with it. This will close the underlying file too.

Types

type OpenInstanceOpts

type OpenInstanceOpts struct {
	// VerificationMode specifies what to do with the hash of the instance file.
	//
	// Passing VerifyHash instructs OpenPackage to calculate the hash of the
	// instance file using the hash algorithm matching InstanceID, and then
	// compare the resulting digest to InstanceID, failing on mismatch with
	// ErrHashMismatch. HashAlgo is ignored in this case and should be 0.
	//
	// Passing SkipHashVerification instructs OpenPackage to unconditionally
	// trust the given InstanceID. HashAlgo is also ignored in this case and
	// should be 0.
	//
	// Passing CalculateHash instructs OpenPackage to calculate the hash of the
	// instance file using the given HashAlgo, and use the resulting digest
	// as an instance ID of the new pkg.Instance object. InstanceID is ignored
	// in this case and should be "".
	VerificationMode VerificationMode

	// InstanceID encodes the expected hash of the instance file.
	//
	// May be empty. See the comment for VerificationMode for more details.
	InstanceID string

	// HashAlgo specifies what hashing algorithm to use for computing instance ID.
	//
	// May be empty. See the comment for VerificationMode for more details.
	HashAlgo api.HashAlgo
}

OpenInstanceOpts is passed to OpenInstance and OpenInstanceFile.

type VerificationMode

type VerificationMode int

VerificationMode defines whether to verify hash or not.

const (
	// VerifyHash instructs OpenPackage to calculate the hash of the package file
	// and compare it to the given InstanceID.
	VerifyHash VerificationMode = iota

	// SkipHashVerification instructs OpenPackage to skip the hash verification
	// and trust that the given InstanceID matches the package.
	SkipHashVerification

	// CalculateHash instructs OpenPackage to calculate the hash of the package
	// file using the given hash algo, and use it as a new instance ID.
	CalculateHash
)

func (VerificationMode) String

func (v VerificationMode) String() string