librats 0.9.1 → 1.0.0

package/native-src/CMakeLists.txt

@@ -132,6 +132,8 @@ set(LIBRARY_SOURCES
     src/socket.h
     src/network_utils.cpp
     src/network_utils.h
+    src/network_monitor.cpp
+    src/network_monitor.h
     src/dht.cpp
     src/dht.h
     src/bencode.cpp
@@ -212,6 +214,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 +468,10 @@ 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
+# Network change detection tests
+        tests/test_network_monitor.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

@@ -1,6 +1,7 @@
 #include "librats.h"
 #include "os.h"
 #include "network_utils.h"
+#include "network_monitor.h"  // complete type for unique_ptr<NetworkMonitor> member
 #include "version.h"
 #include <algorithm>
 #include <array>
@@ -166,7 +167,15 @@ 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();
+
+    // React to host network changes (IP/interface/route): renew port mappings,
+    // re-discover the public address and re-announce. No-op when disabled.
+    start_network_monitor();
+
     LOG_CLIENT_INFO("RatsClient started successfully on port " << listen_port_);
     
     // Attempt to reconnect to saved peers
@@ -197,7 +206,16 @@ void RatsClient::stop() {
     }
     
     LOG_CLIENT_INFO("Stopping RatsClient");
-    
+
+    // Stop network-change detection FIRST and join its recovery worker: that
+    // worker touches the port-mapping backends and the DHT clients, both torn
+    // down below, so it must not be running past this point.
+    stop_network_monitor();
+
+    // 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();
@@ -1379,22 +1397,34 @@ static constexpr std::array<std::string_view,5> localhost_addrs{"127.0.0.1", "::
 
 // Local interface address blocking methods
 void RatsClient::initialize_local_addresses() {
-    LOG_CLIENT_INFO("Initializing local interface addresses for connection blocking");
-    
     std::lock_guard<std::mutex> lock(local_addresses_mutex_);
-    
-    // Get all local interface addresses using network_utils
+
+    // (Re)enumerate the host's interface addresses. This is also called on every
+    // network change, so it must be a diff, not a blind insert: drop auto-detected
+    // addresses that have disappeared (a removed IP must stop being treated as
+    // "ourselves"), while preserving localhost entries and any externally-
+    // discovered / manually-ignored addresses (STUN reflexive, mapped external IP,
+    // user add_ignored_address()), which live in the same set.
     auto addrs = network_utils::get_local_interface_addresses();
-    local_interface_addresses_.insert(addrs.begin(), addrs.end());
-    
-    // Add common localhost addresses
+    std::unordered_set<std::string> new_auto(addrs.begin(), addrs.end());
+
+    for (const auto& old : auto_interface_addresses_) {
+        if (new_auto.find(old) == new_auto.end()) {
+            local_interface_addresses_.erase(old);
+        }
+    }
+    for (const auto& addr : addrs) {
+        local_interface_addresses_.insert(addr);
+    }
     for (const auto& addr : localhost_addrs) {
         local_interface_addresses_.emplace(std::string(addr));
     }
-    
-    LOG_CLIENT_INFO("Found " << local_interface_addresses_.size() << " local addresses to block:");
+    auto_interface_addresses_ = std::move(new_auto);
+
+    LOG_CLIENT_INFO("Local interface addresses: " << local_interface_addresses_.size()
+                    << " blocked (" << addrs.size() << " from interfaces)");
     for (const auto& addr : local_interface_addresses_) {
-        LOG_CLIENT_INFO("  - " << addr);
+        LOG_CLIENT_DEBUG("  - " << addr);
     }
 }
 

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
@@ -36,6 +38,11 @@
 
 namespace librats {
 
+// Detects host network configuration changes (defined in network_monitor.h).
+// Forward-declared here; only used via unique_ptr, so RatsClient's destructor
+// (defined in librats.cpp, which includes network_monitor.h) sees the full type.
+class NetworkMonitor;
+
 /**
  * PeerIOContext - Per-peer async I/O buffers and framing state
  *
@@ -280,6 +287,10 @@ public:
     using DisconnectCallback = std::function<void(socket_t, const std::string&)>;
     using MessageCallback = std::function<void(const std::string&, const nlohmann::json&)>;
     using SendCallback = std::function<void(bool, const std::string&)>;
+    // Fired when the host's network configuration changes (interface up/down, IP
+    // added/removed, default route change). The argument is the new full list of
+    // local interface addresses. See on_network_changed().
+    using NetworkChangeCallback = std::function<void(const std::vector<std::string>& local_addresses)>;
 
     // =========================================================================
     // Constructor and Destructor
@@ -1432,6 +1443,79 @@ 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);
+
+    // =========================================================================
+    // Network change detection
+    // =========================================================================
+    //
+    // A long-lived node must notice when the host's connectivity changes (a new
+    // interface, an IP added/removed, the default route flipping between Wi-Fi
+    // and cellular, dock/undock, VPN up/down, wake-from-sleep) and recover:
+    // renew router port mappings, re-discover its public address via STUN, and
+    // re-announce to the DHT. Otherwise it keeps advertising a stale endpoint
+    // until the next periodic refresh. Enabled by default. Implemented in
+    // librats_portmap.cpp on top of the platform-specific NetworkMonitor.
+
+    /**
+     * Enable or disable automatic reaction to host network changes. Enabled by
+     * default. Can be called before or after start(): toggling while running
+     * starts/stops the monitor immediately. Not persisted.
+     */
+    void set_network_change_detection_enabled(bool enabled);
+    bool is_network_change_detection_enabled() const;
+
+    /**
+     * Register a callback fired (debounced) whenever the set of local interface
+     * addresses changes. The argument is the new full list of local addresses.
+     * Invoked from the monitor's worker thread, so keep the handler quick. This
+     * is in addition to — not a replacement for — the built-in recovery
+     * (port re-mapping, STUN re-discovery, DHT re-announce).
+     */
+    void on_network_changed(NetworkChangeCallback callback);
+
 #ifdef RATS_STORAGE
     // =========================================================================
     // Distributed Storage API (requires RATS_STORAGE)
@@ -1918,6 +2002,11 @@ private:
     // 6. io_mutex_                  (I/O poller and send buffer access)
     // 7. message_handlers_mutex_    (Message handler registration)
     // 8. reconnect_mutex_           (Reconnection queue management)
+    // 9. port_mapping_mutex_        (UPnP/NAT-PMP backends and mapped address)
+    // 10. network_monitor_mutex_ / network_recovery_mutex_ (network-change state)
+    //
+    // (9) and (10) are leaf locks: they are never held while acquiring any lock
+    // above, so they impose no additional ordering constraints.
     // =========================================================================
     
     // [1] Configuration persistence (protected by config_mutex_)
@@ -1942,7 +2031,12 @@ private:
     // [4] Local interface address blocking (protected by local_addresses_mutex_)
     mutable std::mutex local_addresses_mutex_;              // [4] Protects local interface addresses
     std::unordered_set<std::string> local_interface_addresses_;
-    
+    // Subset of local_interface_addresses_ that came from interface enumeration.
+    // Tracked separately so a network-change refresh can drop only stale auto
+    // entries without evicting localhost or externally-discovered addresses
+    // (STUN reflexive, mapped external IP, user add_ignored_address()).
+    std::unordered_set<std::string> auto_interface_addresses_;
+
     // [5] Organized peer management using RatsPeer struct (protected by peers_mutex_)
     mutable std::mutex peers_mutex_;                        // [5] Protects peer data (most frequently locked)
     std::unordered_map<std::string, RatsPeer> peers_;          // keyed by peer_id
@@ -1981,7 +2075,57 @@ 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;
+
+    // Network change detection (implemented in librats_portmap.cpp). Monitor runs
+    // a platform watcher; on a real address-set change it refreshes the self-
+    // address set inline and wakes the recovery worker, which re-maps ports,
+    // re-discovers the public IP and re-announces. These mutexes are last in the
+    // lock order (after [8]) and are never held while calling into other
+    // subsystems, so they introduce no new ordering constraints.
+    std::unique_ptr<NetworkMonitor> network_monitor_;
+    bool network_change_detection_enabled_ = true;          // start the monitor on start()
+    mutable std::mutex network_monitor_mutex_;              // guards the user callback below
+    NetworkChangeCallback network_change_callback_;
+    // Dedicated recovery worker: serialises the slow recovery work (STUN can
+    // block for seconds) off the monitor thread and coalesces rapid changes.
+    std::thread network_recovery_thread_;
+    std::mutex network_recovery_mutex_;
+    std::condition_variable network_recovery_cv_;
+    bool network_recovery_pending_ = false;
+    bool network_recovery_stop_ = false;
+
+    void start_network_monitor();
+    void stop_network_monitor();
+    void network_recovery_loop();
+    void handle_network_change(const std::vector<std::string>& current_addresses);
+    void recover_after_network_change();
+
 #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();