librats 0.9.1 → 0.9.2

package/native-src/CMakeLists.txt

@@ -212,6 +212,14 @@ set(LIBRARY_SOURCES
     src/ice.cpp
     src/ice.h
     src/librats_ice.cpp
+
+# Automatic port forwarding (UPnP IGD / NAT-PMP)
+    src/port_mapping.h
+    src/upnp.cpp
+    src/upnp.h
+    src/natpmp.cpp
+    src/natpmp.h
+    src/librats_portmap.cpp
 )
 
 # Add BitTorrent sources if RATS_SEARCH_FEATURES is enabled
@@ -458,6 +466,8 @@ if(RATS_BUILD_TESTS)
         tests/test_stun.cpp
         tests/test_turn.cpp
         tests/test_ice.cpp
+# Automatic port forwarding tests (UPnP/NAT-PMP)
+        tests/test_portmap.cpp
 # I/O poller abstraction (epoll/kqueue/IOCP)
         tests/test_io_poller.cpp
 # Buffer utilities for file transfer and bittorrent

package/native-src/src/dht.cpp

@@ -1258,38 +1258,9 @@ bool bep42_prefix(const std::string& ip, uint8_t seed, uint8_t prefix[3]) {
 } // namespace
 
 bool DhtClient::is_public_address(const std::string& ip) {
-    if (ip.empty()) return false;
-
-    if (network_utils::is_valid_ipv6(ip)) {
-        struct in6_addr a;
-        if (inet_pton(AF_INET6, ip.c_str(), &a) != 1) return false;
-        const uint8_t* b = a.s6_addr;
-        bool all_zero = true;
-        for (int i = 0; i < 16; ++i) { if (b[i]) { all_zero = false; break; } }
-        if (all_zero) return false;                              // ::  (unspecified)
-        bool loopback = (b[15] == 1);
-        for (int i = 0; i < 15; ++i) { if (b[i]) { loopback = false; break; } }
-        if (loopback) return false;                              // ::1
-        if ((b[0] & 0xfe) == 0xfc) return false;                 // fc00::/7  unique local
-        if (b[0] == 0xfe && (b[1] & 0xc0) == 0x80) return false; // fe80::/10 link-local
-        if (b[0] == 0xff) return false;                          // ff00::/8  multicast
-        return true;
-    }
-
-    struct in_addr a;
-    if (inet_pton(AF_INET, ip.c_str(), &a) != 1) return false;
-    uint32_t h = ntohl(a.s_addr);
-    uint8_t o1 = static_cast<uint8_t>((h >> 24) & 0xff);
-    uint8_t o2 = static_cast<uint8_t>((h >> 16) & 0xff);
-    if (o1 == 0) return false;                                   // 0.0.0.0/8
-    if (o1 == 127) return false;                                 // loopback
-    if (o1 == 10) return false;                                  // 10.0.0.0/8
-    if (o1 == 172 && o2 >= 16 && o2 <= 31) return false;         // 172.16.0.0/12
-    if (o1 == 192 && o2 == 168) return false;                    // 192.168.0.0/16
-    if (o1 == 169 && o2 == 254) return false;                    // 169.254.0.0/16 link-local
-    if (o1 == 100 && o2 >= 64 && o2 <= 127) return false;        // 100.64.0.0/10 CGNAT
-    if (o1 >= 224) return false;                                 // multicast / reserved
-    return true;
+    // Shared with automatic port forwarding; the canonical classifier lives in
+    // network_utils so both subsystems agree on what "publicly routable" means.
+    return network_utils::is_public_ip(ip);
 }
 
 bool DhtClient::generate_node_id_from_ip(const std::string& ip, NodeId& out, std::mt19937& gen) {

package/native-src/src/dht.h

@@ -298,7 +298,15 @@ public:
      * @return true if running, false otherwise
      */
     bool is_running() const { return running_; }
-    
+
+    /**
+     * Actual bound UDP port. May differ from the requested port if it was taken and
+     * the client fell back to an ephemeral port (see start()). Use this — not the
+     * requested port — when forwarding the DHT port through a router.
+     * @return bound port, or 0 if not started
+     */
+    uint16_t get_port() const { return static_cast<uint16_t>(port_); }
+
 #ifdef RATS_SEARCH_FEATURES
     // ============================================================================
     // SPIDER MODE - Aggressive node discovery and announce collection

package/native-src/src/librats.cpp

@@ -166,7 +166,11 @@ bool RatsClient::start() {
     if (gossipsub_ && !gossipsub_->start()) {
         LOG_CLIENT_WARN("Failed to start GossipSub - continuing without it");
     }
-    
+
+    // Start automatic port forwarding (UPnP/NAT-PMP) for the bound listen port.
+    // No-op when disabled; runs discovery/mapping on its own background threads.
+    start_port_mapping();
+
     LOG_CLIENT_INFO("RatsClient started successfully on port " << listen_port_);
     
     // Attempt to reconnect to saved peers
@@ -197,7 +201,11 @@ void RatsClient::stop() {
     }
     
     LOG_CLIENT_INFO("Stopping RatsClient");
-    
+
+    // Remove port mappings and stop UPnP/NAT-PMP backends before tearing down
+    // sockets (best-effort cleanup so we don't leave stale router mappings).
+    stop_port_mapping();
+
     // Stop GossipSub (can broadcast stop message)
     if (gossipsub_) {
         gossipsub_->stop();

package/native-src/src/librats.h

@@ -9,6 +9,8 @@
 #include "file_transfer.h" // File transfer functionality
 #include "noise.h" // Noise Protocol encryption
 #include "ice.h"   // ICE-lite NAT traversal
+#include "upnp.h"  // UPnP IGD automatic port forwarding
+#include "natpmp.h" // NAT-PMP automatic port forwarding
 #include "io_poller.h" // Platform-optimal I/O multiplexing
 #include "receive_buffer.h" // Efficient receive buffer for async I/O
 #include "chained_send_buffer.h" // Zero-copy chained send buffer
@@ -1432,6 +1434,50 @@ public:
      */
     void restart_ice();
 
+    // =========================================================================
+    // Automatic Port Forwarding API (UPnP IGD + NAT-PMP)
+    // =========================================================================
+    //
+    // When enabled (the default), RatsClient asks the home router to forward the
+    // TCP listen port on startup, using UPnP and NAT-PMP in parallel (whichever
+    // the router supports wins). Mappings are refreshed automatically and removed
+    // on stop(). This lets peers behind a NAT accept inbound connections without
+    // manual router configuration.
+
+    /**
+     * Enable or disable automatic port forwarding. If toggled while running, the
+     * port mapping backends are started or stopped immediately. The setting is
+     * persisted to config.json.
+     */
+    void set_port_mapping_enabled(bool enabled);
+
+    /// Whether automatic port forwarding is currently enabled.
+    bool is_port_mapping_enabled() const;
+
+    /// Replace the full port mapping configuration (takes effect on next start).
+    void set_port_mapping_config(const PortMappingConfig& config);
+
+    /// Get the current port mapping configuration.
+    PortMappingConfig get_port_mapping_config() const;
+
+    /**
+     * Request an additional port mapping beyond the automatic listen-port mapping
+     * (e.g. a DHT UDP port). Has effect only while port mapping is enabled.
+     */
+    void add_port_mapping(PortMapProtocol protocol, uint16_t port);
+
+    /**
+     * Get the public (external) address discovered by the port mapping backends.
+     * @return {external_ip, external_port} if a mapping is active, otherwise nullopt
+     */
+    std::optional<std::pair<std::string, uint16_t>> get_mapped_public_address() const;
+
+    /**
+     * Register a callback fired whenever a port mapping is established, refreshed,
+     * removed or fails (invoked from a backend worker thread).
+     */
+    void on_port_mapping(PortMapCallback callback);
+
 #ifdef RATS_STORAGE
     // =========================================================================
     // Distributed Storage API (requires RATS_STORAGE)
@@ -1981,7 +2027,33 @@ private:
     
     // ICE manager for NAT traversal
     std::unique_ptr<IceManager> ice_manager_;
-    
+
+    // Automatic port forwarding (UPnP IGD + NAT-PMP). Implemented in librats_portmap.cpp.
+    mutable std::mutex port_mapping_mutex_;        // guards the fields below
+    PortMappingConfig port_mapping_config_;
+    std::unique_ptr<UpnpClient> upnp_client_;
+    std::unique_ptr<NatPmpClient> natpmp_client_;
+    PortMapCallback port_mapping_callback_;
+    // Public address discovered by the backends. The external port is tracked per
+    // protocol (like libtorrent's per-listen-socket tcp/udp port mappings): the TCP
+    // mapping forwards the peer listen port, the UDP mapping forwards the DHT port.
+    // A single field would let the two backend callbacks clobber each other.
+    std::string mapped_external_ip_;
+    uint16_t mapped_external_tcp_port_ = 0;  // public port for the TCP peer-listen port
+    uint16_t mapped_external_udp_port_ = 0;  // public port for the UDP DHT port
+    // Set once we warn that the gateway's reported external IP is itself private
+    // (double-NAT), so the warning isn't repeated on every lease refresh.
+    bool double_nat_warning_logged_ = false;
+
+    // Start/stop the port mapping backends (no-ops if disabled). Called from
+    // start()/stop(); safe to call repeatedly.
+    void start_port_mapping();
+    void stop_port_mapping();
+    void handle_port_mapping_result(const PortMapResult& result);
+    // Public TCP port to advertise to peers/DHT: the mapped external port once a
+    // TCP mapping is established, otherwise the local listen port.
+    uint16_t get_advertised_port() const;
+
 #ifdef RATS_STORAGE
     // Distributed storage manager (optional, requires RATS_STORAGE)
     std::unique_ptr<StorageManager> storage_manager_;

package/native-src/src/librats_discovery.cpp

@@ -43,6 +43,19 @@ bool RatsClient::start_dht_discovery(int dht_port) {
         dht_client_v6_.reset();
     }
 
+    // Forward the DHT's UDP port through the router, in addition to the TCP peer
+    // port mapped at start(). Like libtorrent (which maps both the TCP listen port
+    // and the UDP DHT/uTP port per listen socket), this makes the node reachable by
+    // inbound DHT traffic behind NAT. No-op when port mapping is disabled; the
+    // mapping uses external==internal so outgoing queries and inbound packets share
+    // one public port. The backends wake their workers to install it immediately.
+    // Use the *actual* bound port: start() may have fallen back to an ephemeral one
+    // when the requested dht_port was taken.
+    uint16_t bound_dht_port = dht_client_->get_port();
+    if (bound_dht_port != 0) {
+        add_port_mapping(PortMapProtocol::UDP, bound_dht_port);
+    }
+
     // Start automatic peer discovery (this thread also performs the best-effort STUN probe
     // that derives our BEP 42 node ID — see automatic_discovery_loop).
     start_automatic_peer_discovery();
@@ -321,8 +334,14 @@ void RatsClient::announce_rats_peer() {
     }
     
     std::string discovery_hash = get_discovery_hash();
-    LOG_CLIENT_INFO("Announcing peer for discovery hash: " << discovery_hash << " on port " << listen_port_);
-    
+
+    // Advertise the mapped public TCP port when UPnP/NAT-PMP has established one,
+    // so WAN peers connect to (external_ip, external_port) rather than our NATed
+    // local listen port. Falls back to listen_port_ when no mapping is active.
+    // (Mirrors libtorrent feeding the port-mapping result into what it announces.)
+    uint16_t announce_port = get_advertised_port();
+    LOG_CLIENT_INFO("Announcing peer for discovery hash: " << discovery_hash << " on port " << announce_port);
+
     InfoHash info_hash = hex_to_node_id(discovery_hash);
 
     // Skip only if every running DHT network already has this announce in flight.
@@ -336,7 +355,7 @@ void RatsClient::announce_rats_peer() {
     
     // Use announce with callback - combines announce and find_peers in one traversal
     // Peers discovered during traversal will be returned through the callback
-    if (announce_for_hash(discovery_hash, listen_port_, [this, info_hash](const std::vector<std::string>& peer_addresses) {
+    if (announce_for_hash(discovery_hash, announce_port, [this, info_hash](const std::vector<std::string>& peer_addresses) {
         LOG_CLIENT_INFO("Announce discovered " << peer_addresses.size() << " peers during traversal");
         
         // Convert peer addresses to Peer objects for handle_dht_peer_discovery()

package/native-src/src/librats_persistence.cpp

@@ -79,8 +79,14 @@ bool RatsClient::load_configuration() {
         if (config.contains("encryption_enabled")) {
             encryption_enabled_ = config.value("encryption_enabled", true);
         }
-        
-        
+
+        // Load automatic port forwarding preference
+        if (config.contains("port_mapping_enabled")) {
+            std::lock_guard<std::mutex> pm_lock(port_mapping_mutex_);
+            port_mapping_config_.enabled = config.value("port_mapping_enabled", true);
+        }
+
+
         // Update last_updated timestamp
         auto now = std::chrono::high_resolution_clock::now();
         auto timestamp = std::chrono::duration_cast<std::chrono::seconds>(now.time_since_epoch()).count();
@@ -119,6 +125,10 @@ bool RatsClient::save_configuration() {
         config["listen_port"] = listen_port_;
         config["max_peers"] = max_peers_;
         config["encryption_enabled"] = encryption_enabled_;
+        {
+            std::lock_guard<std::mutex> pm_lock(port_mapping_mutex_);
+            config["port_mapping_enabled"] = port_mapping_config_.enabled;
+        }
         // TODO: Re-add when implementing new Noise protocol
         // config["encryption_key"] = get_encryption_key();
         

package/native-src/src/librats_portmap.cpp

@@ -0,0 +1,244 @@
+/**
+ * @file librats_portmap.cpp
+ * @brief Automatic port forwarding (UPnP IGD + NAT-PMP) integration for RatsClient
+ *
+ * Wires the standalone @ref UpnpClient and @ref NatPmpClient backends into the
+ * RatsClient lifecycle. Both run in parallel; whichever the router supports maps
+ * the TCP listen port so peers behind NAT can accept inbound connections. The
+ * backends are started from RatsClient::start() and torn down in stop().
+ */
+
+#include "librats.h"
+#include "network_utils.h"
+#include "logger.h"
+
+namespace librats {
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+void RatsClient::set_port_mapping_enabled(bool enabled) {
+    bool was_enabled;
+    {
+        std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+        was_enabled = port_mapping_config_.enabled;
+        port_mapping_config_.enabled = enabled;
+    }
+
+    if (was_enabled != enabled) {
+        LOG_INFO("portmap", "Automatic port forwarding " << (enabled ? "enabled" : "disabled"));
+        if (running_.load()) {
+            if (enabled) {
+                start_port_mapping();
+            } else {
+                stop_port_mapping();
+            }
+        }
+        // Persist the new preference
+        save_configuration();
+    }
+}
+
+bool RatsClient::is_port_mapping_enabled() const {
+    std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+    return port_mapping_config_.enabled;
+}
+
+void RatsClient::set_port_mapping_config(const PortMappingConfig& config) {
+    {
+        std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+        port_mapping_config_ = config;
+    }
+    LOG_DEBUG("portmap", "Port mapping config updated (upnp=" << config.enable_upnp
+              << " natpmp=" << config.enable_natpmp << " lease=" << config.lease_duration_seconds << ")");
+}
+
+PortMappingConfig RatsClient::get_port_mapping_config() const {
+    std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+    return port_mapping_config_;
+}
+
+void RatsClient::on_port_mapping(PortMapCallback callback) {
+    std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+    port_mapping_callback_ = std::move(callback);
+}
+
+std::optional<std::pair<std::string, uint16_t>> RatsClient::get_mapped_public_address() const {
+    std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+    // The "public address" peers should reach us on is the TCP peer-listen mapping.
+    if (mapped_external_tcp_port_ == 0 || mapped_external_ip_.empty()) {
+        return std::nullopt;
+    }
+    return std::make_pair(mapped_external_ip_, mapped_external_tcp_port_);
+}
+
+uint16_t RatsClient::get_advertised_port() const {
+    std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+    return mapped_external_tcp_port_ != 0
+         ? mapped_external_tcp_port_
+         : static_cast<uint16_t>(listen_port_);
+}
+
+void RatsClient::add_port_mapping(PortMapProtocol protocol, uint16_t port) {
+    std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+    if (upnp_client_)   upnp_client_->add_mapping(protocol, port);
+    if (natpmp_client_) natpmp_client_->add_mapping(protocol, port);
+}
+
+// ============================================================================
+// Result handling
+// ============================================================================
+
+void RatsClient::handle_port_mapping_result(const PortMapResult& result) {
+    // A gateway whose reported "external" IP is itself private means we're behind a
+    // second NAT (double-NAT): the mapping forwards a port on the inner router, but
+    // that doesn't make us reachable from the internet, and the inner port won't
+    // match whatever the outer NAT assigns. So such a mapping must NOT be treated as
+    // a public endpoint — we leave mapped_external_* untouched and let the advertised
+    // address fall back to listen_port_ / the STUN-discovered reflexive address.
+    // An empty external IP (gateway didn't report one) is "unknown", not private, so
+    // we keep the previous best-effort behavior for it.
+    const bool ip_is_private = !result.external_ip.empty() && !network_utils::is_public_ip(result.external_ip);
+
+    PortMapCallback user_cb;
+    bool tcp_port_changed = false;
+    bool warn_double_nat = false;
+    {
+        std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+        if (result.success && !ip_is_private) {
+            if (!result.external_ip.empty()) {
+                mapped_external_ip_ = result.external_ip;
+            }
+            // Track the external port per protocol so the TCP (peer) and UDP (DHT)
+            // mappings don't overwrite each other.
+            if (result.protocol == PortMapProtocol::TCP) {
+                tcp_port_changed = (mapped_external_tcp_port_ != result.external_port);
+                mapped_external_tcp_port_ = result.external_port;
+            } else {
+                mapped_external_udp_port_ = result.external_port;
+            }
+        } else if (result.success && ip_is_private && !double_nat_warning_logged_) {
+            double_nat_warning_logged_ = true;
+            warn_double_nat = true;
+        }
+        user_cb = port_mapping_callback_;
+    }
+
+    if (result.success && ip_is_private) {
+        LOG_INFO("portmap", to_string(result.transport) << " mapped " << to_string(result.protocol)
+                 << " port " << result.internal_port << " -> external " << result.external_ip << ":"
+                 << result.external_port << " (gateway external IP is private — not a usable public address)");
+        if (warn_double_nat) {
+            LOG_WARN("portmap", "Gateway reports a private external IP (" << result.external_ip
+                     << ") — likely double-NAT. Port forwarding alone won't make this host publicly "
+                        "reachable; relying on STUN for the public address.");
+        }
+    } else if (result.success) {
+        LOG_INFO("portmap", to_string(result.transport) << " mapped " << to_string(result.protocol)
+                 << " port " << result.internal_port << " -> external "
+                 << (result.external_ip.empty() ? "?" : result.external_ip) << ":" << result.external_port);
+        // Avoid trying to connect to ourselves through the public address. Only a
+        // genuinely public IP belongs on the ignore list — a private one could be a
+        // real LAN peer we still want to reach.
+        if (!result.external_ip.empty()) {
+            add_ignored_address(result.external_ip);
+        }
+        // A new/changed public TCP port means the address peers should reach us on
+        // changed: re-announce to the DHT so it advertises the mapped port instead
+        // of the (NATed) local listen port. Done outside the lock below.
+    } else {
+        LOG_DEBUG("portmap", to_string(result.transport) << " mapping failed: " << result.error);
+    }
+
+    // Invoke the user callback outside the lock to avoid re-entrancy deadlocks.
+    if (user_cb) {
+        user_cb(result);
+    }
+
+    // Re-announce with the freshly mapped public port (outside any lock).
+    if (tcp_port_changed && is_dht_running()) {
+        announce_rats_peer();
+    }
+}
+
+// ============================================================================
+// Lifecycle
+// ============================================================================
+
+void RatsClient::start_port_mapping() {
+    PortMappingConfig config;
+    int port;
+    {
+        std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+        config = port_mapping_config_;
+        // Already started?
+        if (upnp_client_ || natpmp_client_) {
+            return;
+        }
+        port = listen_port_;
+    }
+
+    if (!config.enabled) {
+        return;
+    }
+    if (port <= 0) {
+        LOG_WARN("portmap", "Skipping port mapping: invalid listen port");
+        return;
+    }
+
+    LOG_INFO("portmap", "Starting automatic port forwarding for TCP port " << port
+             << " (upnp=" << config.enable_upnp << " natpmp=" << config.enable_natpmp << ")");
+
+    auto callback = [this](const PortMapResult& r) { handle_port_mapping_result(r); };
+
+    std::unique_ptr<UpnpClient> upnp;
+    std::unique_ptr<NatPmpClient> natpmp;
+
+    if (config.enable_upnp) {
+        upnp = std::make_unique<UpnpClient>();
+        upnp->set_lease_duration(config.lease_duration_seconds);
+        upnp->set_callback(callback);
+        upnp->add_mapping(PortMapProtocol::TCP, static_cast<uint16_t>(port), 0, "rats");
+    }
+    if (config.enable_natpmp) {
+        natpmp = std::make_unique<NatPmpClient>();
+        natpmp->set_lease_duration(config.lease_duration_seconds);
+        natpmp->set_callback(callback);
+        natpmp->add_mapping(PortMapProtocol::TCP, static_cast<uint16_t>(port));
+    }
+
+    // Publish the clients before starting their workers so add_port_mapping() can
+    // reach them, then kick off discovery.
+    {
+        std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+        upnp_client_ = std::move(upnp);
+        natpmp_client_ = std::move(natpmp);
+    }
+    {
+        std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+        if (upnp_client_)   upnp_client_->start();
+        if (natpmp_client_) natpmp_client_->start();
+    }
+}
+
+void RatsClient::stop_port_mapping() {
+    // Move the clients out under the lock, then stop() them outside it: stop()
+    // joins worker threads which may call handle_port_mapping_result() (and thus
+    // re-acquire port_mapping_mutex_), so holding it here would deadlock.
+    std::unique_ptr<UpnpClient> upnp;
+    std::unique_ptr<NatPmpClient> natpmp;
+    {
+        std::lock_guard<std::mutex> lock(port_mapping_mutex_);
+        upnp = std::move(upnp_client_);
+        natpmp = std::move(natpmp_client_);
+    }
+
+    if (upnp || natpmp) {
+        LOG_INFO("portmap", "Removing port mappings and stopping backends");
+    }
+    if (upnp)   upnp->stop();
+    if (natpmp) natpmp->stop();
+}
+
+} // namespace librats