Mainline

https://docs.rs/mainline/latest/
Admin
Mainline is a simple and robust BitTorrent Mainline DHT implementation in Rust, supporting both...
Tokens:100,179
Snippets:489
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start PutQuery and Send Requests

Source: https://docs.rs/mainline/latest/src/mainline/rpc/put_query

The `start` method initiates the PutQuery by sending PUT requests to the closest nodes and any extra nodes. It handles initial checks like ensuring the query hasn't started and validating the number of nodes. It returns an error if no closest nodes are available.

```rust
    pub fn start(
        &mut self,
        socket: &mut KrpcSocket,
        closest_nodes: &[Node],
    ) -> Result<(), PutError> {
        if self.started() {
            panic!("should not call PutQuery::start() twice");
        };

        let target = self.target;
        trace!(?target, "PutQuery start");

        if closest_nodes.is_empty() {
            Err(PutQueryError::NoClosestNodes)?;
        }

        if closest_nodes.len() > u8::MAX as usize {
            panic!("should not send PUT query to more than 256 nodes")
        }

        for node in closest_nodes.iter().chain(self.extra_nodes.iter()) {
            // Set correct values to the request placeholders
            if let Some(token) = node.token() {
                let tid = socket.request(
                    node.address(),
                    RequestSpecific {
                        requester_id: Id::random(),
                        request_type: RequestTypeSpecific::Put(PutRequest {
                            token,
                            put_request_type: self.request.clone(),
                        }),
                    },
                );

                self.inflight_requests.push(tid);
            }
        }

        Ok(())
    }

    // ... other methods ...
```

--------------------------------

### Put and Get Immutable Data in Rust DHT

Source: https://docs.rs/mainline/latest/src/mainline/async_dht

Illustrates the process of storing immutable data using `put_immutable` and retrieving it with `get_immutable`. The example creates a testnet, initializes two DHT nodes, puts a byte slice "Hello World!" and verifies that the returned target matches an expected target. It then retrieves the data using the target and asserts that it matches the original value.

```rust
#[test]
fn put_get_immutable() {
    async fn test() {
        let testnet = Testnet::new(10).unwrap();

        let a = Dht::builder()
            .bootstrap(&testnet.bootstrap)
            .build()
            .unwrap()
            .as_async();
        let b = Dht::builder()
            .bootstrap(&testnet.bootstrap)
            .build()
            .unwrap()
            .as_async();

        let value = b"Hello World!";
        let expected_target = Id::from_str("e5f96f6f38320f0f33959cb4d3d656452117aadb").unwrap();

        let target = a.put_immutable(value).await.unwrap();
        assert_eq!(target, expected_target);

        let response = b.get_immutable(target).await;
        assert_eq!(response, Some(value.to_vec().into_boxed_slice()));
    }

    futures::executor::block_on(test());
}
```

--------------------------------

### Initialize Mainline DHT in Adaptive Mode

Source: https://docs.rs/mainline/latest/mainline/index

Illustrates the adaptive mode for the Mainline DHT, which starts as a client and automatically switches to server mode after 15 minutes if it has a publicly accessible address. This mode can also be explicitly configured to start in server mode with a predefined public IP using the `Dht::builder`.

```rust
use mainline::Dht;

// Default adaptive mode (starts as client, switches to server)
let dht_adaptive = Dht::builder().build();

// Explicitly start in server mode
let dht_server_explicit = Dht::builder().server_mode().build();

// Explicitly start in server mode with a known public IP
let dht_server_public_ip = Dht::builder().server_mode().public_ip().build();
```

--------------------------------

### Start a PUT Query with Closest Nodes in Rust

Source: https://docs.rs/mainline/latest/src/mainline/rpc

This code initiates a PUT query, attempting to use cached closest nodes if they are available and valid. If not, it prepares to fetch them using a GET request.

```rust
if let Some(closest_nodes) = self
            .cached_iterative_queries
            .get(&target)
            .map(|cached| cached.closest_responding_nodes.clone())
            .filter(|closest_nodes| {
                !closest_nodes.is_empty() && closest_nodes.iter().any(|n| n.valid_token())
            }) {
            query.start(&mut self.socket, &closest_nodes)?
        } else {
            let salt = match request {
                PutRequestSpecific::PutMutable(args) => args.salt,
                _ => None,
            };

            self.get(
```

--------------------------------

### Get Bootstrap Nodes

Source: https://docs.rs/mainline/latest/src/mainline/async_dht

Fetches a list of nodes that can be used for bootstrapping the DHT network. The output is a vector of strings representing node addresses.

```rust
impl AsyncDht {
    /// Turn this node's routing table to a list of bootstrapping nodes.   
    pub async fn to_bootstrap(&self) -> Vec<String> {
        let (tx, rx) = flume::bounded::<Vec<String>>(1);
        self.send(ActorMessage::ToBootstrap(tx));

        rx.recv_async()
            .await
            .expect("actor thread unexpectedly shutdown")
    }
}
```

--------------------------------

### Put and Get Mutable Data in Rust DHT

Source: https://docs.rs/mainline/latest/src/mainline/async_dht

Shows how to store and retrieve mutable data using `put_mutable` and `get_mutable`. This involves creating a `MutableItem` with a signer, value, and sequence number. The example puts the item using one DHT instance and retrieves it using another, asserting that the retrieved item matches the original. It also demonstrates handling mutable data with a specific sequence number.

```rust
#[test]
fn put_get_mutable() {
    async fn test() {
        let testnet = Testnet::new(10).unwrap();

        let a = Dht::builder()
            .bootstrap(&testnet.bootstrap)
            .build()
            .unwrap()
            .as_async();
        let b = Dht::builder()
            .bootstrap(&testnet.bootstrap)
            .build()
            .unwrap()
            .as_async();

        let signer = SigningKey::from_bytes(&[
            56, 171, 62, 85, 105, 58, 155, 209, 189, 8, 59, 109, 137, 84, 84, 201, 221, 115, 7,
            228, 127, 70, 4, 204, 182, 64, 77, 98, 92, 215, 27, 103,
        ]);

        let seq = 1000;
        let value = b"Hello World!";

        let item = MutableItem::new(signer.clone(), value, seq, None);

        a.put_mutable(item.clone(), None).await.unwrap();

        let response = b
            .get_mutable(signer.verifying_key().as_bytes(), None, None)
            .next()
            .await
            .expect("No mutable values");

        assert_eq!(&response, &item);
    }

    futures::executor::block_on(test());
}
```

```rust
#[test]
fn put_get_mutable_no_more_recent_value() {
    async fn test() {
        let testnet = Testnet::new(10).unwrap();

        let a = Dht::builder()
            .bootstrap(&testnet.bootstrap)
            .build()
            .unwrap()
            .as_async();
        let b = Dht::builder()
            .bootstrap(&testnet.bootstrap)
            .build()
            .unwrap()
            .as_async();

        let signer = SigningKey::from_bytes(&[
            56, 171, 62, 85, 105, 58, 155, 209, 189, 8, 59, 109, 137, 84, 84, 201, 221, 115, 7,
            228, 127, 70, 4, 204, 182, 64, 77, 98, 92, 215, 27, 103,
        ]);

        let seq = 1000;
        let value = b"Hello World!";

        let item = MutableItem::new(signer.clone(), value, seq, None);

        a.put_mutable(item.clone(), None).await.unwrap();

        let response = b
            .get_mutable(signer.verifying_key().as_bytes(), None, Some(seq))
            .next()
            .await;

        assert!(&response.is_none());
    }

    futures::executor::block_on(test());
}
```

--------------------------------

### Dht: Get Builder

Source: https://docs.rs/mainline/latest/src/mainline/dht

Provides a default DhtBuilder instance, allowing configuration of DHT node settings before creation.

```rust
pub fn builder() -> DhtBuilder {
        DhtBuilder::default()
    }
```

--------------------------------

### Initialize Rust DHT in Server Mode with Public IP

Source: https://docs.rs/mainline/latest/index

Illustrates how to explicitly start the Mainline DHT in server mode and optionally provide a public IP address. This is useful when you know the node is not behind a firewall and want to bypass the need for peer votes to determine its public IP.

```rust
Dht::builder().server_mode().public_ip().build()
```

--------------------------------

### IterativeQuery Public Methods (start, add_candidate, add_address_vote)

Source: https://docs.rs/mainline/latest/src/mainline/rpc/iterative_query

Implements public methods for interacting with the `IterativeQuery`. `start` initiates the query by visiting the closest nodes. `add_candidate` adds a potential node to be considered in the query. `add_address_vote` increments a counter for a specific public address, used for determining the best address.

```rust
/// Force start query traversal by visiting closest nodes.
pub fn start(&mut self, socket: &mut KrpcSocket) {
    self.visit_closest(socket);
}

/// Add a candidate node to query on next tick if it is among the closest nodes.
pub fn add_candidate(&mut self, node: Node) {
    // ready for a ipv6 routing table?
    self.closest.add(node);
}

/// Add a vote for this node's address.
pub fn add_address_vote(&mut self, address: SocketAddrV4) {
    self.public_address_votes
        .entry(address)
        .and_modify(|counter| *counter += 1)
        .or_insert(1);
}
```

--------------------------------

### Announce and Get Peer in Rust DHT

Source: https://docs.rs/mainline/latest/src/mainline/async_dht

Demonstrates how to announce a peer with a specific port for an info hash and then retrieve peers associated with that info hash. It sets up a testnet, initializes two DHT instances, announces a peer using the first instance, and then fetches peers using the second instance, asserting that the announced port is returned.

```rust
fn announce_get_peer() {
    async fn test() {
        let testnet = Testnet::new(10).unwrap();

        let a = Dht::builder()
            .bootstrap(&testnet.bootstrap)
            .build()
            .unwrap()
            .as_async();
        let b = Dht::builder()
            .bootstrap(&testnet.bootstrap)
            .build()
            .unwrap()
            .as_async();

        let info_hash = Id::random();

        a.announce_peer(info_hash, Some(45555))
            .await
            .expect("failed to announce");

        let peers = b.get_peers(info_hash).next().await.expect("No peers");

        assert_eq!(peers.first().unwrap().port(), 45555);
    }

    futures::executor::block_on(test());
}
```

--------------------------------

### Rust: Get VerifyingKey from SigningKey

Source: https://docs.rs/mainline/latest/mainline/struct

Shows how to derive the associated `VerifyingKey` from a `SigningKey`. The `VerifyingKey` is used for signature verification.

```Rust
use ed25519_dalek::SigningKey;
use ed25519_dalek::VerifyingKey;

// Assuming 'signing_key' is an existing SigningKey instance
// let signing_key: SigningKey = ...;

let verifying_key: VerifyingKey = signing_key.verifying_key();
// 'verifying_key' can now be used to verify signatures.
```

--------------------------------

### Rust: Get SigningKey as a byte slice

Source: https://docs.rs/mainline/latest/mainline/struct

Demonstrates obtaining a reference to the byte slice of the `SigningKey`. This can be useful for passing to functions that expect a slice.

```Rust
use ed25519_dalek::SigningKey;

// Assuming 'signing_key' is an existing SigningKey instance
// let signing_key: SigningKey = ...;

let key_slice: &[u8; 32] = signing_key.as_bytes();
// 'key_slice' is now a reference to the [u8; 32] array.
```

--------------------------------

### Get Node Information Summary (Rust)

Source: https://docs.rs/mainline/latest/src/mainline/rpc

Creates and returns a lightweight, thread-safe summary of the node's current state and statistics, encapsulated in an `Info` struct.

```rust
pub fn info(&self) -> Info {
    Info::from(self)
}
```

--------------------------------

### Put Mutable Data to DHT Example

Source: https://docs.rs/mainline/latest/src/mainline/async_dht

Demonstrates how to put mutable data to the DHT, emphasizing the mitigation of the lost update problem. It shows the pattern of fetching the most recent item first and then creating a new item based on it.

```rust
use mainline::{Dht, MutableItem, SigningKey, Testnet};

let testnet = Testnet::new(3).unwrap();
let dht = Dht::builder().bootstrap(&testnet.bootstrap).build().unwrap().as_async();

let signing_key = SigningKey::from_bytes(&[0; 32]);
let key = signing_key.verifying_key().to_bytes();
let salt = Some(b"salt".as_ref());

futures::executor::block_on(async move {
    let (item, cas) = if let Some(most_recent) = dht.get_mutable_most_recent(&key, salt).await {

```

--------------------------------

### Get DHT Bootstrapping Nodes

Source: https://docs.rs/mainline/latest/src/mainline/dht

Retrieves a list of nodes that the current DHT node is using for bootstrapping. This list is crucial for the node's ability to connect to and participate in the DHT network.

```APIDOC
## GET /dht/bootstrap

### Description
Retrieves a list of nodes that the current DHT node is using for bootstrapping. This list is crucial for the node's ability to connect to and participate in the DHT network.

### Method
GET

### Endpoint
/dht/bootstrap

### Parameters
None

### Response
#### Success Response (200)
- **nodes** (array of strings) - A list of node addresses (e.g., IP:port) used for bootstrapping.

#### Response Example
{
  "nodes": [
    "192.168.1.1:6881",
    "10.0.0.1:6881"
  ]
}
```

--------------------------------

### Test Announce and Get Peer

Source: https://docs.rs/mainline/latest/src/mainline/dht

Verifies the DHT's ability to announce a peer for a given info hash and retrieve that peer information from another node in the test network.

```rust
#[test]
fn announce_get_peer() {
    let testnet = Testnet::new(10).unwrap();

    let a = Dht::builder()
        .bootstrap(&testnet.bootstrap)
        .build()
        .unwrap();
    let b = Dht::builder()
        .bootstrap(&testnet.bootstrap)
        .build()
        .unwrap();

    let info_hash = Id::random();

    a.announce_peer(info_hash, Some(45555))
        .expect("failed to announce");

    let peers = b.get_peers(info_hash).next().expect("No peers");

    assert_eq!(peers.first().unwrap().port(), 45555);
}
```

--------------------------------

### Put and Get Mutable Data in Rust DHT

Source: https://docs.rs/mainline/latest/src/mainline/dht

Demonstrates storing a mutable item in the DHT and then retrieving it using the signer's key. Assumes a DHT client is initialized and connected to a testnet.

```rust
    let signer = SigningKey::from_bytes(&[
        56, 171, 62, 85, 105, 58, 155, 209, 189, 8, 59, 109, 137, 84, 84, 201, 221, 115, 7,
        228, 127, 70, 4, 204, 182, 64, 77, 98, 92, 215, 27, 103,
    ]);

    let seq = 1000;
    let value = b"Hello World!";

    let item = MutableItem::new(signer.clone(), value, seq, None);

    a.put_mutable(item.clone(), None).unwrap();

    let response = b
        .get_mutable(signer.verifying_key().as_bytes(), None, None)
        .next()
        .expect("No mutable values");

    assert_eq!(&response, &item);
```

--------------------------------

### Dht Node Initialization API

Source: https://docs.rs/mainline/latest/src/mainline/dht

Covers the creation and initialization of the Dht node.

```APIDOC
## Dht Initialization

### `Dht::new(config: Config)`

Create a new Dht node.

Could return an error if it failed to bind to the specified port or other io errors while binding the udp socket.

### `Dht::builder()`

Returns a builder to edit settings before creating a Dht node.

### `Dht::client()`

Create a new DHT client with default bootstrap nodes.

### `Dht::server()`

Create a new DHT node that is running in [Server mode][DhtBuilder::server_mode] as soon as possible.
```

--------------------------------

### Rust: Create SigningKey from bytes

Source: https://docs.rs/mainline/latest/mainline/struct

Demonstrates how to create a `SigningKey` instance from a byte array. This is useful for loading pre-existing keys.

```Rust
use ed25519_dalek::SigningKey;
use ed25519_dalek::SECRET_KEY_LENGTH;

let secret_key_bytes: [u8; SECRET_KEY_LENGTH] = [
   157, 097, 177, 157, 239, 253, 090, 096,
   186, 132, 074, 244, 146, 236, 044, 196,
   068, 073, 197, 105, 123, 050, 105, 025,
   112, 059, 172, 003, 028, 174, 127, 096, ];

let signing_key: SigningKey = SigningKey::from_bytes(&secret_key_bytes);
assert_eq!(signing_key.to_bytes(), secret_key_bytes);
```

--------------------------------

### Put Mutable Data to DHT with Conflict Resolution

Source: https://docs.rs/mainline/latest/src/mainline/dht

Stores a mutable data item in the DHT, incorporating a strategy to mitigate lost updates. It suggests reading the most recent item first using `get_mutable_most_recent`, then creating a new item with an incremented sequence number and the previous item's sequence as a CAS (Compare-And-Swap) value. This example demonstrates initializing a DHT and signing key for this process.

```rust
use mainline::{Dht, MutableItem, SigningKey, Testnet};

let testnet = Testnet::new(3).unwrap();
let dht = Dht::builder().bootstrap(&testnet.bootstrap).build().unwrap();

let signing_key = SigningKey::from_bytes(&[0; 32]);
let key = signing_key.verifying_key().to_bytes();
let salt = Some(b"salt".as_ref());

let (item, cas) = if let Some(most_recent) = dht .get_mutable_most_recent(&key, salt) {
    // 1. Optionally Create a new value to take the most recent's value in consideration.
    let mut new_value = most_recent.value().to_vec();
    new_value.extend_from_slice(b" more data");

    // 2. Increment the sequence number to be higher than the most recent's.
    let most_recent_seq = most_recent.seq();
    let new_seq = most_recent_seq + 1;

    (
        MutableItem::new(signing_key, &new_value, new_seq, salt),
        // 3. Use the most recent [MutableItem::seq] as a `CAS`.
        Some(most_recent_seq)
    )
} else {
```

--------------------------------

### Create Asynchronous Testnet with Bootstrapped Nodes

Source: https://docs.rs/mainline/latest/src/mainline/dht

Initializes a test network with a specified number of nodes and asynchronously awaits the bootstrapping of all nodes. This is recommended for async runtimes.

```rust
pub async fn new_async(count: usize) -> Result<Testnet, std::io::Error> {
    let testnet = Testnet::new_inner(count)?;

    for node in testnet.nodes.clone() {
        node.as_async().bootstrapped().await;
    }

    Ok(testnet)
}
```

--------------------------------

### AsyncDht Bootstrap Nodes

Source: https://docs.rs/mainline/latest/src/mainline/async_dht

Converts the node's routing table to a list of bootstrapping nodes.

```APIDOC
## GET /bootstrap

### Description
Retrieves a list of nodes that can be used for bootstrapping the Dht network.

### Method
GET

### Endpoint
/bootstrap

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **nodes** (Array<String>) - A list of node addresses (e.g., "ip:port") for bootstrapping.

#### Response Example
```json
[
  "192.168.1.100:6881",
  "192.168.1.101:6881"
]
```
```

--------------------------------

### Iterator for DHT Get Operations

Source: https://docs.rs/mainline/latest/src/mainline/dht

Defines a generic iterator for receiving items from DHT GET operations, wrapping a `flume::IntoIter`.

```rust
pub struct GetIterator<T>(flume::IntoIter<T>);

impl<T> Iterator for GetIterator<T> {
    type Item = T;

    fn next(&mut self) -> Option<Self::Item> {
        self.0.next()
    }
}
```

--------------------------------

### Test Put and Get Mutable Data

Source: https://docs.rs/mainline/latest/src/mainline/dht

Demonstrates storing and retrieving mutable data in the DHT. This test initializes a network and uses two nodes to put and get a mutable value.

```rust
#[test]
fn put_get_mutable() {
    let testnet = Testnet::new(10).unwrap();

    let a = Dht::builder()
        .bootstrap(&testnet.bootstrap)
        .build()
        .unwrap();
    let b = Dht::builder()
        .bootstrap(&testnet.bootstrap)
        .build()
        .unwrap();

    // The actual put_mutable and get_mutable operations would follow here.
```

--------------------------------

### Rust DHT Get Value Request Arguments

Source: https://docs.rs/mainline/latest/src/mainline/common/messages/internal

Defines the arguments for a DHT 'Get Value' request. It includes the sender's ID, the target hash, and an optional sequence number.

```rust
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct DHTGetValueRequestArguments {
    #[serde(with = "serde_bytes")]
    pub id: [u8; 20],

    #[serde(with = "serde_bytes")]
    pub target: [u8; 20],

    #[serde(default)]
    pub seq: Option<i64>,
}
```

--------------------------------

### Rust: Create SigningKey from keypair bytes

Source: https://docs.rs/mainline/latest/mainline/struct

Shows how to construct a `SigningKey` from a 64-byte array containing both the secret and public key components. Returns a Result to handle potential errors.

```Rust
use ed25519_dalek::SigningKey;
use ed25519_dalek::Error;

// Assuming 'keypair_bytes' is a [u8; 64] array
// let keypair_bytes: [u8; 64] = ...;

let signing_key_result: Result<SigningKey, Error> = SigningKey::from_keypair_bytes(&keypair_bytes);

match signing_key_result {
    Ok(signing_key) => {
        // Successfully created SigningKey
    }
    Err(e) => {
        // Handle error, e.g., invalid input bytes
        eprintln!("Error creating SigningKey: {}", e);
    }
}
```

--------------------------------

### Concurrent Get Mutable Data in Rust DHT

Source: https://docs.rs/mainline/latest/src/mainline/dht

Tests retrieving mutable data concurrently from the DHT using two different client instances. It ensures that subsequent gets retrieve the correct, most recent item.

```rust
        let signer = SigningKey::from_bytes(&[
            56, 171, 62, 85, 105, 58, 155, 209, 189, 8, 59, 109, 137, 84, 84, 201, 221, 115, 7,
            228, 127, 70, 4, 204, 182, 64, 77, 98, 92, 215, 27, 103,
        ]);

        let key = signer.verifying_key().to_bytes();
        let seq = 1000;
        let value = b"Hello World!";

        let item = MutableItem::new(signer.clone(), value, seq, None);

        a.put_mutable(item.clone(), None).unwrap();

        let _response_first = b
            .get_mutable(&key, None, None)
            .next()
            .expect("No mutable values");

        let response_second = b
            .get_mutable(&key, None, None)
            .next()
            .expect("No mutable values");

        assert_eq!(&response_second, &item);
```

--------------------------------

### Rust PeersStore: Create and Add Peers

Source: https://docs.rs/mainline/latest/src/mainline/rpc/server/peers

Demonstrates the creation of a PeersStore and adding peers for a given info_hash. The store uses LRU caches to limit the number of info_hashes and peers per info_hash.

```rust
use std::{net::SocketAddrV4, num::NonZeroUsize};
use crate::common::Id;
use getrandom::getrandom;
use lru::LruCache;

const CHANCE_SCALE: f32 = 2.0 * (1u32 << 31) as f32;

#[derive(Debug, Clone)]
/// An LRU cache of "Peers" per info hashes.
///
/// Read [BEP_0005](https://www.bittorrent.org/beps/bep_0005.html) for more information.
pub struct PeersStore {
    info_hashes: LruCache<Id, LruCache<Id, SocketAddrV4>>,
    max_peers: NonZeroUsize,
}

impl PeersStore {
    /// Create a new store of peers announced on info hashes.
    pub fn new(max_info_hashes: NonZeroUsize, max_peers: NonZeroUsize) -> Self {
        Self {
            info_hashes: LruCache::new(max_info_hashes),
            max_peers,
        }
    }

    /// Add a peer for an info hash.
    pub fn add_peer(&mut self, info_hash: Id, peer: (&Id, SocketAddrV4)) {
        if let Some(info_hash_lru) = self.info_hashes.get_mut(&info_hash) {
            info_hash_lru.put(*peer.0, peer.1);
        } else {
            let mut info_hash_lru = LruCache::new(self.max_peers);
            info_hash_lru.put(*peer.0, peer.1);
            self.info_hashes.put(info_hash, info_hash_lru);
        };
    }

    /// Returns a random set of peers per an info hash.
    pub fn get_random_peers(&mut self, info_hash: &Id) -> Option<Vec<SocketAddrV4>> {
        if let Some(info_hash_lru) = self.info_hashes.get(info_hash) {
            let size = info_hash_lru.len();
            let target_size = 20;

            if size == 0 {
                return None;
            }
            if size < target_size {
                return Some(
                    info_hash_lru
                        .iter()
                        .map(|n| n.1.to_owned())
                        .collect::<Vec<_>>(),
                );
            }

            let mut results = Vec::with_capacity(20);

            let mut chunk = vec![0_u8; info_hash_lru.iter().len() * 4];
            getrandom(chunk.as_mut_slice()).expect("getrandom");

            for (index, (_, addr)) in info_hash_lru.iter().enumerate() {
                // Calculate the chance of adding the current item based on remaining items and slots
                let remaining_slots = target_size - results.len();
                let remaining_items = info_hash_lru.len() - index;
                let current_chance =
                    ((remaining_slots as f32 / remaining_items as f32) * CHANCE_SCALE) as u32;

                // Get random integer from the chunk
                let rand_int =
                    u32::from_le_bytes(chunk[index..index + 4].try_into().expect("infallible"));

                // Randomly decide to add the item based on the current chance
                if rand_int < current_chance {
                    results.push(*addr);
                    if results.len() == target_size {
                        break;
                    }
                }
            }

            return Some(results);
        }

        None
    }
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn max_info_hashes() {
        let mut store = PeersStore::new(
            NonZeroUsize::new(1).unwrap(),
            NonZeroUsize::new(100).unwrap(),
        );

        let info_hash_a = Id::random();
        let info_hash_b = Id::random();

        store.add_peer(
            info_hash_a,
            (&info_hash_a, SocketAddrV4::new([127, 0, 1, 1].into(), 0)),
        );
        store.add_peer(
            info_hash_b,
            (&info_hash_b, SocketAddrV4::new([127, 0, 1, 1].into(), 0)),
        );

        assert_eq!(store.info_hashes.len(), 1);
        assert_eq!(
            store.get_random_peers(&info_hash_b),
            Some([SocketAddrV4::new([127, 0, 1, 1].into(), 0)].into())
        );
    }

    #[test]
    fn all_peers() {
        let mut store =
            PeersStore::new(NonZeroUsize::new(1).unwrap(), NonZeroUsize::new(2).unwrap());

        let info_hash_a = Id::random();
        let info_hash_b = Id::random();
        let info_hash_c = Id::random();

        store.add_peer(
            info_hash_a,
            (&info_hash_a, SocketAddrV4::new([127, 0, 1, 1].into(), 0)),
        );
        store.add_peer(
            info_hash_a,
            (&info_hash_b, SocketAddrV4::new([127, 0, 1, 2].into(), 0)),
        );
        store.add_peer(
            info_hash_a,
            (&info_hash_c, SocketAddrV4::new([127, 0, 1, 3].into(), 0)),
        );

        assert_eq!(
            store.get_random_peers(&info_hash_a),
            Some(
                [

```

--------------------------------

### Rust RpcTickReport Structure

Source: https://docs.rs/mainline/latest/src/mainline/rpc

Represents the state change after an RPC tick in the DHT. It includes completed GET and PUT queries, and any new response received for a GET query. Dependencies include `Id` and `Node` types.

```rust
/// State change after a call to [Rpc::tick], including
/// done PUT, GET, and FIND_NODE queries, as well as any
/// incoming value response for any GET query.
#[derive(Debug, Clone)]
pub struct RpcTickReport {
    /// All the [Id]s of the done [Rpc::get] queries.
    pub done_get_queries: Vec<(Id, Box<[Node]>)>,
    /// All the [Id]s of the done [Rpc::put] queries,
    /// and optional [PutError] if the query failed.
    pub done_put_queries: Vec<(Id, Option<PutError>) >,
    /// Received GET query response.
    pub new_query_response: Option<(Id, Response)>,
}
```

--------------------------------

### Node Creation and Management

Source: https://docs.rs/mainline/latest/src/mainline/common/node

Provides methods for creating and initializing Node objects, including those with specific IDs, addresses, tokens, and for testing purposes.

```APIDOC
## Node Creation and Initialization

### Description
Methods for creating new Node instances, either with specific identifiers or for testing scenarios.

### Methods

- **`Node::new(id: Id, address: SocketAddrV4) -> Node`**: Creates a new Node with a given ID and socket address.
- **`Node::new_with_token(id: Id, address: SocketAddrV4, token: Box<[u8]>) -> Node`**: Creates a new Node with a given ID, socket address, and an optional token.
- **`Node::random() -> Node`**: Creates a new Node with a randomly generated ID.
- **`Node::unique(i: usize) -> Node`** (cfg(test)) : Creates a unique node for testing with a random ID and sets the IP and port based on the provided index `i`.

### Request Example
```json
{
  "id": "some_id_representation",
  "address": "127.0.0.1:8080",
  "token": "base64_encoded_token_or_null"
}
```

### Response Example
```json
{
  "node_created": true
}
```
```

--------------------------------

### Rust DHT Get Immutable Response Arguments

Source: https://docs.rs/mainline/latest/src/mainline/common/messages/internal

Defines the arguments for a DHT 'Get Immutable' response. It includes the sender's ID, a token, optional node information, and the requested immutable value.

```rust
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct DHTGetImmutableResponseArguments {
    #[serde(with = "serde_bytes")]
    pub id: [u8; 20],

    #[serde(with = "serde_bytes")]
    pub token: Box<[u8]>,

    #[serde(with = "serde_bytes")]
    #[serde(default)]
    pub nodes: Option<Box<[u8]>>,

    #[serde(with = "serde_bytes")]
    pub v: Box<[u8]>,
}
```

--------------------------------

### Test GET Immutable Response Serialization/Deserialization in Rust

Source: https://docs.rs/mainline/latest/src/mainline/common/messages

Tests the conversion of a `Message` object representing a GET immutable response into bytes and back. It verifies that the process is lossless by comparing the original and deserialized messages.

```Rust
    #[test]
    fn test_get_immutable_response() {
        let original_msg = Message {
            transaction_id: 3,
            version: Some([1, 2, 3, 4]),
            requester_ip: Some("50.51.52.53:5455".parse().unwrap()),
            read_only: false,
            message_type: MessageType::Response(ResponseSpecific::GetImmutable(
                GetImmutableResponseArguments {
                    responder_id: Id::random(),
                    token: [99, 100, 101, 102].into(),
                    nodes: None,
                    v: [99, 100, 101, 102].into(),
                },
            )),
        };

        let serde_msg = original_msg.clone().into_serde_message();
        let bytes = serde_msg.to_bytes().unwrap();
        let parsed_serde_msg = internal::DHTMessage::from_bytes(&bytes).unwrap();
        let parsed_msg = Message::from_serde_message(parsed_serde_msg).unwrap();
        assert_eq!(parsed_msg, original_msg);
    }
```

--------------------------------

### Create Synchronous Testnet with Bootstrapped Nodes

Source: https://docs.rs/mainline/latest/src/mainline/dht

Initializes a test network with a specified number of nodes and blocks until all nodes are bootstrapped. This method is suitable for synchronous runtimes.

```rust
pub fn new(count: usize) -> Result<Testnet, std::io::Error> {
    let testnet = Testnet::new_inner(count)?;

    for node in &testnet.nodes {
        node.bootstrapped();
    }

    Ok(testnet)
}
```

--------------------------------

### Rust DHT Get Peers Request Arguments

Source: https://docs.rs/mainline/latest/src/mainline/common/messages/internal

Defines the arguments for a DHT 'Get Peers' request. It includes the sender's ID and the info hash of the content being searched for. Both fields are 20-byte arrays and serialized as bytes.

```rust
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct DHTGetPeersRequestArguments {
    #[serde(with = "serde_bytes")]
    pub id: [u8; 20],

    #[serde(with = "serde_bytes")]
    pub info_hash: [u8; 20],
}
```

--------------------------------

### Rust DHT Get Peers Response Arguments

Source: https://docs.rs/mainline/latest/src/mainline/common/messages/internal

Defines the arguments for a DHT 'Get Peers' response. It includes the sender's ID, a token, optional node information, and a list of byte buffers representing peer addresses.

```rust
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct DHTGetPeersResponseArguments {
    #[serde(with = "serde_bytes")]
    pub id: [u8; 20],

    #[serde(with = "serde_bytes")]
    pub token: Box<[u8]>,

    #[serde(with = "serde_bytes")]
    #[serde(default)]
    pub nodes: Option<Box<[u8]>>,

    // values are not optional, because if they are missing this missing
    // we can just treat this as DHTNoValuesResponseArguments
    pub values: Vec<ByteBuf>,
}
```

--------------------------------

### SigningKey Construction

Source: https://docs.rs/mainline/latest/mainline/struct

Methods for constructing a SigningKey from byte arrays.

```APIDOC
## SigningKey Construction

### `from_bytes`

#### Description
Construct a `SigningKey` from a `SecretKey` byte array.

#### Method
`pub fn from_bytes(secret_key: &[u8; 32]) -> SigningKey`

#### Parameters
* **secret_key** (`&[u8; 32]`) - A 32-byte array representing the secret key.

#### Returns
A `SigningKey` instance.

### `from_keypair_bytes`

#### Description
Construct a `SigningKey` from the combined bytes of a `VerifyingKey` and `SecretKey`.

#### Method
`pub fn from_keypair_bytes(bytes: &[u8; 64]) -> Result<SigningKey, Error>`

#### Parameters
* **bytes** (`&[u8; 64]`) - A 64-byte array containing the secret key scalar and the public key's compressed Edwards-Y coordinate.

#### Returns
A `Result` containing a `SigningKey` on success, or a `SignatureError` on failure.
```

--------------------------------

### Rust DHT: Handle Get Mutable Request

Source: https://docs.rs/mainline/latest/src/mainline/rpc/server

Handles a 'get mutable' request in a DHT. It retrieves a mutable item by its target ID and returns the value if it's the most recent, or an appropriate response based on the sequence number.

```rust
fn handle_get_mutable(
    &mut self,
    routing_table: &RoutingTable,
    from: SocketAddrV4,
    target: Id,
    seq: Option<i64>,
) -> ResponseSpecific {
    match self.mutable_values.get(&target) {
        Some(item) => {
            let no_more_recent_values = seq.map(|request_seq| item.seq() <= request_seq);

            match no_more_recent_values {
                Some(true) => {
                    ResponseSpecific::NoMoreRecentValue(NoMoreRecentValueResponseArguments {
                        responder_id: *routing_table.id(),
                        token: self.tokens.generate_token(from).into(),
                        nodes: Some(routing_table.closest(target)),
                        seq: item.seq(),
                    })
                }
                _ => ResponseSpecific::GetMutable(GetMutableResponseArguments {
                    responder_id: *routing_table.id(),
                    token: self.tokens.generate_token(from).into(),
                    nodes: Some(routing_table.closest(target)),
                    v: item.value().into(),
                    k: *item.key(),
                    seq: item.seq(),
                    sig: *item.signature(),
                }),
            }
        }
        None => ResponseSpecific::NoValues(NoValuesResponseArguments {
            responder_id: *routing_table.id(),
            token: self.tokens.generate_token(from).into(),
            nodes: Some(routing_table.closest(target)),
        }),
    }
}
```

--------------------------------

### SigningKey Cloning and Debugging (Rust)

Source: https://docs.rs/mainline/latest/mainline/struct

Includes implementations for `Clone` to duplicate a `SigningKey`, `clone_from` for assignment, and `Debug` for formatting the key for debugging purposes.

```rust
fn clone(&self) -> SigningKey
```

```rust
fn clone_from(&mut self, source: &Self)
```

```rust
fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>
```

--------------------------------

### Rust DHT Get Mutable Response Arguments

Source: https://docs.rs/mainline/latest/src/mainline/common/messages/internal

Defines the arguments for a DHT 'Get Mutable' response. It includes the sender's ID, a token, optional node information, the mutable value, the public key, signature, and sequence number.

```rust
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct DHTGetMutableResponseArguments {
    #[serde(with = "serde_bytes")]
    pub id: [u8; 20],

    #[serde(with = "serde_bytes")]
    pub token: Box<[u8]>,

    #[serde(with = "serde_bytes")]
    #[serde(default)]
    pub nodes: Option<Box<[u8]>>,

    #[serde(with = "serde_bytes")]
    pub v: Box<[u8]>,

    #[serde(with = "serde_bytes")]
    pub k: [u8; 32],

    #[serde(with = "serde_bytes")]
    pub sig: [u8; 64],

    pub seq: i64,
}
```

--------------------------------

### Check Query Status and Handle Responses

Source: https://docs.rs/mainline/latest/src/mainline/rpc/put_query

Provides methods to check if a query has started (`started`), if a specific transaction ID is in flight (`inflight`), to record a successful response (`success`), and to record an error (`error`). The `error` method aggregates errors by code and maintains a sorted list of errors by frequency.

```rust
    pub fn started(&self) -> bool {
        !self.inflight_requests.is_empty()
    }

    pub fn inflight(&self, tid: u16) -> bool {
        self.inflight_requests.contains(&tid)
    }

    pub fn success(&mut self) {
        debug!(target = ?self.target, "PutQuery got success response");
        self.stored_at += 1
    }

    pub fn error(&mut self, error: ErrorSpecific) {
        debug!(target = ?self.target, ?error, "PutQuery got error");

        if let Some(pos) = self
            .errors
            .iter()
            .position(|(_, err)| error.code == err.code)
        {
            // Increment the count of the existing error
            self.errors[pos].0 += 1;

            // Move the updated element to maintain the order (highest count first)
            let mut i = pos;
            while i > 0 && self.errors[i].0 > self.errors[i - 1].0 {
                self.errors.swap(i, i - 1);
                i -= 1;
            }
        } else {
            // Add the new error with a count of 1
            self.errors.push((1, error));
        }
    }

    // ... other methods ...
```

--------------------------------

### KBucket Initialization and Node Addition in Rust

Source: https://docs.rs/mainline/latest/src/mainline/common/routing_table

Demonstrates the creation of a new KBucket and the logic for adding nodes. It handles cases where a node already exists (updating its last seen status if conditions are met), when the bucket has space, or when the least recently seen node needs to be replaced by a new one.

```Rust
pub struct KBucket {
    /// Nodes in the k-bucket, sorted by the least recently seen.
    nodes: Vec<Node>,
}

impl KBucket {
    pub fn new() -> Self {
        KBucket {
            nodes: Vec::with_capacity(MAX_BUCKET_SIZE_K),
        }
    }

    pub fn add(&mut self, incoming: Node) -> bool {
        if let Some(index) = self.iter().position(|n| n.id() == incoming.id()) {
            let existing = self.nodes[index].clone();

            // If the incoming node is secure, then we trust its IP address for this Id,
            // and even if it changed its port number, we should accept it.
            //
            // If neither nodes are secure for this Id, but the incoming is the same IP,
            // then add the incoming one, effectively updating the node's
            // `last_seen` and moving it to the end of the bucket.
            // Possibly also updating the port, which is a good thing, instead of waiting
            // for the old port to timeout (not responding to Pings).
            //
            // Using same ip instead of same address, allow
            if incoming.is_secure() || (!existing.is_secure() && existing.same_ip(&incoming)) {
                self.nodes.remove(index);
                self.nodes.push(incoming);

                true
            } else {
                false
            }
        } else if self.nodes.len() < MAX_BUCKET_SIZE_K {
            self.nodes.push(incoming);
            true
        } else if self.nodes[0].is_stale() {
            // Remove the least recently seen node and add the new one
            self.nodes.remove(0);
            self.nodes.push(incoming);

            true
        } else {
            false
        }
    }

    pub fn is_empty(&self) -> bool {
        self.nodes.is_empty()
    }

    pub fn iter(&self) -> Iter<'_, Node> {
        self.nodes.iter()
    }

    #[cfg(test)]
    fn contains(&self, id: &Id) -> bool {
        self.iter().any(|node| node.id() == id)
    }
}

impl Default for KBucket {
    fn default() -> Self {
        Self::new()
    }
}

```

--------------------------------

### Rust: Convert SigningKey to bytes

Source: https://docs.rs/mainline/latest/mainline/struct

Illustrates converting a `SigningKey` instance back into its raw byte representation. This is often needed for storage or transmission.

```Rust
use ed25519_dalek::SigningKey;

// Assuming 'signing_key' is an existing SigningKey instance
// let signing_key: SigningKey = ...;

let key_bytes = signing_key.to_bytes();
// 'key_bytes' is now a [u8; 32] array representing the secret key.
```
Tokens:
Raw