kvdb

type Controller interface {
	// AddMember adds a new member to an existing kvdb cluster. Add API should be
	// invoked on an existing kvdb node where kvdb is already running. It should be
	// followed by a Setup call on the node which is being added.
	// Returns: map of nodeID to peerUrls of all members in the initial cluster or error.
	AddMember(nodeIP, nodePeerPort, nodeName string) (map[string][]string, error)

	// AddLearner is same as AddMember except that the new member is added as a learner.
	// It is caller's responsibility to promote it to a full voting member.
	AddLearner(nodeIP, nodePeerPort, nodeName string) (map[string][]string, error)

	// RemoveMember removes a member based on its Name from an existing kvdb cluster.
	// Returns: error if it fails to remove a member
	RemoveMember(nodeName, nodeIP string) error

	// RemoveMemberByID removes a member based on its ID from an existing kvdb cluster.
	// Returns: error if it fails to remove a member
	RemoveMemberByID(memberID uint64) error

	// UpdateMember updates the IP for the given node in an existing kvdb cluster
	// Returns: map of nodeID to peerUrls of all members from the existing cluster
	UpdateMember(nodeIP, nodePeerPort, nodeName string) (map[string][]string, error)

	// ListMembers enumerates the members of the kvdb cluster. It includes both the
	// started and unstarted members.
	// Returns: the member's ID  to MemberInfo mappings for all the members
	ListMembers() (map[uint64]*MemberInfo, error)

	// SetEndpoints set the kvdb endpoints for the client
	SetEndpoints(endpoints []string) error

	// GetEndpoints returns the kvdb endpoints for the client
	GetEndpoints() []string

	// Defragment defrags the underlying database for the given endpoint
	// with a timeout specified in seconds
	Defragment(endpoint string, timeout int) error
}

type CopyKVPSelect func(kvp *KVPair, val interface{}) *KVPair

type CopySelect func(val interface{}) interface{}

type DatastoreInit func(domain string, machines []string, options map[string]string,
	cb FatalErrorCB) (Kvdb, error)

type DatastoreVersion func(url string, kvdbOptions map[string]string) (string, error)

type EnumerateKVPSelect func(kvp *KVPair, val interface{}) bool

type EnumerateSelect func(val interface{}) bool

type FatalErrorCB func(err error, format string, args ...interface{})

type KVAction int

type KVFlags uint64

type KVPair struct {
	// Key for this kv pair.
	Key string
	// Value for this kv pair
	Value []byte
	// Action the last action on this KVPair.
	Action KVAction
	// TTL value after which this key will expire from KVDB
	TTL int64
	// KVDBIndex A Monotonically index updated at each modification operation.
	KVDBIndex uint64
	// CreatedIndex for this kv pair
	CreatedIndex uint64
	// ModifiedIndex for this kv pair
	ModifiedIndex uint64
	// Lock is a generic interface to represent a lock held on a key.
	Lock interface{}
}

type KVPairs []*KVPair

type Kvdb interface {
	Controller
	// String representation of backend datastore.
	String() string
	// Capbilities - see KVCapabilityXXX
	Capabilities() int
	// Get returns KVPair that maps to specified key or ErrNotFound.
	Get(key string) (*KVPair, error)
	// Get returns KVPair that maps to specified key or ErrNotFound. If found
	// value contains the unmarshalled result or error is ErrUnmarshal
	GetVal(key string, value interface{}) (*KVPair, error)
	// GetWithCopy returns a copy of the value as an interface for the specified key
	GetWithCopy(key string, copySelect CopySelect) (interface{}, error)
	// Put inserts value at key in kvdb. If value is a runtime.Object, it is
	// marshalled. If Value is []byte it is set directly. If Value is a string,
	// its byte representation is stored.
	Put(key string, value interface{}, ttl uint64) (*KVPair, error)
	// Create is the same as Put except that ErrExist is returned if the key exists.
	Create(key string, value interface{}, ttl uint64) (*KVPair, error)
	// Update is the same as Put except that ErrNotFound is returned if the key
	// does not exist.
	Update(key string, value interface{}, ttl uint64) (*KVPair, error)
	// Enumerate returns a list of KVPair for all keys that share the specified prefix.
	Enumerate(prefix string) (KVPairs, error)
	// EnumerateWithSelect returns a copy of all values under the prefix that satisfy the select
	// function in the provided output array of interfaces
	EnumerateWithSelect(prefix string, enumerateSelect EnumerateSelect, copySelect CopySelect) ([]interface{}, error)
	// EnumerateKVPWithSelect returns a copy of all the KVPairs under the prefix that satisfy the select
	// function in the provided output array of key-value pairs
	EnumerateKVPWithSelect(prefix string, enumerateSelect EnumerateKVPSelect, copySelect CopyKVPSelect) (KVPairs, error)
	// Delete deletes the KVPair specified by the key. ErrNotFound is returned
	// if the key is not found. The old KVPair is returned if successful.
	Delete(key string) (*KVPair, error)
	// DeleteTree same as Delete execpt that all keys sharing the prefix are
	// deleted.
	DeleteTree(prefix string) error
	// Keys returns an array of keys that share specified prefix (ie. "1st level directory").
	// sep parameter defines a key-separator, and if not provided the "/" is assumed.
	Keys(prefix, sep string) ([]string, error)
	// CompareAndSet updates value at kvp.Key if the previous resident
	// satisfies conditions set in flags and optional prevValue.
	CompareAndSet(kvp *KVPair, flags KVFlags, prevValue []byte) (*KVPair, error)
	// CompareAndDelete deletes value at kvp.Key if the previous resident matches
	// satisfies conditions set in flags.
	CompareAndDelete(kvp *KVPair, flags KVFlags) (*KVPair, error)
	// WatchKey calls watchCB everytime a value at key is updated. waitIndex
	// is the oldest ModifiedIndex of a KVPair for which updates are requestd.
	WatchKey(key string, waitIndex uint64, opaque interface{}, watchCB WatchCB) error
	// WatchTree is the same as WatchKey except that watchCB is triggered
	// for updates on all keys that share the prefix.
	WatchTree(prefix string, waitIndex uint64, opaque interface{}, watchCB WatchCB) error
	// Snapshot returns a kvdb snapshot of the provided list of prefixes and the last updated index.
	// If no prefixes are provided, then the whole kvdb tree is snapshotted and could be potentially an expensive operation
	// If consistent is true, then snapshot is going to return all the updates happening during the snapshot operation and the last
	// updated index from the snapshot
	Snapshot(prefixes []string, consistent bool) (Kvdb, uint64, error)
	// SnapPut records the key value pair including the index.
	SnapPut(kvp *KVPair) (*KVPair, error)
	// LockWithID locks the specified key and associates a lockerID with it, probably to identify
	// who acquired the lock. The KVPair returned should be used to unlock.
	LockWithID(key string, lockerID string) (*KVPair, error)
	// Lock locks the specified key. The KVPair returned should be used to unlock.
	Lock(key string) (*KVPair, error)
	// LockWithTimeout locks with specified key and associates a lockerID with it.
	// lockTryDuration is the maximum time that can be spent trying to acquire
	// lock, else return error.
	// lockHoldDuration is the maximum time the lock can be held, after which
	// FatalCb is invoked.
	// The KVPair returned should be used to unlock if successful.
	LockWithTimeout(key string, lockerID string, lockTryDuration time.Duration,
		lockHoldDuration time.Duration) (*KVPair, error)
	// IsKeyLocked returns a boolean if the lock is held or not. If held, returns the owner.
	IsKeyLocked(key string) (bool, string, error)
	// Unlock kvp previously acquired through a call to lock.
	Unlock(kvp *KVPair) error
	// TxNew returns a new Tx coordinator object or ErrNotSupported
	TxNew() (Tx, error)
	// AddUser adds a new user to kvdb
	AddUser(username string, password string) error
	// RemoveUser removes a user from kvdb
	RemoveUser(username string) error
	// GrantUserAccess grants user access to a subtree/prefix based on the permission
	GrantUserAccess(username string, permType PermissionType, subtree string) error
	// RevokeUsersAccess revokes user's access to a subtree/prefix based on the permission
	RevokeUsersAccess(username string, permType PermissionType, subtree string) error
	// SetFatalCb sets the function to be called in case of fatal errors
	SetFatalCb(f FatalErrorCB)
	// SetLockHoldDuration sets maximum time a lock may be held
	SetLockHoldDuration(timeout time.Duration)
	// GetLockTryDuration gets the maximum time to attempt to get a lock.
	GetLockTryDuration() time.Duration
	// GetLockHoldDuration gets the currently set lock hold timeout
	GetLockHoldDuration() time.Duration
	// Serialize serializes all the keys under the domain and returns a byte array
	Serialize() ([]byte, error)
	// Deserialize deserializes the given byte array into a list of kv pairs
	Deserialize([]byte) (KVPairs, error)
	// Compact removes the history before the specified index/revision to reduce the space and memory usage
	Compact(index uint64) error
	KvdbWrapper
}

type KvdbWrapper interface {
	// WrapperName is the name of this wrapper
	WrapperName() WrapperName
	// WrappedKvdb is the Kvdb wrapped by this wrapper
	WrappedKvdb() Kvdb
	// Removed is called when wrapper is removed
	Removed()
	// WrappedKvdb is the Kvdb wrapped by this wrapper
	SetWrappedKvdb(kvdb Kvdb) error
}

type MemberInfo struct {
	// PeerUrls is this member's URL on which it talks to its peers
	PeerUrls []string
	// ClientUrls is this member's URL on which clients can reach this member.
	ClientUrls []string
	// Leader indicates if this member is the leader of this cluster.
	Leader bool
	// DbSize is the current DB size as seen by this member.
	DbSize int64
	// IsHealthy indicates the health of the member.
	IsHealthy bool
	// ID is the string representation of member's ID
	ID string
	// Name of the member. A member which has not started has an empty Name.
	Name string
	// HasStarted indicates if this member has successfully started kvdb.
	HasStarted bool
	// IsLearner indicates if this member is a learner (i.e. not yet promoted to a full voting member).
	IsLearner bool
}

type PermissionType int

type ReplayCb struct {
	// Prefix is the watch key/tree prefix
	Prefix string
	// WaitIndex is the index after which updates must be returned
	WaitIndex uint64
	// Opaque is a hint returned by the caller
	Opaque interface{}
	// WatchCB is the watch callback
	WatchCB WatchCB
}

type Tx interface {
	// Put specified key value pair in TX.
	Put(key string, value interface{}, ttl uint64) (*KVPair, error)
	// Get returns KVPair in this TXs view. If not found, returns value from
	// backing KVDB.
	Get(key string) (*KVPair, error)
	// Get same as get except that value has the unmarshalled value.
	GetVal(key string, value interface{}) (*KVPair, error)
	// Prepare returns an error it transaction cannot be logged.
	Prepare() error
	// Commit propagates updates to the KVDB. No operations on this Tx are
	// allowed after commit.
	Commit() error
	// Abort aborts this transaction.  No operations on this Tx are allowed
	// afer commit.
	Abort() error
}

type UpdatesCollector interface {
	// Stop collecting updates
	Stop()
	// ReplayUpdates replays the collected updates.
	// Returns the version until the replay's were done
	// and any errors it encountered.
	ReplayUpdates(updateCb []ReplayCb) (uint64, error)
}

type WatchCB func(prefix string, opaque interface{}, kvp *KVPair, err error) error

type WrapperInit func(kv Kvdb, options map[string]string) (Kvdb, error)

type WrapperName string