kademlia

package
v0.0.0-...-09c16d5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 20, 2024 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package kademlia is a noise implementation of the routing and discovery portion of the Kademlia protocol, with minor improvements suggested by the S/Kademlia paper.

Index

Constants

View Source 
const BucketSize int = 16

BucketSize returns the capacity, or the total number of peer ID entries a single routing table bucket may hold.

Variables

View Source 
var ErrBucketFull = errors.New("bucket is full")

ErrBucketFull is returned when a routing table bucket is at max capacity.

Functions

func PrefixDiff 

func PrefixDiff(a, b []byte, n int) int

PrefixDiff counts the number of equal prefixed bits of a and b.

func PrefixLen 

func PrefixLen(a []byte) int

PrefixLen returns the number of prefixed zero bits of a.

func SortByDistance 

func SortByDistance(id noise.PublicKey, ids []noise.ID) []noise.ID

SortByDistance sorts ids by descending XOR distance with respect to id.

func XOR 

func XOR(a, b []byte) []byte

XOR allocates a new byte slice with the computed result of XOR(a, b).

Types

type Events 

type Events struct {
	// OnPeerAdmitted is called when a peer is admitted to being inserted into your nodes' routing table.
	OnPeerAdmitted func(id noise.ID)

	// OnPeerActivity is called when your node interacts with a peer, causing the peer's entry in your nodes' routing
	// table to be bumped to the head of its respective bucket.
	OnPeerActivity func(id noise.ID)

	// OnPeerEvicted is called when your node fails to ping/dial a peer that was previously admitted into your nodes'
	// routing table, which leads to an eviction of the peers ID from your nodes' routing table.
	OnPeerEvicted func(id noise.ID)
}

Events comprise of callbacks that are to be called upon the encountering of various events as a node follows the Kademlia protocol. An Events declaration may be registered to a Protocol upon instantiation through calling New with the WithProtocolEvents functional option.

type FindNodeRequest 

type FindNodeRequest struct {
	Target noise.PublicKey
}

FindNodeRequest represents a FIND_NODE RPC call in the Kademlia specification. It contains a target public key to which a peer is supposed to respond with a slice of IDs that neighbor the target ID w.r.t. XOR distance.

func UnmarshalFindNodeRequest 

func UnmarshalFindNodeRequest(buf []byte) (FindNodeRequest, error)

UnmarshalFindNodeRequest decodes buf, which must be the exact size of a public key, into a FindNodeRequest. It throws an io.ErrUnexpectedEOF if buf is malformed.

func (FindNodeRequest) Marshal 

func (r FindNodeRequest) Marshal() []byte

Marshal implements noise.Serializable and returns the public key of the target for this search request as a byte slice.

type FindNodeResponse 

type FindNodeResponse struct {
	Results []noise.ID
}

FindNodeResponse returns the results of a FIND_NODE RPC call which comprises of the IDs of peers closest to a target public key specified in a FindNodeRequest.

func UnmarshalFindNodeResponse 

func UnmarshalFindNodeResponse(buf []byte) (FindNodeResponse, error)

UnmarshalFindNodeResponse decodes buf, which is expected to encode a list of closest peer ID results, into a FindNodeResponse. It throws an io.ErrUnexpectedEOF if buf is malformed.

func (FindNodeResponse) Marshal 

func (r FindNodeResponse) Marshal() []byte

Marshal implements noise.Serializable and encodes the list of closest peer ID results into a byte representative of the length of the list, concatenated with the serialized byte representation of the peer IDs themselves.

type Iterator 

type Iterator struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Iterator represents a S/Kademlia overlay network iterator over all peers that may be discovered in the network. It is used for peer discovery, and for finding peers by their public key over an overlay network.

func NewIterator 

func NewIterator(node *noise.Node, table *Table, opts ...IteratorOption) *Iterator

NewIterator instantiates a new overlay network iterator bounded to a node and routing table that may be optionally configured with a variadic list of functional options.

func (*Iterator) Find 

func (it *Iterator) Find(target noise.PublicKey) []noise.ID

Find attempts to salvage through the Kademlia overlay network through the peers of the node this iterator is bound to for a target public key. It blocks the current goroutine until the search is complete.

type IteratorOption 

type IteratorOption func(it *Iterator)

IteratorOption represents a functional option which may be passed to NewIterator, or to (*Protocol).Find or (*Protocol).Discover to configure Iterator.

func WithIteratorLogger 

func WithIteratorLogger(logger *zap.Logger) IteratorOption

WithIteratorLogger configures the logger instance for an iterator. By default, the logger used is the logger of the node which the iterator is bound to.

func WithIteratorLookupTimeout 

func WithIteratorLookupTimeout(lookupTimeout time.Duration) IteratorOption

WithIteratorLookupTimeout sets the max duration to wait until we declare a lookup request sent in amidst a single disjoint lookup to have timed out. By default, it is set to 3 seconds.

func WithIteratorMaxNumResults 

func WithIteratorMaxNumResults(maxNumResults int) IteratorOption

WithIteratorMaxNumResults sets the max number of resultant peer IDs from a single (*Iterator).Find call. By default, it is set to the max capacity of a routing table bucket which is 16 based on the S/Kademlia paper.

func WithIteratorNumParallelLookups 

func WithIteratorNumParallelLookups(numParallelLookups int) IteratorOption

WithIteratorNumParallelLookups sets the max number of parallel disjoint lookups that may occur at once while executing (*Iterator).Find. By default, it is set to 3 based on the S/Kademlia paper.

func WithIteratorNumParallelRequestsPerLookup 

func WithIteratorNumParallelRequestsPerLookup(numParallelRequestsPerLookup int) IteratorOption

WithIteratorNumParallelRequestsPerLookup sets the max number of parallel requests a single disjoint lookup may make during the execution of (*Iterator).Find. By default, it is set to 8 based on the S/Kademlia paper.

type Ping 

type Ping struct{}

Ping represents an empty ping message.

func UnmarshalPing 

func UnmarshalPing([]byte) (Ping, error)

UnmarshalPing returns a Ping instance and never throws an error.

func (Ping) Marshal 

func (r Ping) Marshal() []byte

Marshal implements noise.Serializable and returns a nil byte slice.

type Pong 

type Pong struct{}

Pong represents an empty pong message.

func UnmarshalPong 

func UnmarshalPong([]byte) (Pong, error)

UnmarshalPong returns a Pong instance and never throws an error.

func (Pong) Marshal 

func (r Pong) Marshal() []byte

Marshal implements noise.Serializable and returns a nil byte slice.

type Protocol 

type Protocol struct {
	// contains filtered or unexported fields
}

Protocol implements routing/discovery portion of the Kademlia protocol with improvements suggested by the S/Kademlia paper. It is expected that Protocol is bound to a noise.Node via (*noise.Node).Bind before the node starts listening for incoming peers.

func New 

func New(opts ...ProtocolOption) *Protocol

New returns a new instance of the Kademlia protocol.

func (*Protocol) Ack 

func (p *Protocol) Ack(id noise.ID)

Ack attempts to insert a peer ID into your nodes routing table. If the routing table bucket in which your peer ID was expected to be inserted on is full, the peer ID at the tail of the bucket is pinged. If the ping fails, the peer ID at the tail of the bucket is evicted and your peer ID is inserted to the head of the bucket.

func (*Protocol) Bind 

func (p *Protocol) Bind(node *noise.Node) error

Bind registers messages Ping, Pong, FindNodeRequest, FindNodeResponse, and handles them by registering the (*Protocol).Handle Handler.

func (*Protocol) Discover 

func (p *Protocol) Discover(opts ...IteratorOption) []noise.ID

Discover attempts to discover new peers to your node through peers your node already knows about by calling the FIND_NODE S/Kademlia RPC call with your nodes ID.

func (*Protocol) Find 

func (p *Protocol) Find(target noise.PublicKey, opts ...IteratorOption) []noise.ID

Find executes the FIND_NODE S/Kademlia RPC call to find the closest peers to some given target public key. It returns the IDs of the closest peers it finds.

func (*Protocol) Handle 

func (p *Protocol) Handle(ctx noise.HandlerContext) error

Handle implements noise.Protocol and handles Ping and FindNodeRequest messages.

func (*Protocol) OnMessageRecv 

func (p *Protocol) OnMessageRecv(client *noise.Client)

OnMessageRecv implements noise.Protocol and attempts to push the position in which the clients ID resides in your nodes' routing table's to the head of the bucket it reside within.

func (*Protocol) OnMessageSent 

func (p *Protocol) OnMessageSent(client *noise.Client)

OnMessageSent implements noise.Protocol and attempts to push the position in which the clients ID resides in your nodes' routing table's to the head of the bucket it reside within.

func (*Protocol) OnPeerConnected 

func (p *Protocol) OnPeerConnected(client *noise.Client)

OnPeerConnected attempts to acknowledge the new peers existence by placing its entry into your nodes' routing table via (*Protocol).Ack.

func (*Protocol) OnPingFailed 

func (p *Protocol) OnPingFailed(addr string, err error)

OnPingFailed evicts peers that your node has failed to dial.

func (*Protocol) Ping 

func (p *Protocol) Ping(ctx context.Context, addr string) error

Ping sends a ping request to addr, and returns no error if a pong is received back before ctx has expired/was cancelled. It also throws an error if the connection to addr intermittently drops, or if handshaking with addr should there be no live connection to addr yet fails.

func (*Protocol) Protocol 

func (p *Protocol) Protocol() noise.Protocol

Protocol returns a noise.Protocol that may registered to a node via (*noise.Node).Bind.

func (*Protocol) Table 

func (p *Protocol) Table() *Table

Table returns this Kademlia overlay's routing table from your nodes perspective.

type ProtocolOption 

type ProtocolOption func(p *Protocol)

ProtocolOption represents a functional option which may be passed to New to configure a Protocol.

func WithProtocolEvents 

func WithProtocolEvents(events Events) ProtocolOption

WithProtocolEvents configures an event listener for a Protocol.

func WithProtocolLogger 

func WithProtocolLogger(logger *zap.Logger) ProtocolOption

WithProtocolLogger configures the logger instance for an iterator. By default, the logger used is the logger of the node which the iterator is bound to.

func WithProtocolPingTimeout 

func WithProtocolPingTimeout(pingTimeout time.Duration) ProtocolOption

WithProtocolPingTimeout configures the amount of time to wait for until we declare a ping to have failed. Peers typically either are pinged through a call of (*Protocol).Ping, or in amidst the execution of Kademlia's peer eviction policy. By default, it is set to 3 seconds.

type Table 

type Table struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Table represents a Kademlia routing table.

func NewTable 

func NewTable(self noise.ID) *Table

NewTable instantiates a new routing table whose XOR distance metric is defined with respect to some given ID.

func (*Table) Bucket 

func (t *Table) Bucket(target noise.PublicKey) []noise.ID

Bucket returns all entries of a bucket where target reside within.

func (*Table) Delete 

func (t *Table) Delete(target noise.PublicKey) (noise.ID, bool)

Delete removes target from this routing table. It returns the id of the delted target and true if found, or a zero-value ID and false otherwise.

func (*Table) DeleteByAddress 

func (t *Table) DeleteByAddress(target string) (noise.ID, bool)

DeleteByAddress removes the first occurrence of an id with target as its address from this routing table. It returns the id of the deleted target and true if found, or a zero-value ID and false otherwise.

func (*Table) Entries 

func (t *Table) Entries() []noise.ID

Entries returns all stored ids in this routing table.

func (*Table) FindClosest 

func (t *Table) FindClosest(target noise.PublicKey, k int) []noise.ID

FindClosest returns the k closest peer IDs to target, and sorts them based on how close they are.

func (*Table) Last 

func (t *Table) Last(target noise.PublicKey) noise.ID

Last returns the last id of the bucket where target resides within.

func (*Table) NumEntries 

func (t *Table) NumEntries() int

NumEntries returns the total amount of ids stored in this routing table.

func (*Table) Peers 

func (t *Table) Peers() []noise.ID

Peers returns BucketSize closest peer IDs to the ID which this routing table's distance metric is defined against.

func (*Table) Recorded 

func (t *Table) Recorded(target noise.PublicKey) bool

Recorded returns true if target is already recorded in this routing table.

func (*Table) Self 

func (t *Table) Self() noise.ID

Self returns the ID which this routing table's XOR distance metric is defined with respect to.

func (*Table) Update 

func (t *Table) Update(target noise.ID) (bool, error)

Update attempts to insert the target node/peer ID into this routing table. If the bucket it was expected to be inserted within is full, ErrBucketFull is returned. If the ID already exists in its respective routing table bucket, it is moved to the head of the bucket and false is returned. If the ID has yet to exist, it is appended to the head of its intended bucket and true is returned.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.