keyval

README

Key-value datastore

The keyval package defines the client API to access a key-value data store. It comprises two sub-APIs: the Broker interface supports reading and manipulation of key-value pairs; the Watcher API provides functions for monitoring of changes in a data store. Both interfaces are available with arguments of type []bytes and proto.Message.

The keyval package also provides a skeleton for a key-value plugin. The particular data store is selected in the NewSkeleton constructor using an argument of type CoreBrokerWatcher. The skeleton handles the plugin's life-cycle and provides unified access to datastore implementing the KvPlugin interface.

Documentation

Overview

Package keyval provides an abstraction of a key-value data store and defines the keyval data broker API. The Data Broker API consists of the ProtoBroker API, the KeyValProtoWatcher API, and other supporting APIs. It is used to access data in a key-value store.

Index

• Constants
• func ToChan(ch chan BytesWatchResp, opts ...interface{}) func(dto BytesWatchResp)
• func ToChanProto(ch chan ProtoWatchResp, opts ...interface{}) func(dto ProtoWatchResp)
• type BytesBroker
• type BytesKeyIterator
• type BytesKeyVal
• type BytesKeyValIterator
• type BytesKvPair
• type BytesTxn
• type BytesWatchResp
• type BytesWatcher
• type CoreBrokerWatcher
• type KvBytesPlugin
• type KvProtoPlugin
• type ProtoBroker
• type ProtoKeyIterator
• type ProtoKeyVal
• type ProtoKeyValIterator
• type ProtoKvPair
• type ProtoTxn
• type ProtoWatchResp
• type ProtoWatcher
• type Serializer
• type SerializerJSON
  • func (sj *SerializerJSON) Marshal(message proto.Message) ([]byte, error)
  • func (sj *SerializerJSON) Unmarshal(data []byte, protoData proto.Message) error
• type SerializerProto
  • func (sp *SerializerProto) Marshal(message proto.Message) ([]byte, error)
  • func (sp *SerializerProto) Unmarshal(data []byte, protoData proto.Message) error

Constants

const Root = ""

Root denotes that no prefix is prepended to the keys.

Functions

func ToChan

func ToChan(ch chan BytesWatchResp, opts ...interface{}) func(dto BytesWatchResp)

ToChan creates a callback that can be passed to the Watch function in order to receive notifications through a channel. If the notification can not be delivered until timeout it is dropped.

func ToChanProto

func ToChanProto(ch chan ProtoWatchResp, opts ...interface{}) func(dto ProtoWatchResp)

ToChanProto creates a callback that can be passed to the Watch function in order to receive notifications through a channel. If the notification can not be delivered until timeout it is dropped.

Types

type BytesBroker

type BytesBroker interface {
	// Put puts single key-value pair into etcd. The behavior of put can be adjusted using PutOptions.
	Put(key string, data []byte, opts ...datasync.PutOption) error
	// NewTxn creates a transaction
	NewTxn() BytesTxn
	// GetValue retrieves one item under the provided key
	GetValue(key string) (data []byte, found bool, revision int64, err error)
	// ListValues returns an iterator that enables to traverse all items stored under the provided key
	ListValues(key string) (BytesKeyValIterator, error)
	// ListKeys is similar to the ListValues the difference is that values are not fetched
	ListKeys(prefix string) (BytesKeyIterator, error)
	// Delete removes data stored under the key
	Delete(key string, opts ...datasync.DelOption) (existed bool, err error)
}

BytesBroker allows to store, retrieve and remove data in a key-value form

type BytesKeyIterator

type BytesKeyIterator interface {
	// GetNext retrieves the following item from the context.
	GetNext() (key string, rev int64, stop bool)
}

BytesKeyIterator is an iterator returned by ListKeys call

type BytesKeyVal

type BytesKeyVal interface {
	BytesKvPair
	datasync.WithRevision
}

BytesKeyVal represents a single item in data store

type BytesKeyValIterator

type BytesKeyValIterator interface {
	// GetNext retrieves the following item from the context.
	GetNext() (kv BytesKeyVal, stop bool)
}

BytesKeyValIterator is an iterator returned by ListValues call

type BytesKvPair

type BytesKvPair interface {
	// GetValue returns the value of the pair
	GetValue() []byte

	datasync.WithKey
}

BytesKvPair groups getters for key-value pair

type BytesTxn

type BytesTxn interface {
	// Put adds store operation into transaction
	Put(key string, data []byte) BytesTxn
	// Delete adds delete operation, which removes value identified by the key, into the transaction
	Delete(key string) BytesTxn
	// Commit tries to commit the transaction
	Commit() error
}

BytesTxn allows to group operations into the transaction. Transaction executes multiple operations in a more efficient way in contrast to executing them one by one.

type BytesWatchResp

type BytesWatchResp interface {
	BytesKvPair
	datasync.WithChangeType
	datasync.WithRevision
}

BytesWatchResp represents a notification about change. It is sent through the watch resp channel.

type BytesWatcher

type BytesWatcher interface {
	// Watch starts subscription for changes associated with the selected keys.
	// Watch events will be delivered to respChan.
	Watch(respChan func(BytesWatchResp), keys ...string) error
}

BytesWatcher define API for monitoring changes in datastore

type CoreBrokerWatcher

type CoreBrokerWatcher interface {
	BytesBroker
	BytesWatcher
	NewBroker(prefix string) BytesBroker
	NewWatcher(prefix string) BytesWatcher
	Close() error
}

CoreBrokerWatcher defines methods for full datastore access.

type KvBytesPlugin

type KvBytesPlugin interface {
	// NewPrefixedBroker returns a BytesBroker instance that prepends given keyPrefix to all keys in its calls. To avoid
	// using a prefix pass keyval.Root constant as argument.
	NewBroker(keyPrefix string) BytesBroker
	// NewPrefixedWatcher returns a BytesWatcher instance. Given key prefix is prepended to keys during watch subscribe phase.
	// The prefix is removed from the key retrieved by GetKey() in BytesWatchResp. To avoid  using a prefix pass keyval.Root constant as argument.
	NewWatcher(keyPrefix string) BytesWatcher
}

KvBytesPlugin provides unifying interface for different key-value datastore implementations.

type KvProtoPlugin

type KvProtoPlugin interface {
	// NewPrefixedBroker returns a ProtoBroker instance that prepends given keyPrefix to all keys in its calls. To avoid
	// using a prefix pass keyval.Root constant as argument.
	NewBroker(keyPrefix string) ProtoBroker
	// NewPrefixedWatcher returns a ProtoWatcher instance. Given key prefix is prepended to keys during watch subscribe phase.
	// The prefix is removed from the key retrieved by GetKey() in ProtoWatchResp. To avoid  using a prefix pass keyval.Root constant as argument.
	NewWatcher(keyPrefix string) ProtoWatcher
	// Disabled returns true if there was no configuration and therefore agent
	// started without connectivity to a particular data store
	Disabled() bool
}

KvProtoPlugin provides unifying interface for different key-value datastore implementations.

type ProtoBroker

type ProtoBroker interface {
	// Put puts single key-value pair into key value store
	datasync.KeyProtoValWriter
	// NewTxn creates a transaction
	NewTxn() ProtoTxn
	// GetValue retrieves one item under the provided key. If the item exists it is unmarshaled into the reqObj.
	GetValue(key string, reqObj proto.Message) (found bool, revision int64, err error)
	// ListValues returns an iterator that enables to traverse all items stored under the provided key
	ListValues(key string) (ProtoKeyValIterator, error)
	// ListKeys is similar to the ListValues the difference is that values are not fetched
	ListKeys(prefix string) (ProtoKeyIterator, error)
	// Delete removes data stored under the key
	Delete(key string, opts ...datasync.DelOption) (existed bool, err error)
}

ProtoBroker is decorator that allows to read/write proto file modelled data. It marshals/unmarshals go structures to slice of bytes and vice versa behind the scenes.

type ProtoKeyIterator

type ProtoKeyIterator interface {
	// GetNext retrieves the following item from the context.
	GetNext() (key string, rev int64, stop bool)
	// Closer is needed for closing the iterator (please check error returned by Close method)
	io.Closer
}

ProtoKeyIterator is an iterator returned by ListKeys call

type ProtoKeyVal

type ProtoKeyVal interface {
	ProtoKvPair
	datasync.WithRevision
}

ProtoKeyVal represents a single key-value pair

type ProtoKeyValIterator

type ProtoKeyValIterator interface {
	// GetNext retrieves the following value from the context. GetValue is unmarshaled into the provided argument.
	GetNext() (kv ProtoKeyVal, stop bool)
	// Closer is needed for closing the iterator (please check error returned by Close method)
	io.Closer
}

ProtoKeyValIterator is an iterator returned by ListValues call.

type ProtoKvPair

type ProtoKvPair interface {
	datasync.LazyValue
	datasync.WithKey
}

ProtoKvPair group getter for single key-value pair

type ProtoTxn

type ProtoTxn interface {
	// Put adds put operation into the transaction
	Put(key string, data proto.Message) ProtoTxn
	// Delete adds delete operation, which removes value identified by the key, into the transaction
	Delete(key string) ProtoTxn
	// Commit tries to commit the transaction.
	Commit() error
}

ProtoTxn allows to group operations into the transaction. Transaction executes multiple operations in a more efficient way in contrast to executing them one by one.

type ProtoWatchResp

type ProtoWatchResp interface {
	datasync.ChangeValue
	datasync.WithKey
}

ProtoWatchResp represents a notification about change. It is sent through the watch resp channel.

type ProtoWatcher

type ProtoWatcher interface {
	// Watch starts to monitor changes associated with the keys. Watch events will be delivered to respChan.
	Watch(respChan func(ProtoWatchResp), key ...string) error
}

ProtoWatcher define API for monitoring changes in a datastore

type Serializer

type Serializer interface {
	Unmarshal(data []byte, protoData proto.Message) error
	Marshal(message proto.Message) ([]byte, error)
}

Serializer is responsible for transformation of data stored in etcd.

type SerializerJSON

type SerializerJSON struct{}

SerializerJSON serialize proto message using json serializer

func (*SerializerJSON) Marshal

func (sj *SerializerJSON) Marshal(message proto.Message) ([]byte, error)

Marshal marshals proto message using json marshaller

func (*SerializerJSON) Unmarshal

func (sj *SerializerJSON) Unmarshal(data []byte, protoData proto.Message) error

Unmarshal unmarshals data from slice of bytes into the provided protobuf message

type SerializerProto

type SerializerProto struct{}

SerializerProto serializes proto message using proto serializer

func (*SerializerProto) Marshal

func (sp *SerializerProto) Marshal(message proto.Message) ([]byte, error)

Marshal transforms data from proto message to the slice of bytes using proto marshaller

func (*SerializerProto) Unmarshal

func (sp *SerializerProto) Unmarshal(data []byte, protoData proto.Message) error

Unmarshal unmarshals data from slice of bytes into the provided protobuf message