view release on metacpan or  search on metacpan

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

Retrieves a value. Returns C<undef> if the key is missing or has expired.

    my $data = $storage->get($cid_bin);
    die 'Expired or not found' unless defined $data;

=head2 C<entries( )>

Returns a hash reference of all non-expired entries in the store.

    my %all = $storage->entries();
    for my ($key, $info) (%all) {
        say 'Key: ' . unpack('H*', $key) . ' Value: ' . $info->{value};
    }

=head1 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.

=head2 C<new( target_id_bin =E<gt> ..., [ k =E<gt> 20, alpha =E<gt> 3 ] )>

Constructor. C<alpha> is the concurrency parameter (how many parallel queries to allow).

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

=head2 C<add_candidates( @peers )>

Adds new potential nodes to the search shortlist.

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

=head2 C<pending_queries( )>

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

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

=head2 C<next_to_query( )>

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

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

=head2 C<mark_responded( $id_bin, @new_peers )>

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

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

=head2 C<mark_failed( $id_bin )>

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

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

=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

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=head1 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.

=cut