Algorithm-Kademlia

 view release on metacpan or  search on metacpan

CODE_OF_CONDUCT.md  view on Meta::CPAN

## Our Standards

Examples of behavior that contributes to a positive environment for our
community include:

* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
  and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
  overall community

Examples of unacceptable behavior include:

* The use of sexualized language or imagery, and sexual attention or
  advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
  address, without their explicit permission

README.md  view on Meta::CPAN

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

while (!$search->is_finished) {
    my @to_query = $search->next_to_query();
    for my $node (@to_query) {
        # ... Send FIND_NODE RPC to $node ...
        # If response: $search->mark_responded($node->{id}, @found_peers);
        # If failure:  $search->mark_failed($node->{id});
    }
}
my @results = $search->best_results();
```

# DESCRIPTION

`Algorithm::Kademlia` provides the mathematical and structural foundations for a Kademlia Distributed Hash Table
(DHT). It is designed to be protocol-agnostic, meaning it only handles the XOR-metric distance calculations, the
k-bucket routing table logic, and the search state management.

This module is suitable for building BitTorrent-compatible DHTs, libp2p Kademlia implementations, or custom
peer-to-peer storage systems.

README.md  view on Meta::CPAN

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)

lib/Algorithm/Kademlia.pm  view on Meta::CPAN

            return unless $nodes{$id_bin};
            $nodes{$id_bin}{responded} = 1;
            $self->add_candidates(@new_peers);
        }

        method mark_failed ($id_bin) {
            return unless $nodes{$id_bin};
            $nodes{$id_bin}{failed} = 1;
        }

        method best_results () {
            my @sorted  = sort { ( $a^.$target_id_bin ) cmp( $b^.$target_id_bin ) } grep { $nodes{$_}{responded} } keys %nodes;
            my @results = map  { { id => $_, data => $nodes{$_}{data} } } splice( @sorted, 0, $k );
            @results;
        }

        method is_finished () {
            my @responded = grep { $_->{responded} } values %nodes;
            return 1 if @responded >= $k;
            my @available = grep { !$_->{queried} && !$_->{failed} } values %nodes;
            return 1 if !@available && !$self->pending_queries;

lib/Algorithm/Kademlia.pod  view on Meta::CPAN

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

    while (!$search->is_finished) {
        my @to_query = $search->next_to_query();
        for my $node (@to_query) {
            # ... Send FIND_NODE RPC to $node ...
            # If response: $search->mark_responded($node->{id}, @found_peers);
            # If failure:  $search->mark_failed($node->{id});
        }
    }
    my @results = $search->best_results();

=head1 DESCRIPTION

C<Algorithm::Kademlia> provides the mathematical and structural foundations for a Kademlia Distributed Hash Table
(DHT). It is designed to be protocol-agnostic, meaning it only handles the XOR-metric distance calculations, the
k-bucket routing table logic, and the search state management.

This module is suitable for building BitTorrent-compatible DHTs, libp2p Kademlia implementations, or custom
peer-to-peer storage systems.

lib/Algorithm/Kademlia.pod  view on Meta::CPAN

=head2 C<is_finished()>

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

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

=head2 C<best_results()>

Returns a list of the C<k> closest nodes that successfully responded.

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

=head1 SEE ALSO

L<InterPlanetary::Kademlia> (for the libp2p implementation)

L<Net::BitTorrent::DHT> (for the BitTorrent implementation)

L<https://xlattice.sourceforge.net/components/protocol/kademlia/specs.html>

=head1 AUTHOR

t/06_search.t  view on Meta::CPAN

    is $to_query[0]{id},  $p1->{id}, 'Closest first';
    is $to_query[1]{id},  $p2->{id}, 'Second closest';
    ok !$search->is_finished, 'Not finished yet';
    $search->mark_responded( $p1->{id} );
    $search->mark_failed( $p2->{id} );
    @to_query = $search->next_to_query();
    is scalar(@to_query), 1,         'One more candidate available (p3)';
    is $to_query[0]{id},  $p3->{id}, 'p3 is next';
    $search->mark_responded( $p3->{id} );
    ok $search->is_finished, 'Finished because no more candidates';
    my @results = $search->best_results();
    is scalar(@results), 2,         'Returns up to k=2 results';
    is $results[0]{id},  $p1->{id}, 'Best result is p1';
};
#
done_testing;