Documentation

Overview

    Interfaces for database-related operations.

    Index

    Constants

    View Source
    const (
    	ErrCodeKeyNotFound int = iota + 1
    	ErrCodeKeyExists
    	ErrCodeResourceVersionConflicts
    	ErrCodeInvalidObj
    	ErrCodeUnreachable
    )

    Variables

    View Source
    var Everything = SelectionPredicate{
    	Label: labels.Everything(),
    	Field: fields.Everything(),
    }

      Everything accepts all objects.

      Functions

      func DefaultClusterScopedAttr

      func DefaultClusterScopedAttr(obj runtime.Object) (labels.Set, fields.Set, error)

      func DefaultNamespaceScopedAttr

      func DefaultNamespaceScopedAttr(obj runtime.Object) (labels.Set, fields.Set, error)

      func EverythingFunc

      func EverythingFunc(runtime.Object) bool

      func FieldIndex

      func FieldIndex(field string) string

        FiledIndex add prefix for field index.

        func IsConflict

        func IsConflict(err error) bool

          IsConflict returns true if and only if err is a write conflict.

          func IsInternalError

          func IsInternalError(err error) bool

            IsInternalError returns true if and only if err is an InternalError.

            func IsInvalidError

            func IsInvalidError(err error) bool

              IsInvalidError returns true if and only if err is an InvalidError.

              func IsInvalidObj

              func IsInvalidObj(err error) bool

                IsInvalidObj returns true if and only if err is invalid error

                func IsNodeExist

                func IsNodeExist(err error) bool

                  IsNodeExist returns true if and only if err is an node already exist error.

                  func IsNotFound

                  func IsNotFound(err error) bool

                    IsNotFound returns true if and only if err is "key" not found error.

                    func IsTooLargeResourceVersion

                    func IsTooLargeResourceVersion(err error) bool

                      IsTooLargeResourceVersion returns true if the error is a TooLargeResourceVersion error.

                      func IsUnreachable

                      func IsUnreachable(err error) bool

                        IsUnreachable returns true if and only if err indicates the server could not be reached.

                        func LabelIndex

                        func LabelIndex(label string) string

                          LabelIndex add prefix for label index.

                          func NamespaceKeyFunc

                          func NamespaceKeyFunc(prefix string, obj runtime.Object) (string, error)

                          func NewTooLargeResourceVersionError

                          func NewTooLargeResourceVersionError(minimumResourceVersion, currentRevision uint64, retrySeconds int) error

                            NewTooLargeResourceVersionError returns a timeout error with the given retrySeconds for a request for a minimum resource version that is larger than the largest currently available resource version for a requested resource.

                            func NoNamespaceKeyFunc

                            func NoNamespaceKeyFunc(prefix string, obj runtime.Object) (string, error)

                            func ValidateAllObjectFunc

                            func ValidateAllObjectFunc(ctx context.Context, obj runtime.Object) error

                              ValidateAllObjectFunc is a "admit everything" instance of ValidateObjectFunc.

                              Types

                              type AttrFunc

                              type AttrFunc func(obj runtime.Object) (labels.Set, fields.Set, error)

                                AttrFunc returns label and field sets and the uninitialized flag for List or Watch to match. In any failure to parse given object, it returns error.

                                func (AttrFunc) WithFieldMutation

                                func (f AttrFunc) WithFieldMutation(fieldMutator FieldMutationFunc) AttrFunc

                                type FieldMutationFunc

                                type FieldMutationFunc func(obj runtime.Object, fieldSet fields.Set) error

                                  FieldMutationFunc allows the mutation of the field selection fields. It is mutating to avoid the extra allocation on this common path

                                  type GetOptions

                                  type GetOptions struct {
                                  	// IgnoreNotFound determines what is returned if the requested object is not found. If
                                  	// true, a zero object is returned. If false, an error is returned.
                                  	IgnoreNotFound bool
                                  	// ResourceVersion provides a resource version constraint to apply to the get operation
                                  	// as a "not older than" constraint: the result contains data at least as new as the provided
                                  	// ResourceVersion. The newest available data is preferred, but any data not older than this
                                  	// ResourceVersion may be served.
                                  	ResourceVersion string
                                  }

                                    GetOptions provides the options that may be provided for storage get operations.

                                    type HighWaterMark

                                    type HighWaterMark int64

                                      HighWaterMark is a thread-safe object for tracking the maximum value seen for some quantity.

                                      func (*HighWaterMark) Update

                                      func (hwm *HighWaterMark) Update(current int64) bool

                                        Update returns true if and only if 'current' is the highest value ever seen.

                                        type IndexerFunc

                                        type IndexerFunc func(obj runtime.Object) string

                                          IndexerFunc is a function that for a given object computes <value of an index> for a particular <index>.

                                          type IndexerFuncs

                                          type IndexerFuncs map[string]IndexerFunc

                                            IndexerFuncs is a mapping from <index name> to function that for a given object computes <value for that index>.

                                            type Interface

                                            type Interface interface {
                                            	// Returns Versioner associated with this interface.
                                            	Versioner() Versioner
                                            
                                            	// Create adds a new object at a key unless it already exists. 'ttl' is time-to-live
                                            	// in seconds (0 means forever). If no error is returned and out is not nil, out will be
                                            	// set to the read value from database.
                                            	Create(ctx context.Context, key string, obj, out runtime.Object, ttl uint64) error
                                            
                                            	// Delete removes the specified key and returns the value that existed at that spot.
                                            	// If key didn't exist, it will return NotFound storage error.
                                            	// If 'cachedExistingObject' is non-nil, it can be used as a suggestion about the
                                            	// current version of the object to avoid read operation from storage to get it.
                                            	// However, the implementations have to retry in case suggestion is stale.
                                            	Delete(
                                            		ctx context.Context, key string, out runtime.Object, preconditions *Preconditions,
                                            		validateDeletion ValidateObjectFunc, cachedExistingObject runtime.Object) error
                                            
                                            	// Watch begins watching the specified key. Events are decoded into API objects,
                                            	// and any items selected by 'p' are sent down to returned watch.Interface.
                                            	// resourceVersion may be used to specify what version to begin watching,
                                            	// which should be the current resourceVersion, and no longer rv+1
                                            	// (e.g. reconnecting without missing any updates).
                                            	// If resource version is "0", this interface will get current object at given key
                                            	// and send it in an "ADDED" event, before watch starts.
                                            	Watch(ctx context.Context, key string, opts ListOptions) (watch.Interface, error)
                                            
                                            	// WatchList begins watching the specified key's items. Items are decoded into API
                                            	// objects and any item selected by 'p' are sent down to returned watch.Interface.
                                            	// resourceVersion may be used to specify what version to begin watching,
                                            	// which should be the current resourceVersion, and no longer rv+1
                                            	// (e.g. reconnecting without missing any updates).
                                            	// If resource version is "0", this interface will list current objects directory defined by key
                                            	// and send them in "ADDED" events, before watch starts.
                                            	WatchList(ctx context.Context, key string, opts ListOptions) (watch.Interface, error)
                                            
                                            	// Get unmarshals json found at key into objPtr. On a not found error, will either
                                            	// return a zero object of the requested type, or an error, depending on 'opts.ignoreNotFound'.
                                            	// Treats empty responses and nil response nodes exactly like a not found error.
                                            	// The returned contents may be delayed, but it is guaranteed that they will
                                            	// match 'opts.ResourceVersion' according 'opts.ResourceVersionMatch'.
                                            	Get(ctx context.Context, key string, opts GetOptions, objPtr runtime.Object) error
                                            
                                            	// GetToList unmarshals json found at key and opaque it into *List api object
                                            	// (an object that satisfies the runtime.IsList definition).
                                            	// The returned contents may be delayed, but it is guaranteed that they will
                                            	// match 'opts.ResourceVersion' according 'opts.ResourceVersionMatch'.
                                            	GetToList(ctx context.Context, key string, opts ListOptions, listObj runtime.Object) error
                                            
                                            	// List unmarshalls jsons found at directory defined by key and opaque them
                                            	// into *List api object (an object that satisfies runtime.IsList definition).
                                            	// The returned contents may be delayed, but it is guaranteed that they will
                                            	// match 'opts.ResourceVersion' according 'opts.ResourceVersionMatch'.
                                            	List(ctx context.Context, key string, opts ListOptions, listObj runtime.Object) error
                                            
                                            	// GuaranteedUpdate keeps calling 'tryUpdate()' to update key 'key' (of type 'ptrToType')
                                            	// retrying the update until success if there is index conflict.
                                            	// Note that object passed to tryUpdate may change across invocations of tryUpdate() if
                                            	// other writers are simultaneously updating it, so tryUpdate() needs to take into account
                                            	// the current contents of the object when deciding how the update object should look.
                                            	// If the key doesn't exist, it will return NotFound storage error if ignoreNotFound=false
                                            	// or zero value in 'ptrToType' parameter otherwise.
                                            	// If the object to update has the same value as previous, it won't do any update
                                            	// but will return the object in 'ptrToType' parameter.
                                            	// If 'cachedExistingObject' is non-nil, it can be used as a suggestion about the
                                            	// current version of the object to avoid read operation from storage to get it.
                                            	// However, the implementations have to retry in case suggestion is stale.
                                            	//
                                            	// Example:
                                            	//
                                            	// s := /* implementation of Interface */
                                            	// err := s.GuaranteedUpdate(
                                            	//     "myKey", &MyType{}, true,
                                            	//     func(input runtime.Object, res ResponseMeta) (runtime.Object, *uint64, error) {
                                            	//       // Before each invocation of the user defined function, "input" is reset to
                                            	//       // current contents for "myKey" in database.
                                            	//       curr := input.(*MyType)  // Guaranteed to succeed.
                                            	//
                                            	//       // Make the modification
                                            	//       curr.Counter++
                                            	//
                                            	//       // Return the modified object - return an error to stop iterating. Return
                                            	//       // a uint64 to alter the TTL on the object, or nil to keep it the same value.
                                            	//       return cur, nil, nil
                                            	//    },
                                            	// )
                                            	GuaranteedUpdate(
                                            		ctx context.Context, key string, ptrToType runtime.Object, ignoreNotFound bool,
                                            		precondtions *Preconditions, tryUpdate UpdateFunc, cachedExistingObject runtime.Object) error
                                            
                                            	// Count returns number of different entries under the key (generally being path prefix).
                                            	Count(key string) (int64, error)
                                            }

                                              Interface offers a common interface for object marshaling/unmarshaling operations and hides all the storage-related operations behind it.

                                              type InternalError

                                              type InternalError struct {
                                              	Reason string
                                              }

                                                InternalError is generated when an error occurs in the storage package, i.e., not from the underlying storage backend (e.g., etcd).

                                                func NewInternalError

                                                func NewInternalError(reason string) InternalError

                                                func NewInternalErrorf

                                                func NewInternalErrorf(format string, a ...interface{}) InternalError

                                                func (InternalError) Error

                                                func (e InternalError) Error() string

                                                type InvalidError

                                                type InvalidError struct {
                                                	Errs field.ErrorList
                                                }

                                                  InvalidError is generated when an error caused by invalid API object occurs in the storage package.

                                                  func NewInvalidError

                                                  func NewInvalidError(errors field.ErrorList) InvalidError

                                                  func (InvalidError) Error

                                                  func (e InvalidError) Error() string

                                                  type ListOptions

                                                  type ListOptions struct {
                                                  	// ResourceVersion provides a resource version constraint to apply to the list operation
                                                  	// as a "not older than" constraint: the result contains data at least as new as the provided
                                                  	// ResourceVersion. The newest available data is preferred, but any data not older than this
                                                  	// ResourceVersion may be served.
                                                  	ResourceVersion string
                                                  	// ResourceVersionMatch provides the rule for how the resource version constraint applies. If set
                                                  	// to the default value "" the legacy resource version semantic apply.
                                                  	ResourceVersionMatch metav1.ResourceVersionMatch
                                                  	// Predicate provides the selection rules for the list operation.
                                                  	Predicate SelectionPredicate
                                                  	// ProgressNotify determines whether storage-originated bookmark (progress notify) events should
                                                  	// be delivered to the users. The option is ignored for non-watch requests.
                                                  	ProgressNotify bool
                                                  }

                                                    ListOptions provides the options that may be provided for storage list operations.

                                                    type MatchValue

                                                    type MatchValue struct {
                                                    	IndexName string
                                                    	Value     string
                                                    }

                                                      MatchValue defines a pair (<index name>, <value for that index>).

                                                      type Preconditions

                                                      type Preconditions struct {
                                                      	// Specifies the target UID.
                                                      	// +optional
                                                      	UID *types.UID `json:"uid,omitempty"`
                                                      	// Specifies the target ResourceVersion
                                                      	// +optional
                                                      	ResourceVersion *string `json:"resourceVersion,omitempty"`
                                                      }

                                                        Preconditions must be fulfilled before an operation (update, delete, etc.) is carried out.

                                                        func NewUIDPreconditions

                                                        func NewUIDPreconditions(uid string) *Preconditions

                                                          NewUIDPreconditions returns a Preconditions with UID set.

                                                          func (*Preconditions) Check

                                                          func (p *Preconditions) Check(key string, obj runtime.Object) error

                                                          type ResponseMeta

                                                          type ResponseMeta struct {
                                                          	// TTL is the time to live of the node that contained the returned object. It may be
                                                          	// zero or negative in some cases (objects may be expired after the requested
                                                          	// expiration time due to server lag).
                                                          	TTL int64
                                                          	// The resource version of the node that contained the returned object.
                                                          	ResourceVersion uint64
                                                          }

                                                            ResponseMeta contains information about the database metadata that is associated with an object. It abstracts the actual underlying objects to prevent coupling with concrete database and to improve testability.

                                                            type SelectionPredicate

                                                            type SelectionPredicate struct {
                                                            	Label               labels.Selector
                                                            	Field               fields.Selector
                                                            	GetAttrs            AttrFunc
                                                            	IndexLabels         []string
                                                            	IndexFields         []string
                                                            	Limit               int64
                                                            	Continue            string
                                                            	AllowWatchBookmarks bool
                                                            }

                                                              SelectionPredicate is used to represent the way to select objects from api storage.

                                                              func (*SelectionPredicate) Empty

                                                              func (s *SelectionPredicate) Empty() bool

                                                                Empty returns true if the predicate performs no filtering.

                                                                func (*SelectionPredicate) MatcherIndex

                                                                func (s *SelectionPredicate) MatcherIndex() []MatchValue

                                                                  For any index defined by IndexFields, if a matcher can match only (a subset) of objects that return <value> for a given index, a pair (<index name>, <value>) wil be returned.

                                                                  func (*SelectionPredicate) Matches

                                                                  func (s *SelectionPredicate) Matches(obj runtime.Object) (bool, error)

                                                                    Matches returns true if the given object's labels and fields (as returned by s.GetAttrs) match s.Label and s.Field. An error is returned if s.GetAttrs fails.

                                                                    func (*SelectionPredicate) MatchesObjectAttributes

                                                                    func (s *SelectionPredicate) MatchesObjectAttributes(l labels.Set, f fields.Set) bool

                                                                      MatchesObjectAttributes returns true if the given labels and fields match s.Label and s.Field.

                                                                      func (*SelectionPredicate) MatchesSingle

                                                                      func (s *SelectionPredicate) MatchesSingle() (string, bool)

                                                                        MatchesSingle will return (name, true) if and only if s.Field matches on the object's name.

                                                                        type SimpleUpdateFunc

                                                                        type SimpleUpdateFunc func(runtime.Object) (runtime.Object, error)

                                                                        type StorageError

                                                                        type StorageError struct {
                                                                        	Code               int
                                                                        	Key                string
                                                                        	ResourceVersion    int64
                                                                        	AdditionalErrorMsg string
                                                                        }

                                                                        func NewInvalidObjError

                                                                        func NewInvalidObjError(key, msg string) *StorageError

                                                                        func NewKeyExistsError

                                                                        func NewKeyExistsError(key string, rv int64) *StorageError

                                                                        func NewKeyNotFoundError

                                                                        func NewKeyNotFoundError(key string, rv int64) *StorageError

                                                                        func NewResourceVersionConflictsError

                                                                        func NewResourceVersionConflictsError(key string, rv int64) *StorageError

                                                                        func NewUnreachableError

                                                                        func NewUnreachableError(key string, rv int64) *StorageError

                                                                        func (*StorageError) Error

                                                                        func (e *StorageError) Error() string

                                                                        type UpdateFunc

                                                                        type UpdateFunc func(input runtime.Object, res ResponseMeta) (output runtime.Object, ttl *uint64, err error)

                                                                          Pass an UpdateFunc to Interface.GuaranteedUpdate to make an update that is guaranteed to succeed. See the comment for GuaranteedUpdate for more details.

                                                                          func SimpleUpdate

                                                                          func SimpleUpdate(fn SimpleUpdateFunc) UpdateFunc

                                                                            SimpleUpdateFunc converts SimpleUpdateFunc into UpdateFunc

                                                                            type ValidateObjectFunc

                                                                            type ValidateObjectFunc func(ctx context.Context, obj runtime.Object) error

                                                                              ValidateObjectFunc is a function to act on a given object. An error may be returned if the hook cannot be completed. The function may NOT transform the provided object.

                                                                              type Versioner

                                                                              type Versioner interface {
                                                                              	// UpdateObject sets storage metadata into an API object. Returns an error if the object
                                                                              	// cannot be updated correctly. May return nil if the requested object does not need metadata
                                                                              	// from database.
                                                                              	UpdateObject(obj runtime.Object, resourceVersion uint64) error
                                                                              	// UpdateList sets the resource version into an API list object. Returns an error if the object
                                                                              	// cannot be updated correctly. May return nil if the requested object does not need metadata from
                                                                              	// database. continueValue is optional and indicates that more results are available if the client
                                                                              	// passes that value to the server in a subsequent call. remainingItemCount indicates the number
                                                                              	// of remaining objects if the list is partial. The remainingItemCount field is omitted during
                                                                              	// serialization if it is set to nil.
                                                                              	UpdateList(obj runtime.Object, resourceVersion uint64, continueValue string, remainingItemCount *int64) error
                                                                              	// PrepareObjectForStorage should set SelfLink and ResourceVersion to the empty value. Should
                                                                              	// return an error if the specified object cannot be updated.
                                                                              	PrepareObjectForStorage(obj runtime.Object) error
                                                                              	// ObjectResourceVersion returns the resource version (for persistence) of the specified object.
                                                                              	// Should return an error if the specified object does not have a persistable version.
                                                                              	ObjectResourceVersion(obj runtime.Object) (uint64, error)
                                                                              
                                                                              	// ParseResourceVersion takes a resource version argument and
                                                                              	// converts it to the storage backend. For watch we should pass to helper.Watch().
                                                                              	// Because resourceVersion is an opaque value, the default watch
                                                                              	// behavior for non-zero watch is to watch the next value (if you pass
                                                                              	// "1", you will see updates from "2" onwards).
                                                                              	ParseResourceVersion(resourceVersion string) (uint64, error)
                                                                              }

                                                                                Versioner abstracts setting and retrieving metadata fields from database response onto the object ot list. It is required to maintain storage invariants - updating an object twice with the same data except for the ResourceVersion and SelfLink must be a no-op. A resourceVersion of type uint64 is a 'raw' resourceVersion, intended to be sent directly to or from the backend. A resourceVersion of type string is a 'safe' resourceVersion, intended for consumption by users.

                                                                                Directories

                                                                                Path Synopsis
                                                                                Package storage provides conversion of storage errors to API errors.
                                                                                Package storage provides conversion of storage errors to API errors.
                                                                                Package value contains methods for assisting with transformation of values in storage.
                                                                                Package value contains methods for assisting with transformation of values in storage.
                                                                                encrypt/aes
                                                                                Package aes transforms values for storage at rest using AES-GCM.
                                                                                Package aes transforms values for storage at rest using AES-GCM.
                                                                                encrypt/envelope
                                                                                Package envelope transforms values for storage at rest using a Envelope provider Package envelope transforms values for storage at rest using a Envelope provider
                                                                                Package envelope transforms values for storage at rest using a Envelope provider Package envelope transforms values for storage at rest using a Envelope provider
                                                                                encrypt/envelope/v1beta1
                                                                                Package v1beta1 contains definition of kms-plugin's gRPC service.
                                                                                Package v1beta1 contains definition of kms-plugin's gRPC service.
                                                                                encrypt/secretbox
                                                                                Package secretbox transforms values for storage at rest using XSalsa20 and Poly1305.
                                                                                Package secretbox transforms values for storage at rest using XSalsa20 and Poly1305.