store.go

// Package store provides the interface for a key-value store with different backends
package store

import (
	"encoding/json"
	"errors"
)

var (
	// ErrKeyNotFound is returned when key was not found.
	ErrKeyNotFound = errors.New("key not found")
	// ErrResponseChannelClosed will be returned if the response channel of the keep-alive is closed
	ErrResponseChannelClosed = errors.New("keepalive response channel has been closed")
)

// FilterFunc is a function that is called on (each) returned
// key-value pair during a Get request.
type FilterFunc func([]byte, []byte) bool

// HandlerFunc is a function that is called on (each) returned
// key-value pair during a Get request.
type HandlerFunc func([]byte, []byte) error

// ErrorFunc is a function called on (each) error not returned
type ErrorFunc func(error) error

// NotifyCallback is a function that is called after a watch create event
// is received.
type NotifyCallback func()

// Backend is the interface required for a key value store.
type Backend interface {
	// Put is used to insert or update an entry.
	//
	// The entry is added if the key exists or not.
	// If value is changed, true is returned, false is returned only if
	// value stays unchanged.
	//
	// If WithInsert option is used and the key already
	// exists, nothing is done and false is returned. If key does not exist
	// the entry is added and true is returned.
	Put(*Entry, ...PutOption) (bool, error)

	// Get is used to fetch an entry. If key is not found and WithPrefix is absent ErrKeyNotFound is
	// returned.
	Get(string, ...GetOption) ([]Entry, error)

	// Delete is used to permanently delte an entry. The number of deleted keys will be returned.
	Del(string, ...DelOption) (int64, error)

	// Watch a key
	Watch(string, Watcher, ...WatchOption) error

	// WatchChan creates a watcher for a key or prefix and unmarshals events into channel.
	// The channel elements have to implement the store.KeyOpSetter interface.
	WatchChan(string, interface{}, chan error, ...WatchOption) (WatchStarter, error)

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

// Watcher interface
type Watcher interface {
	BeforeWatch() error
	BeforeLoop() error
	OnDone() error
	OnPut([]byte, []byte) error
	OnDelete([]byte, []byte) error
}

// WatchStarter interface
type WatchStarter interface {
	Start()
}

// BackendKeyer interface extends Backend with key handling
type BackendKeyer interface {
	Backend
	RelKey(k string) string
	AbsKey(k string) string
	JoinKey(args ...string) string
	SplitKey(key string) []string
	KeyLeaf(key string) string
}

// Entry is used to represent data stored by the physical backend
type Entry struct {
	Key   string
	Value []byte
}

// Put is a wrapper around the Backend interface's Put method. This wrapper
// JSON marhals the interface v and uses the generated byte array as value.
func Put(b Backend, key string, v interface{}, opts ...PutOption) (bool, error) {
	data, err := json.Marshal(v)
	if err != nil {
		return false, err
	}

	return b.Put(&Entry{
		Key:   key,
		Value: data,
	}, opts...)
}

// EventMeta contains store events meta data.
type EventMeta struct {
	key string
	op  Operation
}

// SetKey sets the key.
func (e *EventMeta) SetKey(key string) {
	e.key = key
}

// Key gets the key.
func (e *EventMeta) Key() string {
	return e.key
}

// SetOp sets the operation.
func (e *EventMeta) SetOp(o Operation) {
	e.op = o
}

// Op gets the operation.
func (e *EventMeta) Op() Operation {
	return e.op
}

// KeyOpSetter interface.
type KeyOpSetter interface {
	SetKey(string)
	SetOp(Operation)
}

// KeyMarshaller sets struct fields from splitted key.
type KeyMarshaller interface {
	MarshalKey([]string) error
}

// Operation represents a store operation.
type Operation string

// All supported operations.
const (
	Create Operation = "create"
	Update Operation = "update"
	Delete Operation = "delete"
)