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.

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