librats 1.0.2 → 2.2.0

package/native-src/src/librats/subsystems/port_mapping_service.cpp

@@ -0,0 +1,192 @@
+#include "librats/subsystems/port_mapping_service.h"
+#include "librats/node/node_context.h"
+#include "librats/node/host_events.h"
+#include "librats/nat/upnp.h"
+#include "librats/nat/natpmp.h"
+#include "librats/util/network_utils.h"
+#include "librats/util/logger.h"
+
+#include <vector>
+
+namespace librats {
+
+PortMappingService::PortMappingService(PortMappingConfig config) : config_(config) {}
+
+PortMappingService::~PortMappingService() { stop(); }
+
+void PortMappingService::attach(NodeContext& ctx) {
+    network_ = &ctx.network;
+    // On a host network change the LAN IP and/or gateway likely changed, so existing
+    // UPnP/NAT-PMP leases are stale or aimed at the wrong internal address. Tear them
+    // down and re-run discovery from scratch. The handler runs on the node's
+    // maintenance thread (dedicated to recovery), so the blocking stop()/start() is
+    // fine here.
+    ctx.events.on<NetworkChanged>([this](const NetworkChanged&) {
+        if (!config_.enabled) return;
+        LOG_INFO("portmap", "Network changed — renewing port mappings");
+        stop();
+        if (network_) start();
+    });
+}
+
+void PortMappingService::start() {
+    if (!config_.enabled) {
+        LOG_DEBUG("portmap", "Automatic port forwarding disabled by config");
+        return;
+    }
+
+    const uint16_t port = network_ ? network_->listen_port() : 0;
+    if (port == 0) {
+        LOG_WARN("portmap", "Skipping port mapping: node has no listen port");
+        return;
+    }
+
+    // One port, mapped under each protocol actually listening on it. Asking for a
+    // protocol the node does not serve would install a mapping pointing at nothing,
+    // so the node's own transports bitmask — the same one identify advertises — is
+    // what decides.
+    const uint8_t transports = network_->transports();
+    std::vector<PortMapProtocol> protocols;
+    if (transports & PeerTransportTcp) protocols.push_back(PortMapProtocol::TCP);
+    if (transports & PeerTransportUdp) protocols.push_back(PortMapProtocol::UDP);
+    if (protocols.empty()) {
+        LOG_WARN("portmap", "Skipping port mapping: node reports no running transport");
+        return;
+    }
+
+    auto callback = [this](const PortMapResult& r) { handle_result(r); };
+
+    std::unique_ptr<UpnpClient>   upnp;
+    std::unique_ptr<NatPmpClient> natpmp;
+
+    // external_port 0 means "same as internal" in both backends, which is what the
+    // UDP mapping needs: peers learn our datagram endpoint from the port the NAT
+    // rewrites our outbound traffic to (nat_status.h), and only a port-preserving
+    // mapping makes that the same port the router forwards inbound. (A router that
+    // rejects the port with a conflict makes UPnP fall back to a random one — still
+    // dialable through mapped_public_address(), just no longer the observed one.)
+    if (config_.enable_upnp) {
+        upnp = std::make_unique<UpnpClient>();
+        upnp->set_lease_duration(config_.lease_duration_seconds);
+        upnp->set_callback(callback);
+        for (PortMapProtocol proto : protocols)
+            upnp->add_mapping(proto, port, /*external_port=*/0, "rats");
+    }
+    if (config_.enable_natpmp) {
+        natpmp = std::make_unique<NatPmpClient>();
+        natpmp->set_lease_duration(config_.lease_duration_seconds);
+        natpmp->set_callback(callback);
+        for (PortMapProtocol proto : protocols)
+            natpmp->add_mapping(proto, port, /*external_port=*/0);
+    }
+
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (upnp_ || natpmp_) return;  // already started
+        upnp_   = std::move(upnp);
+        natpmp_ = std::move(natpmp);
+        // Start the workers under the lock so a result callback (which takes the
+        // lock from its own thread) cannot observe a half-published state.
+        if (upnp_)   upnp_->start();
+        if (natpmp_) natpmp_->start();
+    }
+
+    std::string proto_list;
+    for (PortMapProtocol proto : protocols) {
+        if (!proto_list.empty()) proto_list += "+";
+        proto_list += to_string(proto);
+    }
+    LOG_INFO("portmap", "Started automatic port forwarding for " << proto_list << " port " << port
+             << " (upnp=" << config_.enable_upnp << " natpmp=" << config_.enable_natpmp
+             << " lease=" << config_.lease_duration_seconds << "s)");
+}
+
+void PortMappingService::stop() {
+    // Move the clients out under the lock, then stop() them outside it: stop()
+    // joins worker threads that call handle_result() (which re-takes mutex_), so
+    // holding it across stop() would deadlock.
+    std::unique_ptr<UpnpClient>   upnp;
+    std::unique_ptr<NatPmpClient> natpmp;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        upnp   = std::move(upnp_);
+        natpmp = std::move(natpmp_);
+    }
+
+    if (upnp || natpmp) LOG_INFO("portmap", "Removing port mappings and stopping backends");
+    if (upnp)   upnp->stop();
+    if (natpmp) natpmp->stop();
+
+    // The backends have just torn their mappings down, so whatever public endpoint
+    // they had established no longer exists. Forget it — NetworkChanged restarts us
+    // through here, and reporting the pre-change mapping afterwards would hand out
+    // an address that now points at a different LAN.
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        mapped_external_ip_.clear();
+        mapped_external_tcp_port_ = 0;
+        mapped_external_udp_port_ = 0;
+    }
+}
+
+uint16_t& PortMappingService::external_port_slot(PortMapProtocol protocol) {
+    return protocol == PortMapProtocol::TCP ? mapped_external_tcp_port_ : mapped_external_udp_port_;
+}
+
+void PortMappingService::handle_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. Such a mapping must
+    // NOT be recorded as a usable public endpoint.
+    const bool ip_is_private =
+        !result.external_ip.empty() && !network_utils::is_public_ip(result.external_ip);
+
+    PortMapCallback user_cb;
+    bool warn_double_nat = false;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        // Only successes are recorded, and a failure never clears an earlier one:
+        // the two backends run in parallel against the same router, so a NAT-PMP
+        // refusal routinely arrives after UPnP has already mapped the very same
+        // port. Each protocol keeps its own slot — a router may take one and
+        // refuse the other.
+        if (result.success && !ip_is_private) {
+            if (!result.external_ip.empty()) mapped_external_ip_ = result.external_ip;
+            external_port_slot(result.protocol) = result.external_port;
+        } else if (result.success && ip_is_private && !double_nat_warned_) {
+            double_nat_warned_ = true;
+            warn_double_nat = true;
+        }
+        user_cb = user_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.");
+        }
+    } 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);
+    } 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);
+}
+
+std::optional<std::pair<std::string, uint16_t>>
+PortMappingService::mapped_public_address(PortMapProtocol protocol) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    const uint16_t port = protocol == PortMapProtocol::TCP ? mapped_external_tcp_port_
+                                                           : mapped_external_udp_port_;
+    if (port == 0 || mapped_external_ip_.empty()) return std::nullopt;
+    return std::make_pair(mapped_external_ip_, port);
+}
+
+} // namespace librats

package/native-src/src/librats/subsystems/port_mapping_service.h

@@ -0,0 +1,84 @@
+#pragma once
+
+/**
+ * @file port_mapping_service.h
+ * @brief Automatic NAT port forwarding (UPnP IGD + NAT-PMP) as a Subsystem.
+ *
+ * Wraps the standalone UpnpClient (src/upnp.h) and NatPmpClient (src/natpmp.h)
+ * backends into the Node lifecycle. On start() it asks the home router to forward
+ * the node's listen port so peers behind NAT can accept inbound connections; on
+ * stop() it removes the mappings. Both backends run in parallel on their own worker
+ * threads — whichever the router supports wins.
+ *
+ * The port is forwarded under EVERY protocol the node is actually listening on
+ * (PeerNetwork::transports()), not just TCP. Both transports share one listen port
+ * by design, and UDP is the dialer's first choice — a TCP-only mapping leaves an
+ * inbound peer able to reach us solely over the TCP fallback. It is also the UDP
+ * mapping that a hole punch benefits from: a static, port-preserving mapping is
+ * what turns the NAT in front of the shared datagram socket into the
+ * endpoint-independent kind HolePunch is willing to fire at (see nat_status.h).
+ *
+ * Threading: the backends invoke our result callback from their own worker
+ * threads, so all shared state is guarded by mutex_. stop() moves the clients out
+ * under the lock and stops them OUTSIDE it — stop() joins those workers, which
+ * take the lock from handle_result(), so holding it across stop() would deadlock.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/node/peer_network.h"
+#include "librats/nat/port_mapping.h"   // PortMappingConfig, PortMapResult, PortMapCallback
+
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <utility>
+
+namespace librats {
+
+class UpnpClient;
+class NatPmpClient;
+
+/// Maps the node's TCP listen port through the home router via UPnP and/or
+/// NAT-PMP. Owns its backends' worker threads; reaches the node only for its
+/// listen port (it neither sends nor receives peer traffic).
+class RATS_API PortMappingService final : public Subsystem {
+public:
+    explicit PortMappingService(PortMappingConfig config = {});
+    ~PortMappingService() override;
+
+    void attach(NodeContext& ctx) override;
+    void start() override;
+    void stop() override;
+
+    /// Observe mapping results (established / refreshed / failed). Optional;
+    /// invoked from a backend worker thread. Register before start().
+    void on_result(PortMapCallback cb) { user_callback_ = std::move(cb); }
+
+    /// The public endpoint peers should reach us on over @p protocol, once a
+    /// backend reports a usable (genuinely public) external IP + port for it.
+    /// nullopt until then. The two protocols are mapped independently and a router
+    /// may accept one and refuse the other, so ask for the one you intend to dial.
+    std::optional<std::pair<std::string, uint16_t>> mapped_public_address(
+        PortMapProtocol protocol = PortMapProtocol::TCP) const;
+
+private:
+    void handle_result(const PortMapResult& result);
+    /// The recorded external port for @p protocol. Call under mutex_.
+    uint16_t& external_port_slot(PortMapProtocol protocol);
+
+    PortMappingConfig config_;
+    PeerNetwork*      network_ = nullptr;
+    PortMapCallback   user_callback_;
+
+    mutable std::mutex            mutex_;  ///< guards the clients and mapped_* below
+    std::unique_ptr<UpnpClient>   upnp_;
+    std::unique_ptr<NatPmpClient> natpmp_;
+    std::string                   mapped_external_ip_;
+    uint16_t                      mapped_external_tcp_port_ = 0;
+    uint16_t                      mapped_external_udp_port_ = 0;
+    bool                          double_nat_warned_ = false;
+};
+
+} // namespace librats