Struct DhtHandle 

pub struct DhtHandle { /* private fields */ }

A cloneable handle to the DHT actor.

Implementations

impl DhtHandle

pub async fn start(config: DhtConfig) -> Result<(Self, Receiver<IpAddr>)>

Start the DHT actor and return a handle plus an IP consensus channel.

The consensus channel fires when the BEP 42 ExternalIpVoter reaches agreement on our external IP address.

Errors

Returns an error if the UDP socket cannot be bound.

pub async fn update_external_ip( &self, ip: IpAddr, source: IpVoteSource, ) -> Result<()>

Notify the DHT of our external IP (from NAT/tracker discovery).

Errors

Returns Error::Shutdown if the actor has stopped.

pub async fn get_peers( &self, info_hash: Id20, ) -> Result<UnboundedReceiver<Vec<SocketAddr>>>

Discover peers for an info_hash.

Returns a channel that receives batches of peers as they are found. The channel closes when the search is exhausted.

Errors

Returns Error::Shutdown if the actor has stopped.

pub async fn announce(&self, info_hash: Id20, port: u16) -> Result<()>

Announce that we have peers for an info_hash on the given port.

Errors

Returns Error::Shutdown if the actor has stopped.

pub async fn stats(&self) -> Result<DhtStats>

Get current DHT statistics.

Errors

Returns Error::Shutdown if the actor has stopped.

pub async fn node_count(&self) -> Result<usize>

Get the number of nodes currently in the routing table (M171 D4).

Thin accessor over DhtStats::routing_table_size used by the qBt v2 transferInfo.dht_nodes field and the DHT pseudo-tracker’s num_peers column. Returns Ok(0) when the routing table is empty — including immediately after startup, before bootstrap has populated any buckets.

Errors

Returns Error::Shutdown if the actor has stopped.

pub async fn shutdown(&self) -> Result<()>

Shut down the DHT actor (fire-and-forget).

Returns once the shutdown command has been queued. The actor will persist the routing table (dht_state.json) before terminating, but this method does NOT wait for that. For runtime DHT-restart paths that need to be sure the state is on disk before starting a new actor, use Self::shutdown_and_wait.

Errors

Returns Error::Shutdown if the command channel has already closed.

pub async fn shutdown_and_wait(&self) -> Result<()>

M173 Lane B (B7): shut down the DHT actor and wait for it to fully drain — including persisting the routing table to dht_state.json.

Returns Ok(()) once the actor has saved its state and terminated. Used by the apply_settings DHT-restart phase so the new DHT actor (started with the same state_dir) can load the pre-restart state.

Errors

Returns Error::Shutdown if the actor exits before sending its reply (typically because it had already shut down for another reason).

pub async fn save_routing_table(&self) -> Result<()>

M173 Lane B (B7): synchronously persist the routing table.

Returns Ok(()) once dht_state.json has been written and renamed atomically. Distinct from Self::shutdown_and_wait in that the actor continues running afterwards — used by callers that want to checkpoint state without restarting DHT.

Errors

Returns Error::Shutdown if the actor channel has closed. May return an underlying I/O error wrapped in Error::Shutdown if the persist itself failed (the actor returns the error verbatim, but the channel-closed case is indistinguishable from the I/O case at the API boundary).

pub async fn put_immutable(&self, value: Vec<u8>) -> Result<Id20>

Store an immutable item in the DHT (BEP 44).

Returns the SHA-1 target hash that can be used to retrieve the item. The value must be valid bencoded data, max 1000 bytes.

Errors

Returns Error::Shutdown if the actor has stopped, or a BEP 44 validation error if the value exceeds size limits.

pub async fn get_immutable(&self, target: Id20) -> Result<Option<Vec<u8>>>

Retrieve an immutable item from the DHT (BEP 44).

Returns the raw bencoded value if found, None if not.

Errors

Returns Error::Shutdown if the actor has stopped.

pub async fn put_mutable( &self, keypair_bytes: [u8; 32], value: Vec<u8>, seq: i64, salt: Vec<u8>, ) -> Result<Id20>

Store a mutable item in the DHT (BEP 44).

• keypair_bytes: 32-byte ed25519 seed (secret key)
• value: bencoded data, max 1000 bytes
• seq: sequence number (must be higher than any previously stored)
• salt: optional salt for sub-key isolation (max 64 bytes)

Returns the target hash.

Errors

Returns Error::Shutdown if the actor has stopped, or a BEP 44 validation error if value or salt exceeds size limits.

pub async fn sample_infohashes( &self, target: Id20, ) -> Result<SampleInfohashesResult>

Query a DHT node for a random sample of info hashes (BEP 51).

Routes toward target to find the responding node. Returns sampled hashes, the interval before re-querying, and closer nodes for traversal.

Errors

Returns Error::Shutdown if the actor has stopped.

pub async fn get_mutable( &self, public_key: [u8; 32], salt: Vec<u8>, ) -> Result<Option<(Vec<u8>, i64)>>

Retrieve a mutable item from the DHT (BEP 44).

Returns (value, seq) if found, None if not.

Errors

Returns Error::Shutdown if the actor has stopped.

pub async fn get_routing_nodes(&self) -> Vec<(Id20, SocketAddr)>

Return all nodes currently in the DHT routing table.

Trait Implementations

impl Clone for DhtHandle

fn clone(&self) -> DhtHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DhtHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.