DHT Kademlia implementation. More...

#include <dht.h>

Public Member Functions
	DhtClient (int port=DHT_PORT, const std::string &bind_address="", const std::string &data_directory="", AddressFamily address_family=AddressFamily::IPv4)
	Constructor.

	~DhtClient ()
	Destructor.

bool	start ()
	Start the DHT client.

void	stop ()
	Stop the DHT client.

void	shutdown_immediate ()
	Trigger immediate shutdown of all background threads.

bool	bootstrap (const std::vector< Peer > &bootstrap_nodes)
	Bootstrap the DHT with known nodes.

bool	find_peers (const InfoHash &info_hash, PeerDiscoveryCallback callback)
	Find peers for a specific info hash.

bool	announce_peer (const InfoHash &info_hash, uint16_t port=0, PeerDiscoveryCallback callback=nullptr)
	Announce that this node is a peer for a specific info hash.

void	cancel_search (const InfoHash &info_hash)
	Cancel an active search or announce for a specific info hash Should be called when a torrent is removed to clean up DHT state.

NodeId	get_node_id () const
	Get our node ID.

void	set_external_ip (const std::string &ip)
	Set our external (public) IP address and regenerate the node ID from it per BEP 42.

std::string	get_external_address () const
	Get the external address currently used to derive our node ID ("" if none/random).

size_t	get_routing_table_size () const
	Get number of nodes in routing table.

size_t	get_pending_ping_verifications_count () const
	Get number of pending ping verifications.

bool	is_search_active (const InfoHash &info_hash) const
	Check if a search is currently active for an info hash.

bool	is_announce_active (const InfoHash &info_hash) const
	Check if an announce is currently active for an info hash.

size_t	get_active_searches_count () const
	Get number of active searches.

size_t	get_active_announces_count () const
	Get number of active announces.

bool	is_running () const
	Check if DHT is running.

uint16_t	get_port () const
	Actual bound UDP port.

void	set_spider_mode (bool enable)
	Enable spider mode In spider mode:

bool	is_spider_mode () const
	Check if spider mode is enabled.

void	set_spider_announce_callback (SpiderAnnounceCallback callback)
	Set callback for announce_peer requests (spider mode) Called when other peers announce they have a torrent.

void	set_spider_ignore (bool ignore)
	Set spider ignore mode - when true, incoming requests are not processed Similar to rate limiting in the original spider implementation.

bool	is_spider_ignoring () const
	Check if spider ignore mode is enabled.

void	spider_walk ()
	Trigger a single spider walk iteration Sends find_node to a random node from the spider pool Should be called from external loop at desired frequency.

size_t	get_spider_pool_size () const
	Get the size of the spider node pool.

size_t	get_spider_visited_count () const
	Get the number of visited nodes in spider mode.

void	clear_spider_state ()
	Clear spider state (pool and visited nodes) Useful for resetting the spider walk.

AddressFamily	address_family () const
	Address family this DHT node operates on.

bool	is_ipv6 () const

std::string	routing_table_file_path () const
	Compute the routing-table persistence file path for this instance.

bool	save_routing_table ()
	Save routing table to disk.

bool	load_routing_table ()
	Load routing table from disk.

void	set_data_directory (const std::string &directory)
	Set data directory for persistence.

Static Public Member Functions
static bool	generate_node_id_from_ip (const std::string &ip, NodeId &out, std::mt19937 &gen)
	BEP 42 helpers (public for testing / explicit use).

static bool	verify_node_id_for_ip (const NodeId &id, const std::string &ip)

static std::vector< Peer >	get_default_bootstrap_nodes ()
	Get default BitTorrent DHT bootstrap nodes.

Detailed Description

DHT Kademlia implementation.

Definition at line 163 of file dht.h.

Constructor & Destructor Documentation

◆ DhtClient()

librats::DhtClient::DhtClient	(	int	port = `DHT_PORT`,
		const std::string &	bind_address = `""`,
		const std::string &	data_directory = `""`,
		AddressFamily	address_family = `AddressFamily::IPv4`
	)

Constructor.

Parameters

port	The UDP port to bind to (default: 6881)
bind_address	The interface IP address to bind to (empty for all interfaces)
data_directory	Directory for routing-table persistence
address_family	Address family this node operates on. IPv4 and IPv6 form separate Kademlia networks (BEP 32), so each family needs its own DhtClient.

◆ ~DhtClient()

librats::DhtClient::~DhtClient ( )

Destructor.

Member Function Documentation

◆ address_family()

AddressFamily librats::DhtClient::address_family ( ) const

inline

Address family this DHT node operates on.

Definition at line 387 of file dht.h.

◆ announce_peer()

bool librats::DhtClient::announce_peer	(	const InfoHash &	info_hash,
		uint16_t	port = `0`,
		PeerDiscoveryCallback	callback = `nullptr`
	)

Announce that this node is a peer for a specific info hash.

Parameters

info_hash	The info hash to announce
port	The port to announce (0 for DHT port)
callback	Optional callback to receive discovered peers during traversal

Returns: true if announcement started successfully, false otherwise

◆ bootstrap()

bool librats::DhtClient::bootstrap ( const std::vector< Peer > & bootstrap_nodes )

Bootstrap the DHT with known nodes.

Parameters

bootstrap_nodes Vector of bootstrap nodes

Returns: true if successful, false otherwise

◆ cancel_search()

void librats::DhtClient::cancel_search ( const InfoHash & info_hash )

Cancel an active search or announce for a specific info hash Should be called when a torrent is removed to clean up DHT state.

Parameters

info_hash The info hash to cancel search for

◆ clear_spider_state()

void librats::DhtClient::clear_spider_state ( )

Clear spider state (pool and visited nodes) Useful for resetting the spider walk.

◆ find_peers()

bool librats::DhtClient::find_peers	(	const InfoHash &	info_hash,
		PeerDiscoveryCallback	callback
	)

Find peers for a specific info hash.

Parameters

info_hash	The info hash to search for
callback	Callback to receive discovered peers

Returns: true if search started successfully, false otherwise

◆ generate_node_id_from_ip()

static bool librats::DhtClient::generate_node_id_from_ip	(	const std::string &	ip,
		NodeId &	out,
		std::mt19937 &	gen
	)

static

BEP 42 helpers (public for testing / explicit use).

generate_node_id_from_ip: build an IP-derived node ID (random where BEP 42 allows). verify_node_id_for_ip: check whether a node ID is valid for the given source IP (always true for non-public IPs, which cannot be verified).

◆ get_active_announces_count()

size_t librats::DhtClient::get_active_announces_count ( ) const

Get number of active announces.

Returns: Number of active announces

◆ get_active_searches_count()

size_t librats::DhtClient::get_active_searches_count ( ) const

Get number of active searches.

Returns: Number of active searches

◆ get_default_bootstrap_nodes()

static std::vector< Peer > librats::DhtClient::get_default_bootstrap_nodes ( )

static

Get default BitTorrent DHT bootstrap nodes.

Hostnames are resolved per-family at send time, so the same list serves both IPv4 and IPv6 (nodes without an AAAA record are simply skipped on IPv6).

Returns: Vector of bootstrap nodes

◆ get_external_address()

std::string librats::DhtClient::get_external_address ( ) const

Get the external address currently used to derive our node ID ("" if none/random).

◆ get_node_id()

NodeId librats::DhtClient::get_node_id ( ) const

inline

Get our node ID.

Returns: The node ID (returned by value; the ID may be regenerated at runtime when our external IP is learned, see set_external_ip)

Definition at line 233 of file dht.h.

◆ get_pending_ping_verifications_count()

size_t librats::DhtClient::get_pending_ping_verifications_count ( ) const

Get number of pending ping verifications.

Returns: Number of pending ping verifications

◆ get_port()

uint16_t librats::DhtClient::get_port ( ) const

inline

Actual bound UDP port.

May differ from the requested port if it was taken and the client fell back to an ephemeral port (see start()). Use this — not the requested port — when forwarding the DHT port through a router.

Returns: bound port, or 0 if not started

Definition at line 308 of file dht.h.

◆ get_routing_table_size()

size_t librats::DhtClient::get_routing_table_size ( ) const

Get number of nodes in routing table.

Returns: Number of nodes

◆ get_spider_pool_size()

size_t librats::DhtClient::get_spider_pool_size ( ) const

Get the size of the spider node pool.

Returns: Number of nodes in spider pool

◆ get_spider_visited_count()

size_t librats::DhtClient::get_spider_visited_count ( ) const

Get the number of visited nodes in spider mode.

Returns: Number of visited nodes

◆ is_announce_active()

bool librats::DhtClient::is_announce_active ( const InfoHash & info_hash ) const

Check if an announce is currently active for an info hash.

Parameters

info_hash The info hash to check

Returns: true if announce is active, false otherwise

◆ is_ipv6()

bool librats::DhtClient::is_ipv6 ( ) const

inline

Definition at line 388 of file dht.h.

References librats::IPv6.

◆ is_running()

bool librats::DhtClient::is_running ( ) const

inline

Check if DHT is running.

Returns: true if running, false otherwise

Definition at line 300 of file dht.h.

◆ is_search_active()

bool librats::DhtClient::is_search_active ( const InfoHash & info_hash ) const

Check if a search is currently active for an info hash.

Parameters

info_hash The info hash to check

Returns: true if search is active, false otherwise

◆ is_spider_ignoring()

bool librats::DhtClient::is_spider_ignoring ( ) const

inline

Check if spider ignore mode is enabled.

Returns: true if ignoring incoming requests

Definition at line 348 of file dht.h.

◆ is_spider_mode()

bool librats::DhtClient::is_spider_mode ( ) const

inline

Check if spider mode is enabled.

Returns: true if spider mode is enabled

Definition at line 328 of file dht.h.

◆ load_routing_table()

bool librats::DhtClient::load_routing_table ( )

Load routing table from disk.

Returns: true if successful, false otherwise

◆ routing_table_file_path()

std::string librats::DhtClient::routing_table_file_path ( ) const

Compute the routing-table persistence file path for this instance.

Includes the address family so the IPv4 and IPv6 nodes (which may share a port) never overwrite each other's saved state.

◆ save_routing_table()

bool librats::DhtClient::save_routing_table ( )

Save routing table to disk.

Returns: true if successful, false otherwise

◆ set_data_directory()

void librats::DhtClient::set_data_directory ( const std::string & directory )

Set data directory for persistence.

Parameters

directory Directory path

◆ set_external_ip()

void librats::DhtClient::set_external_ip ( const std::string & ip )

Set our external (public) IP address and regenerate the node ID from it per BEP 42.

IPv4/IPv6 node IDs must be derived from the matching-family external address, so this is a no-op if the address family does not match this instance. Safe to call at runtime; the routing table is re-bucketed against the new ID. Non-public/invalid addresses are ignored.

Parameters

ip	External IP address as seen by the network (e.g. from STUN or DHT "ip" voting)

◆ set_spider_announce_callback()

void librats::DhtClient::set_spider_announce_callback ( SpiderAnnounceCallback callback )

Set callback for announce_peer requests (spider mode) Called when other peers announce they have a torrent.

Parameters

callback The callback to invoke

◆ set_spider_ignore()

void librats::DhtClient::set_spider_ignore ( bool ignore )

Set spider ignore mode - when true, incoming requests are not processed Similar to rate limiting in the original spider implementation.

Parameters

ignore true to ignore incoming requests, false to process them

◆ set_spider_mode()

void librats::DhtClient::set_spider_mode ( bool enable )

Enable spider mode In spider mode:

Nodes are added to routing table without ping verification
All announce_peer requests from other peers are collected via callback
Parameters

enable true to enable spider mode, false to disable

◆ shutdown_immediate()

void librats::DhtClient::shutdown_immediate ( )

Trigger immediate shutdown of all background threads.

◆ spider_walk()

void librats::DhtClient::spider_walk ( )

Trigger a single spider walk iteration Sends find_node to a random node from the spider pool Should be called from external loop at desired frequency.

◆ start()

bool librats::DhtClient::start ( )

Start the DHT client.

Returns: true if successful, false otherwise

◆ stop()

void librats::DhtClient::stop ( )

Stop the DHT client.

◆ verify_node_id_for_ip()

static bool librats::DhtClient::verify_node_id_for_ip	(	const NodeId &	id,
		const std::string &	ip
	)

static

The documentation for this class was generated from the following file:

dht.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ DhtClient()

◆ ~DhtClient()

Member Function Documentation

◆ address_family()

◆ announce_peer()

◆ bootstrap()

◆ cancel_search()

◆ clear_spider_state()

◆ find_peers()

◆ generate_node_id_from_ip()

◆ get_active_announces_count()

◆ get_active_searches_count()

◆ get_default_bootstrap_nodes()

◆ get_external_address()

◆ get_node_id()

◆ get_pending_ping_verifications_count()

◆ get_port()

◆ get_routing_table_size()

◆ get_spider_pool_size()

◆ get_spider_visited_count()

◆ is_announce_active()

◆ is_ipv6()

◆ is_running()

◆ is_search_active()

◆ is_spider_ignoring()

◆ is_spider_mode()

◆ load_routing_table()

◆ routing_table_file_path()

◆ save_routing_table()

◆ set_data_directory()

◆ set_external_ip()

◆ set_spider_announce_callback()

◆ set_spider_ignore()

◆ set_spider_mode()

◆ shutdown_immediate()

◆ spider_walk()

◆ start()

◆ stop()

◆ verify_node_id_for_ip()