Struct DhtService 

pub struct DhtService { /* private fields */ }

The DHT service for one node. Cloneable-by-Arc internally; wrap in Arc to share between the serving task (inbound RPC) and querying callers.

Implementations

impl DhtService

pub fn new( local_id: PeerId, local_addresses: Vec<CandidateAddr>, config: DhtConfig, transport: Arc<dyn DhtTransport>, ) -> Self

Create a service for the node identified by local_id, advertising local_addresses in the provider records it announces, driving RPC over transport.

pub fn local_id(&self) -> &PeerId

This node’s id.

pub async fn bootstrap( &self, peers: &[BootstrapPeer], ) -> Result<usize, DhtError>

Seed the routing table from peers and populate it by looking up this node’s own id (the canonical Kademlia bootstrap: a self-lookup fills the buckets around us). Returns the number of distinct peers now known.

Safe to call repeatedly (on reconnect / when new bootstrap peers arrive) — it merges, never resets.

pub async fn find_node( &self, peer_id: &PeerId, ) -> Result<Vec<Contact>, DhtError>

Find the k peers closest to peer_id (the routing primitive). Runs an iterative find_node lookup and returns the converged closest contacts.

pub async fn find_providers( &self, content: &ContentId, ) -> Result<Vec<ProviderRecord>, DhtError>

Find the providers of content — the peers holding it. Runs an iterative find_providers lookup toward the content key, returning every live provider record collected (deduped by provider). The node then connects to those providers over dig-nat and fetches via the L7 peer RPC.

Returns an empty vec (not an error) when the content simply has no known providers; returns DhtError::NoPeers only when there is no one to ask (empty routing table + no bootstrap).

pub async fn announce_provider( &self, content: &ContentId, ) -> Result<usize, DhtError>

Announce that THIS node holds content: build a provider record (this node’s peer_id + addresses, expiring at now + provider_ttl), store it locally, remember to republish it, and PUT it at the k nodes closest to the content key. Returns how many peers accepted the PUT.

Called when the node’s inventory gains content (a new capsule/root/resource it now serves).

pub async fn withdraw_provider(&self, content: &ContentId) -> bool

Stop announcing content (the node no longer holds it). The record ages out of the DHT via TTL; we just stop republishing it. Returns whether it was being announced.

pub async fn republish(&self) -> usize

Republish every content key this node still announces — re-runs the announce PUT so provider records never expire while the node is online. Call on the DhtConfig::republish_interval. Returns the number of content keys republished.

pub async fn refresh_buckets(&self) -> usize

Refresh populated buckets by looking up a random key in each — keeps the routing table fresh as peers churn. Call on the DhtConfig::refresh_interval. Returns the number of buckets refreshed.

pub async fn gc(&self) -> usize

Drop expired provider records. Call periodically (piggy-backs on republish/refresh). Returns the number of records removed.

pub async fn ping(&self, peer: &Contact) -> bool

Ping a peer for liveness; on failure, evict it from the routing table. Used by the ping-and-replace maintenance when a bucket is full. Returns whether the peer is alive.

pub async fn handle_request(&self, request: DhtRequest) -> DhtResponse

Answer an inbound DHT request from another node, without a known caller identity. Prefer handle_request_from on an authenticated transport (it lets the responder learn the caller and populate its routing table bidirectionally, the way Kademlia tables fill).

pub async fn handle_request_from( &self, caller: Option<Contact>, request: DhtRequest, ) -> DhtResponse

Answer an inbound DHT request, folding the authenticated caller into the routing table.

This is the server half — a dig-node wires it to inbound DHT streams, passing the caller’s mTLS-verified Contact as caller. Learning the caller from every inbound RPC is how a Kademlia node discovers peers without an explicit announce: a node that talks to you becomes a candidate in your table. The caller MUST come from the authenticated transport (the mTLS peer_id), never from the request body — identity is not self-asserted.

It reads/writes only local state (routing table + provider store) and never makes outbound RPCs, so it cannot recurse or block on the network.

pub async fn known_closest(&self, target: &Key) -> Vec<Contact>

The contacts currently in this node’s routing table closest to target (diagnostic / introspection — the peers this node knows without any network round-trip).

pub async fn routing_len(&self) -> usize

The number of peers currently in this node’s routing table (diagnostic / metrics).