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

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