librats 1.0.2 → 2.2.0

package/native-src/src/librats/dht/node_entry.h

@@ -0,0 +1,81 @@
+#pragma once
+
+/**
+ * @file node_entry.h
+ * @brief A single contact in the routing table: who it is, where to reach it, and
+ *        the liveness/quality bookkeeping that decides who to keep or evict.
+ *
+ * Quality model (mirrors libtorrent's node_entry):
+ *   - rtt        — smoothed round-trip time; kRttUnknown until the first reply.
+ *   - fail_count — consecutive failed queries; kNeverPinged means we've only ever
+ *                  *heard about* this node (from someone else's reply) and never had
+ *                  a reply from it ourselves.
+ *   - verified   — its id is derived from its IP per BEP 42, so it's harder to spoof
+ *                  and is preferred when we have to choose who to drop.
+ */
+
+#include "librats/core/address.h"
+#include "librats/dht/id.h"
+
+#include <chrono>
+#include <cstdint>
+#include <utility>
+
+namespace librats {
+namespace dht {
+
+struct NodeEntry {
+    static constexpr uint16_t kRttUnknown  = 0xffff;  // no RTT sample yet
+    static constexpr uint8_t  kNeverPinged = 0xff;    // only heard about, never replied
+
+    NodeId   id{};
+    Address  endpoint;
+    // Last time we "touched" this contact: a reply received OR a probe issued to it.
+    // Defaults to the clock minimum so a never-contacted contact sorts as most stale
+    // (refreshed first). Read only by RoutingTable::next_to_refresh for its ordering.
+    std::chrono::steady_clock::time_point last_seen{(std::chrono::steady_clock::time_point::min)()};
+    uint16_t rtt        = kRttUnknown;
+    uint8_t  fail_count = kNeverPinged;
+    bool     verified   = false;
+
+    NodeEntry() = default;
+    NodeEntry(const NodeId& id, Address endpoint)
+        : id(id), endpoint(std::move(endpoint)) {}
+
+    // Have we ever had a reply from this node (vs only heard it mentioned)?
+    bool pinged() const noexcept { return fail_count != kNeverPinged; }
+    // Replied with no outstanding failures — safe to hand out and keep.
+    bool confirmed() const noexcept { return fail_count == 0; }
+
+    // A reply arrived: clear failures, refresh last_seen, fold in the RTT sample.
+    void record_success(uint16_t rtt_sample = kRttUnknown) noexcept {
+        fail_count = 0;
+        last_seen  = std::chrono::steady_clock::now();
+        update_rtt(rtt_sample);
+    }
+
+    // A query to this node timed out. Only meaningful once pinged; saturates just
+    // below kNeverPinged so a long-dead node never wraps back to "never pinged".
+    void record_failure() noexcept {
+        if (pinged() && fail_count < kNeverPinged - 1) ++fail_count;
+    }
+
+    // Exponential moving average (2/3 old + 1/3 new), seeded by the first sample.
+    void update_rtt(uint16_t sample) noexcept {
+        if (sample == kRttUnknown) return;
+        rtt = (rtt == kRttUnknown)
+                  ? sample
+                  : static_cast<uint16_t>(rtt * 2 / 3 + sample / 3);
+    }
+
+    // Eviction ordering: true if *this is the worse contact and should go first.
+    // Worse = more failures, then unverified before verified, then higher RTT.
+    bool is_worse_than(const NodeEntry& other) const noexcept {
+        if (fail_count != other.fail_count) return fail_count > other.fail_count;
+        if (verified   != other.verified)   return !verified;  // unverified is worse
+        return rtt > other.rtt;
+    }
+};
+
+} // namespace dht
+} // namespace librats

package/native-src/src/librats/dht/observer.h

@@ -0,0 +1,72 @@
+#pragma once
+
+/**
+ * @file observer.h
+ * @brief One outstanding query to a single node.
+ *
+ * An Observer is both the RPC callback the RpcManager invokes when a reply or
+ * timeout arrives, and the little bag of per-node state (id, endpoint, flags) the
+ * issuer tracks. It is owned via shared_ptr by whoever started the query (a
+ * Traversal); the RpcManager holds a shared_ptr only while the query is in flight,
+ * and takes a local copy across each callback so an observer can't be freed in the
+ * middle of handling its own reply (e.g. if the traversal truncates it meanwhile).
+ *
+ * Observers reference their Traversal by plain reference, never owning it, so there
+ * is no ownership cycle to untangle.
+ */
+
+#include "librats/core/address.h"
+#include "librats/dht/id.h"
+
+#include <chrono>
+#include <cstdint>
+#include <memory>
+
+namespace librats {
+struct KrpcMessage;  // defined in dht/krpc.h; only referenced by const& here
+
+namespace dht {
+
+using TimePoint = std::chrono::steady_clock::time_point;
+
+class Observer {
+public:
+    enum Flag : uint8_t {
+        kQueried      = 1 << 0,  // a query was sent
+        kAlive        = 1 << 1,  // a reply was received
+        kFailed       = 1 << 2,  // fully timed out / errored
+        kShortTimeout = 1 << 3,  // exceeded the short timeout (slot freed, still waiting)
+        kInitial      = 1 << 4,  // a seed/router node (id may be unknown until it replies)
+        kDone         = 1 << 5,  // abandoned by the traversal; ignore any late reply
+    };
+
+    Observer(const NodeId& id, const Address& endpoint) : id_(id), endpoint_(endpoint) {}
+    virtual ~Observer() = default;
+    Observer(const Observer&) = delete;
+    Observer& operator=(const Observer&) = delete;
+
+    const NodeId&  id() const noexcept { return id_; }
+    const Address& endpoint() const noexcept { return endpoint_; }
+
+    bool has(Flag f) const noexcept { return (flags_ & f) != 0; }
+    void set(Flag f) noexcept { flags_ = static_cast<uint8_t>(flags_ | f); }
+
+    // Invoked by the RpcManager exactly once, when the query resolves.
+    virtual void on_response(const KrpcMessage& msg, uint16_t rtt_ms, TimePoint now) = 0;
+    virtual void on_timeout(TimePoint now) = 0;
+    virtual void on_short_timeout(TimePoint now) = 0;
+
+protected:
+    NodeId  id_;
+    Address endpoint_;
+    uint8_t flags_ = 0;
+
+private:
+    friend class RpcManager;
+    uint16_t txn_ = 0;  // transaction id, owned by the RpcManager while in flight
+};
+
+using ObserverPtr = std::shared_ptr<Observer>;
+
+} // namespace dht
+} // namespace librats

package/native-src/src/librats/dht/persistence.cpp

@@ -0,0 +1,90 @@
+#include "librats/dht/persistence.h"
+#include "librats/dht/log.h"
+#include "librats/util/json.h"
+
+#include <fstream>
+#include <iterator>
+
+namespace librats {
+namespace dht {
+
+bool save_routing_table(const std::string& path, const NodeId& self,
+                        const std::vector<NodeEntry>& contacts) {
+    Json root;
+    root["version"] = 1;
+    root["node_id"] = to_hex(self);
+
+    Json nodes = Json::array();
+    for (const auto& n : contacts) {
+        if (!n.confirmed()) continue;  // only persist good contacts
+        Json e;
+        e["id"] = to_hex(n.id);
+        e["ip"] = n.endpoint.ip.to_string();
+        e["port"] = static_cast<int>(n.endpoint.port);
+        if (n.rtt != NodeEntry::kRttUnknown) e["rtt"] = static_cast<int>(n.rtt);
+        nodes.push_back(e);
+    }
+    root["nodes"] = nodes;
+
+    std::ofstream file(path);
+    if (!file.is_open()) {
+        // The headline "saved N contact(s)" lives in the facade; here we surface the
+        // failure it can't see — a silent write failure means losing the warm set on restart.
+        LOG_WARN("dht", "could not open routing table for writing: " << path);
+        return false;
+    }
+    file << root.dump(2);
+    if (!file.good()) {
+        LOG_WARN("dht", "failed writing routing table to " << path);
+        return false;
+    }
+    return true;
+}
+
+bool load_routing_table(const std::string& path, NodeId& self,
+                        std::vector<NodeEntry>& contacts) {
+    std::ifstream file(path);
+    if (!file.is_open()) return false;
+    const std::string text((std::istreambuf_iterator<char>(file)), std::istreambuf_iterator<char>());
+
+    try {
+        Json root = Json::parse(text);
+        if (!root.contains("version") || !root.contains("nodes")) {
+            LOG_WARN("dht", "routing table at " << path << " missing required fields, ignoring");
+            return false;
+        }
+
+        NodeId loaded_self = self;
+        if (root.contains("node_id")) loaded_self = from_hex(root["node_id"].get<std::string>());
+
+        std::vector<NodeEntry> loaded;
+        std::size_t skipped = 0;
+        for (const auto& e : root["nodes"]) {
+            if (!e.contains("id") || !e.contains("ip") || !e.contains("port")) { ++skipped; continue; }
+            const auto ip = IpAddress::parse(e["ip"].get<std::string>());
+            if (!ip) { ++skipped; continue; }
+            NodeEntry n(from_hex(e["id"].get<std::string>()),
+                        Address(*ip, static_cast<uint16_t>(e["port"].get<int>())));
+            const uint16_t rtt = e.contains("rtt")
+                                     ? static_cast<uint16_t>(e["rtt"].get<int>())
+                                     : NodeEntry::kRttUnknown;
+            n.record_success(rtt);  // a saved contact starts life confirmed
+            loaded.push_back(n);
+        }
+
+        self = loaded_self;
+        contacts = std::move(loaded);
+        // The loaded count is the facade's INFO line; only the malformed-entry detail is
+        // new here, so stay silent unless some entries were actually dropped.
+        if (skipped)
+            LOG_DEBUG("dht", "loaded routing table from " << path << ": " << contacts.size()
+                             << " contact(s), " << skipped << " malformed entr(ies) skipped");
+        return true;
+    } catch (const std::exception& ex) {
+        LOG_WARN("dht", "malformed routing table at " << path << " (" << ex.what() << "), ignoring");
+        return false;
+    }
+}
+
+} // namespace dht
+} // namespace librats

package/native-src/src/librats/dht/persistence.h

@@ -0,0 +1,32 @@
+#pragma once
+
+/**
+ * @file persistence.h
+ * @brief Save/restore the routing table across restarts as JSON.
+ *
+ * Persists our node id (so our identity is stable) plus the confirmed contacts (a
+ * warm set to bootstrap from). The JSON schema is unchanged from earlier releases, so
+ * previously saved tables still load (the file is named dht_routing[_v6].json under the
+ * data dir; the name is port-independent so an ephemeral node restores on restart).
+ */
+
+#include "librats/dht/id.h"
+#include "librats/dht/node_entry.h"
+
+#include <string>
+#include <vector>
+
+namespace librats {
+namespace dht {
+
+// Writes `self` + the given (confirmed) contacts to `path`. Returns false on I/O error.
+bool save_routing_table(const std::string& path, const NodeId& self,
+                        const std::vector<NodeEntry>& contacts);
+
+// Reads `path` into `self` and `contacts` (restored as confirmed). Returns false if
+// the file is missing or malformed; outputs are only written on success.
+bool load_routing_table(const std::string& path, NodeId& self,
+                        std::vector<NodeEntry>& contacts);
+
+} // namespace dht
+} // namespace librats