Expand description
§n0-mainline
Simple, robust, BitTorrent’s Mainline DHT implementation.
This is an iroh-flavored fork of nuhvi/dht: it is a support crate for iroh and integrates with the iroh ecosystem (e.g. iroh-base keys, async UDP via noq-udp). It does not depend on the iroh crate itself, so it can be used standalone. It does however require noq-udp for its socket layer.
The main purpose for which iroh uses n0-mainline is endpoint address lookup via BEP_0044.
§Getting started
Check the Examples.
§Features
§Client
Running as a client, means you can store and query for values on the DHT, but not accept any incoming requests.
use n0_mainline::Dht;
let dht = Dht::client().await.unwrap();Supported BEPs:
- BEP_0005 DHT Protocol
- BEP_0042 DHT Security extension
- BEP_0043 Read-only DHT Nodes
- BEP_0044 Storing arbitrary data in the DHT
This implementation also includes measures against Vertical Sybil Attacks.
§Server
Running as a server is the same as a client, but you also respond to incoming requests and serve as a routing and storing node, supporting the general routing of the DHT, and contributing to the storage capacity of the DHT.
use n0_mainline::Dht;
let dht = Dht::server().await.unwrap(); // or `Dht::builder().server_mode().build().await;`Supported BEPs:
- BEP_0005 DHT Protocol
- BEP_0042 DHT Security extension
- BEP_0043 Read-only DHT Nodes
- BEP_0044 Storing arbitrary data in the DHT
§Rate limiting
The server implementation has no rate-limiting, you can run your own request filter and apply your custom rate-limiting. However, that limit/block will only apply after parsing incoming messages, and it won’t affect handling incoming responses.
§Adaptive mode
The default Adaptive mode will start the node in client mode, and after 15 minutes of running with a publicly accessible address, it will switch to server mode. This way nodes that can serve as routing nodes (accessible and less likely to churn), serve as such.
If you want to explicitly start in Server mode, because you know you are not running behind firewall,
you can call Dht::builder().server_mode().build().await, and you can optionally add your known public ip so the node doesn’t have to depend on,
votes from responding nodes: Dht::builder().server_mode().public_ip().build().await.
§Acknowledgment
This implementation was possible thanks to Webtorrent’s Bittorrent-dht as a reference, and Rustydht-lib that saved me a lot of time, especially at the serialization and deserialization of Bencode messages.
Modules§
- errors
- Exported errors
Structs§
- Actor
Shutdown - Error returned when the DHT actor task has shut down.
- Closest
Nodes - Manage closest nodes found in a query.
- Dht
- Mainline Dht node.
- DhtBuilder
- A builder for the Dht node.
- GetStream
- A Stream of incoming peers, immutable or mutable values.
- Id
- Kademlia node Id or a lookup target
- Mutable
Item - BEP_0044’s Mutable item.
- Node
- Node entry in Kademlia routing table
- Request
Specific - An incoming KRPC request, as observed by the local node.
- Server
Settings - Settings for the default dht server.
- Signing
Key - ed25519 signing key which can be used to produce signatures.
- Testnet
- Create a testnet of Dht nodes to run tests against instead of the real mainline network.
Enums§
- PutRequest
Specific - The kind of storage request, with operation-specific arguments.
Traits§
- Request
Filter - A trait for filtering incoming requests to a DHT node and decide whether to allow handling it or rate limit or ban the requester, or prohibit specific requests’ details.