librats 0.9.1 → 1.0.0

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/native-src/src/network_utils.cpp

@@ -16,6 +16,17 @@
     #else
         #include <ifaddrs.h>
     #endif
+
+    // macOS / BSD default-gateway lookup via the PF_ROUTE sysctl routing table.
+    #if defined(__APPLE__) || defined(__FreeBSD__) || defined(__NetBSD__) || \
+        defined(__OpenBSD__) || defined(__DragonFly__)
+        #define RATS_HAVE_BSD_ROUTES 1
+        #include <sys/types.h>
+        #include <sys/socket.h>
+        #include <sys/sysctl.h>
+        #include <net/route.h>
+        #include <net/if.h>
+    #endif
 #endif
 
 
@@ -25,6 +36,12 @@
 #include <cstring>
 #include <iostream>
 #include <vector>
+#include <algorithm>
+
+#ifndef _WIN32
+    #include <cstdio>
+    #include <cstdlib>
+#endif
 
 // Network utilities module logging macros
 #define LOG_NETUTILS_DEBUG(message) LOG_DEBUG("network_utils", message)
@@ -379,6 +396,41 @@ bool is_hostname(const std::string& str) {
     return true;
 }
 
+bool is_public_ip(const std::string& ip) {
+    if (ip.empty()) return false;
+
+    if (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;
+}
+
 std::vector<std::string> get_local_interface_addresses() {
     LOG_NETUTILS_DEBUG("Getting all local interface addresses (IPv4 and IPv6)");
     
@@ -390,11 +442,140 @@ std::vector<std::string> get_local_interface_addresses() {
     auto ipv6_addresses = get_local_interface_addresses_v6();
     addresses.insert(addresses.end(), ipv6_addresses.begin(), ipv6_addresses.end());
     
-    LOG_NETUTILS_INFO("Found " << addresses.size() << " total local interface addresses (" 
+    LOG_NETUTILS_INFO("Found " << addresses.size() << " total local interface addresses ("
                       << ipv4_addresses.size() << " IPv4, " << ipv6_addresses.size() << " IPv6)");
-    
+
     return addresses;
 }
 
+namespace {
+
+// Append unique, non-empty entries preserving order
+void append_unique(std::vector<std::string>& out, const std::string& value) {
+    if (value.empty()) return;
+    if (std::find(out.begin(), out.end(), value) == out.end()) {
+        out.push_back(value);
+    }
+}
+
+// Best-effort guess: for each local IPv4 assume the gateway is the .1 host of a
+// /24 network. Covers the overwhelming majority of home routers and serves as a
+// fallback when the OS routing table is unavailable.
+void append_gateway_heuristics(std::vector<std::string>& out) {
+    for (const auto& ip : get_local_interface_addresses_v4()) {
+        if (ip.empty() || ip == "127.0.0.1") continue;
+        auto last_dot = ip.find_last_of('.');
+        if (last_dot == std::string::npos) continue;
+        append_unique(out, ip.substr(0, last_dot) + ".1");
+    }
+}
+
+} // anonymous namespace
+
+std::vector<std::string> get_default_gateways() {
+    std::vector<std::string> gateways;
+
+#ifdef _WIN32
+    ULONG out_buf_len = sizeof(IP_ADAPTER_INFO);
+    std::vector<uint8_t> buffer(out_buf_len);
+    DWORD ret = GetAdaptersInfo(reinterpret_cast<PIP_ADAPTER_INFO>(buffer.data()), &out_buf_len);
+    if (ret == ERROR_BUFFER_OVERFLOW) {
+        buffer.resize(out_buf_len);
+        ret = GetAdaptersInfo(reinterpret_cast<PIP_ADAPTER_INFO>(buffer.data()), &out_buf_len);
+    }
+    if (ret == NO_ERROR) {
+        for (PIP_ADAPTER_INFO adapter = reinterpret_cast<PIP_ADAPTER_INFO>(buffer.data());
+             adapter != nullptr; adapter = adapter->Next) {
+            for (const IP_ADDR_STRING* gw = &adapter->GatewayList; gw != nullptr; gw = gw->Next) {
+                std::string gw_ip(gw->IpAddress.String);
+                if (gw_ip != "0.0.0.0") {
+                    append_unique(gateways, gw_ip);
+                }
+            }
+        }
+    } else {
+        LOG_NETUTILS_DEBUG("GetAdaptersInfo failed with error: " << ret);
+    }
+#elif defined(__linux__)
+    // /proc/net/route columns: Iface Destination Gateway Flags ... (hex, little-endian)
+    if (FILE* f = std::fopen("/proc/net/route", "r")) {
+        char line[256];
+        // Skip header line
+        if (std::fgets(line, sizeof(line), f)) {
+            char iface[64];
+            unsigned long dest = 0, gw = 0;
+            while (std::fgets(line, sizeof(line), f)) {
+                if (std::sscanf(line, "%63s %lx %lx", iface, &dest, &gw) == 3) {
+                    if (dest == 0 && gw != 0) {
+                        struct in_addr addr;
+                        addr.s_addr = static_cast<in_addr_t>(gw);
+                        char ip_str[INET_ADDRSTRLEN];
+                        if (inet_ntop(AF_INET, &addr, ip_str, sizeof(ip_str))) {
+                            append_unique(gateways, ip_str);
+                        }
+                    }
+                }
+            }
+        }
+        std::fclose(f);
+    }
+#elif defined(RATS_HAVE_BSD_ROUTES)
+    // Dump the IPv4 routing table and pick the gateway of the default route(s).
+    int mib[6] = { CTL_NET, PF_ROUTE, 0, AF_INET, NET_RT_DUMP, 0 };
+    size_t needed = 0;
+    if (sysctl(mib, 6, nullptr, &needed, nullptr, 0) == 0 && needed > 0) {
+        std::vector<char> buf(needed);
+        if (sysctl(mib, 6, buf.data(), &needed, nullptr, 0) == 0) {
+            // sockaddrs in a routing message are padded to a 4-byte boundary.
+            auto sa_roundup = [](socklen_t len) -> size_t {
+                return len ? (1 + ((static_cast<size_t>(len) - 1) | (sizeof(uint32_t) - 1)))
+                           : sizeof(uint32_t);
+            };
+            char* lim = buf.data() + needed;
+            for (char* next = buf.data(); next + sizeof(struct rt_msghdr) <= lim; ) {
+                auto* rtm = reinterpret_cast<struct rt_msghdr*>(next);
+                if (rtm->rtm_msglen == 0) break;
+                char* msg_end = next + rtm->rtm_msglen;
+                next = msg_end;
+
+                if (!(rtm->rtm_flags & RTF_GATEWAY)) continue;
+                if (!(rtm->rtm_addrs & RTA_DST) || !(rtm->rtm_addrs & RTA_GATEWAY)) continue;
+
+                // Address list follows the header, ordered by the RTA_* bit flags.
+                char* sa_ptr = reinterpret_cast<char*>(rtm + 1);
+                struct sockaddr* dst = nullptr;
+                struct sockaddr* gw = nullptr;
+                for (int bit = 1; bit && sa_ptr < msg_end; bit <<= 1) {
+                    if (!(rtm->rtm_addrs & bit)) continue;
+                    auto* sa = reinterpret_cast<struct sockaddr*>(sa_ptr);
+                    if (bit == RTA_DST) dst = sa;
+                    else if (bit == RTA_GATEWAY) gw = sa;
+                    sa_ptr += sa_roundup(sa->sa_len);
+                }
+
+                if (!dst || !gw) continue;
+                if (dst->sa_family != AF_INET || gw->sa_family != AF_INET) continue;
+                // Default route: destination 0.0.0.0
+                if (reinterpret_cast<struct sockaddr_in*>(dst)->sin_addr.s_addr != 0) continue;
+
+                char ip_str[INET_ADDRSTRLEN];
+                auto* gw4 = reinterpret_cast<struct sockaddr_in*>(gw);
+                if (inet_ntop(AF_INET, &gw4->sin_addr, ip_str, sizeof(ip_str))) {
+                    append_unique(gateways, ip_str);
+                }
+            }
+        }
+    } else {
+        LOG_NETUTILS_DEBUG("PF_ROUTE sysctl for default gateway failed");
+    }
+#endif
+
+    // Always add heuristics as a fallback so callers have something to try
+    append_gateway_heuristics(gateways);
+
+    LOG_NETUTILS_INFO("Detected " << gateways.size() << " default gateway candidate(s)");
+    return gateways;
+}
+
 } // namespace network_utils
 } // namespace librats