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).

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.