common

Documentation

Index

• Constants
• func HexDigest(h hash.Hash) string
• func InstanceIDToObjectRef(iid string) *api.ObjectRef
• func InstanceMetadataFingerprint(key string, value []byte) string
• func JoinInstanceTag(t *api.Tag) string
• func MustNewHash(algo api.HashAlgo) hash.Hash
• func MustParseInstanceTag(t string) *api.Tag
• func NewHash(algo api.HashAlgo) (hash.Hash, error)
• func NormalizePrefixMetadata(m *api.PrefixMetadata) error
• func ObjectRefFromHash(h hash.Hash) *api.ObjectRef
• func ObjectRefToInstanceID(ref *api.ObjectRef) string
• func ParseInstanceTag(t string) (*api.Tag, error)
• func ValidateContentType(ct string) error
• func ValidateHashAlgo(h api.HashAlgo) error
• func ValidateInstanceID(iid string, v HashAlgoValidation) (err error)
• func ValidateInstanceMetadataFingerprint(fp string) error
• func ValidateInstanceMetadataKey(key string) error
• func ValidateInstanceMetadataLen(l int) error
• func ValidateInstanceTag(t string) error
• func ValidateInstanceVersion(v string) error
• func ValidateObjectRef(ref *api.ObjectRef, v HashAlgoValidation) error
• func ValidatePackageName(name string) error
• func ValidatePackagePrefix(p string) (string, error)
• func ValidatePackageRef(r string) error
• func ValidatePin(pin Pin, v HashAlgoValidation) error
• func ValidatePrincipalName(p string) error
• func ValidateSubdir(subdir string) error
• type HashAlgoValidation
• type Pin
  • func (pin Pin) String() string
• type PinMap
  • func (m PinMap) ToSlice() PinSlice
• type PinMapBySubdir
  • func (p PinMapBySubdir) ToSlice() PinSliceBySubdir
• type PinSlice
  • func (s PinSlice) ToMap() PinMap
  • func (s PinSlice) Validate(v HashAlgoValidation) error
• type PinSliceBySubdir
  • func (p PinSliceBySubdir) ToMap() PinMapBySubdir
  • func (p PinSliceBySubdir) Validate(v HashAlgoValidation) error

Constants

const DefaultHashAlgo = api.HashAlgo_SHA256

DefaultHashAlgo is a hash algorithm to use for deriving IDs of new package instances. Older existing instances are allowed to use some other hash algo.

const MetadataMaxLen = 512 * 1024

MetadataMaxLen is maximum allowed length of an instance metadata entry body.

Functions

func HexDigest

func HexDigest(h hash.Hash) string

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

func InstanceIDToObjectRef

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 InstanceMetadataFingerprint

func InstanceMetadataFingerprint(key string, value []byte) string

InstanceMetadataFingerprint calculates a fingerprint of an instance metadata entry.

Doesn't do any validation.

func JoinInstanceTag

func JoinInstanceTag(t *api.Tag) string

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

Doesn't validate it.

func MustNewHash

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

func MustParseInstanceTag(t string) *api.Tag

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

func NewHash

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

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

func NormalizePrefixMetadata

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 ObjectRefFromHash

func ObjectRefFromHash(h hash.Hash) *api.ObjectRef

ObjectRefFromHash returns ObjectRef based on the given hash.Hash.

`h` must be one of the supported hashes (as created by `NewHash`). Panics otherwise.

func ObjectRefToInstanceID

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

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

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

func ValidateContentType

func ValidateContentType(ct string) error

ValidateContentType returns an error if the given string can't be used as an instance metadata content type.

func ValidateHashAlgo

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

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 ValidateInstanceMetadataFingerprint

func ValidateInstanceMetadataFingerprint(fp string) error

ValidateInstanceMetadataFingerprint returns an error if the given string doesn't look like an output of InstanceMetadataFingerprint.

func ValidateInstanceMetadataKey

func ValidateInstanceMetadataKey(key string) error

ValidateInstanceMetadataKey returns an error if the given key can't be used as an instance metadata key.

func ValidateInstanceMetadataLen

func ValidateInstanceMetadataLen(l int) error

ValidateInstanceMetadataLen returns an error if the given length of the metadata payload is too large.

func ValidateInstanceTag

func ValidateInstanceTag(t string) error

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

func ValidateInstanceVersion

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

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

func ValidatePackageName(name string) error

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

func ValidatePackagePrefix

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

func ValidatePackageRef(r string) error

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

func ValidatePin

func ValidatePin(pin Pin, v HashAlgoValidation) error

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

func ValidatePrincipalName

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

func ValidateSubdir(subdir string) error

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

Types

type HashAlgoValidation

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 Pin

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

Pin uniquely identifies an instance of some package.

func (Pin) String

func (pin Pin) String() string

String converts pin to a human readable string.

type PinMap

type PinMap map[string]string

PinMap is a map of package_name to instanceID.

func (PinMap) ToSlice

func (m PinMap) ToSlice() PinSlice

ToSlice converts the PinMap to a PinSlice.

type PinMapBySubdir

type PinMapBySubdir map[string]PinMap

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

func (PinMapBySubdir) ToSlice

func (p PinMapBySubdir) ToSlice() PinSliceBySubdir

ToSlice converts this to a PinSliceBySubdir

type PinSlice

type PinSlice []Pin

PinSlice is a simple list of Pins

func (PinSlice) ToMap

func (s PinSlice) ToMap() PinMap

ToMap converts the PinSlice to a PinMap.

func (PinSlice) Validate

func (s PinSlice) Validate(v HashAlgoValidation) error

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

type PinSliceBySubdir

type PinSliceBySubdir map[string]PinSlice

PinSliceBySubdir is a simple mapping of subdir to pin slice.

func (PinSliceBySubdir) ToMap

func (p PinSliceBySubdir) ToMap() PinMapBySubdir

ToMap converts this to a PinMapBySubdir

func (PinSliceBySubdir) Validate

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.