storage

package
v1.3.0-alpha.2 Latest Latest
Warning

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

 Go to latest Published: Apr 11, 2016 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Interfaces for database-related operations.

Index

Constants

View Source 
const (
	ErrCodeKeyNotFound int = iota + 1
	ErrCodeKeyExists
	ErrCodeResourceVersionConflicts
	ErrCodeInvalidObj
	ErrCodeUnreachable
)
View Source 
const (
	// MaximumListWait determines how long we're willing to wait for a
	// list if a client specified a resource version in the future.
	MaximumListWait = 60 * time.Second
)

Variables

This section is empty.

Functions

func Everything 

func Everything(runtime.Object) bool

Everything is a FilterFunc which accepts all objects.

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

IsInvalidUID returns true if and only if err is invalid UID error

func IsNodeExist added in v1.2.0 

func IsNodeExist(err error) bool

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

func IsNotFound added in v1.2.0 

func IsNotFound(err error) bool

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

func IsTestFailed added in v1.2.0 

func IsTestFailed(err error) bool

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

func IsUnreachable added in v1.2.0 

func IsUnreachable(err error) bool

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

func NamespaceKeyFunc 

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

func NoNamespaceKeyFunc 

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

func ParseListResourceVersion added in v1.2.0 

func ParseListResourceVersion(resourceVersion string) (uint64, error)

ParseListResourceVersion takes a resource version argument and converts it to the etcd version.

func ParseWatchResourceVersion 

func ParseWatchResourceVersion(resourceVersion string) (uint64, error)

ParseWatchResourceVersion takes a resource version argument and converts it to the etcd version 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).

Types

type Cacher 

type Cacher struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Cacher is responsible for serving WATCH and LIST requests for a given resource from its internal cache and updating its cache in the background based on the underlying storage contents. Cacher implements storage.Interface (although most of the calls are just delegated to the underlying storage).

func NewCacherFromConfig added in v1.2.0 

func NewCacherFromConfig(config CacherConfig) *Cacher

Create a new Cacher responsible from service WATCH and LIST requests from its internal cache and updating its cache in the background based on the given configuration.

func (*Cacher) Backends 

func (c *Cacher) Backends(ctx context.Context) []string

Implements storage.Interface.

func (*Cacher) Codec 

func (c *Cacher) Codec() runtime.Codec

Implements storage.Interface.

func (*Cacher) Create 

func (c *Cacher) Create(ctx context.Context, key string, obj, out runtime.Object, ttl uint64) error

Implements storage.Interface.

func (*Cacher) Delete 

func (c *Cacher) Delete(ctx context.Context, key string, out runtime.Object, preconditions *Preconditions) error

Implements storage.Interface.

func (*Cacher) Get 

func (c *Cacher) Get(ctx context.Context, key string, objPtr runtime.Object, ignoreNotFound bool) error

Implements storage.Interface.

func (*Cacher) GetToList 

func (c *Cacher) GetToList(ctx context.Context, key string, filter FilterFunc, listObj runtime.Object) error

Implements storage.Interface.

func (*Cacher) GuaranteedUpdate 

func (c *Cacher) GuaranteedUpdate(ctx context.Context, key string, ptrToType runtime.Object, ignoreNotFound bool, preconditions *Preconditions, tryUpdate UpdateFunc) error

Implements storage.Interface.

func (*Cacher) LastSyncResourceVersion 

func (c *Cacher) LastSyncResourceVersion() (uint64, error)

Returns resource version to which the underlying cache is synced.

func (*Cacher) List 

func (c *Cacher) List(ctx context.Context, key string, resourceVersion string, filter FilterFunc, listObj runtime.Object) error

Implements storage.Interface.

func (*Cacher) Set 

func (c *Cacher) Set(ctx context.Context, key string, obj, out runtime.Object, ttl uint64) error

Implements storage.Interface.

func (*Cacher) Stop added in v1.2.0 

func (c *Cacher) Stop()

func (*Cacher) Versioner 

func (c *Cacher) Versioner() Versioner

Implements storage.Interface.

func (*Cacher) Watch 

func (c *Cacher) Watch(ctx context.Context, key string, resourceVersion string, filter FilterFunc) (watch.Interface, error)

Implements storage.Interface.

func (*Cacher) WatchList 

func (c *Cacher) WatchList(ctx context.Context, key string, resourceVersion string, filter FilterFunc) (watch.Interface, error)

Implements storage.Interface.

type CacherConfig 

type CacherConfig struct {
	// Maximum size of the history cached in memory.
	CacheCapacity int

	// An underlying storage.Interface.
	Storage Interface

	// An underlying storage.Versioner.
	Versioner Versioner

	// The Cache will be caching objects of a given Type and assumes that they
	// are all stored under ResourcePrefix directory in the underlying database.
	Type           interface{}
	ResourcePrefix string

	// KeyFunc is used to get a key in the underyling storage for a given object.
	KeyFunc func(runtime.Object) (string, error)

	// NewList is a function that creates new empty object storing a list of
	// objects of type Type.
	NewListFunc func() runtime.Object
}

CacherConfig contains the configuration for a given Cache.

type Config added in v1.2.0 

type Config interface {
	// Creates the Interface base on ConfigObject
	NewStorage() (Interface, error)

	// This function is used to enforce membership, and return the underlying type
	GetType() string
}

Config interface allows storage tiers to generate the proper storage.interface and reduce the dependencies to encapsulate storage.

type FilterFunc 

type FilterFunc func(obj runtime.Object) bool

FilterFunc is a predicate which takes an API object and returns true if and only if the object should remain in the set.

type Interface 

type Interface interface {
	// Returns list of servers addresses of the underyling database.
	// TODO: This method is used only in a single place. Consider refactoring and getting rid
	// of this method from the interface.
	Backends(ctx context.Context) []string

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

	// Set marshals obj via json and stores in database under key. Will do an atomic update
	// if obj's ResourceVersion field is set. '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.
	Set(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.
	Delete(ctx context.Context, key string, out runtime.Object, preconditions *Preconditions) error

	// Watch begins watching the specified key. Events are decoded into API objects,
	// and any items passing 'filter' 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).
	Watch(ctx context.Context, key string, resourceVersion string, filter FilterFunc) (watch.Interface, error)

	// WatchList begins watching the specified key's items. Items are decoded into API
	// objects and any item passing 'filter' 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).
	WatchList(ctx context.Context, key string, resourceVersion string, filter FilterFunc) (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 ignoreNotFound.
	// Treats empty responses and nil response nodes exactly like a not found error.
	Get(ctx context.Context, key string, objPtr runtime.Object, ignoreNotFound bool) error

	// GetToList unmarshals json found at key and opaque it into *List api object
	// (an object that satisfies the runtime.IsList definition).
	GetToList(ctx context.Context, key string, filter FilterFunc, 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
	// be have at least 'resourceVersion'.
	List(ctx context.Context, key string, resourceVersion string, filter FilterFunc, 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, to 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.
	//
	// Example:
	//
	// s := /* implementation of Interface */
	// err := s.GuaranteedUpdate(
	//     "myKey", &MyType{}, true,
	//     func(input runtime.Object, res ResponseMeta) (runtime.Object, *uint64, error) {
	//       // Before each incovation 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) error

	// Codec provides access to the underlying codec being used by the implementation.
	Codec() runtime.Codec
}

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

func NewCacher 

func NewCacher(
	storage Interface,
	capacity int,
	versioner Versioner,
	objectType runtime.Object,
	resourcePrefix string,
	scopeStrategy rest.NamespaceScopedStrategy,
	newListFunc func() runtime.Object) Interface

Create a new Cacher responsible from service WATCH and LIST requests from its internal cache and updating its cache in the background based on the given configuration.

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 Preconditions 

type Preconditions struct {
	// Specifies the target UID.
	UID *types.UID `json:"uid,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.

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
	// Expiration is the time at which the node that contained the returned object will expire and be deleted.
	// This can be nil if there is no expiration time set for the node.
	Expiration *time.Time
	// 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 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 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, expiration *time.Time, 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.
	UpdateList(obj runtime.Object, resourceVersion uint64) 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)
}

Versioner abstracts setting and retrieving metadata fields from database response onto the object ot list.

Source Files

View all Source files

Directories

Path Synopsis
etcdtest
metrics
testing
util
Package util holds generic etcd-related utility functions that any user of ectd might want to use, without pulling in kubernetes-specific code.
 Package util holds generic etcd-related utility functions that any user of ectd might want to use, without pulling in kubernetes-specific code.

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.