@libp2p/upnp-nat 2.0.12 → 3.0.0

package/src/check-external-address.ts

@@ -1,16 +1,15 @@
 import { NotStartedError, start, stop } from '@libp2p/interface'
 import { repeatingTask } from '@libp2p/utils/repeating-task'
-import { multiaddr } from '@multiformats/multiaddr'
 import pDefer from 'p-defer'
 import { raceSignal } from 'race-signal'
-import type { NatAPI } from '@achingbrain/nat-port-mapper'
+import type { Gateway } from '@achingbrain/nat-port-mapper'
 import type { AbortOptions, ComponentLogger, Logger, Startable } from '@libp2p/interface'
 import type { AddressManager } from '@libp2p/interface-internal'
 import type { RepeatingTask } from '@libp2p/utils/repeating-task'
 import type { DeferredPromise } from 'p-defer'
 
 export interface ExternalAddressCheckerComponents {
-  client: NatAPI
+  gateway: Gateway
   addressManager: AddressManager
   logger: ComponentLogger
 }
@@ -18,7 +17,7 @@ export interface ExternalAddressCheckerComponents {
 export interface ExternalAddressCheckerInit {
   interval?: number
   timeout?: number
-  autoConfirmAddress?: boolean
+  onExternalAddressChange?(newExternalAddress: string): void
 }
 
 export interface ExternalAddress {
@@ -30,19 +29,19 @@ export interface ExternalAddress {
  */
 class ExternalAddressChecker implements ExternalAddress, Startable {
   private readonly log: Logger
-  private readonly client: NatAPI
+  private readonly gateway: Gateway
   private readonly addressManager: AddressManager
   private started: boolean
   private lastPublicIp?: string
   private readonly lastPublicIpPromise: DeferredPromise<string>
   private readonly check: RepeatingTask
-  private readonly autoConfirmAddress: boolean
+  private readonly onExternalAddressChange?: (newExternalAddress: string) => void
 
-  constructor (components: ExternalAddressCheckerComponents, init: ExternalAddressCheckerInit = {}) {
+  constructor (components: ExternalAddressCheckerComponents, init: ExternalAddressCheckerInit) {
     this.log = components.logger.forComponent('libp2p:upnp-nat:external-address-check')
-    this.client = components.client
+    this.gateway = components.gateway
     this.addressManager = components.addressManager
-    this.autoConfirmAddress = init.autoConfirmAddress ?? false
+    this.onExternalAddressChange = init.onExternalAddressChange
     this.started = false
 
     this.checkExternalAddress = this.checkExternalAddress.bind(this)
@@ -61,14 +60,11 @@ class ExternalAddressChecker implements ExternalAddress, Startable {
     }
 
     await start(this.check)
-
-    this.check.start()
     this.started = true
   }
 
   async stop (): Promise<void> {
     await stop(this.check)
-
     this.started = false
   }
 
@@ -87,37 +83,21 @@ class ExternalAddressChecker implements ExternalAddress, Startable {
 
   private async checkExternalAddress (options?: AbortOptions): Promise<void> {
     try {
-      const externalAddress = await this.client.externalIp(options)
+      const externalAddress = await this.gateway.externalIp(options)
 
       // check if our public address has changed
       if (this.lastPublicIp != null && externalAddress !== this.lastPublicIp) {
         this.log('external address changed from %s to %s', this.lastPublicIp, externalAddress)
 
-        for (const ma of this.addressManager.getAddresses()) {
-          const addrString = ma.toString()
-
-          if (!addrString.includes(this.lastPublicIp)) {
-            continue
-          }
-
-          // create a new version of the multiaddr with the new public IP
-          const newAddress = multiaddr(addrString.replace(this.lastPublicIp, externalAddress))
-
-          // remove the old address and add the new one
-          this.addressManager.removeObservedAddr(ma)
-          this.addressManager.confirmObservedAddr(newAddress)
-
-          if (this.autoConfirmAddress) {
-            this.addressManager.confirmObservedAddr(newAddress)
-          } else {
-            this.addressManager.addObservedAddr(newAddress)
-          }
-        }
+        // notify listeners that the address has changed
+        this.onExternalAddressChange?.(externalAddress)
       }
 
       this.lastPublicIp = externalAddress
       this.lastPublicIpPromise.resolve(externalAddress)
     } catch (err: any) {
+      this.log.error('could not resolve external address - %e', err)
+
       if (this.lastPublicIp != null) {
         // ignore the error if we've previously run successfully
         return
@@ -128,7 +108,7 @@ class ExternalAddressChecker implements ExternalAddress, Startable {
   }
 }
 
-export function dynamicExternalAddress (components: ExternalAddressCheckerComponents, init: ExternalAddressCheckerInit = {}): ExternalAddress {
+export function dynamicExternalAddress (components: ExternalAddressCheckerComponents, init: ExternalAddressCheckerInit): ExternalAddress {
   return new ExternalAddressChecker(components, init)
 }
 

package/src/constants.ts

@@ -0,0 +1,2 @@
+export const DEFAULT_GATEWAY_SEARCH_TIMEOUT = 60_000
+export const DEFAULT_GATEWAY_SEARCH_INTERVAL = 300_000

package/src/gateway-finder.ts

@@ -0,0 +1,75 @@
+import { TypedEventEmitter, start, stop } from '@libp2p/interface'
+import { repeatingTask } from '@libp2p/utils/repeating-task'
+import { DEFAULT_GATEWAY_SEARCH_INTERVAL, DEFAULT_GATEWAY_SEARCH_TIMEOUT } from './constants.js'
+import type { Gateway, UPnPNAT } from '@achingbrain/nat-port-mapper'
+import type { ComponentLogger, Logger } from '@libp2p/interface'
+import type { RepeatingTask } from '@libp2p/utils/repeating-task'
+
+export interface GatewayFinderComponents {
+  logger: ComponentLogger
+}
+
+export interface GatewayFinderInit {
+  portMappingClient: UPnPNAT
+}
+
+export interface GatewayFinderEvents {
+  'gateway': CustomEvent<Gateway>
+}
+
+export class GatewayFinder extends TypedEventEmitter<GatewayFinderEvents> {
+  private readonly log: Logger
+  private readonly gateways: Gateway[]
+  private readonly findGateways: RepeatingTask
+  private readonly portMappingClient: UPnPNAT
+  private started: boolean
+
+  constructor (components: GatewayFinderComponents, init: GatewayFinderInit) {
+    super()
+
+    this.log = components.logger.forComponent('libp2p:upnp-nat')
+    this.portMappingClient = init.portMappingClient
+    this.started = false
+    this.gateways = []
+
+    // every five minutes, search for network gateways for one minute
+    this.findGateways = repeatingTask(async (options) => {
+      for await (const gateway of this.portMappingClient.findGateways({
+        ...options,
+        searchInterval: 10000
+      })) {
+        if (this.gateways.some(g => {
+          return g.id === gateway.id && g.family === gateway.family
+        })) {
+          // already seen this gateway
+          continue
+        }
+
+        this.gateways.push(gateway)
+        this.safeDispatchEvent('gateway', {
+          detail: gateway
+        })
+      }
+    }, DEFAULT_GATEWAY_SEARCH_INTERVAL, {
+      runImmediately: true,
+      timeout: DEFAULT_GATEWAY_SEARCH_TIMEOUT
+    })
+  }
+
+  async start (): Promise<void> {
+    if (this.started) {
+      return
+    }
+
+    this.started = true
+    await start(this.findGateways)
+  }
+
+  /**
+   * Stops the NAT manager
+   */
+  async stop (): Promise<void> {
+    await stop(this.findGateways)
+    this.started = false
+  }
+}

package/src/index.ts

@@ -35,11 +35,12 @@
  * ```
  */
 
-import { UPnPNAT as UPnPNATClass, type NatAPI, type MapPortOptions } from './upnp-nat.js'
+import { UPnPNAT as UPnPNATClass } from './upnp-nat.js'
+import type { UPnPNAT as UPnPNATClient, MapPortOptions } from '@achingbrain/nat-port-mapper'
 import type { ComponentLogger, Libp2pEvents, NodeInfo, PeerId, TypedEventTarget } from '@libp2p/interface'
 import type { AddressManager } from '@libp2p/interface-internal'
 
-export type { NatAPI, MapPortOptions }
+export type { UPnPNATClient, MapPortOptions }
 
 export interface PMPOptions {
   /**
@@ -49,12 +50,6 @@ export interface PMPOptions {
 }
 
 export interface UPnPNATInit {
-  /**
-   * Pass a string to hard code the external address, otherwise it will be
-   * auto-detected
-   */
-  externalAddress?: string
-
   /**
    * Check if the external address has changed this often in ms. Ignored if an
    * external address is specified.
@@ -71,55 +66,38 @@ export interface UPnPNATInit {
    */
   externalAddressCheckTimeout?: number
 
-  /**
-   * Pass a value to use instead of auto-detection
-   */
-  localAddress?: string
-
   /**
    * A string value to use for the port mapping description on the gateway
    */
-  description?: string
-
-  /**
-   * How long UPnP port mappings should last for in seconds (minimum 1200)
-   */
-  ttl?: number
+  portMappingDescription?: string
 
   /**
-   * Whether to automatically refresh UPnP port mappings when their TTL is reached
-   */
-  keepAlive?: boolean
-
-  /**
-   * Pass a value to use instead of auto-detection
+   * How long UPnP port mappings should last for in ms
+   *
+   * @default 720_000
    */
-  gateway?: string
+  portMappingTTL?: number
 
   /**
-   * How long in ms to wait before giving up trying to auto-detect a
-   * `urn:schemas-upnp-org:device:InternetGatewayDevice:1` device on the local
-   * network
+   * Whether to automatically refresh UPnP port mappings when their TTL is
+   * reached
    *
-   * @default 10000
+   * @default true
    */
-  gatewayDetectionTimeout?: number
+  portMappingAutoRefresh?: boolean
 
   /**
-   * Ports are mapped when the `self:peer:update` event fires, which happens
-   * when the node's addresses change. To avoid starting to map ports while
-   * multiple addresses are being added, the mapping function is debounced by
-   * this number of ms
+   * How long before a port mapping expires to refresh it in ms
    *
-   * @default 5000
+   * @default 60_000
    */
-  delay?: number
+  portMappingRefreshThreshold?: number
 
   /**
    * A preconfigured instance of a NatAPI client can be passed as an option,
    * otherwise one will be created
    */
-  client?: NatAPI
+  portMappingClient?: UPnPNATClient
 
   /**
    * Any mapped addresses are added to the observed address list. These
@@ -142,7 +120,7 @@ export interface UPnPNATComponents {
 }
 
 export interface UPnPNAT {
-  client: NatAPI
+  portMappingClient: UPnPNATClient
 }
 
 export function uPnPNAT (init: UPnPNATInit = {}): (components: UPnPNATComponents) => UPnPNAT {

package/src/upnp-nat.ts

@@ -1,84 +1,55 @@
 import { upnpNat } from '@achingbrain/nat-port-mapper'
-import { isIPv4, isIPv6 } from '@chainsafe/is-ip'
-import { InvalidParametersError, serviceCapabilities, serviceDependencies, start, stop } from '@libp2p/interface'
+import { serviceCapabilities, serviceDependencies, setMaxListeners, start, stop } from '@libp2p/interface'
 import { debounce } from '@libp2p/utils/debounce'
-import { isLoopback } from '@libp2p/utils/multiaddr/is-loopback'
-import { isPrivate } from '@libp2p/utils/multiaddr/is-private'
-import { isPrivateIp } from '@libp2p/utils/private-ip'
-import { multiaddr } from '@multiformats/multiaddr'
-import { QUICV1, TCP, WebSockets, WebSocketsSecure, WebTransport } from '@multiformats/multiaddr-matcher'
-import { raceSignal } from 'race-signal'
-import { dynamicExternalAddress, staticExternalAddress } from './check-external-address.js'
-import { DoubleNATError, InvalidIPAddressError } from './errors.js'
-import type { ExternalAddress } from './check-external-address.js'
+import { GatewayFinder } from './gateway-finder.js'
+import { UPnPPortMapper } from './upnp-port-mapper.js'
 import type { UPnPNATComponents, UPnPNATInit, UPnPNAT as UPnPNATInterface } from './index.js'
-import type { NatAPI, MapPortOptions } from '@achingbrain/nat-port-mapper'
-import type { Libp2pEvents, Logger, Startable, TypedEventTarget } from '@libp2p/interface'
-import type { AddressManager } from '@libp2p/interface-internal'
+import type { Gateway, UPnPNAT as UPnPNATClient } from '@achingbrain/nat-port-mapper'
+import type { Logger, Startable } from '@libp2p/interface'
 import type { DebouncedFunction } from '@libp2p/utils/debounce'
-import type { Multiaddr } from '@multiformats/multiaddr'
-
-const DEFAULT_TTL = 7200
-
-export type { NatAPI, MapPortOptions }
 
 export class UPnPNAT implements Startable, UPnPNATInterface {
-  public client: NatAPI
-  private readonly addressManager: AddressManager
-  private readonly events: TypedEventTarget<Libp2pEvents>
-  private readonly externalAddress: ExternalAddress
-  private readonly localAddress?: string
-  private readonly description: string
-  private readonly ttl: number
-  private readonly keepAlive: boolean
-  private readonly gateway?: string
-  private started: boolean
   private readonly log: Logger
-  private readonly gatewayDetectionTimeout: number
-  private readonly mappedPorts: Map<number, number>
-  private readonly onSelfPeerUpdate: DebouncedFunction
+  private readonly components: UPnPNATComponents
+  private readonly init: UPnPNATInit
+  private started: boolean
+  public portMappingClient: UPnPNATClient
+  private shutdownController?: AbortController
+  private readonly mapIpAddressesDebounced: DebouncedFunction
+  private readonly gatewayFinder: GatewayFinder
+  private readonly portMappers: UPnPPortMapper[]
   private readonly autoConfirmAddress: boolean
 
   constructor (components: UPnPNATComponents, init: UPnPNATInit) {
     this.log = components.logger.forComponent('libp2p:upnp-nat')
-    this.addressManager = components.addressManager
-    this.events = components.events
+    this.components = components
+    this.init = init
     this.started = false
-    this.localAddress = init.localAddress
-    this.description = init.description ?? `${components.nodeInfo.name}@${components.nodeInfo.version} ${components.peerId.toString()}`
-    this.ttl = init.ttl ?? DEFAULT_TTL
-    this.keepAlive = init.keepAlive ?? true
-    this.gateway = init.gateway
-    this.gatewayDetectionTimeout = init.gatewayDetectionTimeout ?? 10000
+    this.portMappers = []
     this.autoConfirmAddress = init.autoConfirmAddress ?? false
-    this.mappedPorts = new Map()
 
-    if (this.ttl < DEFAULT_TTL) {
-      throw new InvalidParametersError(`NatManager ttl should be at least ${DEFAULT_TTL} seconds`)
-    }
-
-    this.client = init.client ?? upnpNat({
-      description: this.description,
-      ttl: this.ttl,
-      keepAlive: this.keepAlive,
-      gateway: this.gateway
+    this.portMappingClient = init.portMappingClient ?? upnpNat({
+      description: init.portMappingDescription ?? `${components.nodeInfo.name}@${components.nodeInfo.version} ${components.peerId.toString()}`,
+      ttl: init.portMappingTTL,
+      autoRefresh: init.portMappingAutoRefresh,
+      refreshThreshold: init.portMappingRefreshThreshold
     })
 
-    this.onSelfPeerUpdate = debounce(this._onSelfPeerUpdate.bind(this), init.delay ?? 5000)
+    // trigger update when our addresses change
+    this.mapIpAddressesDebounced = debounce(async () => {
+      try {
+        await this.mapIpAddresses()
+      } catch (err: any) {
+        this.log.error('error mapping IP addresses - %e', err)
+      }
+    }, 5_000)
 
-    if (typeof init.externalAddress === 'string') {
-      this.externalAddress = staticExternalAddress(init.externalAddress)
-    } else {
-      this.externalAddress = dynamicExternalAddress({
-        client: this.client,
-        addressManager: this.addressManager,
-        logger: components.logger
-      }, {
-        autoConfirmAddress: init.autoConfirmAddress,
-        interval: init.externalAddressCheckInterval,
-        timeout: init.externalAddressCheckTimeout
-      })
-    }
+    // trigger update when we discovery gateways on the network
+    this.gatewayFinder = new GatewayFinder(components, {
+      portMappingClient: this.portMappingClient
+    })
+
+    this.onGatewayDiscovered = this.onGatewayDiscovered.bind(this)
   }
 
   readonly [Symbol.toStringTag] = '@libp2p/upnp-nat'
@@ -107,158 +78,48 @@ export class UPnPNAT implements Startable, UPnPNATInterface {
     }
 
     this.started = true
-    this.events.addEventListener('self:peer:update', this.onSelfPeerUpdate)
-    await start(this.externalAddress, this.onSelfPeerUpdate)
+    this.shutdownController = new AbortController()
+    setMaxListeners(Infinity, this.shutdownController.signal)
+    this.components.events.addEventListener('self:peer:update', this.mapIpAddressesDebounced)
+    this.gatewayFinder.addEventListener('gateway', this.onGatewayDiscovered)
+    await start(this.mapIpAddressesDebounced, this.gatewayFinder, ...this.portMappers)
   }
 
   /**
    * Stops the NAT manager
    */
   async stop (): Promise<void> {
-    try {
-      await this.client?.close()
-    } catch (err: any) {
-      this.log.error(err)
-    }
-
-    this.events.removeEventListener('self:peer:update', this.onSelfPeerUpdate)
-    await stop(this.externalAddress, this.onSelfPeerUpdate)
+    this.shutdownController?.abort()
+    this.components.events.removeEventListener('self:peer:update', this.mapIpAddressesDebounced)
+    this.gatewayFinder.removeEventListener('gateway', this.onGatewayDiscovered)
+    await stop(this.mapIpAddressesDebounced, this.gatewayFinder, ...this.portMappers)
     this.started = false
   }
 
-  _onSelfPeerUpdate (): void {
-    this.mapIpAddresses()
-      .catch(err => {
-        this.log.error('error mapping IP addresses - %e', err)
-      })
-  }
-
-  private getUnmappedAddresses (multiaddrs: Multiaddr[], ipType: 4 | 6): Multiaddr[] {
-    const output: Multiaddr[] = []
-
-    for (const ma of multiaddrs) {
-      // ignore public addresses
-      if (!isPrivate(ma)) {
-        continue
-      }
-
-      // ignore loopback
-      if (isLoopback(ma)) {
-        continue
-      }
-
-      // only IP based addresses
-      if (!(
-        TCP.exactMatch(ma) ||
-        WebSockets.exactMatch(ma) ||
-        WebSocketsSecure.exactMatch(ma) ||
-        QUICV1.exactMatch(ma) ||
-        WebTransport.exactMatch(ma)
-      )) {
-        continue
-      }
-
-      const { port, family } = ma.toOptions()
-
-      if (family !== ipType) {
-        continue
-      }
-
-      if (this.mappedPorts.has(port)) {
-        continue
-      }
-
-      output.push(ma)
-    }
-
-    return output
-  }
-
-  async mapIpAddresses (): Promise<void> {
-    if (this.externalAddress == null) {
-      this.log('discovering public address')
-    }
-
-    const publicIp = await this.externalAddress.getPublicIp({
-      signal: AbortSignal.timeout(this.gatewayDetectionTimeout)
+  onGatewayDiscovered (event: CustomEvent<Gateway>): void {
+    const mapper = new UPnPPortMapper(this.components, {
+      ...this.init,
+      gateway: event.detail
     })
 
-    this.externalAddress ?? await raceSignal(this.client.externalIp(), AbortSignal.timeout(this.gatewayDetectionTimeout), {
-      errorMessage: `Did not discover a "urn:schemas-upnp-org:device:InternetGatewayDevice:1" device on the local network after ${this.gatewayDetectionTimeout}ms - UPnP may not be configured on your router correctly`
-    })
-
-    let ipType: 4 | 6 = 4
-
-    if (isIPv4(publicIp)) {
-      ipType = 4
-    } else if (isIPv6(publicIp)) {
-      ipType = 6
-    } else {
-      throw new InvalidIPAddressError(`Public address ${publicIp} was not an IPv4 address`)
-    }
-
-    // filter addresses to get private, non-relay, IP based addresses that we
-    // haven't mapped yet
-    const addresses = this.getUnmappedAddresses(this.addressManager.getAddresses(), ipType)
+    this.portMappers.push(mapper)
 
-    if (addresses.length === 0) {
-      this.log('no private, non-relay, unmapped, IP based addresses found')
-      return
-    }
-
-    this.log('%s public IP %s', this.externalAddress != null ? 'using configured' : 'discovered', publicIp)
-
-    this.assertNotBehindDoubleNAT(publicIp)
-
-    for (const addr of addresses) {
-      // try to open uPnP ports for each thin waist address
-      const { family, host, port, transport } = addr.toOptions()
-
-      if (family === 6) {
-        // only support IPv4 addresses
-        continue
-      }
-
-      if (this.mappedPorts.has(port)) {
-        // already mapped this port
-        continue
-      }
-
-      const protocol = transport.toUpperCase()
-
-      this.log(`creating mapping of ${host}:${port}`)
-
-      const mappedPort = await this.client.map(port, {
-        localAddress: host,
-        protocol: protocol === 'TCP' ? 'TCP' : 'UDP'
+    start(mapper)
+      .then(() => {
+        this.mapIpAddressesDebounced()
       })
-
-      this.mappedPorts.set(port, mappedPort)
-
-      const ma = multiaddr(addr.toString().replace(`/ip${family}/${host}/${transport}/${port}`, `/ip${family}/${publicIp}/${transport}/${mappedPort}`))
-
-      this.log(`created mapping of ${publicIp}:${mappedPort} to ${host}:${port} as %a`, ma)
-
-      if (this.autoConfirmAddress) {
-        this.addressManager.confirmObservedAddr(ma)
-      } else {
-        this.addressManager.addObservedAddr(ma)
-      }
-    }
+      .catch(() => {})
   }
 
-  /**
-   * Some ISPs have double-NATs, there's not much we can do with them
-   */
-  private assertNotBehindDoubleNAT (publicIp: string): void {
-    const isPrivate = isPrivateIp(publicIp)
-
-    if (isPrivate === true) {
-      throw new DoubleNATError(`${publicIp} is private - please set config.nat.externalIp to an externally routable IP or ensure you are not behind a double NAT`)
-    }
-
-    if (isPrivate == null) {
-      throw new InvalidParametersError(`${publicIp} is not an IP address`)
+  async mapIpAddresses (): Promise<void> {
+    try {
+      await Promise.all(
+        this.portMappers.map(async mapper => mapper.mapIpAddresses({
+          autoConfirmAddress: this.autoConfirmAddress
+        }))
+      )
+    } catch (err: any) {
+      this.log.error('error mapping IP addresses - %e', err)
     }
   }
 }