luci: go.chromium.org/luci/cipd/common Index | Files

package common

import "go.chromium.org/luci/cipd/common"

Package common defines structures and functions used by cipd/* packages.

Index

Package Files

common.go hash.go iid.go paranoia.go

Constants

const DefaultHashAlgo = api.HashAlgo_SHA1

DefaultHashAlgo is a hash algorithm to use for deriving IDs of new package instances.

Currently SHA1, but will change to SHA256 soon. Older existing instances are allowed to use some other hash algo.

func HexDigest Uses

func HexDigest(h hash.Hash) string

HexDigest returns a digest string as it is used in ObjectRef.

func InstanceIDToObjectRef Uses

func InstanceIDToObjectRef(iid string) *api.ObjectRef

InstanceIDToObjectRef is a reverse of ObjectRefToInstanceID.

Panics if the instance ID is incorrect. Use ValidateInstanceID if this is a concern.

func JoinInstanceTag Uses

func JoinInstanceTag(t *api.Tag) string

JoinInstanceTag returns "k:v" representation of the tag.

Doesn't validate it.

func MustNewHash Uses

func MustNewHash(algo api.HashAlgo) hash.Hash

MustNewHash as like NewHash, but panics on errors.

Appropriate for cases when the hash algo has already been validated.

func MustParseInstanceTag Uses

func MustParseInstanceTag(t string) *api.Tag

MustParseInstanceTag takes "k:v" string returns its proto representation or panics if the tag is invalid.

func NewHash Uses

func NewHash(algo api.HashAlgo) (hash.Hash, error)

NewHash returns a hash implementation or an error if the algo is unknown.

func NormalizePrefixMetadata Uses

func NormalizePrefixMetadata(m *api.PrefixMetadata) error

NormalizePrefixMetadata validates and normalizes the prefix metadata proto.

Updates r.Prefix in-place by stripping trailing '/', sorts r.Acls and principals lists inside them. Skips r.Fingerprint, r.UpdateTime and r.UpdateUser, since they are always overridden on the server side.

func ObjectRefToInstanceID Uses

func ObjectRefToInstanceID(ref *api.ObjectRef) string

ObjectRefToInstanceID returns an Instance ID that matches the given CAS object ref.

Instance ID is a human readable string representation of ObjectRef used in higher level APIs (command line flags, ensure files, etc) and internally in the datastore.

Its exact form depends on a hash being used:

* SHA1: Instance IDs are hex encoded SHA1 digests, in lowercase.
* Everything else: base64(digest + []byte{ref.HashAlgo}), where base64 is
  without padding and using URL-safe charset.

The ref is not checked for correctness. Use ValidateObjectRef if this is a concern. Panics if something is not right.

func ParseInstanceTag Uses

func ParseInstanceTag(t string) (*api.Tag, error)

ParseInstanceTag takes "k:v" string and returns its proto representation.

func ValidateHashAlgo Uses

func ValidateHashAlgo(h api.HashAlgo) error

ValidateHashAlgo returns a grpc-annotated error if the given algo is invalid, e.g. either unspecified or not known to the current version of the code.

Errors have InvalidArgument grpc code.

func ValidateInstanceID Uses

func ValidateInstanceID(iid string, v HashAlgoValidation) (err error)

ValidateInstanceID returns an error if the string isn't a valid instance id.

If v is KnownHash, will verify the current version of the code understands the hash algo encoded in idd. Otherwise (if v is AnyHash) will just validate that iid looks syntactically sane, and will accept any hash algo (even if the current code doesn't understand it). This is useful when round-tripping ObjectRefs and instance IDs through the (outdated) client code back to the server.

func ValidateInstanceTag Uses

func ValidateInstanceTag(t string) error

ValidateInstanceTag returns error if a string doesn't look like a valid tag.

func ValidateInstanceVersion Uses

func ValidateInstanceVersion(v string) error

ValidateInstanceVersion return error if a string can't be used as version.

A version can be specified as:

1) Instance ID (hash, e.g "1234deadbeef2234...").
2) Package ref (e.g. "latest").
3) Instance tag (e.g. "git_revision:abcdef...").

func ValidateObjectRef Uses

func ValidateObjectRef(ref *api.ObjectRef, v HashAlgoValidation) error

ValidateObjectRef returns a grpc-annotated error if the given object ref is invalid.

If v is KnownHash, will verify the current version of the code understands the hash algo. Otherwise (if v is AnyHash) will just validate that the hex digest looks sane, and will accept any hash algo (even if the current code doesn't understand it). This is useful when round-tripping ObjectRefs and instance IDs through the (outdated) client code back to the server.

Errors have InvalidArgument grpc code.

func ValidatePackageName Uses

func ValidatePackageName(name string) error

ValidatePackageName returns error if a string isn't a valid package name.

func ValidatePackagePrefix Uses

func ValidatePackagePrefix(p string) (string, error)

ValidatePackagePrefix normalizes and validates a package prefix.

A prefix is basically like a package name, except it is allowed to have '/' at the end (such trailing '/' is stripped by this function), and it can be an empty string or "/" (to indicate the root of the repository).

func ValidatePackageRef Uses

func ValidatePackageRef(r string) error

ValidatePackageRef returns error if a string doesn't look like a valid ref.

func ValidatePin Uses

func ValidatePin(pin Pin, v HashAlgoValidation) error

ValidatePin returns error if package name or instance id are invalid.

func ValidatePrincipalName Uses

func ValidatePrincipalName(p string) error

ValidatePrincipalName validates strings used to identify principals in ACLs.

The expected format is "<key>:<value>" pair, where <key> is one of "group", "user", "anonymous", "service". See also go.chromium.org/luci/auth/identity.

func ValidateSubdir Uses

func ValidateSubdir(subdir string) error

ValidateSubdir returns an error if the string can't be used as an ensure-file subdir.

type HashAlgoValidation Uses

type HashAlgoValidation bool

HashAlgoValidation is passed to ValidateObjectRef.

const (
    // KnownHash indicates that ValidateObjectRef should only accept refs that
    // use hash algo known to the current version of the code.
    //
    // This is primarily useful on the backend, since it always needs to be sure
    // that it can handle any ObjectRef that is passed to it.
    KnownHash HashAlgoValidation = true

    // AnyHash indicates that ValidateObject may accept refs that use algo number
    // not known to the current version of the code (i.e. presumably from the
    // future version of the protocol).
    //
    // This is useful on the client that for some operations just round-trips
    // ObjectRef it received from the server, without trying to interpret it.
    // Using AnyHash allows the client to be friendlier to future protocol
    // changes. This is particularly important in self-update flow.
    AnyHash HashAlgoValidation = false
)

type ParanoidMode Uses

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 Uses

func (p ParanoidMode) Validate() error

Validate returns an error if the mode is unrecognized.

type Pin Uses

type Pin struct {
    PackageName string `json:"package"`
    InstanceID  string `json:"instance_id"`
}

Pin uniquely identifies an instance of some package.

func (Pin) String Uses

func (pin Pin) String() string

String converts pin to a human readable string.

type PinMap Uses

type PinMap map[string]string

PinMap is a map of package_name to instanceID.

func (PinMap) ToSlice Uses

func (m PinMap) ToSlice() PinSlice

ToSlice converts the PinMap to a PinSlice.

type PinMapBySubdir Uses

type PinMapBySubdir map[string]PinMap

PinMapBySubdir is a simple mapping of subdir -> package_name -> instanceID

func (PinMapBySubdir) ToSlice Uses

func (p PinMapBySubdir) ToSlice() PinSliceBySubdir

ToSlice converts this to a PinSliceBySubdir

type PinSlice Uses

type PinSlice []Pin

PinSlice is a simple list of Pins

func (PinSlice) ToMap Uses

func (s PinSlice) ToMap() PinMap

ToMap converts the PinSlice to a PinMap.

func (PinSlice) Validate Uses

func (s PinSlice) Validate(v HashAlgoValidation) error

Validate ensures that this PinSlice contains no duplicate packages or invalid pins.

type PinSliceBySubdir Uses

type PinSliceBySubdir map[string]PinSlice

PinSliceBySubdir is a simple mapping of subdir to pin slice.

func (PinSliceBySubdir) ToMap Uses

func (p PinSliceBySubdir) ToMap() PinMapBySubdir

ToMap converts this to a PinMapBySubdir

func (PinSliceBySubdir) Validate Uses

func (p PinSliceBySubdir) Validate(v HashAlgoValidation) error

Validate ensures that this doesn't contain any invalid subdirs, duplicate packages within the same subdir, or invalid pins.

Package common imports 15 packages (graph) and is imported by 24 packages. Updated 2018-08-20. Refresh now. Tools for package owners.