deployer

Documentation

Overview

Package deployer holds functionality for deploying CIPD packages.

Index

• Variables
• func ExtractFiles(ctx context.Context, files []fs.File, dest fs.Destination, ...) error
• func ExtractFilesTxn(ctx context.Context, files []fs.File, dest fs.TransactionalDestination, ...) (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 DeployedPackage
• type Deployer
  • func New(root string) Deployer
• type ManifestMode
• type OpenInstanceOpts
• type ParanoidMode
  • func (p ParanoidMode) Validate() error
• type RepairParams
• type VerificationMode

Variables

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

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

Functions

func ExtractFiles

func ExtractFiles(ctx context.Context, files []fs.File, dest fs.Destination, withManifest ManifestMode) 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.

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, withManifest ManifestMode) (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 DeployedPackage

type DeployedPackage struct {
	Deployed    bool            // true if the package is deployed (perhaps partially)
	Pin         common.Pin      // the currently installed pin
	Subdir      string          // the site subdirectory where the package is installed
	Manifest    *pkg.Manifest   // instance's manifest, if available
	InstallMode pkg.InstallMode // validated install mode, if available

	// ToRedeploy is a list of files that needs to be reextracted from the
	// original package and relinked into the site root.
	ToRedeploy []string

	// ToRelink is a list of files that needs to be relinked into the site root.
	//
	// They are already present in the .cipd/* guts, so there's no need to fetch
	// the original package to get them.
	ToRelink []string
	// contains filtered or unexported fields
}

DeployedPackage represents a state of the deployed (or partially deployed) package, as returned by CheckDeployed.

ToRedeploy is populated only when CheckDeployed is called in a paranoid mode, and the package needs repairs.

type Deployer

type Deployer interface {
	// DeployInstance installs an instance of a package into the given subdir of
	// the root.
	//
	// It unpacks the package into <base>/.cipd/pkgs/*, and rearranges
	// symlinks to point to unpacked files. It tries to make it as "atomic" as
	// possible. Returns information about the deployed instance.
	//
	// Due to a historical bug, if inst contains any files which are intended to
	// be deployed to `.cipd/*`, they will not be extracted and you'll see
	// warnings logged.
	DeployInstance(ctx context.Context, subdir string, inst pkg.Instance) (common.Pin, error)

	// CheckDeployed checks whether a given package is deployed at the given
	// subdir.
	//
	// Returns an error if it can't check the package state for some reason.
	// Otherwise returns the state of the package. In particular, if the package
	// is not deployed, returns DeployedPackage{Deployed: false}.
	//
	// Depending on the paranoia mode will also verify that package's files are
	// correctly installed into the site root and will return a list of files
	// that needs to be redeployed (as part of DeployedPackage).
	//
	// If manifest is set to WithManifest, will also fetch and return the instance
	// manifest and install mode. This is optional, since not all callers need it,
	// and it is pretty heavy operation. Any paranoid mode implies WithManifest
	// too.
	CheckDeployed(ctx context.Context, subdir, packageName string, paranoia ParanoidMode, manifest ManifestMode) (*DeployedPackage, error)

	// FindDeployed returns a list of packages deployed to a site root.
	//
	// It just does a shallow examination of the metadata directory, without
	// paranoid checks that all installed packages are free from corruption.
	FindDeployed(ctx context.Context) (out common.PinSliceBySubdir, err error)

	// RemoveDeployed deletes a package from a subdir given its name.
	RemoveDeployed(ctx context.Context, subdir, packageName string) error

	// RepairDeployed attempts to restore broken deployed instance.
	//
	// Use CheckDeployed first to figure out what parts of the package need
	// repairs.
	//
	// 'pin' indicates an instances that is supposed to be installed in the given
	// subdir. If there's no such package there or its version is different from
	// the one specified in the pin, returns an error.
	RepairDeployed(ctx context.Context, subdir string, pin common.Pin, params RepairParams) error

	// TempFile returns os.File located in <base>/.cipd/tmp/*.
	//
	// The file is open for reading and writing.
	TempFile(ctx context.Context, prefix string) (*os.File, error)

	// CleanupTrash attempts to remove stale files.
	//
	// This is a best effort operation. Errors are logged (either at Debug or
	// Warning level, depending on severity of the trash state).
	CleanupTrash(ctx context.Context)
}

Deployer knows how to unzip and place packages into site root directory.

func New

func New(root string) Deployer

New return default Deployer implementation.

type ManifestMode

type ManifestMode bool

ManifestMode is used to indicate presence of absence of manifest when calling various functions.

Just to improve code readability, since Func(..., WithManifest) is less cryptic than Func(..., true).

const (
	// WithoutManifest indicates the function should skip manifest.
	WithoutManifest ManifestMode = false
	// WithManifest indicates the function should handle manifest.
	WithManifest ManifestMode = true
)

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 ParanoidMode

type ParanoidMode string

ParanoidMode specifies how paranoid CIPD client should be.

const (
	// NotParanoid indicates that CIPD client should trust its metadata
	// directory: if a package is marked as installed there, it should be
	// considered correctly installed in the site root too.
	NotParanoid ParanoidMode = "NotParanoid"

	// CheckPresence indicates that CIPD client should verify all files
	// that are supposed to be installed into the site root are indeed present
	// there.
	//
	// Note that it will not check file's content or file mode. Only its presence.
	CheckPresence ParanoidMode = "CheckPresence"
)

func (ParanoidMode) Validate

func (p ParanoidMode) Validate() error

Validate returns an error if the mode is unrecognized.

type RepairParams

type RepairParams struct {
	// Instance holds the original package data.
	//
	// Must be present if ToRedeploy is not empty. Otherwise not used.
	Instance pkg.Instance

	// ToRedeploy is a list of files that needs to be extracted from the instance
	// and relinked into the site root.
	ToRedeploy []string

	// ToRelink is a list of files that just needs to be relinked into the site
	// root.
	ToRelink []string
}

RepairsParams is passed to RepairDeployed.

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 = 0

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

	// 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 VerificationMode = 2
)