cipd

package
v0.0.0-...-01cd1ea Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 21, 2024 License: Apache-2.0 Imports: 50 Imported by: 15

Documentation

Overview

Package cipd implements client side of Chrome Infra Package Deployer.

Binary package file format (in free form representation): 

<binary package> := <zipped data>
<zipped data> := DeterministicZip(<all input files> + <manifest json>)
<manifest json> := File{
  name: ".cipdpkg/manifest.json",
  data: JSON({
    "FormatVersion": "1",
    "PackageName": <name of the package>
  }),
}
DeterministicZip = zip archive with deterministic ordering of files and stripped timestamps

Main package data (<zipped data> above) is deterministic, meaning its content depends only on inputs used to built it (byte to byte): contents and names of all files added to the package (plus 'executable' file mode bit) and a package name (and all other data in the manifest).

Binary package data MUST NOT depend on a timestamp, hostname of machine that built it, revision of the source code it was built from, etc. All that information will be distributed as a separate metadata packet associated with the package when it gets uploaded to the server.

TODO: expand more when there's server-side package data model (labels and stuff).

Index

Constants

View Source 
const (
	// NotParanoid indicates that EnsurePackages 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 = deployer.NotParanoid

	// CheckPresence indicates that CheckDeployed should verify all files
	// that are supposed to be installed into the site root are indeed present
	// there, and reinstall ones that are missing.
	//
	// Note that it will not check file's content or file mode. Only its presence.
	CheckPresence = deployer.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 = deployer.CheckIntegrity
)
View Source 
const (
	// WithoutManifest indicates the function should skip manifest.
	WithoutManifest = pkg.WithoutManifest
	// WithManifest indicates the function should handle manifest.
	WithManifest = pkg.WithManifest
)
View Source 
const (
	// CASFinalizationTimeout is how long to wait for CAS service to finalize
	// the upload in RegisterInstance.
	CASFinalizationTimeout = 5 * time.Minute

	// SetRefTimeout is how long to wait for an instance to be processed when
	// setting a ref in SetRefWhenReady.
	SetRefTimeout = 3 * time.Minute

	// TagAttachTimeout is how long to wait for an instance to be processed when
	// attaching tags in AttachTagsWhenReady.
	TagAttachTimeout = 3 * time.Minute

	// MetadataAttachTimeout is how long to wait for an instance to be processed
	// when attaching metadata in AttachMetadataWhenReady.
	MetadataAttachTimeout = 3 * time.Minute

	// DefaultParallelDownloads is a default value for CIPD_PARALLEL_DOWNLOADS.
	//
	// See ParallelDownloads client option.
	DefaultParallelDownloads = 4
)
View Source 
const (
	EnvConfigFile          = "CIPD_CONFIG_FILE"
	EnvCacheDir            = "CIPD_CACHE_DIR"
	EnvHTTPUserAgentPrefix = "CIPD_HTTP_USER_AGENT_PREFIX"
	EnvMaxThreads          = "CIPD_MAX_THREADS"
	EnvParallelDownloads   = "CIPD_PARALLEL_DOWNLOADS"
	EnvAdmissionPlugin     = "CIPD_ADMISSION_PLUGIN"
	EnvCIPDServiceURL      = "CIPD_SERVICE_URL"
)

Environment variable definitions

Variables

View Source 
var (
	// ClientPackage is a package with the CIPD client. Used during self-update.
	ClientPackage = "infra/tools/cipd/${platform}"
	// UserAgent is HTTP user agent string for CIPD client.
	UserAgent = "cipd 2.6.18"
)

Functions

func DefaultConfigFilePath 

func DefaultConfigFilePath() string

DefaultConfigFilePath is path to the config to load by default.

func MaybeUpdateClient 

func MaybeUpdateClient(ctx context.Context, opts ClientOptions, targetVersion, clientExe string, digests *digests.ClientDigestsFile) (common.Pin, error)

MaybeUpdateClient will update the client binary at clientExe (given as a native path) to targetVersion if it's out of date (based on its hash).

This update is done from the "infra/tools/cipd/${platform}" package, see ClientPackage. The function will use the given ClientOptions to figure out how to establish a connection with the backend. Its Root and CacheDir values are ignored (values derived from clientExe are used instead).

If given 'digests' is not nil, will make sure the hash of the downloaded client binary is in 'digests'.

Note that this function make sense only in a context of a default CIPD CLI client. Other binaries that link to cipd package should not use it, they'll be "updated" to the CIPD client binary.

Types

type ActionError 

type ActionError struct {
	Action       ActionKind       `json:"action"`
	Pin          common.Pin       `json:"pin"`
	Error        JSONError        `json:"error,omitempty"`         // human readable message
	ErrorCode    cipderr.Code     `json:"error_code,omitempty"`    // enum with categories
	ErrorDetails *cipderr.Details `json:"error_details,omitempty"` // structured details
}

ActionError holds an error that happened when working on the pin.

type ActionKind 

type ActionKind string

ActionKind defines what is being done to a particular package. 

const (
	ActionRemove  ActionKind = "remove"  // package removal
	ActionRelink  ActionKind = "relink"  // restoration of broken symlinks
	ActionRepair  ActionKind = "repair"  // restoration of deleted files
	ActionInstall ActionKind = "install" // installation or upgrade
)

type ActionMap 

type ActionMap map[string]*Actions

ActionMap is a map of subdir to the Actions which will occur within it.

func (ActionMap) Empty 

func (am ActionMap) Empty() bool

Empty is true if ActionMap is empty.

func (ActionMap) Log 

func (am ActionMap) Log(ctx context.Context, verbose bool)

Log prints the pending action to the logger installed in ctx.

If verbose is true, prints filenames of files that need a repair.

type Actions 

type Actions struct {
	ToInstall common.PinSlice `json:"to_install,omitempty"` // pins to be installed
	ToUpdate  []UpdatedPin    `json:"to_update,omitempty"`  // pins to be replaced
	ToRemove  common.PinSlice `json:"to_remove,omitempty"`  // pins to be removed
	ToRepair  []BrokenPin     `json:"to_repair,omitempty"`  // pins to be repaired

	Errors []ActionError `json:"errors,omitempty"` // all individual errors
}

Actions lists what the cipd.Client should do or did to ensure the state of some single subdirectory under the installation root.

Is it part of a per-directory ActionMap returned by EnsurePackages.

func (*Actions) Empty 

func (a *Actions) Empty() bool

Empty is true if there are no actions specified.

type BrokenPin 

type BrokenPin struct {
	Pin        common.Pin `json:"pin"`
	RepairPlan RepairPlan `json:"repair_plan"`
}

BrokenPin specifies a pin that should be repaired and how.

type Client 

type Client interface {
	// Options is fully populated ClientOptions the client was created with.
	Options() ClientOptions

	// Close terminates plugins started by the client.
	//
	// Should be used to cleanly shutdown the client when using plugins.
	Close(ctx context.Context)

	// BeginBatch makes the client enter into a "batch mode".
	//
	// In this mode various cleanup and cache updates, usually performed right
	// away, are deferred until 'EndBatch' call.
	//
	// This is an optimization. Use it if you plan to call a bunch of Client
	// methods in a short amount of time (parallel or sequentially).
	//
	// Batches can be nested.
	BeginBatch(ctx context.Context)

	// EndBatch ends a batch started with BeginBatch.
	//
	// EndBatch does various delayed maintenance tasks (like cache updates, trash
	// cleanup and so on). This is best-effort operations, and thus this method
	// doesn't return an errors.
	//
	// See also BeginBatch doc for more details.
	EndBatch(ctx context.Context)

	// FetchACL returns a list of PackageACL objects (parent paths first).
	//
	// Together they define the access control list for the given package prefix.
	FetchACL(ctx context.Context, prefix string) ([]PackageACL, error)

	// ModifyACL applies a set of PackageACLChanges to a package prefix ACL.
	ModifyACL(ctx context.Context, prefix string, changes []PackageACLChange) error

	// FetchRoles returns all roles the caller has in the given package prefix.
	//
	// Understands roles inheritance, e.g. if the caller is OWNER, the return
	// value will list all roles implied by being an OWNER (e.g. READER, WRITER,
	// ...).
	FetchRoles(ctx context.Context, prefix string) ([]string, error)

	// FetchRolesOnBehalfOf returns all roles the given user has in the given package prefix.
	//
	// This works the same way as FetchRoles, except:
	//   * The caller requires the same permission as GetPrefixMetadata.
	//   * Uses the given id identity.Identity, rather than the caller's
	//   identity, for determining the returned Roles.
	FetchRolesOnBehalfOf(ctx context.Context, prefix string, id identity.Identity) ([]string, error)

	// ResolveVersion converts an instance ID, a tag or a ref into a concrete Pin.
	ResolveVersion(ctx context.Context, packageName, version string) (common.Pin, error)

	// RegisterInstance makes the package instance available for clients.
	//
	// It uploads the instance to the storage, waits until the storage verifies
	// its hash matches instance ID in 'pin', and then registers the package in
	// the repository, making it discoverable.
	//
	// 'pin' here should match the package body, otherwise CIPD backend will
	// reject the package. Either get it from builder.BuildInstance (when building
	// a new package) or from reader.CalculatePin (when uploading an existing
	// package file).
	//
	// 'timeout' specifies for how long to wait until the instance hash is
	// verified by the storage backend. If 0, default CASFinalizationTimeout will
	// be used.
	RegisterInstance(ctx context.Context, pin common.Pin, src pkg.Source, timeout time.Duration) error

	// DescribeInstance returns information about a package instance.
	//
	// May also be used as a simple instance presence check, if opts is nil. If
	// the request succeeds, then the instance exists.
	DescribeInstance(ctx context.Context, pin common.Pin, opts *DescribeInstanceOpts) (*InstanceDescription, error)

	// DescribeClient returns information about a CIPD client binary matching the
	// given client package pin.
	DescribeClient(ctx context.Context, pin common.Pin) (*ClientDescription, error)

	// SetRefWhenReady moves a ref to point to a package instance.
	SetRefWhenReady(ctx context.Context, ref string, pin common.Pin) error

	// AttachTagsWhenReady attaches tags to an instance.
	AttachTagsWhenReady(ctx context.Context, pin common.Pin, tags []string) error

	// AttachMetadataWhenReady attaches metadata to an instance.
	AttachMetadataWhenReady(ctx context.Context, pin common.Pin, md []Metadata) error

	// FetchPackageRefs returns information about all refs defined for a package.
	//
	// The returned list is sorted by modification timestamp (newest first).
	FetchPackageRefs(ctx context.Context, packageName string) ([]RefInfo, error)

	// FetchInstance downloads a package instance file from the repository.
	//
	// It verifies that the package hash matches pin.InstanceID.
	//
	// It returns a pkg.Source pointing to the raw package data. The caller must
	// close it when done.
	FetchInstance(ctx context.Context, pin common.Pin) (pkg.Source, error)

	// FetchInstanceTo downloads a package instance file into the given writer.
	//
	// This is roughly the same as getting a reader with 'FetchInstance' and
	// copying its data into the writer, except this call skips unnecessary temp
	// files if the client is not using cache.
	//
	// It verifies that the package hash matches pin.InstanceID, but does it while
	// writing to 'output', so expect to discard all data there if FetchInstanceTo
	// returns an error.
	FetchInstanceTo(ctx context.Context, pin common.Pin, output io.WriteSeeker) error

	// ListPackages returns a list packages and prefixes under the given prefix.
	ListPackages(ctx context.Context, prefix string, recursive, includeHidden bool) ([]string, error)

	// SearchInstances finds instances of some package with all given tags.
	//
	// Returns their concrete Pins. If the package doesn't exist at all, returns
	// empty slice and nil error.
	SearchInstances(ctx context.Context, packageName string, tags []string) (common.PinSlice, error)

	// ListInstances enumerates instances of a package, most recent first.
	//
	// Returns an object that can be used to fetch the listing, page by page.
	ListInstances(ctx context.Context, packageName string) (InstanceEnumerator, error)

	// FindDeployed returns a list of packages deployed to the 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) (common.PinSliceBySubdir, error)

	// EnsurePackages installs, removes and updates packages in the site root.
	//
	// Given a description of what packages (and versions) should be installed it
	// will do all necessary actions to bring the state of the site root to the
	// desired one.
	//
	// If the update was only partially applied, returns both Actions and error.
	//
	// NOTE: You can repair the current deployment by passing in the output of
	// FindDeployed, plus an opts.Paranoia. Doing this with opts.DryRun=true
	// will check the integrity of the current deployment.
	EnsurePackages(ctx context.Context, pkgs common.PinSliceBySubdir, opts *EnsureOptions) (ActionMap, error)
}

Client provides high-level CIPD client interface. Thread safe.

func NewClient 

func NewClient(opts ClientOptions) (Client, error)

NewClient initializes CIPD client using given options.

This is a relatively low level function that doesn't lookup any environment variables or configuration files to populate unset fields in ClientOptions and doesn't hardcode any preferences.

If you just need to construct a simple functioning CIPD client with all defaults based on the environment, use NewClientFromEnv. If you need to examine options before constructing the client, use ClientOption's LoadFromEnv before calling NewClient.

The client must be shutdown with Close when no longer needed.

func NewClientFromEnv 

func NewClientFromEnv(ctx context.Context, opts ClientOptions) (Client, error)

NewClientFromEnv initializes CIPD client using given options and applying settings from the environment and the configuration file on top using ClientOptions' LoadFromEnv.

This is the preferred method of constructing fully-functioning CIPD clients programmatically.

If the client will be used to install packages, at least Root in ClientOptions must be populated (otherwise EnsurePackages will fail). If the client will be used only to make backend calls (e.g. to resolve versions), Root can be empty.

If AuthenticatedClient in ClientOptions is unset, initializes a new authenticating client using the hardcoded Chrome Infra OAuth client credentials.

The CIPD client will use the given context for logging from plugins (if any).

The client must be shutdown with Close when no longer needed.

type ClientDescription 

type ClientDescription struct {
	InstanceInfo

	// Size of the client binary file in bytes.
	Size int64 `json:"size"`

	// SignedURL is URL of the client binary.
	SignedURL string `json:"signed_url"`

	// Digest is the client binary digest using the best hash algo understood by
	// the current process.
	//
	// May potentially be nil if the current process doesn't understand any of
	// the algos, but this is an extreme situation and it is OK to panic in this
	// case. At very least all client binaries have SHA1 digests, and it should
	// be understood by all clients.
	Digest *api.ObjectRef `json:"digest"`

	// AlternativeDigests is a list of digest calculated using hash algos other
	// than the one used by Digest.
	//
	// This may include both old hash algos (obsoleted by the algo in Digest), as
	// well as a new ones, not supported by the current process.
	//
	// Not all client versions have all digests calculated. Older versions have
	// only SHA1 digest, which means for them Digest will be SHA1 and
	// AlternativeDigests list will be empty.
	AlternativeDigests []*api.ObjectRef `json:"alternative_digests"`
}

ClientDescription contains extended information about a CIPD client binary at some version for some platform, as returned by DescribeClient.

type ClientOptions 

type ClientOptions struct {
	// ServiceURL is root URL of the backend service.
	ServiceURL string

	// Root is a site root directory.
	//
	// It is a directory where packages will be installed to. It also hosts
	// .cipd/* directory that tracks internal state of installed packages and
	// keeps various cache files. 'Root' can be an empty string if the client is
	// not going to be used to deploy or remove local packages.
	Root string

	// CacheDir is a directory for shared cache.
	//
	// If empty, instances are not cached and tags are cached inside the site
	// root. If both Root and CacheDir are empty, tag cache is disabled.
	CacheDir string

	// Versions is optional database of (pkg, version) => instance ID resolutions.
	//
	// If set, it will be used for all version resolutions done by the client.
	// The client won't be consulting (or updating) the tag cache and won't make
	// 'ResolveVersion' backend RPCs.
	//
	// This is primarily used to implement $ResolvedVersions ensure file feature.
	Versions ensure.VersionsFile

	// AnonymousClient is http.Client that doesn't attach authentication headers.
	//
	// Will be used when talking to the Google Storage. We use signed URLs that do
	// not require additional authentication.
	//
	// Default is http.DefaultClient.
	AnonymousClient *http.Client

	// AuthenticatedClient is http.Client that attaches authentication headers.
	//
	// Will be used when talking to the backend.
	//
	// Default is same as AnonymousClient (it will probably not work for most
	// packages, since the backend won't authorize an anonymous access).
	AuthenticatedClient *http.Client

	// MaxThreads defines how many threads to use when unzipping packages.
	//
	// If 0 or negative, will use all available CPUs.
	MaxThreads int

	// ParallelDownloads defines how many packages are allowed to be fetched
	// concurrently.
	//
	// Possible values:
	//   0: will use some default value (perhaps loading it from the environ).
	//  <0: will do fetching and unzipping completely serially.
	//   1: will fetch at most one package at once and unzip in parallel to that.
	//  >1: will fetch multiple packages at once and unzip in parallel to that.
	ParallelDownloads int

	// UserAgent is put into User-Agent HTTP header with each request.
	//
	// Default is UserAgent const.
	UserAgent string

	// LoginInstructions is appended to "permission denied" error messages.
	LoginInstructions string

	// PluginsContext is a context to use for logging from plugins (if any).
	//
	// If not set, logging from plugins will be ignored.
	PluginsContext context.Context

	// AdmissionPlugin is the deployment admission plugin command line (if any).
	//
	// Will be started lazily when needed.
	AdmissionPlugin []string
	// contains filtered or unexported fields
}

ClientOptions is passed to NewClient and NewClientFromEnv.

If you construct options manually to call NewClient, you almost certainly also need to call LoadFromEnv to load unset values from the process environment and the config file before passing options to NewClient. NewClientFromEnv will do that for you.

func (*ClientOptions) LoadFromEnv 

func (opts *ClientOptions) LoadFromEnv(ctx context.Context) error

LoadFromEnv loads supplied default values from an environment into opts.

Uses the environment in the context via luci/common/system/environ library, falling back to the regular process environment as usual (so if you don't need to mess with the process environment, just pass any context, it would work fine).

Loads and interprets the configuration file based on `CIPD_CONFIG_FILE` env var (defaulting to `/etc/chrome-infra/cipd.cfg` on Linux/OSX and `C:\chrome-infra\cipd.cfg` on Windows). See configpb/config.proto for the schema.

type DescribeInstanceOpts 

type DescribeInstanceOpts struct {
	DescribeRefs     bool // if true, will fetch all refs pointing to the instance
	DescribeTags     bool // if true, will fetch all tags attached to the instance
	DescribeMetadata bool // if true, will fetch all metadata attached to the instance
}

DescribeInstanceOpts is passed to DescribeInstance.

type EnsureOptions 

type EnsureOptions struct {
	// Paranoia controls how much verification EnsurePackages does to verify that
	// the currently-installed packages are, in fact, correctly installed.
	//
	// If EnsurePackages determines that packages are NOT correctly installed, it
	// will attempt to fix them.
	//
	// Defaults to NotParanoid.
	// See the enum for more info.
	Paranoia ParanoidMode

	// DryRun, if true, will only check for changes and return them in the
	// ActionMap, but won't actually perform them.
	DryRun bool

	// Silent, if true, suppresses all logging output from EnsurePackages.
	Silent bool

	// OverrideInstallMode, if set, will be the install mode used for all
	// packages installed or repaired by this ensure operation. Note that
	// Paranoia needs to be at least CheckDeployed to change the install
	// mode of an already-deployed package.
	OverrideInstallMode pkg.InstallMode
}

EnsureOptions is passed to Client.EnsurePackages.

This can be used to control HOW Ensure does its actions.

type InstanceDescription 

type InstanceDescription struct {
	InstanceInfo

	// Refs is a list of refs pointing to the instance, sorted by modification
	// timestamp (newest first)
	//
	// Present only if DescribeRefs in DescribeInstanceOpts is true.
	Refs []RefInfo `json:"refs,omitempty"`

	// Tags is a list of tags attached to the instance, sorted by tag key and
	// creation timestamp (newest first).
	//
	// Present only if DescribeTags in DescribeInstanceOpts is true.
	Tags []TagInfo `json:"tags,omitempty"`

	// Metadata is a list of metadata attached to the instance.
	//
	// Present only if DescribeMetadata in DescribeInstanceOpts is true.
	Metadata []MetadataInfo `json:"metadata,omitempty"`
}

InstanceDescription contains extended information about an instance as returned by DescribeInstance.

type InstanceEnumerator 

type InstanceEnumerator interface {
	// Next returns up to 'limit' instances or 0 if there's no more.
	Next(ctx context.Context, limit int) ([]InstanceInfo, error)
}

InstanceEnumerator emits a list of instances, fetching them in batches.

Returned by ListInstances call.

type InstanceInfo 

type InstanceInfo struct {
	// Pin identifies package instance.
	Pin common.Pin `json:"pin"`
	// RegisteredBy is identity of whoever uploaded this instance.
	RegisteredBy string `json:"registered_by"`
	// RegisteredTs is when the instance was registered.
	RegisteredTs UnixTime `json:"registered_ts"`
}

InstanceInfo is information about single package instance.

type JSONError 

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

JSONError is wrapper around Error that serializes it as string.

func (JSONError) MarshalJSON 

func (e JSONError) MarshalJSON() ([]byte, error)

MarshalJSON is used by JSON encoder.

type ManifestMode 

type ManifestMode = pkg.ManifestMode

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).

type Metadata 

type Metadata struct {
	// Key is a lowercase string matching [a-z0-9_\-]{1,400}.
	Key string `json:"key"`
	// Value is an arbitrary byte blob smaller than 512 Kb.
	Value []byte `json:"value,omitempty"`
	// Optional MIME content type of the metadata value, primarily for UI.
	ContentType string `json:"content_type,omitempty"`
}

Metadata is a metadata entry that can be attached to an instance.

type MetadataInfo 

type MetadataInfo struct {
	// Fingerprint identifies this particular metadata entry.
	//
	// It is derived from the key+value via common.InstanceMetadataFingerprint.
	Fingerprint string `json:"fingerprint"`

	// Key is a lowercase string matching [a-z0-9_\-]{1,400}.
	Key string `json:"key"`
	// Value is an arbitrary byte blob smaller than 512 Kb.
	Value []byte `json:"value,omitempty"`
	// Optional MIME content type of the metadata value, primarily for UI.
	ContentType string `json:"content_type,omitempty"`

	// AttachedBy is identity of whoever attached this metadata.
	AttachedBy string `json:"attached_by"`
	// AttachedTs is when the metadata was attached.
	AttachedTs UnixTime `json:"attached_ts"`
}

MetadataInfo describes an already attached metadata entry.

type PackageACL 

type PackageACL struct {
	// PackagePath is a package subpath this ACL is defined for.
	PackagePath string `json:"package_path"`
	// Role is a role that listed users have, e.g. 'READER', 'WRITER', ...
	Role string `json:"role"`
	// Principals list users and groups granted the role.
	Principals []string `json:"principals"`
	// ModifiedBy specifies who modified the list the last time.
	ModifiedBy string `json:"modified_by"`
	// ModifiedTs is a timestamp when the list was modified the last time.
	ModifiedTs UnixTime `json:"modified_ts"`
}

PackageACL is per package path per role access control list that is a part of larger overall ACL: ACL for package "a/b/c" is a union of PackageACLs for "a" "a/b" and "a/b/c".

type PackageACLChange 

type PackageACLChange struct {
	// Action defines what action to perform: GrantRole or RevokeRole.
	Action PackageACLChangeAction
	// Role to grant or revoke to a user or group, see Role enum repo.proto.
	Role string
	// Principal is a user or a group to grant or revoke a role for.
	Principal string
}

PackageACLChange is a mutation to some package ACL.

type PackageACLChangeAction 

type PackageACLChangeAction string

PackageACLChangeAction defines a flavor of PackageACLChange.

Used by ModifyACL. 

const (
	// GrantRole is used in PackageACLChange to request a role to be granted.
	GrantRole PackageACLChangeAction = "GRANT"
	// RevokeRole is used in PackageACLChange to request a role to be revoked.
	RevokeRole PackageACLChangeAction = "REVOKE"
)

type ParanoidMode 

type ParanoidMode = deployer.ParanoidMode

ParanoidMode specifies how paranoid EnsurePackages should be.

type RefInfo 

type RefInfo struct {
	// Ref is the ref name.
	Ref string `json:"ref"`
	// InstanceID is ID of a package instance the ref points to.
	InstanceID string `json:"instance_id"`
	// ModifiedBy is identity of whoever modified this ref last time.
	ModifiedBy string `json:"modified_by"`
	// ModifiedTs is when the ref was modified last time.
	ModifiedTs UnixTime `json:"modified_ts"`
}

RefInfo is returned by DescribeInstance and FetchPackageRefs.

type RepairPlan 

type RepairPlan struct {
	// NeedsReinstall is true if the package is broken to the point it is simpler
	// to completely reinstall it.
	//
	// ReinstallReason contains explanation why the reinstall is needed.
	//
	// If NeedsReinstall is false, then the package may be repaired just by
	// extracting a bunch of files, specified in ToRedeploy list.
	NeedsReinstall bool `json:"needs_reinstall,omitempty"`

	// ReinstallReason is a human-readable reason of why the package should be
	// completely reinstalled rather than selectively repaired.
	ReinstallReason string `json:"reinstall_reason,omitempty"`

	// ToRedeploy is a list of slash-separated file names (as they are specified
	// inside the package file) that needs to be reextracted from the original
	// package and relinked into the site root in order to repair the deployment.
	//
	// If this list is not empty, it means we'll need an original package file
	// to repair the deployment.
	//
	// Set only if NeedsReinstall is false.
	ToRedeploy []string `json:"to_redeploy,omitempty"`

	// ToRelink is a list of slash-separated file names (as they are specified
	// inside the package file) that needs to be relinked into the site root in
	// order to repair the deployment.
	//
	// They are already present in the .cipd/* guts, so there's no need to fetch
	// the original package file to get them.
	//
	// Set only if NeedsReinstall is false.
	ToRelink []string `json:"to_relink,omitempty"`
}

RepairPlan describes what should be redeployed to fix a broken pin.

func (*RepairPlan) NumBrokenFiles 

func (p *RepairPlan) NumBrokenFiles() int

NumBrokenFiles returns number of files that will be repaired.

type Resolver 

type Resolver struct {
	// Client is the CIPD client to use for resolving versions.
	Client Client

	// VerifyPresence specifies whether the resolver should check the resolved
	// versions actually exist on the backend.
	VerifyPresence bool

	// Visitor is called for each package version that the resolver has
	// successfully processed.
	//
	// It receives the original (pkg, version) tuple and an instance ID it
	// resolves to.
	//
	// Called concurrently from multiple goroutines in undefined order. Same
	// (pkg, version) tuple may be visited multiple times. May be called for noop
	// version resolutions (when the version is already given as an instance ID).
	Visitor func(pkg, ver, iid string)
	// contains filtered or unexported fields
}

Resolver resolves versions of packages in an ensure file into concrete instance IDs.

For versions that are already defined as instance IDs, it verifies they actually exist.

The instance of Resolver is stateful. It caches results of resolutions and verifications, so that subsequent attempts to resolve/verify same pins are fast.

Resolver can be safely used concurrently.

func (*Resolver) Resolve 

func (r *Resolver) Resolve(ctx context.Context, file *ensure.File, expander template.Expander) (*ensure.ResolvedFile, error)

Resolve resolves versions of all packages in the ensure file using the given expander to expand templates.

Succeeds only if all packages have been successfully resolved and verified.

Names of packages that failed the resolution are returned as part of the multi-error.

func (*Resolver) ResolveAllPlatforms 

func (r *Resolver) ResolveAllPlatforms(ctx context.Context, file *ensure.File) (map[template.Platform]*ensure.ResolvedFile, error)

ResolveAllPlatforms resolves the ensure file for all platform it is verified for (see file.VerifyPlatforms list).

Doesn't stop on a first error. Collects them all into a single multi-error.

func (*Resolver) ResolvePackage 

func (r *Resolver) ResolvePackage(ctx context.Context, pkg, ver string) (pin common.Pin, err error)

ResolvePackage resolves the package's version into a concrete instance ID and (if Resolver.VerifyPresence is true) verifies it exists.

type TagInfo 

type TagInfo struct {
	// Tag is actual tag name ("key:value" pair).
	Tag string `json:"tag"`
	// RegisteredBy is identity of whoever attached this tag.
	RegisteredBy string `json:"registered_by"`
	// RegisteredTs is when the tag was registered.
	RegisteredTs UnixTime `json:"registered_ts"`
}

TagInfo is returned by DescribeInstance.

type UnixTime 

type UnixTime time.Time

UnixTime is time.Time that serializes to integer unix timestamp in JSON (represented as a number of seconds since January 1, 1970 UTC).

func (UnixTime) Before 

func (t UnixTime) Before(t2 UnixTime) bool

Before is used to compare UnixTime objects.

func (UnixTime) IsZero 

func (t UnixTime) IsZero() bool

IsZero reports whether t represents the zero time instant.

func (UnixTime) MarshalJSON 

func (t UnixTime) MarshalJSON() ([]byte, error)

MarshalJSON is used by JSON encoder.

func (UnixTime) String 

func (t UnixTime) String() string

String is needed to be able to print UnixTime.

type UpdatedPin 

type UpdatedPin struct {
	From common.Pin `json:"from"`
	To   common.Pin `json:"to"`
}

UpdatedPin specifies a pair of pins: old and new version of a package.

type UploadSession 

type UploadSession struct {
	// ID identifies upload session in the backend.
	ID string
	// URL is where to upload the data to.
	URL string
}

UploadSession describes open CAS upload session.

Source Files

View all Source files

Directories

Path Synopsis
Package builder holds functionality for building CIPD packages.
 Package builder holds functionality for building CIPD packages.
Package configpb contains definition of CIPD client config schema.
 Package configpb contains definition of CIPD client config schema.
Package deployer holds functionality for deploying CIPD packages.
 Package deployer holds functionality for deploying CIPD packages.
Package digests holds types used by selfupdate mechanism to pin client hashes.
 Package digests holds types used by selfupdate mechanism to pin client hashes.
Package ensure contains methods and types for interacting with the 'ensure file format'.
 Package ensure contains methods and types for interacting with the 'ensure file format'.
Package fs is file-system related utilities used internally by CIPD.
 Package fs is file-system related utilities used internally by CIPD.
messages
retry
Package retry contains helpers for doing tight retry loops.
 Package retry contains helpers for doing tight retry loops.
Package pkg contains interfaces and struct related to CIPD package files.
 Package pkg contains interfaces and struct related to CIPD package files.
Package platform contains definition of what ${os} and ${arch} mean for the current platform.
 Package platform contains definition of what ${os} and ${arch} mean for the current platform.
Package plugin contains public API of the plugin system.
 Package plugin contains public API of the plugin system.
host
Package host implements the plugin hosting functionality.
 Package host implements the plugin hosting functionality.
plugins
Package plugins contains shared plugin-side functionality.
 Package plugins contains shared plugin-side functionality.
plugins/admission
Package admission contains API for writing admission plugins.
 Package admission contains API for writing admission plugins.
plugins/admission/example
protocol
Package protocol hosts protobuf messages for the CIPD plugin system.
 Package protocol hosts protobuf messages for the CIPD plugin system.
Package reader implements reading contents of a CIPD package.
 Package reader implements reading contents of a CIPD package.
Package template implements handling of package name templates.
 Package template implements handling of package name templates.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.