Module lookup 

The iterative Kademlia lookup: converge on the k closest peers to a target key by repeatedly querying the α closest un-queried peers we know, folding their returned closer contacts back into the shortlist, until no closer peer can be found.

This is the heart of a Kademlia DHT. iterative_find drives it:

1. Seed a shortlist with the closest contacts we already know (routing table + bootstrap).
2. Each round, pick the α closest un-queried contacts and query them in parallel with the supplied query closure (a find_node for node lookup, or a find_providers for provider lookup — the closure returns both closer contacts AND any providers it collected).
3. Merge every returned contact into the shortlist (dedup by peer_id), keeping it sorted by XOR distance to the target and capped so it stays bounded.
4. Stop when a full round of the k closest have all been queried and none produced a strictly closer un-queried contact — the shortlist has converged. Return the k closest and any providers collected.

The closure abstraction means node-lookup and provider-lookup share ONE convergence engine; only what each query returns differs. Transport failures to individual peers are non-fatal — a peer that errors is simply marked queried and the walk continues (the service’s query closure maps a transport error to Err(())).

Each round’s α-sized batch is queried truly concurrently: every peer’s RPC is tokio::spawned as its own task, so all α requests are in flight at once rather than awaited one at a time. A round of α peers that each stall to the transport timeout therefore costs about one rpc_timeout, not α × rpc_timeout.

Structs

LookupResult

The result of a completed iterative lookup.

QueryOutcome

The outcome of querying one peer during a lookup: the closer contacts it knows, and any provider records it holds for the target (empty for a pure node lookup).

Constants

MAX_CLOSER_PER_RESPONSE

Baseline ceiling on how many closer contacts a single peer’s response may contribute to a lookup (#1352). An honest responder returns at most k; the effective cap is the larger of this and 2·k. Bounds the per-response merge work an adversarial peer can impose.

MAX_LOOKUP_ROUNDS

Absolute ceiling on the number of iterative rounds a single lookup may run (#1352). A converging Kademlia lookup needs O(log n) rounds; this bound only ever trips on a pathological/adversarial swarm where responders keep feeding an endless stream of ever-closer contacts to prevent convergence (a lookup-livelock DoS). 64 rounds is far beyond any honest convergence depth.

MAX_PROVIDERS_PER_RESPONSE

Baseline ceiling on how many provider records a single peer’s response may contribute to a lookup (#1352). An honest responder returns at most its per-key cap (max_providers_per_key, default 20) live records; a response off the wire is untrusted and could otherwise pack an unbounded set into one frame, inflating the collected-providers map. The effective cap is the larger of this and 2·k, so a network tuned to a large k is never under-bounded.

Functions

iterative_find

Drive an iterative lookup toward target, seeded with seeds, querying at most alpha peers per round and converging on the k closest.