noise: github.com/perlin-network/noise/kademlia Index | Files

package kademlia

import "github.com/perlin-network/noise/kademlia"

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

Package Files

binary.go events.go iterator.go iterator_options.go msg.go protocol.go protocol_options.go table.go

Constants

const BucketSize int = 16

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

Variables

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

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

func PrefixDiff Uses

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

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

func PrefixLen Uses

func PrefixLen(a []byte) int

PrefixLen returns the number of prefixed zero bits of a.

func SortByDistance Uses

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

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

func XOR Uses

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

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

type Events Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

type Ping struct{}

Ping represents an empty ping message.

func UnmarshalPing Uses

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

UnmarshalPing returns a Ping instance and never throws an error.

func (Ping) Marshal Uses

func (r Ping) Marshal() []byte

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

type Pong Uses

type Pong struct{}

Pong represents an empty pong message.

func UnmarshalPong Uses

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

UnmarshalPong returns a Pong instance and never throws an error.

func (Pong) Marshal Uses

func (r Pong) Marshal() []byte

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

type Protocol Uses

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 Uses

func New(opts ...ProtocolOption) *Protocol

New returns a new instance of the Kademlia protocol.

func (*Protocol) Ack Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

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

func (*Protocol) OnMessageRecv Uses

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 Uses

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 Uses

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 Uses

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

OnPingFailed evicts peers that your node has failed to dial.

func (*Protocol) Ping Uses

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 Uses

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

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

func (*Protocol) Table Uses

func (p *Protocol) Table() *Table

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

type ProtocolOption Uses

type ProtocolOption func(p *Protocol)

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

func WithProtocolEvents Uses

func WithProtocolEvents(events Events) ProtocolOption

WithProtocolEvents configures an event listener for a Protocol.

func WithProtocolLogger Uses

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 Uses

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 Uses

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

Table represents a Kademlia routing table.

func NewTable Uses

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 Uses

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

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

func (*Table) Delete Uses

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 Uses

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 Uses

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

Entries returns all stored ids in this routing table.

func (*Table) FindClosest Uses

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 Uses

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

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

func (*Table) NumEntries Uses

func (t *Table) NumEntries() int

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

func (*Table) Peers Uses

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 Uses

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

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

func (*Table) Self Uses

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 Uses

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.

Package kademlia imports 12 packages (graph) and is imported by 5 packages. Updated 2020-02-08. Refresh now. Tools for package owners.