kad_dht

README

Kademlia DHT

A lightweight implementation of the kademlia DHT paper(Well not exactly) with additional features inspired from @libp2p.

Usage Example

Refer to the tests for usage examples.

dhtHost1 := NewKademliaHost("127.0.0.1", 5959)
dhtHost2 := NewKademliaHost("127.0.0.1", 5960)

// Host 1 is the bootstrap, start without boot nodes.
dhtHost1.Start(make([]string, 0))
log.Println("host1 started at: ", dhtHost1.GetSelf())
time.Sleep(10 * time.Second)
// Bootstrap Host2 with host1 address.
h1Self := dhtHost1.GetSelf()
host1Addr, _ := (&h1Self).ToSerializedAddressFormat()
b2 := make([]string, 0)
b2 = append(b2, host1Addr)
// Start host 2
dhtHost2.Start(b2)
log.Println("host2 started at: ", dhtHost2.GetSelf())

// Basic Case #1 : Bootstrap and discovery
// Without any discovery thing running, host1 should know about
// host2 and vice versa

// Bootstrap worker starts every one minute
time.Sleep(80 * time.Second)
if len(dhtHost1.GetKnownPeers()) < 1 {
	t.Error("Host 1 didnt know host 2")
}
if len(dhtHost2.GetKnownPeers()) < 1 {
	t.Error("Host 2 didnt know host 1")
}

log.Println("dhtHost1 Address Book:: ", dhtHost1.GetKnownPeers())
log.Println("dhtHost2 Address Book:: ", dhtHost2.GetKnownPeers())

// Basic Case #2 Content Routing tests
err := dhtHost2.Provide(context.Background(), []byte("OliviaDunham"))
if err != nil {
	t.Error(err)
}
providers, err := dhtHost2.FindProvider(context.Background(), []byte("OliviaDunham"))
if err != nil {
	t.Error(err)
}
cnt := 0
for prov := range providers {
	log.Println("[TC Log]Provider: ", prov)
	cnt++
}
log.Println("[TC] Find Providers", cnt)
if cnt != 1 {
	t.Error("find provider err")
}

providers, err = dhtHost1.FindProvider(context.Background(), []byte("OliviaDunham"))
if err != nil {
	t.Error(err)
}
cnt = 0
for prov := range providers {
	log.Println("[TC Log] Provider: ", prov)
	cnt++
}
log.Println("[TC] Find Providers", cnt)
if cnt != 1 {
	t.Error("find provider err")
}

err = dhtHost1.Provide(context.Background(), []byte("OliviaDunham"))
if err != nil {
	t.Error(err)
}
providers, err = dhtHost1.FindProvider(context.Background(), []byte("OliviaDunham"))
if err != nil {
	t.Error(err)
}
cnt = 0
for prov := range providers {
	log.Println("[TC Log] Provider: ", prov)
	cnt++
}
log.Println("[TC] Find Providers", cnt)
if cnt != 2 {
	t.Error("find provider err")
}

// Basic Test #3 Value Store tests
err = dhtHost1.Put([]byte("JonSnow"), []byte("DaenerysTargaryen"))
if err != nil {
	t.Error(err)
}
value, err := dhtHost2.Get([]byte("JonSnow"))
if err != nil {
	t.Error(err)
}
if string(value) != "DaenerysTargaryen" {
	t.Error("wrong value")
}

Roadmap: Minimal Phase 0.0.1

• Basic Interfaces for Peer Routing, Content Routing, K Bucket & KV store.
• gRPC Wire Messenger set up and proto declarations.
• Implementation of k-bucket
• Peer Routing Basic Functionalities.
• Provider Record Store Interfaces and In Memory Impl.
• Content Routing Impl.
• Decentralized KV store impl
• Bootstrapping and Bridging Implementations.
• Unit Tests.

Documentation

Index

• Variables
• type ContentRouting
• type DistributedHashTable
  • func NewKademliaHost(host string, port int32) DistributedHashTable
• type Kademlia
  • func (kad *Kademlia) FindPeerAtDistance(context context.Context, target []byte, _ int) ([]address.PeerAddressInfo, error)
  • func (kad *Kademlia) FindPeersClosest(ctx context.Context, targetId []byte, k int) ([]address.PeerAddressInfo, error)
  • func (kad *Kademlia) FindProvider(context context.Context, key []byte) (chan address.PeerAddressInfo, error)
  • func (kad *Kademlia) Get(key []byte) ([]byte, error)
  • func (kad *Kademlia) GetKnownPeers() []address.PeerAddressInfo
  • func (kad *Kademlia) GetSelf() address.PeerAddressInfo
  • func (kad *Kademlia) Provide(context context.Context, key []byte) error
  • func (kad *Kademlia) Put(key []byte, value []byte) error
  • func (kad *Kademlia) Start(bootNodes []string)
  • func (kad *Kademlia) Stop()
• type KeyValueStore
• type PeerRouting

Variables

var (
	ErrAllWireMessagesFailed = errors.New("all wire protocol messages failed")
)

Types

type ContentRouting

type ContentRouting interface {
	// Provide announces that the given dht host
	// can provide for the current key.
	// Record TTL is defined by ProviderRecordTTL
	Provide(context context.Context, key []byte) error

	// FindProvider finds the provider record
	// for the given key.
	// Will be continuing until the records are found
	// or the context expires.
	FindProvider(context context.Context, key []byte) (chan address.PeerAddressInfo, error)
}

ContentRouting - Basic Functionalities for Content Routing Such as Adding and finding providers for a given key

type DistributedHashTable

type DistributedHashTable interface {
	PeerRouting
	ContentRouting
	KeyValueStore

	// Start the host with the boot nodes.
	Start([]string)

	GetKnownPeers() []address.PeerAddressInfo

	GetSelf() address.PeerAddressInfo

	Stop()
}

DistributedHashTable DHT interface, which embeds all the functionality of PeerRouting, ContentRouting and a KeyValueStore

func NewKademliaHost

func NewKademliaHost(host string, port int32) DistributedHashTable

type Kademlia

type Kademlia struct {
	SelfAddrInfo        address.PeerAddressInfo    // The AddrInfo of the kademlia node
	SelfAddrSerialized  string                     // The Addr Info in Serialized format.
	RoutingController   *routing.Controller        // The PeerRouting Controller responsible for peer routing functions
	ProviderRecordStore *prstore.ProviderStore     // The ContentRouting Controller responsible for content routing functions
	ValueStore          *vstore.ValueStore         // The ValueStore Controller responsible for the KV store functions.
	RoutingTable        *routingtable.RoutingTable // The Node table/Routing table/kBucket impl
	WireMessengerServer *network.Server            // The server for responding to wire messages
	LiveCheckTask       *tasks.LiveCheckTask       // The Live check worker
	ProtocolMessenger   *network.ProtocolMessenger // The protocol Messenger
}

func (*Kademlia) FindPeerAtDistance

func (kad *Kademlia) FindPeerAtDistance(context context.Context, target []byte, _ int) ([]address.PeerAddressInfo, error)

func (*Kademlia) FindPeersClosest

func (kad *Kademlia) FindPeersClosest(ctx context.Context, targetId []byte, k int) ([]address.PeerAddressInfo, error)

func (*Kademlia) FindProvider

func (kad *Kademlia) FindProvider(context context.Context, key []byte) (chan address.PeerAddressInfo, error)

func (*Kademlia) Get

func (kad *Kademlia) Get(key []byte) ([]byte, error)

func (*Kademlia) GetKnownPeers

func (kad *Kademlia) GetKnownPeers() []address.PeerAddressInfo

func (*Kademlia) GetSelf

func (kad *Kademlia) GetSelf() address.PeerAddressInfo

func (*Kademlia) Provide

func (kad *Kademlia) Provide(context context.Context, key []byte) error

func (*Kademlia) Put

func (kad *Kademlia) Put(key []byte, value []byte) error

func (*Kademlia) Start

func (kad *Kademlia) Start(bootNodes []string)

func (*Kademlia) Stop

func (kad *Kademlia) Stop()

type KeyValueStore

type KeyValueStore interface {
	// Put - Adds the pair to KV store
	// TTL is defined by KeyValueStoreTTL
	Put(key []byte, value []byte) error

	// Get the value for a key
	Get(key []byte) ([]byte, error)
}

KeyValueStore - Functionalities for a decentralized Key value store.

type PeerRouting

type PeerRouting interface {
	// FindPeerAtDistance Finds peer at a specified distance from targetId
	// if a negative distance is specified, all peers are returned.
	// usage of context is self explanatory
	FindPeerAtDistance(context context.Context, target []byte, distance int) ([]address.PeerAddressInfo, error)

	// FindPeersClosest Find k most closest peers to the target Id.
	FindPeersClosest(ctx context.Context, targetId []byte, k int) ([]address.PeerAddressInfo, error)
}

PeerRouting - Basic Functions for discovering peer nodes.