librats 0.9.2 → 1.0.1

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
@@ -468,6 +470,8 @@ if(RATS_BUILD_TESTS)
         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

@@ -2894,7 +2894,30 @@ bool DhtClient::load_routing_table() {
             LOG_DHT_WARN("Unsupported routing table version: " << version);
             return false;
         }
-        
+
+        // Restore our own node ID so it stays stable across restarts (matches libtorrent's
+        // calculate_node_id). The external address is not known yet at load time, which is
+        // libtorrent's "external_address.is_unspecified()" case -> reuse the saved ID as long
+        // as it is valid (non-zero). If the external IP is later discovered and the restored
+        // ID is no longer valid for it (BEP 42), set_external_ip() regenerates it then.
+        // Restored before bucketing the loaded nodes below, since get_bucket_index() is
+        // computed relative to node_id_.
+        if (routing_data.contains("node_id")) {
+            try {
+                NodeId saved_id = hex_to_node_id(routing_data["node_id"].get<std::string>());
+                bool all_zeros = std::all_of(saved_id.begin(), saved_id.end(),
+                                             [](uint8_t b) { return b == 0; });
+                if (!all_zeros) {
+                    node_id_ = saved_id;
+                    LOG_DHT_INFO("Restored DHT node ID from disk: " << node_id_to_hex(node_id_));
+                } else {
+                    LOG_DHT_WARN("Saved node ID is invalid (zero/malformed), keeping generated one");
+                }
+            } catch (const std::exception& e) {
+                LOG_DHT_WARN("Failed to restore saved node ID, keeping generated one: " << e.what());
+            }
+        }
+
         // Load nodes
         const auto& nodes_array = routing_data["nodes"];
         size_t loaded_count = 0;

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>
@@ -171,6 +172,10 @@ bool RatsClient::start() {
     // 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
@@ -202,6 +207,11 @@ 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();
@@ -1387,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

@@ -38,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
  *
@@ -282,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
@@ -1478,6 +1487,35 @@ public:
      */
     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)
@@ -1964,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_)
@@ -1988,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
@@ -2054,6 +2102,30 @@ private:
     // 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

@@ -265,22 +265,19 @@ std::chrono::seconds RatsClient::calculate_discovery_interval() const {
 
 void RatsClient::automatic_discovery_loop() {
     LOG_CLIENT_INFO("Automatic peer discovery loop started");
-    
-    // Initial delay to let DHT bootstrap
-    {
-        std::unique_lock<std::mutex> lock(shutdown_mutex_);
-        if (shutdown_cv_.wait_for(lock, std::chrono::seconds(INITIAL_DISCOVERY_DELAY_SECONDS), [this] { return !auto_discovery_running_.load() || !running_.load(); })) {
-            LOG_CLIENT_INFO("Automatic peer discovery loop stopped during initial delay");
-            return;
-        }
-    }
 
-    // Best-effort: discover our public IP via STUN and derive a BEP 42 node ID from it before
-    // we announce, so we announce under the correct ID. This runs on the discovery thread (not
-    // a standalone one) on purpose: stop_dht_discovery() joins this thread via
-    // stop_automatic_peer_discovery() BEFORE resetting the DHT clients, so set_external_ip()
-    // can never touch a destroyed DhtClient. It complements the in-DHT "ip"-field voting, which
-    // keeps the node ID correct if the address changes or STUN is unavailable.
+    // Best-effort: discover our public IP via STUN and derive a BEP 42 node ID from it BEFORE
+    // the initial bootstrap delay below. The DHT starts receiving KRPC responses (each carrying
+    // our address in the "ip" field) immediately on bootstrap, and that in-DHT vote can reach
+    // EXTERNAL_IP_VOTE_THRESHOLD within a few seconds. Probing STUN first lets set_external_ip()
+    // adopt the address and regenerate the node ID up front, so the DHT bootstraps under the
+    // correct ID and the ip-field voting silently confirms the already-adopted address instead
+    // of racing it to consensus. The voting remains the fallback when STUN is unavailable or the
+    // address later changes.
+    //
+    // This runs on the discovery thread (not a standalone one) on purpose: stop_dht_discovery()
+    // joins this thread via stop_automatic_peer_discovery() BEFORE resetting the DHT clients, so
+    // set_external_ip() can never touch a destroyed DhtClient.
     if (auto_discovery_running_.load() && running_.load()) {
         auto mapped = discover_public_address("stun.l.google.com", 19302, 4000);
         if (mapped) {
@@ -296,6 +293,15 @@ void RatsClient::automatic_discovery_loop() {
         }
     }
 
+    // Initial delay to let DHT bootstrap
+    {
+        std::unique_lock<std::mutex> lock(shutdown_mutex_);
+        if (shutdown_cv_.wait_for(lock, std::chrono::seconds(INITIAL_DISCOVERY_DELAY_SECONDS), [this] { return !auto_discovery_running_.load() || !running_.load(); })) {
+            LOG_CLIENT_INFO("Automatic peer discovery loop stopped during initial delay");
+            return;
+        }
+    }
+
     // Announce immediately - this also discovers peers during traversal
     announce_rats_peer();
 

package/native-src/src/librats_portmap.cpp

@@ -9,7 +9,9 @@
  */
 
 #include "librats.h"
+#include "librats_log_macros.h"
 #include "network_utils.h"
+#include "network_monitor.h"
 #include "logger.h"
 
 namespace librats {
@@ -241,4 +243,177 @@ void RatsClient::stop_port_mapping() {
     if (natpmp) natpmp->stop();
 }
 
+// ============================================================================
+// Network change detection
+// ============================================================================
+
+void RatsClient::set_network_change_detection_enabled(bool enabled) {
+    bool was_enabled;
+    {
+        std::lock_guard<std::mutex> lock(network_monitor_mutex_);
+        was_enabled = network_change_detection_enabled_;
+        network_change_detection_enabled_ = enabled;
+    }
+    if (was_enabled == enabled) {
+        return;
+    }
+    LOG_INFO("netmon", "Network change detection " << (enabled ? "enabled" : "disabled"));
+    if (running_.load()) {
+        if (enabled) {
+            start_network_monitor();
+        } else {
+            stop_network_monitor();
+        }
+    }
+}
+
+bool RatsClient::is_network_change_detection_enabled() const {
+    std::lock_guard<std::mutex> lock(network_monitor_mutex_);
+    return network_change_detection_enabled_;
+}
+
+void RatsClient::on_network_changed(NetworkChangeCallback callback) {
+    std::lock_guard<std::mutex> lock(network_monitor_mutex_);
+    network_change_callback_ = std::move(callback);
+}
+
+void RatsClient::start_network_monitor() {
+    {
+        std::lock_guard<std::mutex> lock(network_monitor_mutex_);
+        if (!network_change_detection_enabled_ || network_monitor_) {
+            return;  // disabled or already running
+        }
+    }
+
+    // Spin up the recovery worker before the monitor so it can never miss the
+    // first wake-up.
+    {
+        std::lock_guard<std::mutex> lock(network_recovery_mutex_);
+        network_recovery_stop_ = false;
+        network_recovery_pending_ = false;
+    }
+    network_recovery_thread_ = std::thread([this]() { network_recovery_loop(); });
+
+    auto monitor = std::make_unique<NetworkMonitor>();
+    monitor->start([this](const std::vector<std::string>& addrs) {
+        handle_network_change(addrs);
+    });
+    {
+        std::lock_guard<std::mutex> lock(network_monitor_mutex_);
+        network_monitor_ = std::move(monitor);
+    }
+    LOG_INFO("netmon", "Network change detection active");
+}
+
+void RatsClient::stop_network_monitor() {
+    // Stop the OS watcher first so no further change events are queued.
+    std::unique_ptr<NetworkMonitor> monitor;
+    {
+        std::lock_guard<std::mutex> lock(network_monitor_mutex_);
+        monitor = std::move(network_monitor_);
+    }
+    if (monitor) {
+        monitor->stop();   // joins the monitor's worker thread
+    }
+
+    // Then wake and join the recovery worker. Done after the monitor is down so
+    // no new recovery can be scheduled while we shut it down.
+    {
+        std::lock_guard<std::mutex> lock(network_recovery_mutex_);
+        network_recovery_stop_ = true;
+    }
+    network_recovery_cv_.notify_all();
+    if (network_recovery_thread_.joinable()) {
+        network_recovery_thread_.join();
+    }
+}
+
+void RatsClient::network_recovery_loop() {
+    while (true) {
+        {
+            std::unique_lock<std::mutex> lock(network_recovery_mutex_);
+            network_recovery_cv_.wait(lock, [this]() {
+                return network_recovery_pending_ || network_recovery_stop_;
+            });
+            if (network_recovery_stop_) {
+                break;
+            }
+            network_recovery_pending_ = false;
+        }
+        recover_after_network_change();
+    }
+}
+
+void RatsClient::handle_network_change(const std::vector<std::string>& current_addresses) {
+    if (!running_.load()) {
+        return;
+    }
+    LOG_CLIENT_INFO("Network change detected (" << current_addresses.size()
+                    << " local address(es)); refreshing network state");
+
+    // Cheap and synchronous: refresh the self-address set so a freshly added
+    // local address isn't misjudged as a remote peer, and a removed one stops
+    // being blocked. (Diff-based; preserves STUN/mapped/ignored entries.)
+    initialize_local_addresses();
+
+    // Notify the application.
+    NetworkChangeCallback cb;
+    {
+        std::lock_guard<std::mutex> lock(network_monitor_mutex_);
+        cb = network_change_callback_;
+    }
+    if (cb) {
+        cb(current_addresses);
+    }
+
+    // Hand the slow recovery (port re-mapping + STUN + re-announce) to the
+    // dedicated worker so we don't block the monitor thread. Coalesced: if a
+    // recovery is already running, this just marks another pass is needed.
+    {
+        std::lock_guard<std::mutex> lock(network_recovery_mutex_);
+        network_recovery_pending_ = true;
+    }
+    network_recovery_cv_.notify_all();
+}
+
+void RatsClient::recover_after_network_change() {
+    if (!running_.load()) {
+        return;
+    }
+    LOG_CLIENT_INFO("Recovering after network change: renewing port mappings and re-announcing");
+
+    // 1. Renew router port mappings. Our LAN IP and/or the gateway likely
+    //    changed, so existing UPnP/NAT-PMP leases are stale or aimed at the wrong
+    //    internal address. Tear down and re-run discovery from scratch.
+    if (is_port_mapping_enabled()) {
+        stop_port_mapping();
+        if (running_.load()) {
+            start_port_mapping();
+        }
+    }
+
+    if (!running_.load()) {
+        return;
+    }
+
+    // 2. Re-discover our public address via STUN, update the BEP 42 node IDs and
+    //    re-announce so the DHT advertises our current reachable endpoint rather
+    //    than the one from the previous network. This runs on the recovery
+    //    thread, which stop() joins before the DHT clients are destroyed, so the
+    //    set_external_ip()/announce calls can never touch a freed DhtClient.
+    if (is_dht_running()) {
+        auto mapped = discover_public_address("stun.l.google.com", 19302, 4000);
+        if (mapped) {
+            if (dht_client_)    dht_client_->set_external_ip(mapped->address);
+            if (dht_client_v6_) dht_client_v6_->set_external_ip(mapped->address);
+            LOG_CLIENT_INFO("Public address after network change: " << mapped->address);
+        } else {
+            LOG_CLIENT_DEBUG("STUN public address discovery failed after network change");
+        }
+        if (running_.load()) {
+            announce_rats_peer();
+        }
+    }
+}
+
 } // namespace librats

package/native-src/src/network_monitor.cpp

@@ -0,0 +1,367 @@
+/**
+ * @file network_monitor.cpp
+ * @brief Platform backends for NetworkMonitor (see network_monitor.h).
+ */
+
+// socket.h pulls in winsock2.h/ws2tcpip.h first on Windows (must precede the
+// iphlpapi / windows headers below to avoid the classic winsock2/windows.h clash).
+#include "socket.h"
+#include "network_monitor.h"
+#include "network_utils.h"
+#include "logger.h"
+
+#include <algorithm>
+
+#ifdef _WIN32
+    #include <iphlpapi.h>
+    #include <netioapi.h>
+#elif defined(__linux__)
+    #include <sys/socket.h>
+    #include <linux/netlink.h>
+    #include <linux/rtnetlink.h>
+    #include <unistd.h>
+    #include <poll.h>
+    #include <cstring>
+    #include <cerrno>
+#elif defined(__APPLE__) || defined(__FreeBSD__) || defined(__NetBSD__) || \
+      defined(__OpenBSD__) || defined(__DragonFly__)
+    #define RATS_MONITOR_BSD_ROUTES 1
+    #include <sys/types.h>
+    #include <sys/socket.h>
+    #include <net/route.h>
+    #include <net/if.h>
+    #include <unistd.h>
+    #include <poll.h>
+    #include <cerrno>
+#endif
+
+#define LOG_NETMON_DEBUG(message) LOG_DEBUG("netmon", message)
+#define LOG_NETMON_INFO(message)  LOG_INFO("netmon", message)
+#define LOG_NETMON_WARN(message)  LOG_WARN("netmon", message)
+#define LOG_NETMON_ERROR(message) LOG_ERROR("netmon", message)
+
+namespace librats {
+
+namespace {
+
+std::vector<std::string> snapshot_addresses() {
+    auto addrs = network_utils::get_local_interface_addresses();
+    std::sort(addrs.begin(), addrs.end());
+    addrs.erase(std::unique(addrs.begin(), addrs.end()), addrs.end());
+    return addrs;
+}
+
+} // namespace
+
+// ============================================================================
+// Platform backend state
+// ============================================================================
+
+struct NetworkMonitor::Impl {
+#ifdef _WIN32
+    HANDLE handle = nullptr;
+#elif defined(__linux__) || defined(RATS_MONITOR_BSD_ROUTES)
+    int fd = -1;            // netlink (Linux) or PF_ROUTE (BSD) socket
+    int stop_pipe[2] = {-1, -1};
+    std::thread reader;
+#endif
+};
+
+#ifdef _WIN32
+// NotifyUnicastIpAddressChange invokes this from an OS worker thread on any
+// unicast address add/remove/change. Windows gives no usable detail here, so we
+// just trigger a re-enumeration (matches the cross-platform "something changed"
+// contract). Must be __stdcall (WINAPI) to match PUNICAST_IPADDRESS_CHANGE_CALLBACK.
+static void WINAPI rats_ip_change_cb(void* ctx, MIB_UNICASTIPADDRESS_ROW* /*row*/,
+                                     MIB_NOTIFICATION_TYPE /*type*/) {
+    auto* self = static_cast<NetworkMonitor*>(ctx);
+    if (self) self->check_now();
+}
+#endif
+
+// ============================================================================
+// Lifecycle
+// ============================================================================
+
+NetworkMonitor::NetworkMonitor() = default;
+
+NetworkMonitor::~NetworkMonitor() {
+    stop();
+}
+
+bool NetworkMonitor::start(ChangeCallback on_change) {
+    if (running_.exchange(true)) {
+        return event_backend_active_;
+    }
+    on_change_ = std::move(on_change);
+    impl_ = std::make_unique<Impl>();
+    last_addresses_ = snapshot_addresses();
+
+    event_backend_active_ = backend_start();
+    LOG_NETMON_INFO("Network monitor started ("
+                    << (event_backend_active_ ? "event-driven" : "polling")
+                    << ", " << last_addresses_.size() << " local address(es))");
+
+    worker_ = std::thread([this]() { worker_loop(); });
+    return event_backend_active_;
+}
+
+void NetworkMonitor::stop() {
+    if (!running_.exchange(false)) {
+        return;
+    }
+    cv_.notify_all();   // wake the worker out of its wait
+    backend_stop();     // stop OS notifications / join the reader thread
+    if (worker_.joinable()) {
+        worker_.join();
+    }
+    impl_.reset();
+    event_backend_active_ = false;
+    LOG_NETMON_INFO("Network monitor stopped");
+}
+
+void NetworkMonitor::check_now() {
+    if (!running_.load()) return;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        change_pending_ = true;
+    }
+    cv_.notify_all();
+}
+
+// ============================================================================
+// Worker: debounce + diff + dispatch
+// ============================================================================
+
+void NetworkMonitor::worker_loop() {
+    // When push notifications are active, the long interval is just a safety net
+    // for events the OS might drop (e.g. across suspend/resume). Without them,
+    // this interval is the actual detection latency.
+    const auto poll_interval = event_backend_active_
+        ? std::chrono::milliseconds(30000)
+        : std::chrono::milliseconds(5000);
+
+    while (running_.load()) {
+        bool was_event = false;
+        {
+            std::unique_lock<std::mutex> lock(mutex_);
+            cv_.wait_for(lock, poll_interval,
+                         [this]() { return !running_.load() || change_pending_; });
+            if (!running_.load()) break;
+
+            was_event = change_pending_;
+            change_pending_ = false;
+
+            if (was_event) {
+                // Coalesce the burst: wait out a quiet debounce window (only a
+                // stop interrupts it), then drop any events that arrived during it.
+                cv_.wait_for(lock, debounce_, [this]() { return !running_.load(); });
+                if (!running_.load()) break;
+                change_pending_ = false;
+            }
+        }
+
+        auto current = snapshot_addresses();
+        if (current != last_addresses_) {
+            LOG_NETMON_INFO("Local address set changed (" << last_addresses_.size()
+                            << " -> " << current.size() << ")");
+            last_addresses_ = current;
+            if (on_change_) {
+                on_change_(current);
+            }
+        } else if (was_event) {
+            LOG_NETMON_DEBUG("Network event with no effective address change; ignored");
+        }
+    }
+}
+
+// ============================================================================
+// Windows backend: NotifyUnicastIpAddressChange
+// ============================================================================
+#ifdef _WIN32
+
+bool NetworkMonitor::backend_start() {
+    DWORD rv = NotifyUnicastIpAddressChange(AF_UNSPEC, &rats_ip_change_cb, this,
+                                            FALSE, &impl_->handle);
+    if (rv != NO_ERROR) {
+        LOG_NETMON_WARN("NotifyUnicastIpAddressChange failed (" << rv
+                        << "); falling back to polling");
+        impl_->handle = nullptr;
+        return false;
+    }
+    return true;
+}
+
+void NetworkMonitor::backend_stop() {
+    if (impl_ && impl_->handle != nullptr) {
+        // Cancels and waits for any in-flight callback to return, so no callback
+        // can run against a half-destroyed monitor afterwards.
+        CancelMibChangeNotify2(impl_->handle);
+        impl_->handle = nullptr;
+    }
+}
+
+// ============================================================================
+// Linux backend: NETLINK_ROUTE socket
+// ============================================================================
+#elif defined(__linux__)
+
+bool NetworkMonitor::backend_start() {
+    int fd = ::socket(AF_NETLINK, SOCK_RAW | SOCK_CLOEXEC, NETLINK_ROUTE);
+    if (fd < 0) {
+        LOG_NETMON_WARN("netlink socket() failed (" << errno << "); falling back to polling");
+        return false;
+    }
+
+    sockaddr_nl addr{};
+    addr.nl_family = AF_NETLINK;
+    addr.nl_groups = RTMGRP_IPV4_IFADDR | RTMGRP_IPV6_IFADDR
+                   | RTMGRP_LINK | RTMGRP_IPV4_ROUTE | RTMGRP_IPV6_ROUTE;
+    if (::bind(fd, reinterpret_cast<sockaddr*>(&addr), sizeof(addr)) < 0) {
+        LOG_NETMON_WARN("netlink bind() failed (" << errno << "); falling back to polling");
+        ::close(fd);
+        return false;
+    }
+
+    if (::pipe(impl_->stop_pipe) < 0) {
+        ::close(fd);
+        return false;
+    }
+    impl_->fd = fd;
+
+    impl_->reader = std::thread([this]() {
+        char buf[4096];
+        struct pollfd fds[2];
+        fds[0].fd = impl_->fd;        fds[0].events = POLLIN;
+        fds[1].fd = impl_->stop_pipe[0]; fds[1].events = POLLIN;
+
+        while (running_.load()) {
+            int pr = ::poll(fds, 2, -1);
+            if (pr < 0) {
+                if (errno == EINTR) continue;
+                break;
+            }
+            if (fds[1].revents & POLLIN) break;   // stop requested
+            if (!(fds[0].revents & POLLIN)) continue;
+
+            ssize_t len = ::recv(impl_->fd, buf, sizeof(buf), 0);
+            if (len <= 0) {
+                // ENOBUFS just means we missed messages under load — treat as a change.
+                if (len < 0 && errno == ENOBUFS) { check_now(); continue; }
+                if (len < 0 && errno == EINTR) continue;
+                break;
+            }
+
+            bool pertinent = false;
+            for (auto* nh = reinterpret_cast<nlmsghdr*>(buf);
+                 NLMSG_OK(nh, len); nh = NLMSG_NEXT(nh, len)) {
+                switch (nh->nlmsg_type) {
+                    case RTM_NEWADDR: case RTM_DELADDR:
+                    case RTM_NEWLINK: case RTM_DELLINK:
+                    case RTM_NEWROUTE: case RTM_DELROUTE:
+                        pertinent = true;
+                        break;
+                    default:
+                        break;
+                }
+            }
+            if (pertinent) check_now();
+        }
+    });
+    return true;
+}
+
+void NetworkMonitor::backend_stop() {
+    if (!impl_) return;
+    if (impl_->stop_pipe[1] >= 0) {
+        char b = 1;
+        ssize_t n = ::write(impl_->stop_pipe[1], &b, 1);
+        (void)n;
+    }
+    if (impl_->reader.joinable()) impl_->reader.join();
+    if (impl_->fd >= 0) { ::close(impl_->fd); impl_->fd = -1; }
+    if (impl_->stop_pipe[0] >= 0) { ::close(impl_->stop_pipe[0]); impl_->stop_pipe[0] = -1; }
+    if (impl_->stop_pipe[1] >= 0) { ::close(impl_->stop_pipe[1]); impl_->stop_pipe[1] = -1; }
+}
+
+// ============================================================================
+// macOS / BSD backend: PF_ROUTE routing socket
+// ============================================================================
+#elif defined(RATS_MONITOR_BSD_ROUTES)
+
+bool NetworkMonitor::backend_start() {
+    int fd = ::socket(PF_ROUTE, SOCK_RAW, AF_UNSPEC);
+    if (fd < 0) {
+        LOG_NETMON_WARN("PF_ROUTE socket() failed (" << errno << "); falling back to polling");
+        return false;
+    }
+    if (::pipe(impl_->stop_pipe) < 0) {
+        ::close(fd);
+        return false;
+    }
+    impl_->fd = fd;
+
+    impl_->reader = std::thread([this]() {
+        char buf[2048];
+        struct pollfd fds[2];
+        fds[0].fd = impl_->fd;           fds[0].events = POLLIN;
+        fds[1].fd = impl_->stop_pipe[0]; fds[1].events = POLLIN;
+
+        while (running_.load()) {
+            int pr = ::poll(fds, 2, -1);
+            if (pr < 0) {
+                if (errno == EINTR) continue;
+                break;
+            }
+            if (fds[1].revents & POLLIN) break;   // stop requested
+            if (!(fds[0].revents & POLLIN)) continue;
+
+            ssize_t len = ::read(impl_->fd, buf, sizeof(buf));
+            if (len <= 0) {
+                if (len < 0 && errno == EINTR) continue;
+                break;
+            }
+            if (static_cast<size_t>(len) < sizeof(rt_msghdr)) continue;
+
+            auto* rtm = reinterpret_cast<rt_msghdr*>(buf);
+            switch (rtm->rtm_type) {
+                case RTM_NEWADDR: case RTM_DELADDR:
+                case RTM_IFINFO:
+#ifdef RTM_IFANNOUNCE
+                case RTM_IFANNOUNCE:
+#endif
+                case RTM_ADD: case RTM_DELETE: case RTM_CHANGE:
+                    check_now();
+                    break;
+                default:
+                    break;
+            }
+        }
+    });
+    return true;
+}
+
+void NetworkMonitor::backend_stop() {
+    if (!impl_) return;
+    if (impl_->stop_pipe[1] >= 0) {
+        char b = 1;
+        ssize_t n = ::write(impl_->stop_pipe[1], &b, 1);
+        (void)n;
+    }
+    if (impl_->reader.joinable()) impl_->reader.join();
+    if (impl_->fd >= 0) { ::close(impl_->fd); impl_->fd = -1; }
+    if (impl_->stop_pipe[0] >= 0) { ::close(impl_->stop_pipe[0]); impl_->stop_pipe[0] = -1; }
+    if (impl_->stop_pipe[1] >= 0) { ::close(impl_->stop_pipe[1]); impl_->stop_pipe[1] = -1; }
+}
+
+// ============================================================================
+// Fallback backend: polling only (worker_loop diffs on its poll interval)
+// ============================================================================
+#else
+
+bool NetworkMonitor::backend_start() { return false; }
+void NetworkMonitor::backend_stop()  {}
+
+#endif
+
+} // namespace librats

package/native-src/src/network_monitor.h

@@ -0,0 +1,104 @@
+#pragma once
+
+/**
+ * @file network_monitor.h
+ * @brief Detects host network configuration changes (IP / interface / route).
+ *
+ * When the machine's connectivity changes — a new interface comes up, an IP
+ * address is added or removed, the default route flips (Wi-Fi <-> cellular,
+ * dock/undock, VPN up/down, wake-from-sleep) — a long-lived P2P node must react:
+ * re-create router port mappings, re-discover its public address via STUN, and
+ * re-announce to the DHT. Otherwise it keeps advertising a stale, unreachable
+ * endpoint until the next periodic refresh.
+ *
+ * NetworkMonitor provides an event-driven signal for exactly that. The design
+ * mirrors libtorrent's aux::ip_notifier but is adapted to librats' own threading
+ * model (no boost::asio): each platform backend only signals "something changed",
+ * and the monitor itself re-enumerates the local interface addresses and invokes
+ * the callback ONLY when the address set actually differs. Bursts of OS events
+ * (a single interface transition typically emits several) are coalesced with a
+ * short debounce window.
+ *
+ * Platform backends:
+ *   - Windows:    NotifyUnicastIpAddressChange()        (iphlpapi)
+ *   - Linux:      NETLINK_ROUTE socket, RTMGRP_*_IFADDR / *_LINK groups
+ *   - macOS/BSD:  PF_ROUTE routing socket
+ *   - otherwise:  periodic polling of the interface address list
+ *
+ * The callback runs on the monitor's worker thread, so it must not block for
+ * long; offload slow recovery work (STUN, port mapping) to another thread.
+ */
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace librats {
+
+class NetworkMonitor {
+public:
+    /// Invoked (debounced) whenever the set of local interface addresses changes.
+    /// @param current_addresses the new, full list of local interface addresses.
+    using ChangeCallback = std::function<void(const std::vector<std::string>& current_addresses)>;
+
+    NetworkMonitor();
+    ~NetworkMonitor();
+
+    NetworkMonitor(const NetworkMonitor&) = delete;
+    NetworkMonitor& operator=(const NetworkMonitor&) = delete;
+
+    /**
+     * Start monitoring. The callback fires on each detected change (after the
+     * debounce window) on the monitor's worker thread.
+     *
+     * @return true if an OS push-notification backend is active; false if the
+     *         monitor fell back to periodic polling. The monitor works either
+     *         way, so the return value is informational only.
+     */
+    bool start(ChangeCallback on_change);
+
+    /// Stop monitoring and join the worker thread. Idempotent.
+    void stop();
+
+    bool is_running() const { return running_.load(); }
+
+    /// Whether OS push notifications (vs. polling) are in use. Valid after start().
+    bool is_event_driven() const { return event_backend_active_; }
+
+    /**
+     * Request an immediate re-check, coalesced/debounced exactly like a real OS
+     * event. Thread-safe. Useful to call after the device wakes from sleep, or
+     * from the platform backends themselves. A no-op if not running.
+     */
+    void check_now();
+
+    /// Override the debounce window used to coalesce event bursts (default 2s).
+    void set_debounce(std::chrono::milliseconds d) { debounce_ = d; }
+
+private:
+    void worker_loop();
+    bool backend_start();   // set up the OS notifier; returns true if event-driven
+    void backend_stop();    // tear the OS notifier / reader thread down
+
+    ChangeCallback on_change_;
+    std::atomic<bool> running_{false};
+    bool change_pending_ = false;        // guarded by mutex_
+    bool event_backend_active_ = false;  // true once an OS backend is confirmed up
+    std::thread worker_;
+    std::mutex mutex_;
+    std::condition_variable cv_;
+    std::chrono::milliseconds debounce_{2000};
+    std::vector<std::string> last_addresses_;
+
+    // Platform-specific backend state (fds, OS handles, reader thread).
+    struct Impl;
+    std::unique_ptr<Impl> impl_;
+};
+
+} // namespace librats

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "librats",
-  "version": "0.9.2",
+  "version": "1.0.1",
   "description": "Node.js bindings for librats - A high-performance peer-to-peer networking library",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",