common

package
v0.0.0-...-8ff35f7 Latest Latest
Warning

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

 Go to latest Published: Dec 20, 2024 License: Apache-2.0 Imports: 18 Imported by: 61

Documentation

Index

Constants

View Source 
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.

View Source 
const MetadataMaxLen = 512 * 1024

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

Variables

This section is empty.

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.

Source Files

View all Source files

Directories

Path Synopsis
Package cipderr contains an enumeration with possible CIPD error categories.
 Package cipderr contains an enumeration with possible CIPD error categories.

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.