view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    say 'Key: ' . unpack('H*', $key) . ' Value: ' . $info->{value};
}
```

# Algorithm::Kademlia::Search

A state manager for the iterative Kademlia lookup algorithm. It tracks which nodes have been queried, which have
responded, and which have failed.

## `new( target_id_bin => ..., [ k => 20, alpha => 3 ] )`

Constructor. `alpha` is the concurrency parameter (how many parallel queries to allow).

```perl
my $search = Algorithm::Kademlia::Search->new(
    target_id_bin => $target_key,
    alpha         => 3
);
```

## `add_candidates( @peers )`

Adds new potential nodes to the search shortlist.

```
$search->add_candidates( $rt->find_closest($target_key) );
```

## `pending_queries( )`

Returns a list of nodes that have been queried but have not yet responded or failed.

```perl
my @waiting = $search->pending_queries();
say 'Waiting for ' . scalar(@waiting) . ' nodes...';
```

## `next_to_query( )`

Returns a list of up to `alpha` nodes that have not yet been queried, sorted by proximity to the target.

```perl
my @to_query = $search->next_to_query();
# Now send your RPCs to these nodes...
```

## `mark_responded( $id_bin, @new_peers )`

Marks a node as having responded and adds any new peers it returned to the shortlist.

```python
# After getting a response from a FIND_NODE RPC:
$search->mark_responded($peer_id, @peers_from_rpc);
```

## `mark_failed( $id_bin )`

Marks a node as failed (e.g., RPC timeout).

```
# After a timeout or connection error:
$search->mark_failed($peer_id);
```

## `is_finished()`

Returns true if the search has reached a termination condition (either `k` nodes have responded, or there are no more
nodes to query and no pending requests).

```
while (!$search->is_finished) {
    # ... keep querying ...
}
```

## `best_results()`

Returns a list of the `k` closest nodes that successfully responded.

```perl
my @k_closest = $search->best_results();
```

# SEE ALSO

[InterPlanetary::Kademlia](https://metacpan.org/pod/InterPlanetary%3A%3AKademlia) (for the libp2p implementation)

[Net::BitTorrent::DHT](https://metacpan.org/pod/Net%3A%3ABitTorrent%3A%3ADHT) (for the BitTorrent implementation)

[https://xlattice.sourceforge.net/components/protocol/kademlia/specs.html](https://xlattice.sourceforge.net/components/protocol/kademlia/specs.html)

# AUTHOR

Sanko Robinson <sanko@cpan.org>

# COPYRIGHT

Copyright (C) 2023-2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.