Add UPnP Support

docs/Reference/Pantheon-CLI-Syntax.md

@@ -770,6 +770,27 @@ The default is 30303. Ports must be [exposed appropriately](../Configuring-Panth
 !!!note
     This option is not used when running Pantheon from the [Docker image](../Getting-Started/Run-Docker-Image.md#exposing-ports). 
 
+### nat-method
+
+```bash tab="Syntax"
+--nat-method=UPNP
+```
+
+```bash tab="Example Configuration File"
+nat-method="UPNP"
+```
+
+Specify the method for handling NAT environments. Options are: `UPNP` and `NONE`.
+The default is `NONE`, which disables NAT functionality.
+
+!!!tip
+    `UPNP` works well with a typical home or small office environment where a wireless router or modem provides NAT isolation. This should provide
+    automatic detection and port-forwarding. UPnP support is often disabled by default in networking equipment firmware, however, any may need to be
+    explicitly enabled.
+
+!!!note
+    Option `UPNP` may introduce delays during node startup, especially on networks where no UPnP gateway device can be found.
+
 ### permissions-accounts-config-file-enabled
 
 ```bash tab="Syntax"

ethereum/jsonrpc/build.gradle

@@ -36,6 +36,7 @@ dependencies {
   implementation project(':ethereum:rlp')
   implementation project(':ethereum:permissioning')
   implementation project(':metrics:core')
+  implementation project(':nat')
 
   implementation 'com.google.guava:guava'
   implementation 'io.vertx:vertx-core'

ethereum/jsonrpc/src/main/java/tech/pegasys/pantheon/ethereum/jsonrpc/JsonRpcHttpService.java

@@ -35,6 +35,7 @@
 import tech.pegasys.pantheon.metrics.OperationTimer;
 import tech.pegasys.pantheon.metrics.OperationTimer.TimingContext;
 import tech.pegasys.pantheon.metrics.PantheonMetricCategory;
+import tech.pegasys.pantheon.nat.upnp.UpnpNatManager;
 import tech.pegasys.pantheon.util.NetworkUtility;
 
 import java.net.InetSocketAddress;
@@ -82,6 +83,7 @@ public class JsonRpcHttpService {
   private final Vertx vertx;
   private final JsonRpcConfiguration config;
   private final RpcMethods rpcMethods;
+  private final Optional<UpnpNatManager> natManager;
   private final Path dataDir;
   private final LabelledMetric<OperationTimer> requestTimer;
 
@@ -91,11 +93,24 @@ public class JsonRpcHttpService {
   private final HealthService livenessService;
   private final HealthService readinessService;
 
+  /**
+   * Construct a JsonRpcHttpService handler
+   *
+   * @param vertx The vertx process that will be running this service
+   * @param dataDir The data directory where requests can be buffered
+   * @param config Configuration for the rpc methods being loaded
+   * @param metricsSystem The metrics service that activities should be reported to
+   * @param natManager The NAT environment manager.
+   * @param methods The json rpc methods that should be enabled
+   * @param livenessService A service responsible for reporting whether this node is live
+   * @param readinessService A service responsible for reporting whether this node has fully started
+   */
   public JsonRpcHttpService(
       final Vertx vertx,
       final Path dataDir,
       final JsonRpcConfiguration config,
       final MetricsSystem metricsSystem,
+      final Optional<UpnpNatManager> natManager,
       final Map<String, JsonRpcMethod> methods,
       final HealthService livenessService,
       final HealthService readinessService) {
@@ -104,6 +119,7 @@ public JsonRpcHttpService(
         dataDir,
         config,
         metricsSystem,
+        natManager,
         methods,
         AuthenticationService.create(vertx, config),
         livenessService,
@@ -115,6 +131,7 @@ private JsonRpcHttpService(
       final Path dataDir,
       final JsonRpcConfiguration config,
       final MetricsSystem metricsSystem,
+      final Optional<UpnpNatManager> natManager,
       final Map<String, JsonRpcMethod> methods,
       final Optional<AuthenticationService> authenticationService,
       final HealthService livenessService,
@@ -129,6 +146,7 @@ private JsonRpcHttpService(
     validateConfig(config);
     this.config = config;
     this.vertx = vertx;
+    this.natManager = natManager;
     this.rpcMethods = new RpcMethods(methods);
     this.authenticationService = authenticationService;
     this.livenessService = livenessService;
@@ -144,6 +162,7 @@ private void validateConfig(final JsonRpcConfiguration config) {
 
   public CompletableFuture<?> start() {
     LOG.info("Starting JsonRPC service on {}:{}", config.getHost(), config.getPort());
+
     // Create the HTTP server and a router object.
     httpServer =
         vertx.createHttpServer(
@@ -207,6 +226,13 @@ public CompletableFuture<?> start() {
                 LOG.info(
                     "JsonRPC service started and listening on {}:{}", config.getHost(), actualPort);
                 config.setPort(actualPort);
+                // Request that a NAT port forward for our server port
+                if (natManager.isPresent()) {
+                  natManager
+                      .get()
+                      .requestPortForward(
+                          config.getPort(), UpnpNatManager.Protocol.TCP, "partheon-json-rpc");
+                }
                 return;
               }
               httpServer = null;

ethereum/jsonrpc/src/test/java/tech/pegasys/pantheon/ethereum/jsonrpc/AbstractEthJsonRpcHttpServiceTest.java

@@ -209,6 +209,7 @@ public void setupTest() throws Exception {
             folder.newFolder().toPath(),
             config,
             new NoOpMetricsSystem(),
+            Optional.empty(),
             methods,
             HealthService.ALWAYS_HEALTHY,
             HealthService.ALWAYS_HEALTHY);

ethereum/jsonrpc/src/test/java/tech/pegasys/pantheon/ethereum/jsonrpc/JsonRpcHttpServiceCorsTest.java

@@ -18,6 +18,7 @@
 import tech.pegasys.pantheon.metrics.noop.NoOpMetricsSystem;
 
 import java.util.HashMap;
+import java.util.Optional;
 
 import com.google.common.collect.Lists;
 import io.vertx.core.Vertx;
@@ -193,6 +194,7 @@ private JsonRpcHttpService createJsonRpcHttpServiceWithAllowedDomains(
             folder.newFolder().toPath(),
             config,
             new NoOpMetricsSystem(),
+            Optional.empty(),
             new HashMap<>(),
             HealthService.ALWAYS_HEALTHY,
             HealthService.ALWAYS_HEALTHY);

ethereum/jsonrpc/src/test/java/tech/pegasys/pantheon/ethereum/jsonrpc/JsonRpcHttpServiceHostWhitelistTest.java

@@ -125,6 +125,7 @@ private JsonRpcHttpService createJsonRpcHttpService() throws Exception {
         folder.newFolder().toPath(),
         jsonRpcConfig,
         new NoOpMetricsSystem(),
+        Optional.empty(),
         rpcMethods,
         HealthService.ALWAYS_HEALTHY,
         HealthService.ALWAYS_HEALTHY);

ethereum/jsonrpc/src/test/java/tech/pegasys/pantheon/ethereum/jsonrpc/JsonRpcHttpServiceLoginTest.java

@@ -164,6 +164,7 @@ private static JsonRpcHttpService createJsonRpcHttpService() throws Exception {
         folder.newFolder().toPath(),
         config,
         new NoOpMetricsSystem(),
+        Optional.empty(),
         rpcMethods,
         HealthService.ALWAYS_HEALTHY,
         HealthService.ALWAYS_HEALTHY);

ethereum/jsonrpc/src/test/java/tech/pegasys/pantheon/ethereum/jsonrpc/JsonRpcHttpServiceRpcApisTest.java

@@ -212,6 +212,7 @@ private JsonRpcHttpService createJsonRpcHttpServiceWithRpcApis(final JsonRpcConf
             folder.newFolder().toPath(),
             config,
             new NoOpMetricsSystem(),
+            Optional.empty(),
             rpcMethods,
             HealthService.ALWAYS_HEALTHY,
             HealthService.ALWAYS_HEALTHY);
@@ -301,6 +302,7 @@ private JsonRpcHttpService createJsonRpcHttpService(
             folder.newFolder().toPath(),
             jsonRpcConfiguration,
             new NoOpMetricsSystem(),
+            Optional.empty(),
             rpcMethods,
             HealthService.ALWAYS_HEALTHY,
             HealthService.ALWAYS_HEALTHY);

ethereum/jsonrpc/src/test/java/tech/pegasys/pantheon/ethereum/jsonrpc/JsonRpcHttpServiceTest.java

@@ -154,6 +154,7 @@ private static JsonRpcHttpService createJsonRpcHttpService(final JsonRpcConfigur
         folder.newFolder().toPath(),
         config,
         new NoOpMetricsSystem(),
+        Optional.empty(),
         rpcMethods,
         HealthService.ALWAYS_HEALTHY,
         HealthService.ALWAYS_HEALTHY);
@@ -165,6 +166,7 @@ private static JsonRpcHttpService createJsonRpcHttpService() throws Exception {
         folder.newFolder().toPath(),
         createJsonRpcConfig(),
         new NoOpMetricsSystem(),
+        Optional.empty(),
         rpcMethods,
         HealthService.ALWAYS_HEALTHY,
         HealthService.ALWAYS_HEALTHY);

ethereum/p2p/build.gradle

@@ -30,6 +30,7 @@ dependencies {
   implementation project(':ethereum:core')
   implementation project(':ethereum:rlp')
   implementation project(':metrics:core')
+  implementation project(':nat')
 
   implementation 'com.google.guava:guava'
   implementation 'io.prometheus:simpleclient'

ethereum/p2p/src/main/java/tech/pegasys/pantheon/ethereum/p2p/discovery/PeerDiscoveryAgent.java

@@ -28,6 +28,7 @@
 import tech.pegasys.pantheon.ethereum.p2p.peers.PeerId;
 import tech.pegasys.pantheon.ethereum.p2p.permissions.PeerPermissions;
 import tech.pegasys.pantheon.metrics.MetricsSystem;
+import tech.pegasys.pantheon.nat.upnp.UpnpNatManager;
 import tech.pegasys.pantheon.util.NetworkUtility;
 import tech.pegasys.pantheon.util.Subscribers;
 import tech.pegasys.pantheon.util.bytes.BytesValue;
@@ -39,6 +40,7 @@
 import java.util.OptionalInt;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.TimeUnit;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
@@ -61,6 +63,7 @@ public abstract class PeerDiscoveryAgent {
   protected final List<DiscoveryPeer> bootstrapPeers;
   private final List<PeerRequirement> peerRequirements = new CopyOnWriteArrayList<>();
   private final PeerPermissions peerPermissions;
+  private final Optional<UpnpNatManager> natManager;
   private final MetricsSystem metricsSystem;
   /* The peer controller, which takes care of the state machine of peers. */
   protected Optional<PeerDiscoveryController> controller = Optional.empty();
@@ -83,6 +86,7 @@ public PeerDiscoveryAgent(
       final SECP256K1.KeyPair keyPair,
       final DiscoveryConfiguration config,
       final PeerPermissions peerPermissions,
+      final Optional<UpnpNatManager> natManager,
       final MetricsSystem metricsSystem) {
     this.metricsSystem = metricsSystem;
     checkArgument(keyPair != null, "keypair cannot be null");
@@ -91,6 +95,7 @@ public PeerDiscoveryAgent(
     validateConfiguration(config);
 
     this.peerPermissions = peerPermissions;
+    this.natManager = natManager;
     this.bootstrapPeers =
         config.getBootnodes().stream().map(DiscoveryPeer::fromEnode).collect(Collectors.toList());
 
@@ -117,6 +122,26 @@ public CompletableFuture<Integer> start(final int tcpPort) {
       final int port = config.getBindPort();
       LOG.info("Starting peer discovery agent on host={}, port={}", host, port);
 
+      // override advertised host if we detect an external IP address via NAT manager
+      String externalIpAddress = null;
+      if (natManager.isPresent()) {
+        try {
+          final int timeoutSeconds = 60;
+          LOG.info("Waiting for up to {} seconds to detect external IP address...", timeoutSeconds);
+          externalIpAddress =
+              natManager.get().queryExternalIPAddress().get(timeoutSeconds, TimeUnit.SECONDS);
+
+        } catch (Exception e) {
+          LOG.warn(
+              "Caught exception while trying to query NAT external IP address (ignoring): {}", e);
+        }
+      }
+
+      final String advertisedAddress =
+          (null != externalIpAddress && !externalIpAddress.equals(""))
+              ? externalIpAddress
+              : config.getAdvertisedHost();
+
       return listenForConnections()
           .thenApply(
               (InetSocketAddress localAddress) -> {
@@ -126,7 +151,7 @@ public CompletableFuture<Integer> start(final int tcpPort) {
                     DiscoveryPeer.fromEnode(
                         EnodeURL.builder()
                             .nodeId(id)
-                            .ipAddress(config.getAdvertisedHost())
+                            .ipAddress(advertisedAddress)
                             .listeningPort(tcpPort)
                             .discoveryPort(discoveryPort)
                             .build());

ethereum/p2p/src/main/java/tech/pegasys/pantheon/ethereum/p2p/discovery/VertxPeerDiscoveryAgent.java

@@ -24,12 +24,14 @@
 import tech.pegasys.pantheon.ethereum.p2p.permissions.PeerPermissions;
 import tech.pegasys.pantheon.metrics.MetricsSystem;
 import tech.pegasys.pantheon.metrics.PantheonMetricCategory;
+import tech.pegasys.pantheon.nat.upnp.UpnpNatManager;
 import tech.pegasys.pantheon.util.NetworkUtility;
 
 import java.io.IOException;
 import java.net.BindException;
 import java.net.InetSocketAddress;
 import java.net.SocketException;
+import java.util.Optional;
 import java.util.OptionalInt;
 import java.util.concurrent.CompletableFuture;
 import java.util.function.IntSupplier;
@@ -58,8 +60,9 @@ public VertxPeerDiscoveryAgent(
       final KeyPair keyPair,
       final DiscoveryConfiguration config,
       final PeerPermissions peerPermissions,
+      final Optional<UpnpNatManager> natManager,
       final MetricsSystem metricsSystem) {
-    super(keyPair, config, peerPermissions, metricsSystem);
+    super(keyPair, config, peerPermissions, natManager, metricsSystem);
     checkArgument(vertx != null, "vertx instance cannot be null");
     this.vertx = vertx;