digests

Documentation

Overview

Package digests holds types used by selfupdate mechanism to pin client hashes.

Index

• type ClientDigestsFile
  • func ParseClientDigestsFile(r io.Reader) (*ClientDigestsFile, error)
  • func (d *ClientDigestsFile) AddClientRef(plat string, ref *api.ObjectRef) error
  • func (d *ClientDigestsFile) ClientRef(plat string) (ref *api.ObjectRef)
  • func (d *ClientDigestsFile) Contains(plat string, ref *api.ObjectRef) bool
  • func (d *ClientDigestsFile) Equal(a *ClientDigestsFile) bool
  • func (d *ClientDigestsFile) Serialize(w io.Writer, version, versionFile string) error
  • func (d *ClientDigestsFile) Sort()

Types

type ClientDigestsFile

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

ClientDigestsFile holds a mapping "platform => hash of the client binary for given platform", for some particular version of the CIPD client (provided elsewhere).

It is used to "lock" the client binary during updates, much in a same way $ResolvedVersions file is used to "lock" hashes of the packages. Unlike the latter, the client version file holds digests of the CIPD client binary itself, not a CIPD package.

This file is parsed by 'cipd selfupdate' and also by various bootstrap scripts that fetch the initial copy of the client. For that reason the format is relatively simple:

""" # Comment.

<platform> <hash algo> <hex digest> ... """

Where <platform> is one of ${platform} values (e.g. "linux-amd64"), and <hash algo> is one of stringified case-insensitive HashAlgo enum values from api/cas.proto (e.g. "sha256").

Comments are allowed and must occupy their own line. Empty new lines are skipped. All non-empty lines have 3 fields (with any number of whitespace characters between fields).

Order of lines is not significant.

func ParseClientDigestsFile

func ParseClientDigestsFile(r io.Reader) (*ClientDigestsFile, error)

ParseClientDigestsFile parses previously serialized client digests file.

Unrecognized algorithms are silently skipped, to be compatible with files generated by the future versions of CIPD that may use different algorithms.

func (*ClientDigestsFile) AddClientRef

func (d *ClientDigestsFile) AddClientRef(plat string, ref *api.ObjectRef) error

AddClientRef appends the client's digest given as ObjectRef.

Returns an error (platform, hash algo) combination has already been added or the hash is unrecognized.

func (*ClientDigestsFile) ClientRef

func (d *ClientDigestsFile) ClientRef(plat string) (ref *api.ObjectRef)

ClientRef returns an expected client ObjectRef for the given platform.

Returns the best hash (higher algo number) or nil if there are no digests for this platform at all.

func (*ClientDigestsFile) Contains

func (d *ClientDigestsFile) Contains(plat string, ref *api.ObjectRef) bool

Contains returns true if the given ref is among refs for the given platform.

Compares 'ref' to all hashes corresponding to 'plat', not only the best one.

func (*ClientDigestsFile) Equal

func (d *ClientDigestsFile) Equal(a *ClientDigestsFile) bool

Equal returns true if files have same entries in same order.

func (*ClientDigestsFile) Serialize

func (d *ClientDigestsFile) Serialize(w io.Writer, version, versionFile string) error

Serialize writes the ClientDigestsFile to an io.Writer.

'version' and 'versionFile' are used to construct a meaningful comment footer.

func (*ClientDigestsFile) Sort

func (d *ClientDigestsFile) Sort()

Sort orders the entries by (platform, -hashAlgo).