librats 1.0.2 → 2.2.0

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

@@ -0,0 +1,241 @@
+#include "librats/subsystems/peer_exchange.h"
+#include "librats/node/node_context.h"
+#include "librats/subsystems/hole_punch_service.h"
+#include "librats/util/logger.h"
+#include "librats/util/network_utils.h"
+
+#include <algorithm>
+#include <unordered_set>
+
+namespace librats {
+
+namespace {
+
+constexpr uint8_t kVersion  = 1;  // peer IPs are raw address bytes (4/16), not text
+constexpr uint8_t kRequest  = 0;
+constexpr uint8_t kResponse = 1;
+
+constexpr size_t kRequestSize = 4;  // ver + op + u16 max
+
+void put_u16(Bytes& out, uint16_t v) {
+    out.push_back(static_cast<uint8_t>(v >> 8));
+    out.push_back(static_cast<uint8_t>(v & 0xFF));
+}
+
+uint16_t get_u16(const uint8_t* p) {
+    return static_cast<uint16_t>((static_cast<uint16_t>(p[0]) << 8) | p[1]);
+}
+
+} // namespace
+
+PeerExchange::PeerExchange() : PeerExchange(Config()) {}
+PeerExchange::PeerExchange(Config config) : config_(std::move(config)) {}
+PeerExchange::~PeerExchange() { stop(); }
+
+void PeerExchange::attach(NodeContext& ctx) {
+    network_  = &ctx.network;
+    services_ = &ctx.services;   // both references outlive every subsystem
+    network_->on(MessageType::Pex,
+                         [this](const Peer& peer, ByteView payload) { handle(peer, payload); });
+    network_->on_peer_connected([this](const Peer& peer) { on_connected(peer); });
+    network_->on_dial_failed([this](const Address& addr) { on_dial_failed(addr); });
+}
+
+void PeerExchange::start() {
+    // Resolved here rather than in attach(): HolePunch may be attached after us, and
+    // every attach() runs before any start(). Stored before running_ goes true, so a
+    // dial failure arriving on a reactor thread never sees a half-initialised state.
+    punch_.store(config_.punch_on_dial_failure && services_
+                     ? services_->get<HolePunchService>()
+                     : nullptr);
+    running_.store(true);
+}
+
+void PeerExchange::stop() {
+    running_.store(false);
+    punch_.store(nullptr);
+    std::lock_guard<std::mutex> lock(mutex_);
+    pending_dials_.clear();
+}
+
+// ── Outgoing request (on connect) ────────────────────────────────────────────
+
+void PeerExchange::on_connected(const Peer& peer) {
+    if (!running_.load() || !config_.request_on_connect) return;
+    const uint16_t max = static_cast<uint16_t>(std::min<size_t>(config_.request_max, 0xFFFF));
+
+    uint8_t req[kRequestSize] = {kVersion, kRequest,
+                                 static_cast<uint8_t>(max >> 8), static_cast<uint8_t>(max & 0xFF)};
+    network_->send(peer.id(), MessageType::Pex, ByteView(req, kRequestSize));
+}
+
+// ── Inbound dispatch ─────────────────────────────────────────────────────────
+
+void PeerExchange::handle(const Peer& peer, ByteView payload) {
+    if (!running_.load() || payload.size() < 2) return;
+    if (payload.data()[0] != kVersion) return;                // unknown version → ignore
+
+    const uint8_t op = payload.data()[1];
+    const ByteView body(payload.data() + 2, payload.size() - 2);
+    if (op == kRequest) {
+        if (body.size() < 2) return;
+        handle_request(peer, get_u16(body.data()));
+    } else if (op == kResponse) {
+        handle_response(body);
+    }
+}
+
+void PeerExchange::handle_request(const Peer& requester, uint16_t max) {
+    const size_t limit = std::min<size_t>(max, config_.max_addresses_per_response);
+    if (limit == 0) return;
+    const PeerId& self = network_->local_id();
+
+    Bytes out;
+    out.push_back(kVersion);
+    out.push_back(kResponse);
+    const size_t count_pos = out.size();
+    put_u16(out, 0);  // count placeholder, back-patched below
+
+    uint16_t count = 0;
+    for (const PeerInfo& p : network_->peers()) {
+        if (count >= limit) break;
+        if (p.id == requester.id() || p.id == self) continue;  // not the asker, not us
+        const Address* addr = pick_shareable(p.addresses);
+        if (!addr) continue;
+
+        const ByteView ip = addr->ip.bytes();  // 4 (v4) or 16 (v6) raw bytes
+        out.push_back(static_cast<uint8_t>(ip.size()));
+        out.insert(out.end(), ip.begin(), ip.end());
+        put_u16(out, addr->port);
+        const auto& id_bytes = p.id.bytes();
+        out.insert(out.end(), id_bytes.begin(), id_bytes.end());
+        ++count;
+    }
+    if (count == 0) return;  // nothing worth sending
+
+    out[count_pos]     = static_cast<uint8_t>(count >> 8);
+    out[count_pos + 1] = static_cast<uint8_t>(count & 0xFF);
+    network_->send(requester.id(), MessageType::Pex, ByteView(out));
+}
+
+void PeerExchange::handle_response(ByteView body) {
+    const uint8_t* p = body.data();
+    size_t         n = body.size();
+    // Bounds-checked forward reader: any short read aborts the whole response.
+    auto take = [&](size_t k) -> const uint8_t* {
+        if (n < k) return nullptr;
+        const uint8_t* at = p;
+        p += k; n -= k;
+        return at;
+    };
+
+    const uint8_t* hdr = take(2);
+    if (!hdr) return;
+    const uint16_t count = get_u16(hdr);
+
+    const PeerId self = network_->local_id();
+    std::unordered_set<PeerId, PeerId::Hash> connected;
+    for (const PeerId& id : network_->connected_peers()) connected.insert(id);
+
+    // Already at the size the application asked for: read the response no further.
+    // The sample is a snapshot anyway — when a peer drops, the next connect asks again.
+    if (config_.peer_target && connected.size() >= config_.peer_target) return;
+
+    size_t dialed = 0;
+    for (uint16_t i = 0; i < count; ++i) {
+        if (dialed >= config_.max_addresses_per_response) break;  // bound receiver work
+
+        const uint8_t* len_p = take(1);
+        if (!len_p) return;
+        const uint8_t ip_len = *len_p;
+        if (ip_len != 4 && ip_len != 16) return;  // malformed
+        const uint8_t* ip_p = take(ip_len);
+        if (!ip_p) return;
+        const auto ip = IpAddress::from_bytes(ByteView(ip_p, ip_len));
+        const uint8_t* port_p = take(2);
+        if (!port_p) return;
+        const uint16_t port = get_u16(port_p);
+        const uint8_t* id_p = take(PeerId::kSize);
+        if (!id_p) return;
+        const auto id = PeerId::from_bytes(ByteView(id_p, PeerId::kSize));
+
+        if (!id || *id == self || connected.count(*id)) continue;     // us / already linked
+        if (!ip || port == 0 || ip->is_any()) continue;               // not dialable
+        Address addr{*ip, port};
+        if (!should_dial(addr)) continue;                             // cooldown / dedup
+
+        LOG_DEBUG("pex", "Discovered peer " << id->short_hex() << " at " << addr.to_string() << "; dialing");
+        remember_dial(addr, *id);   // before connect(): the verdict is asynchronous
+        network_->connect(addr);
+        ++dialed;
+    }
+}
+
+// ── Punch fallback ───────────────────────────────────────────────────────────
+
+void PeerExchange::on_dial_failed(const Address& address) {
+    if (!running_.load()) return;
+    HolePunchService* punch = punch_.load();
+    if (!punch) return;   // no HolePunch attached, or the fallback is off
+
+    PeerId target;
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        auto it = pending_dials_.find(address);
+        // Not one of ours (ReconnectionService and the app dial too), or too old to
+        // still be attributable to a peer id.
+        if (it == pending_dials_.end()) return;
+        const auto age = std::chrono::steady_clock::now() - it->second.started;
+        target = it->second.id;
+        pending_dials_.erase(it);
+        if (age > config_.punch_window) return;
+    }
+
+    LOG_DEBUG("pex", "Peer " << target.short_hex() << " would not dial at "
+              << address.to_string() << "; asking for a hole punch");
+    punch->punch(target);
+}
+
+void PeerExchange::remember_dial(const Address& addr, const PeerId& id) {
+    if (!config_.punch_on_dial_failure) return;
+    const auto now = std::chrono::steady_clock::now();
+    std::lock_guard<std::mutex> lock(mutex_);
+
+    // A dial that neither failed nor was reported leaves its entry behind, so the
+    // window is also what bounds the map in steady state; the cap is the backstop.
+    for (auto it = pending_dials_.begin(); it != pending_dials_.end();) {
+        if (now - it->second.started > config_.punch_window) it = pending_dials_.erase(it);
+        else ++it;
+    }
+    if (pending_dials_.size() >= config_.max_pending_dials) return;  // best-effort
+
+    pending_dials_[addr] = PendingDial{id, now};
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+const Address* PeerExchange::pick_shareable(const std::vector<Address>& addrs) const {
+    for (const Address& a : addrs) {
+        if (a.port == 0 || a.ip.is_any()) continue;
+        if (config_.public_only && !network_utils::is_public_ip(a.ip)) continue;
+        return &a;
+    }
+    return nullptr;
+}
+
+bool PeerExchange::should_dial(const Address& addr) {
+    const auto now = std::chrono::steady_clock::now();
+    std::lock_guard<std::mutex> lock(mutex_);
+
+    // Drop expired entries so the set stays bounded and old failures can be retried.
+    for (auto it = recent_dials_.begin(); it != recent_dials_.end();) {
+        if (now - it->second > config_.dial_cooldown) it = recent_dials_.erase(it);
+        else ++it;
+    }
+    if (recent_dials_.size() >= config_.max_recent_dials) return false;  // overloaded → back off
+
+    auto [it, inserted] = recent_dials_.emplace(addr, now);
+    return inserted;  // false ⇒ dialed within the cooldown window
+}
+
+} // namespace librats

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

@@ -0,0 +1,136 @@
+#pragma once
+
+/**
+ * @file peer_exchange.h
+ * @brief Peer exchange (PEX): peers gossip the addresses of peers they know, so a
+ *        node bootstraps the mesh from its existing links — no DHT/tracker needed.
+ *
+ * A Subsystem built on PeerNetwork, plus one optional capability: when a peer it
+ * discovered refuses to be dialed and HolePunch is present, it asks for a NAT hole
+ * punch to that peer's id instead of writing the peer off (see below). This first
+ * cut is deliberately
+ * **pull-only**: when we connect to a peer we ask it for some of its known peers,
+ * and it replies with a random sample (address + id). We then dial the ones we do
+ * not already have. Both sides must run PeerExchange — the responder needs it to
+ * answer the request.
+ *
+ * It rides on the node's identify layer: identify is what fills in each peer's
+ * dialable address (an inbound peer's listen port is otherwise unknown), and PEX
+ * simply forwards those addresses on. A discovered peer we dial becomes an
+ * outbound link, so — paired with ReconnectionService — it is then persisted and
+ * kept alive automatically.
+ *
+ * Wire format (MessageType::Pex payload), all integers big-endian:
+ *   Request  : [u8 ver=1][u8 op=0][u16 max]
+ *   Response : [u8 ver=1][u8 op=1][u16 count] × { [u8 ip_len][ip][u16 port][32B peer_id] }
+ *
+ * ── Punch fallback ──────────────────────────────────────────────────────────
+ * A PEX entry carries an id *and* an address, which is exactly what a peer behind a
+ * NAT cannot be reached at: its advertised endpoint is unreachable from the outside,
+ * so the dial fails and the mesh silently stays one link short. That is the case
+ * HolePunch exists for, and PEX is the only module that holds both halves it needs —
+ * so each dial started here is remembered by address for `punch_window`, and if
+ * on_dial_failed reports that address back, the id is handed to HolePunchService.
+ * Entirely optional: with no HolePunch attached the lookup answers nullptr and the
+ * failure is simply the end of the story, as before.
+ *
+ * Safety: response size is capped both sides; the receiver bounds how many it
+ * dials per response and de-duplicates dials with a TTL'd cooldown set (so a slow
+ * dial or a repeated response can't trigger a connect storm); malformed payloads
+ * are ignored, never fatal. `public_only` restricts sharing to globally-routable
+ * addresses for WAN deployments that must not relay private/LAN endpoints. The
+ * punch fallback inherits those bounds — one punch per dial we ourselves started,
+ * and HolePunch caps sessions and cooldowns on top of that.
+ *
+ * Threading: handlers run on reactor threads (possibly several with a multi-reactor
+ * pool), so the cooldown set is mutex-guarded. The subsystem owns no thread.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/node/peer_network.h"
+#include "librats/peer/peer.h"
+#include "librats/peer/peer_id.h"
+#include "librats/core/address.h"
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+namespace librats {
+
+class ServiceRegistry;
+struct HolePunchService;
+
+class RATS_API PeerExchange final : public Subsystem {
+public:
+    struct Config {
+        size_t max_addresses_per_response = 32;  ///< cap entries we send / act on per response
+        size_t request_max                = 32;  ///< how many peers we ask for on connect
+        bool   request_on_connect         = true;
+        bool   public_only                = false;  ///< only share globally-routable addresses
+        std::chrono::milliseconds dial_cooldown{std::chrono::minutes(5)};  ///< re-dial suppression
+        size_t max_recent_dials           = 4096;  ///< bound the cooldown set
+
+        /// Stop dialing discovered peers once this many are connected. 0 (default)
+        /// keeps the historical behaviour: grow without bound. Worth setting,
+        /// because NodeConfig::max_peers guards *inbound* connections only — every
+        /// discovered peer we dial is honored regardless of it, and PEX is the one
+        /// discovery source that compounds (each new peer is asked for more peers).
+        /// Answering other peers' requests is unaffected: that costs one message.
+        size_t peer_target                = 0;
+
+        /// Ask HolePunch to reach a discovered peer whose address would not dial.
+        /// A no-op when no HolePunch is attached.
+        bool punch_on_dial_failure        = true;
+        /// How long a dial started here stays eligible for that fallback. Only has
+        /// to outlive the dial itself (connect + handshake, ~15 s worst case).
+        std::chrono::milliseconds punch_window{std::chrono::seconds(30)};
+        /// Bound on dials awaiting their verdict — one entry is an address and an id.
+        size_t max_pending_dials          = 512;
+    };
+
+    PeerExchange();
+    explicit PeerExchange(Config config);
+    ~PeerExchange() override;
+
+    void attach(NodeContext& ctx) override;
+    void start() override;
+    void stop() override;
+
+private:
+    void on_connected(const Peer& peer);
+    void handle(const Peer& peer, ByteView payload);
+    void handle_request(const Peer& requester, uint16_t max);
+    void handle_response(ByteView body);
+    /// An outbound dial resolved as failed. Ours ⇒ punch the peer it was meant for.
+    void on_dial_failed(const Address& address);
+
+    const Address* pick_shareable(const std::vector<Address>& addrs) const;
+    bool           should_dial(const Address& addr);  ///< cooldown + dedup; records on success
+    /// Note who a dial we are about to start was aimed at. Called BEFORE connect():
+    /// the failure lands on a reactor thread and may beat us back here otherwise.
+    void           remember_dial(const Address& addr, const PeerId& id);
+
+    Config       config_;
+    PeerNetwork* network_ = nullptr;
+    ServiceRegistry*  services_ = nullptr;
+    /// Resolved in start(), cleared in stop(). Atomic because a dial failure can
+    /// land on a reactor thread the moment the node is up.
+    std::atomic<HolePunchService*> punch_{nullptr};
+    std::atomic<bool> running_{false};
+
+    struct PendingDial {
+        PeerId                                id;
+        std::chrono::steady_clock::time_point started;
+    };
+
+    std::mutex mutex_;
+    std::unordered_map<Address, std::chrono::steady_clock::time_point> recent_dials_;
+    std::unordered_map<Address, PendingDial>                           pending_dials_;
+};
+
+} // namespace librats

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

@@ -0,0 +1,98 @@
+#include "librats/subsystems/ping_service.h"
+#include "librats/node/node_context.h"
+
+#include <cstring>
+
+namespace librats {
+
+namespace {
+constexpr uint8_t kPing = 0;
+constexpr uint8_t kPong = 1;
+constexpr size_t  kProbeSize = 1 + 8;  // tag + 8-byte token
+
+uint64_t now_ticks() {
+    return static_cast<uint64_t>(
+        std::chrono::steady_clock::now().time_since_epoch().count());
+}
+} // namespace
+
+PingService::PingService(std::chrono::milliseconds interval) : interval_(interval) {}
+
+PingService::~PingService() { stop(); }
+
+void PingService::attach(NodeContext& ctx) {
+    network_ = &ctx.network;
+    network_->on(MessageType::Ping,
+                         [this](const Peer& peer, ByteView payload) { handle(peer, payload); });
+}
+
+void PingService::start() {
+    if (running_.exchange(true)) return;
+    thread_ = std::thread(&PingService::run, this);
+}
+
+void PingService::stop() {
+    if (!running_.exchange(false)) return;
+    wake_.notify_all();
+    if (thread_.joinable()) thread_.join();
+}
+
+void PingService::run() {
+    while (running_.load()) {
+        std::unique_lock<std::mutex> lock(wait_mutex_);
+        wake_.wait_for(lock, interval_, [this] { return !running_.load(); });
+        if (!running_.load()) break;
+        lock.unlock();
+        ping_all();
+    }
+}
+
+void PingService::ping_all() {
+    if (!network_) return;
+
+    uint8_t probe[kProbeSize];
+    probe[0] = kPing;
+    const uint64_t token = now_ticks();
+    std::memcpy(probe + 1, &token, 8);
+
+    for (const PeerId& id : network_->connected_peers())
+        network_->send(id, MessageType::Ping, ByteView(probe, kProbeSize));
+}
+
+void PingService::handle(const Peer& peer, ByteView payload) {
+    if (payload.size() != kProbeSize) return;
+    const uint8_t tag = payload.data()[0];
+
+    if (tag == kPing) {
+        // Echo the probe straight back as a pong.
+        uint8_t pong[kProbeSize];
+        pong[0] = kPong;
+        std::memcpy(pong + 1, payload.data() + 1, 8);
+        network_->send(peer.id(), MessageType::Ping, ByteView(pong, kProbeSize));
+        return;
+    }
+
+    if (tag == kPong) {
+        uint64_t token = 0;
+        std::memcpy(&token, payload.data() + 1, 8);
+        const uint64_t elapsed_ticks = now_ticks() - token;
+        const auto rtt = std::chrono::duration_cast<std::chrono::milliseconds>(
+            std::chrono::steady_clock::duration(static_cast<std::chrono::steady_clock::rep>(elapsed_ticks)));
+        std::lock_guard<std::mutex> lock(mutex_);
+        rtt_[peer.id()] = rtt;
+    }
+}
+
+std::optional<std::chrono::milliseconds> PingService::last_rtt(const PeerId& id) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    auto it = rtt_.find(id);
+    if (it == rtt_.end()) return std::nullopt;
+    return it->second;
+}
+
+size_t PingService::alive_peer_count() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return rtt_.size();
+}
+
+} // namespace librats

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

@@ -0,0 +1,66 @@
+#pragma once
+
+/**
+ * @file ping_service.h
+ * @brief Liveness + round-trip-time probing, built purely on PeerNetwork.
+ *
+ * The first real subsystem on the redesigned plugin model — and the template for
+ * porting the larger ones. It depends on NOTHING but the PeerNetwork contract:
+ * no Node, no reactor internals, no `friend`. Its own thread periodically pings
+ * every connected peer; a peer echoes the probe back, letting the sender measure
+ * RTT. Easily mocked by handing it a fake PeerNetwork in tests.
+ *
+ * Wire format (MessageType::Ping payload): [tag:u8][token:8 bytes].
+ *   tag 0 = ping, tag 1 = pong. The 8 token bytes are echoed back verbatim, so
+ *   the original sender decodes them in its own format (endianness irrelevant).
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/node/peer_network.h"
+#include "librats/peer/peer.h"
+#include "librats/peer/peer_id.h"
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <mutex>
+#include <optional>
+#include <thread>
+#include <unordered_map>
+
+namespace librats {
+
+class RATS_API PingService final : public Subsystem {
+public:
+    explicit PingService(std::chrono::milliseconds interval = std::chrono::seconds(10));
+    ~PingService() override;
+
+    void attach(NodeContext& ctx) override;
+    void start() override;
+    void stop() override;
+
+    /// Most recent measured round-trip time to a peer, if one has been seen.
+    std::optional<std::chrono::milliseconds> last_rtt(const PeerId& id) const;
+
+    /// Number of peers we have received at least one pong from.
+    size_t alive_peer_count() const;
+
+private:
+    void run();                                       ///< own thread: ping loop
+    void handle(const Peer& peer, ByteView payload);
+    void ping_all();
+
+    PeerNetwork*              network_ = nullptr;
+    std::chrono::milliseconds interval_;
+
+    std::thread             thread_;
+    std::atomic<bool>       running_{false};
+    std::mutex              wait_mutex_;
+    std::condition_variable wake_;
+
+    mutable std::mutex mutex_;
+    std::unordered_map<PeerId, std::chrono::milliseconds, PeerId::Hash> rtt_;
+};
+
+} // namespace librats