view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

## `new( local_id_bin => ..., [ k => 20 ] )`

Constructor. `local_id_bin` is the binary string of the local node's ID.

```perl
my $rt = Algorithm::Kademlia::RoutingTable->new(
    local_id_bin => $my_id_bin,
    k            => 20
);
```

## `add_peer( $id_bin, $data )`

Adds a peer to the appropriate bucket.

- If the peer is already present, it is moved to the "most recently seen" position (the tail of the bucket).
- If the bucket is full (reaches size `k`), it returns the "least recently seen" peer (the head of the bucket). According to the Kademlia whitepaper, the caller should ping this stale peer.
- If the bucket is not full, the peer is added and it returns `undef`.

```perl
my $stale = $rt->add_peer($id, { ip => '1.2.3.4', port => 4444 });
if ($stale) {
    # Bucket full! Ping $stale->{data}{ip}
}
```

## `evict_peer( $id_bin )`

Removes a peer from the routing table. Usually called after a stale peer fails a ping check.

```
$rt->evict_peer($stale_id);
```

## `find_closest( $target_id_bin, [ $count ] )`

Returns a list of up to `$count` (defaults to `k`) peers closest to the target ID according to the XOR metric.

```perl
my @peers = $rt->find_closest($target_key, 10);
for my $peer (@peers) {
    say 'Node ' . unpack('H*', $peer->{id}) . ' is at ' . $peer->{data}{ip};
}
```

## `size( )`

Returns the total number of peers across all buckets.

```
say 'Routing table has ' . $rt->size . ' peers';
```

# Algorithm::Kademlia::Storage

A simple in-memory key-value store intended to hold the DHT data.

## `new( [ ttl => 86400 ] )`

Constructor. `ttl` is the time-to-live for entries in seconds.

```perl
my $storage = Algorithm::Kademlia::Storage->new( ttl => 3600 );
```

## `put( $key_bin, $value_bin, [ $publisher_id_bin ] )`

Stores a value.

```
$storage->put($cid_bin, $data_bin, $provider_id);
```

## `get( $key_bin )`

Retrieves a value. Returns `undef` if the key is missing or has expired.

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

## `entries( )`

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

```perl
my %all = $storage->entries();
for my ($key, $info) (%all) {
    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.