deployer

Documentation

Overview

Package deployer holds functionality for deploying CIPD packages.

Index

• type DeployedPackage
• type Deployer
  • func New(root string) Deployer
• type ParanoidMode
  • func (p ParanoidMode) Validate() error
• type RepairParams

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 pkg.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 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"

	// CheckIntegrity indicates that CIPD client should verify all files installed
	// in the site root have correct content (based on their hashes).
	//
	// CIPD will use information from 'stat' to skip rechecking hashes all the
	// time. Only files modified (based on 'stat') since they were installed are
	// checked.
	CheckIntegrity ParanoidMode = "CheckIntegrity"
)

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
}

RepairParams is passed to RepairDeployed.