Nat hole punching for discv5.2

.github/workflows/build.yml

@@ -19,7 +19,7 @@ jobs:
  - name: Get latest version of stable rust
  run: rustup update stable
  - name: Lint code for quality and style with Clippy
- run: cargo clippy --workspace --tests --all-features -- -D warnings
+ run: cargo clippy --workspace --tests --all-features -- -D warnings -A clippy::assertions_on_constants 
  release-tests-ubuntu:
  runs-on: ubuntu-latest
  needs: cargo-fmt
@@ -50,7 +50,7 @@ jobs:
  - name: Get latest version of stable rust
  run: rustup update stable
  - name: Check rustdoc links
- run: RUSTDOCFLAGS="--deny broken_intra_doc_links" cargo doc --verbose --workspace --no-deps --document-private-items
+ run: RUSTDOCFLAGS="--deny rustdoc::broken_intra_doc_links" cargo doc --verbose --workspace --no-deps --document-private-items
  cargo-udeps:
  name: cargo-udeps
  runs-on: ubuntu-latest

Cargo.toml

@@ -34,10 +34,11 @@ aes = { version = "0.7.5", features = ["ctr"] }
 aes-gcm = "0.9.4"
 tracing = { version = "0.1.29", features = ["log"] }
 tracing-subscriber = { version = "0.3.3", features = ["env-filter"] }
-lru = "0.7.1"
+lru = {version = "0.7.1", default-features = false }
 hashlink = "0.7.0"
 delay_map = "0.3.0"
 more-asserts = "0.2.2"
+derive_more = { version = "0.99.17", default-features = false, features = ["from", "display", "deref", "deref_mut"] }
 
 [dev-dependencies]
 rand_07 = { package = "rand", version = "0.7" }

src/config.rs

@@ -1,9 +1,14 @@
 //! A set of configuration parameters to tune the discovery protocol.
 use crate::{
- kbucket::MAX_NODES_PER_BUCKET, socket::ListenConfig, Enr, Executor, PermitBanList, RateLimiter,
+ kbucket::MAX_NODES_PER_BUCKET, Enr, Executor, ListenConfig, PermitBanList, RateLimiter,
  RateLimiterBuilder,
 };
-use std::time::Duration;
+
+/// The minimum number of unreachable Sessions a node must allow. This enables the network to
+/// boostrap.
+const MIN_SESSIONS_UNREACHABLE_ENR: usize = 10;
+
+use std::{ops::RangeInclusive, time::Duration};
 
 /// Configuration parameters that define the performance of the discovery network.
 #[derive(Clone)]
@@ -96,6 +101,15 @@ pub struct Discv5Config {
  /// timing support. By default, the executor that created the discv5 struct will be used.
  pub executor: Option<Box<dyn Executor + Send + Sync>>,
 
+ /// The max limit for peers with unreachable ENRs. Benevolent examples of such peers are peers
+ /// that are discovering their externally reachable socket, nodes must assist at least one
+ /// such peer in discovering their reachable socket via ip voting, and peers behind symmetric
+ /// NAT. Default is no limit. Minimum is 10.
+ pub unreachable_enr_limit: Option<usize>,
+
+ /// The unused port range to try and bind to when testing if this node is behind NAT based on
+ /// observed address reported at runtime by peers.
+ pub unused_port_range: Option<RangeInclusive<u16>>,
  /// Configuration for the sockets to listen on.
  pub listen_config: ListenConfig,
 }
@@ -142,6 +156,8 @@ impl Discv5ConfigBuilder {
  permit_ban_list: PermitBanList::default(),
  ban_duration: Some(Duration::from_secs(3600)), // 1 hour
  executor: None,
+ unreachable_enr_limit: None,
+ unused_port_range: None,
  listen_config,
  };
 
@@ -302,13 +318,33 @@ impl Discv5ConfigBuilder {
  self
  }
 
+ /// Sets the maximum number of sessions with peers with unreachable ENRs to allow. Minimum is 1
+ /// peer. Default is no limit.
+ pub fn unreachable_enr_limit(&mut self, peer_limit: Option<usize>) -> &mut Self {
+ self.config.unreachable_enr_limit = peer_limit;
+ self
+ }
+
+ /// Sets the unused port range for testing if node is behind a NAT. Default is the range
+ /// covering user and dynamic ports.
+ pub fn unused_port_range(
+ &mut self,
+ unused_port_range: Option<RangeInclusive<u16>>,
+ ) -> &mut Self {
+ self.config.unused_port_range = unused_port_range;
+ self
+ }
+
  pub fn build(&mut self) -> Discv5Config {
  // If an executor is not provided, assume a current tokio runtime is running.
  if self.config.executor.is_none() {
  self.config.executor = Some(Box::<crate::executor::TokioExecutor>::default());
  };
 
  assert!(self.config.incoming_bucket_limit <= MAX_NODES_PER_BUCKET);
+ if let Some(limit) = self.config.unreachable_enr_limit {
+ assert!(limit >= MIN_SESSIONS_UNREACHABLE_ENR);
+ }
 
  self.config.clone()
  }

src/error.rs

@@ -1,15 +1,24 @@
-use crate::{handler::Challenge, node_info::NonContactable};
+use crate::{
+ handler::Challenge,
+ node_info::{NodeAddress, NonContactable},
+};
+use derive_more::From;
 use rlp::DecoderError;
 use std::fmt;
 
-#[derive(Debug)]
+#[derive(Debug, From)]
 /// A general error that is used throughout the Discv5 library.
 pub enum Discv5Error {
+ /// An invalid message type was received.
+ InvalidMessage,
  /// An invalid ENR was received.
  InvalidEnr,
+ /// The limit for sessions with peers that have an unreachable ENR is reached.
+ LimitSessionsUnreachableEnr,
  /// The public key type is known.
  UnknownPublicKey,
  /// The ENR key used is not supported.
+ #[from(ignore)]
  KeyTypeNotSupported(&'static str),
  /// Failed to derive an ephemeral public key.
  KeyDerivationFailed,
@@ -27,25 +36,48 @@ pub enum Discv5Error {
  ServiceAlreadyStarted,
  /// A session could not be established with the remote.
  SessionNotEstablished,
+ /// A session to the given peer is already established.
+ SessionAlreadyEstablished(NodeAddress),
  /// An RLP decoding error occurred.
  RLPError(DecoderError),
  /// Failed to encrypt a message.
+ #[from(ignore)]
  EncryptionFail(String),
  /// Failed to decrypt a message.
+ #[from(ignore)]
  DecryptionFailed(String),
  /// The custom error has occurred.
+ #[from(ignore)]
  Custom(&'static str),
  /// A generic dynamic error occurred.
+ #[from(ignore)]
  Error(String),
  /// An IO error occurred.
  Io(std::io::Error),
 }
 
-impl From<std::io::Error> for Discv5Error {
- fn from(err: std::io::Error) -> Discv5Error {
- Discv5Error::Io(err)
- }
+/// An error occurred whilst attempting to hole punch NAT.
+#[derive(Debug)]
+pub enum NatError {
+ /// Initiator error.
+ Initiator(Discv5Error),
+ /// Relayer error.
+ Relay(Discv5Error),
+ /// Target error.
+ Target(Discv5Error),
+}
+
+macro_rules! impl_from_variant {
+ ($(<$($generic: ident,)+>)*, $from_type: ty, $to_type: ty, $variant: path) => {
+ impl$(<$($generic,)+>)* From<$from_type> for $to_type {
+ fn from(_e: $from_type) -> Self {
+ $variant
+ }
+ }
+ };
 }
+impl_from_variant!(<T,>, tokio::sync::mpsc::error::SendError<T>, Discv5Error, Self::ServiceChannelClosed);
+impl_from_variant!(, NonContactable, Discv5Error, Self::InvalidEnr);
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 /// Types of packet errors.
@@ -111,6 +143,9 @@ pub enum RequestError {
  InvalidMultiaddr(&'static str),
  /// Failure generating random numbers during request.
  EntropyFailure(&'static str),
+ /// Malicious peer tried to initiate nat hole punching for another peer. todo(emhane): this is
+ /// notification error.
+ MaliciousRelayInit,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]