distkv

README

distkv

distkv is a distributed K/V store library for Go powered by the raft consensus algorithm. Values are only changed when a majority of nodes in the cluster agree on the operation. Internal communication is secured and powered by the SSH protocol.

It was originally based on hraftd by Philip O'Toole. An modified version of it is provided in example/http-rest as an example application built on top of distkv.

Usage

Check out the example folder in this repository for two basic usage examples. Some guidance is provided by godoc. API stability is not guaranteed yet, but it is unlikely to change as it is purposefully kept simple - please vendor it nonetheless.

Leader forwarding is built-in, so the application does not have to deal with the implementation of the actual distributed raft cluster. Consistent reads are going to be implemented using a separate function.

Security

distkv ensures confidentiality and security by enforcing asymmetric authentication and encryption using the SSH protocol. A custom built interface leveraging the protocols features (TCP/IP forwarding and out-of-band requests) secures all raft and control communication.

Key distribution

Without this step, distkv will not work for security reasons

On first start, applications using distkv will write an authenticated.key file to the specified RaftDir ($(pwd)/raft if nothing is specified). This file contains the public key of this node, which has to be copied to every other nodes authenticated.key file. After that is done, all further cluster communication will be automatically secured. Don't forget to distributed the new key after adding a new node.

Threat model

Every node in the cluster is inherently trusted - it has access to all data and functions (except being able to join a new node for itself). Thus it is important to secure the private key (raftDir/id_rsa) and apply standard best security practices (privilege separation, etc.).

Contribution

If you find any bugs or would like to see (or contribute to) a feature, please don't hesitate to open an issue or PR.

License

This project is licensed under the MIT License (see LICENSE.md)

Documentation

Overview

distkv provides a simple and secure distributed key-value store. The keys and associated values are changed via distributed consensus over an authenticated ssh channel. This means that the values are changed only when a majority of nodes in the cluster agree on the new value.

Distributed consensus is provided via the Raft algorithm.

Index

• Variables
• type Store
  • func NewStore(debug bool) *Store
  • func (s *Store) Close() error
  • func (s *Store) Delete(key string) error
  • func (s *Store) Get(key string) ([]byte, error)
  • func (s *Store) Join(joinAddr, raftAddr string) error
  • func (s *Store) Open(enableSingle bool) error
  • func (s *Store) Set(key string, value []byte) error

Variables

var (
	ShutdownError      = errors.New("Store was shutdown")
	AlreadyOpenedError = errors.New("Store was already opened")
	KeyNotFoundError   = errors.New("Key not present in store")
)

Types

type Store

type Store struct {
	RaftDir  string
	RaftBind string
	// contains filtered or unexported fields
}

Store is a simple key-value store, where all changes are made via Raft consensus.

func NewStore

func NewStore(debug bool) *Store

New returns a new Store. If debug is true, informational and debug messages are printed to os.Stderr

func (*Store) Close

func (s *Store) Close() error

Close closes the store after stepping down as node/leader.

func (*Store) Delete

func (s *Store) Delete(key string) error

Delete deletes the given key.

func (*Store) Get

func (s *Store) Get(key string) ([]byte, error)

Get returns the value for the given key. TODO implement strongly consistent read with extra argument or func

func (*Store) Join

func (s *Store) Join(joinAddr, raftAddr string) error

Join joins a node reachable under raftAddr, to the cluster lead by the node reachable under joinAddr. The joined node must be ready to respond to Raft communications at that raftAddr.

func (*Store) Open

func (s *Store) Open(enableSingle bool) error

Open opens the store. If enableSingle is set, and there are no existing peers, then this node becomes the first node, and therefore leader, of the cluster.

func (*Store) Set

func (s *Store) Set(key string, value []byte) error

Set sets the value for the given key.