kad

Documentation

Overview

Package kad implements a Kademlia Distributed Hash Table for node discovery.

It provides a full Kademlia routing table with XOR-distance-based bucket management, iterative FindNode lookup, and the hub.DHT interface.

The implementation uses only the standard library. Node IDs are SHA-256 hashes of the node's identity string.

Index

• func NewDHTNode(id string, ...) hub.DHT
• type Bucket
• type Kademlia
  • func NewKademlia(id string, logger *slog.Logger) *Kademlia
  • func (k *Kademlia) FindClosest(target NodeID, n int) []hub.PeerInfo
  • func (k *Kademlia) Insert(info hub.PeerInfo)
  • func (k *Kademlia) Lookup(ctx context.Context, target NodeID, findNode findNodeFunc) ([]hub.PeerInfo, error)
  • func (k *Kademlia) NodeID() NodeID
  • func (k *Kademlia) Remove(id string)
• type KademliaDHT
  • func NewDHT(id string, lookup findNodeFunc, logger *slog.Logger) *KademliaDHT
  • func (d *KademliaDHT) Bootstrap(_ context.Context, seeds []string) error
  • func (d *KademliaDHT) Close() error
  • func (d *KademliaDHT) GetClosestNodes(_ context.Context, targetID string, n int) ([]hub.PeerInfo, error)
  • func (d *KademliaDHT) Lookup(ctx context.Context, nodeID string) (hub.PeerInfo, error)
  • func (d *KademliaDHT) Register(_ context.Context, info hub.PeerInfo) error
• type NodeID
  • func NodeIDFromHex(s string) (NodeID, error)
  • func NodeIDFromString(s string) NodeID
  • func (n NodeID) Hex() string
  • func (n NodeID) Less(other NodeID) bool
  • func (n NodeID) PrefixLen() int
  • func (n NodeID) Xor(other NodeID) NodeID

Functions

func NewDHTNode

func NewDHTNode(id string, lookup func(ctx context.Context, target NodeID, remote hub.PeerInfo) ([]hub.PeerInfo, error), logger *slog.Logger) hub.DHT

NewDHTNode creates a new Kademlia DHT node with the given identity. This is the primary factory function users call to instantiate a DHT node. id is the local node's identity string (used to derive the Kademlia NodeID via SHA-256). lookup is the function to query remote nodes for iterative FindNode (can be nil for standalone).

Types

type Bucket

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

Bucket is a Kademlia k-bucket containing up to bucketSize nodes.

type Kademlia

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

Kademlia implements the Kademlia DHT routing table. 注意：当前实现不持有自身锁（Bucket 内部各自加锁）；若未来需要跨 bucket 原子 操作（如并发安全的重合/拆分），需补回 Kademlia 级锁。

func NewKademlia

func NewKademlia(id string, logger *slog.Logger) *Kademlia

NewKademlia creates a new Kademlia instance with the given node ID.

func (*Kademlia) FindClosest

func (k *Kademlia) FindClosest(target NodeID, n int) []hub.PeerInfo

FindClosest returns the k closest nodes to the target ID from the routing table. It searches from the closest bucket outward and returns nodes sorted by XOR distance.

func (*Kademlia) Insert

func (k *Kademlia) Insert(info hub.PeerInfo)

Insert adds or updates a node in the appropriate k-bucket.

func (*Kademlia) Lookup

func (k *Kademlia) Lookup(ctx context.Context, target NodeID, findNode findNodeFunc) ([]hub.PeerInfo, error)

Lookup performs an iterative Kademlia FindNode lookup for the target ID. It returns the k closest nodes to the target.

func (*Kademlia) NodeID

func (k *Kademlia) NodeID() NodeID

NodeID returns this node's Kademlia ID.

func (*Kademlia) Remove

func (k *Kademlia) Remove(id string)

Remove removes a node from the routing table.

type KademliaDHT

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

KademliaDHT wraps Kademlia to implement the hub.DHT interface.

func NewDHT

func NewDHT(id string, lookup findNodeFunc, logger *slog.Logger) *KademliaDHT

NewDHT creates a new Kademlia DHT that implements hub.DHT. id is the local node's identity string. lookup is the function to query remote nodes (can be nil for standalone use).

func (*KademliaDHT) Bootstrap

func (d *KademliaDHT) Bootstrap(_ context.Context, seeds []string) error

Bootstrap connects to seed nodes to join the DHT network. For now, it just inserts the seed nodes into the routing table.

func (*KademliaDHT) Close

func (d *KademliaDHT) Close() error

Close cleans up resources.

func (*KademliaDHT) GetClosestNodes

func (d *KademliaDHT) GetClosestNodes(_ context.Context, targetID string, n int) ([]hub.PeerInfo, error)

GetClosestNodes returns the k closest nodes to the target ID.

func (*KademliaDHT) Lookup

func (d *KademliaDHT) Lookup(ctx context.Context, nodeID string) (hub.PeerInfo, error)

Lookup finds a specific node by ID.

func (*KademliaDHT) Register

func (d *KademliaDHT) Register(_ context.Context, info hub.PeerInfo) error

Register adds a node to the routing table.

type NodeID

type NodeID [32]byte

NodeID is a 256-bit Kademlia node identifier.

func NodeIDFromHex

func NodeIDFromHex(s string) (NodeID, error)

NodeIDFromHex parses a hex-encoded NodeID.

func NodeIDFromString

func NodeIDFromString(s string) NodeID

NodeIDFromString creates a NodeID by SHA-256 hashing the input string.

func (NodeID) Hex

func (n NodeID) Hex() string

Hex returns the hex-encoded representation of the NodeID.

func (NodeID) Less

func (n NodeID) Less(other NodeID) bool

Less compares two NodeIDs lexicographically.

func (NodeID) PrefixLen

func (n NodeID) PrefixLen() int

PrefixLen returns the number of leading zero bits in the XOR distance. This determines the k-bucket index.

func (NodeID) Xor

func (n NodeID) Xor(other NodeID) NodeID

Xor returns the XOR distance between two NodeIDs.