store

Documentation

Overview

Package store contains KV store backends.

Index

• Variables
• func CreateEndpoints(addrs []string, scheme string) (entries []string)
• func GetDirectory(key string) string
• func Normalize(key string) string
• func SplitKey(key string) (path []string)
• type Backend
• type ClientTLSConfig
• type Config
• type KVPair
• type LockOptions
• type Locker
• type ReadOptions
• type Store
• type WriteOptions

Variables

var (
	// ErrBackendNotSupported is thrown when the backend k/v store is not supported by kvdb.
	ErrBackendNotSupported = errors.New("backend storage not supported yet, please choose one of")
	// ErrCallNotSupported is thrown when a method is not implemented/supported by the current backend.
	ErrCallNotSupported = errors.New("the current call is not supported with this backend")
	// ErrNotReachable is thrown when the API cannot be reached for issuing common store operations.
	ErrNotReachable = errors.New("api not reachable")
	// ErrCannotLock is thrown when there is an error acquiring a lock on a key.
	ErrCannotLock = errors.New("error acquiring the lock")
	// ErrKeyModified is thrown during an atomic operation if the index does not match the one in the store.
	ErrKeyModified = errors.New("unable to complete atomic operation, key modified")
	// ErrKeyNotFound is thrown when the key is not found in the store during a Get operation.
	ErrKeyNotFound = errors.New("key not found in store")
	// ErrPreviousNotSpecified is thrown when the previous value is not specified for an atomic operation.
	ErrPreviousNotSpecified = errors.New("previous K/V pair should be provided for the Atomic operation")
	// ErrKeyExists is thrown when the previous value exists in the case of an AtomicPut.
	ErrKeyExists = errors.New("previous K/V pair exists, cannot complete Atomic operation")
)

Functions

func CreateEndpoints

func CreateEndpoints(addrs []string, scheme string) (entries []string)

CreateEndpoints creates a list of endpoints given the right scheme.

func GetDirectory

func GetDirectory(key string) string

GetDirectory gets the full directory part of the key to the form:

/path/to/

func Normalize

func Normalize(key string) string

Normalize the key for each store to the form:

/path/to/key

func SplitKey

func SplitKey(key string) (path []string)

SplitKey splits the key to extract path information.

Types

type Backend

type Backend string

Backend represents a KV Store Backend.

const (
	// CONSUL backend.
	CONSUL Backend = "consul"
	// ETCD backend with v2 client (backward compatibility).
	ETCD Backend = "etcd"
	// ETCDV3 backend with v3 client.
	ETCDV3 Backend = "etcdv3"
	// ZK backend.
	ZK Backend = "zk"
	// BOLTDB backend.
	BOLTDB Backend = "boltdb"
	// REDIS backend.
	REDIS Backend = "redis"
	// DYNAMODB backend.
	DYNAMODB Backend = "dynamodb"
)

type ClientTLSConfig

type ClientTLSConfig struct {
	CertFile   string
	KeyFile    string
	CACertFile string
}

ClientTLSConfig contains data for a Client TLS configuration in the form the etcd client wants it. Eventually we'll adapt it for ZK and Consul.

type Config

type Config struct {
	ClientTLS         *ClientTLSConfig
	TLS               *tls.Config
	ConnectionTimeout time.Duration
	SyncPeriod        time.Duration
	Bucket            string
	PersistConnection bool
	Username          string
	Password          string
	Token             string
	Namespace         string
}

Config contains the options for a storage client.

type KVPair

type KVPair struct {
	Key       string
	Value     []byte
	LastIndex uint64
}

KVPair represents {Key, Value, LastIndex} tuple.

type LockOptions

type LockOptions struct {
	Value          []byte        // Optional, value to associate with the lock.
	TTL            time.Duration // Optional, expiration ttl associated with the lock.
	RenewLock      chan struct{} // Optional, chan used to control and stop the session ttl renewal for the lock.
	DeleteOnUnlock bool          // If true, the value will be deleted when the lock is unlocked or expires.
}

LockOptions contains optional request parameters.

type Locker

type Locker interface {
	Lock(ctx context.Context, stopChan chan struct{}) (<-chan struct{}, error)
	Unlock(ctx context.Context) error
}

Locker provides locking mechanism on top of the store. Similar to sync.Locker except it may return errors.

type ReadOptions

type ReadOptions struct {
	// Consistent defines if the behavior of a Get operation is linearizable or not.
	// Linearizability allows us to 'see' objects based on a real-time total order
	// as opposed to an arbitrary order or with stale values ('inconsistent' scenario).
	Consistent bool
}

ReadOptions contains optional request parameters.

type Store

type Store interface {
	// Put a value at the specified key.
	Put(ctx context.Context, key string, value []byte, options *WriteOptions) error

	// Get a value given its key.
	Get(ctx context.Context, key string, options *ReadOptions) (*KVPair, error)

	// Delete the value at the specified key.
	Delete(ctx context.Context, key string) error

	// Exists Verify if a Key exists in the store.
	Exists(ctx context.Context, key string, options *ReadOptions) (bool, error)

	// Watch for changes on a key.
	Watch(ctx context.Context, key string, stopCh <-chan struct{}, options *ReadOptions) (<-chan *KVPair, error)

	// WatchTree watches for changes on child nodes under a given directory.
	WatchTree(ctx context.Context, directory string, stopCh <-chan struct{}, options *ReadOptions) (<-chan []*KVPair, error)

	// NewLock creates a lock for a given key.
	// The returned Locker is not held and must be acquired with `.Lock`.
	// The Value is optional.
	NewLock(ctx context.Context, key string, options *LockOptions) (Locker, error)

	// List the content of a given prefix.
	List(ctx context.Context, directory string, options *ReadOptions) ([]*KVPair, error)

	// DeleteTree deletes a range of keys under a given directory.
	DeleteTree(ctx context.Context, directory string) error

	// AtomicPut Atomic CAS operation on a single value.
	// Pass previous = nil to create a new key.
	AtomicPut(ctx context.Context, key string, value []byte, previous *KVPair, options *WriteOptions) (bool, *KVPair, error)

	// AtomicDelete Atomic delete of a single value.
	AtomicDelete(ctx context.Context, key string, previous *KVPair) (bool, error)

	// Close the store connection.
	Close() error
}

Store represents the backend K/V storage. Each store should support every call listed here. Or it couldn't be implemented as a K/V backend for kvdb.

type WriteOptions

type WriteOptions struct {
	IsDir bool
	TTL   time.Duration

	// If true, the client will keep the lease alive in the background
	// for stores that are allowing it.
	KeepAlive bool
}

WriteOptions contains optional request parameters.