librats 1.0.2 → 2.2.0

package/native-src/src/librats/node/nat_status.cpp

@@ -0,0 +1,103 @@
+#include "librats/node/nat_status.h"
+
+#include <algorithm>
+
+namespace librats {
+
+const char* to_string(NatMapping m) noexcept {
+    switch (m) {
+        case NatMapping::Unknown:             return "unknown";
+        case NatMapping::Open:                return "open";
+        case NatMapping::EndpointIndependent: return "endpoint-independent";
+        case NatMapping::EndpointDependent:   return "endpoint-dependent";
+    }
+    return "unknown";
+}
+
+void NatStatus::record_udp_observation(const PeerId& reporter, const Address& external,
+                                       bool is_own_address) {
+    if (!external.is_valid()) return;
+
+    std::lock_guard<std::mutex> lock(mutex_);
+
+    auto it = seen_.find(reporter);
+    if (it == seen_.end()) {
+        // Bounded by observers rather than by observations, so the cap is only ever
+        // reached by a node with a genuinely large mesh — and once it is, the ones
+        // already held are the ones that have been confirmed longest.
+        if (seen_.size() >= kMaxObservers) return;
+        it = seen_.emplace(reporter, Observation{}).first;
+    }
+    it->second.endpoint       = external;
+    it->second.is_own_address = is_own_address;
+    it->second.seq            = next_seq_++;
+}
+
+void NatStatus::forget(const PeerId& reporter) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    seen_.erase(reporter);
+}
+
+void NatStatus::reset() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    seen_.clear();
+    next_seq_ = 1;
+}
+
+size_t NatStatus::observation_count() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return seen_.size();
+}
+
+std::vector<Address> NatStatus::external_udp_endpoints() const {
+    std::vector<Observation> all;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        all.reserve(seen_.size());
+        for (const auto& [id, obs] : seen_) all.push_back(obs);
+    }
+
+    // Freshest first: under a NAT that has just remapped us, the endpoint the most
+    // recent peer saw is the one a punch should be aimed at, and the stale ones
+    // behind it are worth keeping only as fallbacks.
+    std::sort(all.begin(), all.end(),
+              [](const Observation& a, const Observation& b) { return a.seq > b.seq; });
+
+    std::vector<Address> out;
+    out.reserve(all.size());
+    for (const Observation& obs : all)
+        if (std::find(out.begin(), out.end(), obs.endpoint) == out.end())
+            out.push_back(obs.endpoint);
+    return out;
+}
+
+NatMapping NatStatus::udp_mapping() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+
+    // Observations from peers that see us at an address we hold ourselves say
+    // nothing about a NAT — they are LAN peers, or there is no NAT at all. They are
+    // counted separately so a node whose only peers are on its own segment reports
+    // Open rather than the Unknown a bare "not enough samples" would give, while a
+    // single peer out on the internet still decides the answer for everybody.
+    size_t  own = 0;
+    size_t  external = 0;
+    bool    all_same = true;
+    Address first{};
+
+    for (const auto& [id, obs] : seen_) {
+        if (obs.is_own_address) { ++own; continue; }
+        if (external == 0) first = obs.endpoint;
+        else if (obs.endpoint != first) all_same = false;
+        ++external;
+    }
+
+    if (external == 0) return own > 0 ? NatMapping::Open : NatMapping::Unknown;
+
+    // One vantage point cannot tell a stable mapping from a per-destination one: it
+    // has only ever seen the mapping made for itself. Two disagreeing ones prove the
+    // NAT picks per destination; two agreeing ones are what a punch relies on.
+    if (external < 2) return NatMapping::Unknown;
+    return all_same ? NatMapping::EndpointIndependent : NatMapping::EndpointDependent;
+}
+
+} // namespace librats

package/native-src/src/librats/node/nat_status.h

@@ -0,0 +1,118 @@
+#pragma once
+
+/**
+ * @file nat_status.h
+ * @brief What the mesh has told us about our own side of the NAT.
+ *
+ * A node behind a NAT cannot see its own external endpoint; only somebody on the
+ * other side can. The usual answer is a STUN server, but a connected mesh already
+ * carries the same information for free — and, unlike a single STUN reply, it
+ * carries it from *several* independent vantage points, which is what turns a bare
+ * address into a statement about how the NAT behaves.
+ *
+ * The source is the identify exchange (node/identify.h). Each peer reports the
+ * address it observed us connecting from; on a DATAGRAM link that address is the
+ * NAT's rewriting of the one socket every UDP peer shares, so its port is exactly
+ * the port a third party must aim at to reach us. (On TCP the port is an ephemeral
+ * one our OS picked per connection and means nothing, so it is not reported and
+ * never reaches this class.)
+ *
+ * Two peers are then enough to classify the mapping:
+ *
+ *   - both see the SAME external port  → the NAT maps our socket to one port
+ *     regardless of who we are talking to (endpoint-independent, "cone"). This is
+ *     the case a hole punch works in: the port one peer tells us about is the port
+ *     another peer can dial.
+ *   - they see DIFFERENT ports         → the NAT picks a fresh mapping per
+ *     destination (endpoint-dependent, "symmetric"). Nothing we learn from one peer
+ *     predicts what a third will see, so punching to an advertised endpoint cannot
+ *     work and a relay is the only way through.
+ *   - the observed endpoint is one of our own local addresses → there is no NAT in
+ *     the path at all, and an ordinary dial already reaches us.
+ *
+ * Threading: observations arrive on reactor threads (possibly several), readers are
+ * application/subsystem threads. One small mutex; nothing on a data path.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/core/address.h"
+#include "librats/peer/peer_id.h"
+
+#include <cstddef>
+#include <mutex>
+#include <unordered_map>
+#include <vector>
+
+namespace librats {
+
+/// How the NAT in front of our shared datagram socket maps it, as far as the mesh
+/// has been able to show.
+enum class NatMapping : uint8_t {
+    Unknown,              ///< not enough independent observations yet
+    Open,                 ///< no NAT: peers see us at an address we hold ourselves
+    EndpointIndependent,  ///< one external port for every destination — punchable
+    EndpointDependent,    ///< a fresh mapping per destination (symmetric) — not punchable
+};
+
+RATS_API const char* to_string(NatMapping) noexcept;
+
+/// The read side, published in the node's ServiceRegistry so a NAT-traversal module
+/// can consult it without holding the Node:
+///
+///     if (auto* nat = ctx.services.get<ExternalAddressService>())
+///         if (nat->udp_mapping() == NatMapping::EndpointDependent) return;  // don't bother
+class ExternalAddressService {
+public:
+    virtual ~ExternalAddressService() = default;
+
+    /// Endpoints peers have reported observing our shared datagram socket at, most
+    /// recently confirmed first. Empty until at least one peer has said so over a
+    /// datagram link. These are what a hole punch advertises to its target.
+    virtual std::vector<Address> external_udp_endpoints() const = 0;
+
+    /// What the observations so far say about the mapping.
+    virtual NatMapping udp_mapping() const = 0;
+};
+
+class RATS_API NatStatus final : public ExternalAddressService {
+public:
+    /// Observations kept. One per reporting peer, so a node with many peers does not
+    /// grow this without bound and a single peer cannot flood it either — a second
+    /// report from the same peer replaces its first rather than adding to it.
+    static constexpr size_t kMaxObservers = 32;
+
+    /// Record that `reporter` observed our datagram socket at `external`.
+    /// @param is_own_address whether that endpoint is one this node holds locally
+    ///        (the caller knows its interfaces; this class does not) — the signal
+    ///        that there is no NAT in the path.
+    void record_udp_observation(const PeerId& reporter, const Address& external,
+                                bool is_own_address);
+
+    /// Forget a reporter's observation — its link is gone and what it saw may have
+    /// been a mapping that died with it.
+    void forget(const PeerId& reporter);
+
+    /// Drop everything. The node is restarting, or the host's network changed and
+    /// every mapping learned under the old one is now a guess.
+    void reset();
+
+    /// How many distinct peers have reported an endpoint.
+    size_t observation_count() const;
+
+    // — ExternalAddressService —
+    std::vector<Address> external_udp_endpoints() const override;
+    NatMapping           udp_mapping() const override;
+
+private:
+    struct Observation {
+        Address  endpoint;
+        bool     is_own_address = false;
+        uint64_t seq = 0;   ///< arrival order, so the freshest endpoint sorts first
+    };
+
+    mutable std::mutex                                       mutex_;
+    std::unordered_map<PeerId, Observation, PeerId::Hash>    seen_;
+    uint64_t                                                 next_seq_ = 1;
+};
+
+} // namespace librats