Add hole punching test

tests/integration/nat/hole-punching/README.md

@@ -0,0 +1,43 @@
+# NAT hole-punching scenario
+
+## Scenario
+
+A node behind a NAT is reachable only through A's relay. When the reachable node
+C dials it through the relay, the relayed node dials C back directly (C is
+public) and the relayed connection is upgraded to a direct one.
+
+## Topology
+
+```
+node B ──── lan ──── router (NAT) ──── wan ──── bootstrap A (relay)
+                                        └────── node C (reachable)
+```
+
+- **bootstrap A** — public node on the wan, autonat + relay server.
+- **router** — `lan -> wan` masquerade and *no* inbound forward.
+- **node B** — `nat=auto`, on the lan. NotReachable, takes a relay reservation
+  on A. When C reaches it through the relay, its hole-punching handler dials C
+  back directly and closes the relayed connection.
+- **node C** — `nat=auto`, directly on the wan, so it is `Reachable`. It dials B
+  through the relay.
+
+## Run
+
+```bash
+make testNatIntegration \
+  STORAGE_INTEGRATION_TEST_INCLUDES=tests/integration/nat/hole-punching/testholepunching.nim
+```
+
+Builds the shared image and brings the compose topology up and down. Rootless, but
+needs the host netfilter modules — if the router fails on iptables:
+`sudo modprobe iptable_nat nf_conntrack`.
+
+## Expected result
+
+B is `NotReachable` behind the relay, C is `Reachable`. C downloads from B
+through the relay, which opens a relayed connection; B then dials C back
+directly. Hole punching has no REST surface, so the test asserts on B's log line
+`Direct connection created.`.
+
+Per-run container logs (router, bootstrap, client, node) are written before teardown to
+`tests/integration/logs/<timestamp>__NAT_hole_punching/<test>/<service>.log`.

tests/integration/nat/hole-punching/compose.yml

@@ -0,0 +1,112 @@
+# A node behind a NAT is reachable only through A's relay. When the reachable
+# node C dials it through the relay, the relayed node dials C back directly
+# (C is public) and the relayed connection is upgraded to a direct one. Same
+# topology as relay-download. Run via testholepunching.nim.
+#
+#   node B ──── lan ──── router (NAT) ──── wan ──── bootstrap A (relay)
+#                                           └────── node C (reachable)
+name: nat-hole-punching
+
+# Topology addresses, named for their role (defined once, referenced below).
+x-addresses:
+  # fake public internet; a routable range so B looks public to A
+  wan_subnet: &wan_subnet 7.7.7.0/24
+  # private network behind the NAT
+  lan_subnet: &lan_subnet 10.99.0.0/24
+  # A: public bootstrap, autonat + relay server
+  bootstrap_ip: &bootstrap_ip 7.7.7.10
+  # C: public node on the wan, reachable, the one that dials B through the relay
+  client_ip: &client_ip 7.7.7.20
+  # router's public face
+  router_wan_ip: &router_wan_ip 7.7.7.2
+  # router's private face = B's gateway
+  router_lan_ip: &router_lan_ip 10.99.0.2
+  # B, behind the NAT
+  node_ip: &node_ip 10.99.0.10
+
+networks:
+  wan:
+    # Keep the fake public range private, not exposed to the host
+    internal: true
+    ipam:
+      config:
+        - subnet: *wan_subnet
+  lan:
+    ipam:
+      config:
+        - subnet: *lan_subnet
+
+services:
+  router:
+    image: localhost/storage-nat
+    cap_add: [NET_ADMIN]
+    sysctls:
+      net.ipv4.ip_forward: 1
+    networks:
+      wan:
+        ipv4_address: *router_wan_ip
+      lan:
+        ipv4_address: *router_lan_ip
+    environment:
+      ROUTER_WAN_IP: *router_wan_ip
+      LAN_SUBNET: *lan_subnet
+    # scripts mounted, so editing them needs no image rebuild
+    volumes:
+      - ../router-common.sh:/scripts/router-common.sh:ro,z
+      - ./router-entrypoint.sh:/scripts/router-entrypoint.sh:ro,z
+    entrypoint: ["bash", "/scripts/router-entrypoint.sh"]
+
+  bootstrap:
+    image: localhost/storage-nat
+    networks:
+      wan:
+        ipv4_address: *bootstrap_ip
+    entrypoint: ["/app/build/storage"]
+    command:
+      - --listen-ip=0.0.0.0
+      - --api-bindaddr=0.0.0.0
+      - --listen-port=8070
+      - --disc-port=8090
+      - --api-port=8080
+      # bootstrap_ip (anchors can't go inside a string)
+      - --nat=extip:7.7.7.10
+      - --relay-server
+      - --autonat-server
+      - --no-bootstrap-node
+      - --data-dir=/data
+      - --log-level=DEBUG
+
+  # C sits on the wan, directly reachable
+  client:
+    image: localhost/storage-nat
+    depends_on: [bootstrap]
+    networks:
+      wan:
+        ipv4_address: *client_ip
+    # C's API, published so the test can drive the download from C and poll it
+    ports:
+      - "127.0.0.1:18089:8080"
+    environment:
+      # C fetches A's SPR from this API at startup to join the network (bootstrap_ip)
+      BOOTSTRAP_API: http://7.7.7.10:8080
+    volumes:
+      - ../node-entrypoint.sh:/scripts/node-entrypoint.sh:ro,z
+    entrypoint: ["bash", "/scripts/node-entrypoint.sh"]
+
+  node:
+    image: localhost/storage-nat
+    cap_add: [NET_ADMIN]
+    depends_on: [router, bootstrap]
+    networks:
+      lan:
+        ipv4_address: *node_ip
+    # B's API, published so the test can upload to it and poll it
+    ports:
+      - "127.0.0.1:18088:8080"
+    environment:
+      ROUTER_LAN_IP: *router_lan_ip
+      # B fetches A's SPR from this API at startup to join the network (bootstrap_ip)
+      BOOTSTRAP_API: http://7.7.7.10:8080
+    volumes:
+      - ../node-entrypoint.sh:/scripts/node-entrypoint.sh:ro,z
+    entrypoint: ["bash", "/scripts/node-entrypoint.sh"]

tests/integration/nat/hole-punching/router-entrypoint.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+source "$(dirname "$0")/router-common.sh"
+
+echo "router ready (wan iface $wanif)"
+
+hold_until_stopped

tests/integration/nat/hole-punching/testholepunching.nim

@@ -0,0 +1,72 @@
+## NAT hole-punching scenario — a node reached through the relay is upgraded to
+## a direct connection.
+##
+## B sits behind a NAT and is reachable only via A's relay. When the reachable
+## node C dials B through the relay, B's hole-punching handler dials C back
+## directly (C is public) and the relayed connection is replaced by a direct one.
+##
+## Hole punching has no REST surface, so success is asserted on B's container log
+## line below (DEBUG). Brittle if that message ever changes.
+##
+## Requires podman-compose and the scenario image:
+##   podman build -t localhost/storage-nat \
+##     -f tests/integration/nat/Dockerfile .
+
+import std/[json, os, sequtils, strutils, times]
+import pkg/chronos
+import pkg/questionable/results
+
+import ../../../asynctest
+import ../../../checktest
+import ../../storageclient
+import ../composehelper
+
+const directConnLog = "Direct connection created."
+
+proc announcesCircuitAddr(info: JsonNode): bool =
+  ## A node behind the relay announces its circuit (p2p-circuit) address.
+  info{"announceAddresses"}.getElems.anyIt("p2p-circuit" in it.getStr)
+
+asyncchecksuite "NAT hole punching":
+  let
+    composeFile = currentSourcePath.parentDir / "compose.yml"
+    nodeApiUrl = "http://127.0.0.1:18088/api/storage/v1"
+    clientApiUrl = "http://127.0.0.1:18089/api/storage/v1"
+    suiteName = "NAT hole punching"
+    testName = "a relayed node is upgraded to a direct connection"
+    services = ["router", "bootstrap", "client", "node"]
+    startTime = now().format("yyyy-MM-dd'_'HH:mm:ss")
+  var
+    nodeClient: StorageClient
+    clientC: StorageClient
+
+  setup:
+    compose(composeFile, "up -d")
+    nodeClient = StorageClient.new(nodeApiUrl)
+    clientC = StorageClient.new(clientApiUrl)
+
+  teardown:
+    await nodeClient.close()
+    await clientC.close()
+    saveContainerLogs(composeFile, suiteName, testName, startTime, services)
+    compose(composeFile, "down -v")
+
+  test testName:
+    # B is NotReachable behind the relay, C is reachable
+    check eventuallyInfo(
+      nodeClient,
+      info{"nat"}{"reachability"}.getStr == "NotReachable" and
+        info.announcesCircuitAddr(),
+    )
+    check eventuallyInfo(clientC, info{"nat"}{"reachability"}.getStr == "Reachable")
+
+    # C dials B through the relay; a download is enough to open the connection
+    let cid = (await nodeClient.upload("hole punch me")).get
+    check (await clientC.download(cid)).isOk
+
+    # B sees the relayed peer C join and dials it back directly
+    check eventuallySafe(
+      directConnLog in serviceLogs(composeFile, "node"),
+      timeout = 60_000,
+      pollInterval = 2_000,
+    )