librats 1.0.2 → 2.2.0

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

@@ -0,0 +1,211 @@
+#include "librats/subsystems/bittorrent.h"
+#include "librats/subsystems/dht_service.h"
+#include "librats/node/node_context.h"
+#include "librats/util/logger.h"
+
+#include <chrono>
+#include <memory>
+#include <thread>
+#include <utility>
+
+namespace librats {
+
+Bittorrent::Bittorrent(Config config) : config_(std::move(config)) {}
+
+Bittorrent::Bittorrent(const bittorrent::Client::Config& client_config) {
+    config_.client = client_config;
+}
+
+Bittorrent::~Bittorrent() { stop(); }
+
+void Bittorrent::attach(NodeContext& ctx) {
+    // We only need the service registry — to discover a sibling DhtDiscovery at
+    // start(). BitTorrent runs its own transport, so it never touches ctx.network.
+    services_ = &ctx.services;
+}
+
+void Bittorrent::start() {
+    if (client_) return;  // already running
+    client_ = std::make_unique<bittorrent::Client>(config_.client);
+
+    // Borrow the node's DHT swarm if a DhtDiscovery published one and it is up.
+    // set_external_dht() must be called before start(); otherwise the client runs
+    // DHT-less (trackers/PEX/manual peers still work).
+    shared_dht_ = false;
+    if (config_.use_node_dht && services_) {
+        if (auto* svc = services_->get<DhtService>()) {
+            if (DhtClient* shared = svc->dht_client()) {
+                client_->set_external_dht(shared);
+                shared_dht_ = true;
+            }
+        }
+    }
+    LOG_INFO("bt.node", (shared_dht_ ? "sharing the node's DHT swarm"
+                                     : "running BitTorrent without a DHT"));
+
+    client_->start();
+}
+
+void Bittorrent::stop() {
+    if (!client_) return;
+
+    // Wake every in-flight metadata watcher and wait for them to finish before we
+    // tear down client_, so a watcher's reactor.post() can't race teardown.
+    {
+        std::unique_lock<std::mutex> lk(meta_mutex_);
+        meta_stopping_ = true;
+        meta_cv_.notify_all();
+        meta_drain_cv_.wait(lk, [&] { return meta_inflight_ == 0; });
+    }
+
+    client_->stop();   // never stops the borrowed external DHT (owner's lifecycle)
+    client_.reset();
+    shared_dht_ = false;
+
+    std::lock_guard<std::mutex> lk(meta_mutex_);
+    meta_stopping_ = false;  // ready for a future start()
+}
+
+DhtClient* Bittorrent::active_dht() const {
+    return client_ ? client_->get_dht_client() : nullptr;
+}
+
+//=============================================================================
+// Spider mode wrappers
+//=============================================================================
+
+void Bittorrent::set_spider_mode(bool enable) {
+    if (auto* d = active_dht()) d->set_spider_mode(enable);
+    else LOG_WARN("bt.node", "set_spider_mode ignored: no shared DHT");
+}
+
+bool Bittorrent::is_spider_mode() const {
+    auto* d = active_dht();
+    return d && d->is_spider_mode();
+}
+
+void Bittorrent::set_spider_announce_callback(SpiderAnnounceCallback callback) {
+    if (auto* d = active_dht()) d->set_spider_announce_callback(std::move(callback));
+    else LOG_WARN("bt.node", "set_spider_announce_callback ignored: no shared DHT");
+}
+
+void Bittorrent::set_spider_ignore(bool ignore) {
+    if (auto* d = active_dht()) d->set_spider_ignore(ignore);
+}
+
+bool Bittorrent::is_spider_ignoring() const {
+    auto* d = active_dht();
+    return d && d->is_spider_ignoring();
+}
+
+void Bittorrent::spider_walk() {
+    if (auto* d = active_dht()) d->spider_walk();
+}
+
+size_t Bittorrent::spider_pool_size() const {
+    auto* d = active_dht();
+    return d ? d->get_spider_pool_size() : 0;
+}
+
+size_t Bittorrent::spider_visited_count() const {
+    auto* d = active_dht();
+    return d ? d->get_spider_visited_count() : 0;
+}
+
+void Bittorrent::clear_spider_state() {
+    if (auto* d = active_dht()) d->clear_spider_state();
+}
+
+//=============================================================================
+// Metadata-only fetch (BEP 9)
+//=============================================================================
+
+void Bittorrent::get_torrent_metadata(const std::string& info_hash_hex,
+                                      MetadataCallback callback, int timeout_ms) {
+    fetch_metadata_impl(info_hash_hex, "", 0, /*direct=*/false, std::move(callback), timeout_ms);
+}
+
+void Bittorrent::get_torrent_metadata_from_peer(const std::string& info_hash_hex,
+                                                const std::string& ip, uint16_t port,
+                                                MetadataCallback callback, int timeout_ms) {
+    fetch_metadata_impl(info_hash_hex, ip, port, /*direct=*/true, std::move(callback), timeout_ms);
+}
+
+void Bittorrent::fetch_metadata_impl(const std::string& info_hash_hex, const std::string& ip,
+                                     uint16_t port, bool direct, MetadataCallback callback,
+                                     int timeout_ms) {
+    if (!client_) {
+        if (callback) callback(bittorrent::TorrentInfo{}, false, "bittorrent not running");
+        return;
+    }
+    auto ih = bittorrent::info_hash_from_hex(info_hash_hex);
+    if (!ih) {
+        if (callback) callback(bittorrent::TorrentInfo{}, false, "invalid info hash");
+        return;
+    }
+
+    // Completion state shared between the (reactor-thread) metadata callback and
+    // the watcher thread that waits on it.
+    struct State {
+        bool                    done = false;
+        bool                    success = false;
+        bittorrent::TorrentInfo info;
+    };
+    auto state = std::make_shared<State>();
+
+    {
+        std::lock_guard<std::mutex> lk(meta_mutex_);
+        if (meta_stopping_) {
+            if (callback) callback(bittorrent::TorrentInfo{}, false, "shutting down");
+            return;
+        }
+        ++meta_inflight_;
+    }
+
+    // All Client mutations happen on its reactor thread.
+    const std::string magnet = "magnet:?xt=urn:btih:" + info_hash_hex;
+    client_->reactor().post([this, magnet, ip, port, direct, state] {
+        bittorrent::Torrent* t = client_->add_magnet(magnet);
+        if (!t) {
+            std::lock_guard<std::mutex> lk(meta_mutex_);
+            state->done = true;
+            meta_cv_.notify_all();
+            return;
+        }
+        t->set_metadata_callback([this, state](const bittorrent::TorrentInfo& info) {
+            std::lock_guard<std::mutex> lk(meta_mutex_);
+            if (state->done) return;
+            state->info    = info;
+            state->success = true;
+            state->done    = true;
+            meta_cv_.notify_all();
+        });
+        if (direct && !ip.empty() && port != 0) t->add_peer(ip, port);
+    });
+
+    std::thread([this, ih = *ih, callback = std::move(callback), timeout_ms, state] {
+        bool                    success = false;
+        bittorrent::TorrentInfo info;
+        {
+            std::unique_lock<std::mutex> wl(meta_mutex_);
+            meta_cv_.wait_for(wl, std::chrono::milliseconds(timeout_ms),
+                              [&] { return state->done || meta_stopping_; });
+            state->done = true;  // block any late metadata callback
+            success = state->success;
+            info    = state->info;
+        }
+
+        // Drop the temporary torrent on the reactor thread. client_ is alive:
+        // stop() waits on meta_drain_cv_ until meta_inflight_ hits 0.
+        if (client_) client_->reactor().post([this, ih] { client_->remove_torrent(ih); });
+
+        if (callback)
+            callback(info, success, success ? std::string() : std::string("metadata timeout"));
+
+        std::lock_guard<std::mutex> dl(meta_mutex_);
+        --meta_inflight_;
+        meta_drain_cv_.notify_all();
+    }).detach();
+}
+
+} // namespace librats

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

@@ -0,0 +1,136 @@
+#pragma once
+
+/**
+ * @file bittorrent.h
+ * @brief BitTorrent as a node Subsystem — wraps bittorrent::Client and shares the node's DHT.
+ *
+ * Attach it like any other subsystem, BEFORE start():
+ *
+ *     auto* dht = node.add_subsystem(std::make_unique<DhtDiscovery>(dht_cfg));
+ *     auto* bt  = node.add_subsystem(std::make_unique<Bittorrent>(bt_cfg));
+ *     node.start();
+ *     bt->client()->add_magnet("magnet:?xt=urn:btih:…", "./downloads");
+ *
+ * BitTorrent keeps its own transport (bittorrent::Client runs its own reactor and
+ * the swarm protocol), so this subsystem does NOT touch the node's peer mesh. What
+ * it integrates is lifecycle and the DHT: when a DhtDiscovery is also attached, the
+ * client borrows that same Kademlia node (DhtService) instead of standing one up —
+ * one routing table, one swarm. Attach Bittorrent AFTER DhtDiscovery so the borrowed
+ * client is live at start() and (thanks to reverse-order teardown) still alive
+ * through stop(). Without a DhtDiscovery the client simply runs DHT-less (trackers,
+ * PEX and manually-added peers still work).
+ *
+ * Spider mode (the rats-search infohash crawler) lives in the DHT layer; the
+ * wrappers here delegate to whichever DHT the client ended up using.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/node/peer_network.h"          // Subsystem, NodeContext (fwd)
+#include "librats/bittorrent/client.h"          // bittorrent::Client, TorrentInfo, InfoHash
+#include "librats/dht/dht.h"                     // DhtClient, SpiderAnnounceCallback
+
+#include <condition_variable>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <string>
+
+namespace librats {
+
+class ServiceRegistry;
+
+class RATS_API Bittorrent final : public Subsystem {
+public:
+    struct Config {
+        bittorrent::Client::Config client;       ///< download path, listen port, …
+        bool                       use_node_dht = true;  ///< borrow DhtDiscovery's DHT if attached
+    };
+
+    Bittorrent() = default;
+    explicit Bittorrent(Config config);
+    /// Convenience: configure the underlying client directly, share the node DHT.
+    explicit Bittorrent(const bittorrent::Client::Config& client_config);
+    ~Bittorrent() override;
+
+    Bittorrent(const Bittorrent&) = delete;
+    Bittorrent& operator=(const Bittorrent&) = delete;
+
+    // — Subsystem —
+    void attach(NodeContext& ctx) override;
+    void start() override;
+    void stop() override;
+
+    /// The underlying client — drive torrents through it (add_magnet,
+    /// add_torrent_file, add_torrent_for_seeding, …). Non-null between start() and
+    /// stop(); nullptr otherwise.
+    bittorrent::Client*       client() noexcept { return client_.get(); }
+    const bittorrent::Client* client() const noexcept { return client_.get(); }
+
+    bool is_running()     const { return client_ && client_->is_running(); }
+    /// True when start() borrowed the node's DHT rather than running DHT-less.
+    bool using_node_dht() const noexcept { return shared_dht_; }
+
+    //=========================================================================
+    // Spider mode (rats-search) — DHT-wide infohash crawling.
+    // Delegates to the active DHT (the shared node DHT). No-op before start()
+    // or when no DHT is shared.
+    //
+    // Guarded to match dht.h, which declares SpiderAnnounceCallback behind the
+    // same macro: the whole subsystem needs RATS_SEARCH_FEATURES to link, but the
+    // header must still *parse* without it (IDE indexers, a consumer probing the
+    // installed tree) rather than fail on an undeclared type.
+    //=========================================================================
+#ifdef RATS_SEARCH_FEATURES
+    void   set_spider_mode(bool enable);
+    bool   is_spider_mode() const;
+    void   set_spider_announce_callback(SpiderAnnounceCallback callback);
+    void   set_spider_ignore(bool ignore);
+    bool   is_spider_ignoring() const;
+    void   spider_walk();
+    size_t spider_pool_size() const;
+    size_t spider_visited_count() const;
+    void   clear_spider_state();
+#endif
+
+    //=========================================================================
+    // Metadata-only fetch (BEP 9). Adds a temporary metadata-only magnet torrent,
+    // waits up to timeout_ms for its info dict to arrive, removes the temporary
+    // torrent, then invokes `callback` with the result (success=false on timeout).
+    // `callback` runs on an internal worker thread; it is invoked exactly once.
+    //=========================================================================
+    using MetadataCallback = std::function<void(const bittorrent::TorrentInfo& info, bool success,
+                                                const std::string& error)>;
+
+    /// Fetch metadata by searching the DHT/trackers for peers that have it.
+    void get_torrent_metadata(const std::string& info_hash_hex,
+                              MetadataCallback callback, int timeout_ms = 60000);
+
+    /// Fetch metadata directly from a known peer (the fast path used when a spider
+    /// announce told us exactly who has it).
+    void get_torrent_metadata_from_peer(const std::string& info_hash_hex,
+                                        const std::string& ip, uint16_t port,
+                                        MetadataCallback callback, int timeout_ms = 60000);
+
+private:
+    /// The DHT the client is actually using (the shared node DHT), or nullptr.
+    DhtClient* active_dht() const;
+
+    void fetch_metadata_impl(const std::string& info_hash_hex, const std::string& ip,
+                             uint16_t port, bool direct, MetadataCallback callback, int timeout_ms);
+
+    Config                              config_;
+    ServiceRegistry*                    services_ = nullptr;
+    std::unique_ptr<bittorrent::Client> client_;
+    bool                                shared_dht_ = false;
+
+    // In-flight metadata watchers; stop() drains them before tearing down client_.
+    std::mutex              meta_mutex_;
+    std::condition_variable meta_cv_;        ///< metadata arrived OR stopping
+    std::condition_variable meta_drain_cv_;  ///< a watcher finished
+    bool                    meta_stopping_ = false;
+    int                     meta_inflight_ = 0;
+};
+
+} // namespace librats

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

@@ -0,0 +1,202 @@
+#include "librats/subsystems/dht_discovery.h"
+#include "librats/node/node_context.h"
+#include "librats/node/host_events.h"
+#include "librats/nat/stun.h"
+#include "librats/crypto/sha1.h"
+#include "librats/util/fs.h"
+#include "librats/util/logger.h"
+
+namespace librats {
+
+namespace {
+int hex_val(char c) {
+    if (c >= '0' && c <= '9') return c - '0';
+    if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+    if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+    return 0;
+}
+
+// A couple of well-known public STUN servers, tried in order. Kept short so a
+// total-outage startup costs at most a few timeouts before we fall back to voting.
+std::vector<HostEndpoint> default_stun_servers() {
+    return { HostEndpoint("stun.l.google.com", 19302), HostEndpoint("stun1.l.google.com", 19302) };
+}
+
+// The configured bind literal only applies to its own family; the other family
+// binds the wildcard. An empty config means wildcard for both.
+std::string bind_for(const std::string& cfg, bool want_v6) {
+    if (cfg.empty()) return "";
+    const bool cfg_is_v6 = cfg.find(':') != std::string::npos;
+    return (cfg_is_v6 == want_v6) ? cfg : "";
+}
+} // namespace
+
+InfoHash DhtDiscovery::hash_for_key(const std::string& key) {
+    const std::string hex = SHA1::hash(key);  // 40 hex chars
+    InfoHash hash{};
+    for (size_t i = 0; i < hash.size() && (2 * i + 1) < hex.size(); ++i)
+        hash[i] = static_cast<uint8_t>((hex_val(hex[2 * i]) << 4) | hex_val(hex[2 * i + 1]));
+    return hash;
+}
+
+DhtDiscovery::DhtDiscovery(Config config)
+    : config_(std::move(config)) {}  // hash_ is resolved in attach() (may depend on the node protocol)
+
+DhtDiscovery::~DhtDiscovery() { stop(); }
+
+void DhtDiscovery::attach(NodeContext& ctx) {
+    network_ = &ctx.network;
+    // Namespace discovery by the node's protocol unless an explicit key overrides
+    // it: peers of the same app/version announce/search the same hash, and ones with
+    // a different protocol (which couldn't complete a handshake anyway) never meet in
+    // the DHT. A non-empty discovery_key opts into a custom, protocol-independent net.
+    const std::string& key = config_.discovery_key.empty() ? network_->protocol()
+                                                           : config_.discovery_key;
+    hash_ = hash_for_key(key);
+    // Publish the DHT as a borrowable capability so a sibling subsystem (e.g.
+    // Bittorrent) can share this Kademlia node instead of running a second one.
+    ctx.services.provide<DhtService>(this);
+    // A host network change means our public endpoint may have moved. Re-probe it
+    // via STUN and re-announce so the DHT advertises our current reachable address
+    // rather than the previous network's. We only flag + wake here (cheap, on the
+    // node's maintenance thread); the actual STUN runs on our own loop thread.
+    ctx.events.on<NetworkChanged>([this](const NetworkChanged&) {
+        recover_pending_.store(true);
+        wake_.notify_all();
+    });
+}
+
+std::unique_ptr<DhtClient> DhtDiscovery::make_client(AddressFamily family) {
+    const bool v6 = (family == AddressFamily::IPv6);
+    const char* label = v6 ? "IPv6" : "IPv4";
+
+    auto client = std::make_unique<DhtClient>(config_.dht_port, bind_for(config_.bind_address, v6),
+                                              config_.data_dir, family);
+    if (!client->start()) {
+        LOG_WARN("dht-discovery", label << " DHT client failed to start (skipping this family)");
+        return nullptr;
+    }
+
+    const std::vector<HostEndpoint> nodes =
+        config_.bootstrap_nodes.empty() ? DhtClient::get_default_bootstrap_nodes() : config_.bootstrap_nodes;
+    if (!nodes.empty()) client->bootstrap(nodes);
+
+    LOG_INFO("dht-discovery", label << " DHT on UDP port " << client->get_port());
+    return client;
+}
+
+void DhtDiscovery::start() {
+    if (running_.exchange(true)) return;
+
+    // Make sure the routing-table directory exists before the clients try to use it.
+    if (!config_.data_dir.empty()) create_directories(config_.data_dir.c_str());
+
+    if (config_.enable_ipv4) dht_  = make_client(AddressFamily::IPv4);
+    if (config_.enable_ipv6) dht6_ = make_client(AddressFamily::IPv6);
+
+    if (!dht_ && !dht6_) {
+        LOG_ERROR("dht-discovery", "Failed to start DHT client on any address family");
+        running_.store(false);
+        return;
+    }
+
+    thread_ = std::thread(&DhtDiscovery::loop, this);
+    LOG_INFO("dht-discovery", "Started (" << (dht_ ? "IPv4" : "") << (dht_ && dht6_ ? "+" : "")
+             << (dht6_ ? "IPv6" : "") << "), hash key '" << config_.discovery_key << "'");
+}
+
+void DhtDiscovery::stop() {
+    if (!running_.exchange(false)) return;
+    wake_.notify_all();
+    if (thread_.joinable()) thread_.join();
+    if (dht_)  { dht_->stop();  dht_.reset(); }
+    if (dht6_) { dht6_->stop(); dht6_.reset(); }
+}
+
+bool DhtDiscovery::is_running() const {
+    return running_.load() && ((dht_ && dht_->is_running()) || (dht6_ && dht6_->is_running()));
+}
+
+uint16_t DhtDiscovery::dht_port() const { return dht_ ? static_cast<uint16_t>(dht_->get_port()) : 0; }
+
+uint16_t DhtDiscovery::dht_port_v6() const { return dht6_ ? static_cast<uint16_t>(dht6_->get_port()) : 0; }
+
+std::string DhtDiscovery::external_address() const {
+    // The IPv4 reflexive address is the public-facing one most callers expect;
+    // fall back to the IPv6 client's view if only that family is up.
+    if (dht_) {
+        std::string a = dht_->get_external_address();
+        if (!a.empty()) return a;
+    }
+    return dht6_ ? dht6_->get_external_address() : "";
+}
+
+// Discover our reflexive (public) address via STUN and feed it to the DHT so the
+// node id is BEP-42-correct from the start instead of waiting for "ip" voting.
+// Runs on the loop thread; stop() joins that thread before resetting dht_, so the
+// dht_ access here can never touch a freed client.
+void DhtDiscovery::probe_external_ip() {
+    std::vector<HostEndpoint> servers = config_.stun_servers.empty() ? default_stun_servers()
+                                                                      : config_.stun_servers;
+    StunClient stun;
+    const int timeout = static_cast<int>(config_.stun_timeout.count());
+    for (const HostEndpoint& s : servers) {
+        if (!running_.load()) return;  // stopping; don't keep probing
+        StunResult r = stun.binding_request(s.host, s.port, timeout);
+        if (r.success && r.mapped_address) {
+            const std::string& ip = r.mapped_address->address;
+            LOG_INFO("dht-discovery", "STUN reflexive address " << ip << " (via " << s.host << ":" << s.port << ")");
+            // Feed it to whichever clients are up; each ignores it if it's not a
+            // public address of its own family (e.g. a v4 reflexive on the v6 client).
+            if (running_.load()) for_each_client([&](DhtClient& c) { c.set_external_ip(ip); });
+            return;
+        }
+    }
+    LOG_DEBUG("dht-discovery", "STUN external-IP discovery failed; relying on DHT ip voting");
+}
+
+void DhtDiscovery::loop() {
+    if (config_.discover_external_ip) probe_external_ip();
+
+    auto last_announce = std::chrono::steady_clock::now() - config_.announce_interval;
+    while (running_.load()) {
+        // Network changed: re-learn our public IP and force an immediate re-announce.
+        if (recover_pending_.exchange(false)) {
+            LOG_INFO("dht-discovery", "Network changed — re-probing STUN and re-announcing");
+            if (config_.discover_external_ip) probe_external_ip();
+            last_announce = std::chrono::steady_clock::now() - config_.announce_interval;
+        }
+
+        const auto now = std::chrono::steady_clock::now();
+        auto deliver = [this](const std::vector<Address>& peers, const InfoHash& h) { on_peers(peers, h); };
+        if (now - last_announce >= config_.announce_interval) {
+            // announce_peer runs a get_peers traversal and announces on completion, so it
+            // discovers peers itself — feed them to on_peers and skip the separate
+            // find_peers this cycle, otherwise we'd run two identical traversals per hash
+            // (every node queried twice). find_peers covers the faster search cadence in
+            // between announces.
+            for_each_client([&](DhtClient& c) { c.announce_peer(hash_, network_->listen_port(), deliver); });
+            last_announce = now;
+        } else {
+            for_each_client([&](DhtClient& c) { c.find_peers(hash_, deliver); });
+        }
+
+        std::unique_lock<std::mutex> lock(wait_mutex_);
+        wake_.wait_for(lock, config_.search_interval,
+                       [this] { return !running_.load() || recover_pending_.load(); });
+    }
+}
+
+void DhtDiscovery::on_peers(const std::vector<Address>& peers, const InfoHash& /*info_hash*/) {
+    for (const Address& peer : peers) {
+        if (peer.ip.is_any() || peer.port == 0) continue;
+        {
+            std::lock_guard<std::mutex> lock(dialed_mutex_);
+            if (!dialed_.insert(peer).second) continue;  // already dialed this address
+        }
+        LOG_DEBUG("dht-discovery", "Dialing discovered peer " << peer.to_string());
+        network_->connect(peer);
+    }
+}
+
+} // namespace librats

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

@@ -0,0 +1,123 @@
+#pragma once
+
+/**
+ * @file dht_discovery.h
+ * @brief Peer discovery via the Kademlia DHT — a thin adapter, not a rewrite.
+ *
+ * Wraps the existing, well-tested DhtClient (src/dht.h) as a Subsystem WITHOUT
+ * modifying it. On start it brings up DhtClients (their own UDP sockets + threads),
+ * then periodically announces our TCP listen port under a discovery hash and
+ * searches that hash, dialing any peers it finds through the node. The discovery
+ * hash namespaces peers of the same application (same key → same hash).
+ *
+ * Dual-stack: IPv4 and IPv6 are separate Kademlia networks (BEP 32), so each runs
+ * its own DhtClient. Both announce/search the same hash and feed discovered peers
+ * to the same dial path, so a peer reachable over either family is found. Startup
+ * is best-effort per family: if one family can't bind (e.g. a host with no usable
+ * IPv6) the subsystem still runs on the other.
+ *
+ * Everything DHT-specific stays in DhtClient; this class only bridges its
+ * callbacks to PeerNetwork::connect().
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/node/peer_network.h"
+#include "librats/subsystems/dht_service.h"
+#include "librats/dht/dht.h"
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <unordered_set>
+#include <vector>
+
+namespace librats {
+
+class RATS_API DhtDiscovery final : public Subsystem, public DhtService {
+public:
+    struct Config {
+        uint16_t                  dht_port = 0;          ///< 0 = ephemeral
+        std::string               bind_address = "";
+        std::string               data_dir = "";         ///< routing-table persistence dir (empty = cwd). Set to the node's data_dir to co-locate state.
+        bool                      enable_ipv4 = true;    ///< run the IPv4 Kademlia network
+        bool                      enable_ipv6 = true;    ///< run the IPv6 Kademlia network (BEP 32)
+        std::string               discovery_key = "";  ///< DHT namespace. Empty → the node's `protocol` (resolved at attach), so peers of the same app/version discover each other and mismatched protocols (which can't handshake anyway) don't even meet. Set non-empty to override with a custom discovery network.
+        std::vector<HostEndpoint>    bootstrap_nodes;       ///< empty → default internet nodes
+        std::chrono::milliseconds search_interval{30000}; /// every 30 seconds
+        /// Re-announce cadence. Kept at ~⅓ of the peer TTL (librats stores announced peers
+        /// for 30 min, libtorrent ~45 min) so we stay findable with a comfortable margin
+        /// even if an announce or two is lost — libtorrent's own default is 15 min. A fresh
+        /// node still announces immediately at startup regardless of this value (see loop()).
+        std::chrono::milliseconds announce_interval{600000};  // 10 min
+
+        /// Probe a STUN server once at startup to learn our public IP and seed the
+        /// DHT node id per BEP 42. Without it we still converge via the slower
+        /// in-DHT "ip" voting, but bootstrap under the wrong node id until then.
+        bool                      discover_external_ip = true;
+        std::vector<HostEndpoint> stun_servers;          ///< empty → built-in public defaults
+        std::chrono::milliseconds stun_timeout{3000};
+    };
+
+    explicit DhtDiscovery(Config config);
+    ~DhtDiscovery() override;
+
+    void attach(NodeContext& ctx) override;
+    void start() override;
+    void stop() override;
+
+    bool     is_running() const;
+
+    /// DhtService: hand out the live Kademlia node so siblings (e.g. Bittorrent)
+    /// can share this swarm. IPv4 preferred, IPv6 fallback; nullptr before start()
+    /// / after stop(). Borrow it during start() and drop it in stop() (see DhtService).
+    DhtClient* dht_client() override { return dht_ ? dht_.get() : dht6_.get(); }
+
+    uint16_t dht_port() const;       ///< IPv4 DHT UDP port (0 if not running)
+    uint16_t dht_port_v6() const;    ///< IPv6 DHT UDP port (0 if not running)
+    InfoHash discovery_hash() const { return hash_; }
+
+    /// Our external (public) IP currently used to derive the DHT node id, learned
+    /// via STUN at startup or in-DHT "ip" voting. "" if not yet known / random.
+    std::string external_address() const;
+
+    /// Map an application key to a stable 20-byte discovery hash (SHA-1).
+    static InfoHash hash_for_key(const std::string& key);
+
+private:
+    void loop();
+    void probe_external_ip();  ///< STUN → set_external_ip on each client (runs on the loop thread)
+    void on_peers(const std::vector<Address>& peers, const InfoHash& info_hash);
+
+    /// Bring up one family's DhtClient (bind + bootstrap). Returns nullptr if it
+    /// could not bind/start, so the caller can run on whatever family did come up.
+    std::unique_ptr<DhtClient> make_client(AddressFamily family);
+
+    /// Run `fn` on each live client (IPv4 then IPv6). Loop-thread side.
+    template <typename Fn>
+    void for_each_client(Fn fn) {
+        if (dht_)  fn(*dht_);
+        if (dht6_) fn(*dht6_);
+    }
+
+    Config                     config_;
+    InfoHash                   hash_;
+    PeerNetwork*               network_ = nullptr;
+    std::unique_ptr<DhtClient> dht_;    ///< IPv4 Kademlia network
+    std::unique_ptr<DhtClient> dht6_;   ///< IPv6 Kademlia network (BEP 32)
+
+    std::thread             thread_;
+    std::atomic<bool>       running_{false};
+    std::atomic<bool>       recover_pending_{false};  ///< network changed: re-STUN + re-announce
+    std::mutex              wait_mutex_;
+    std::condition_variable wake_;
+
+    std::mutex                      dialed_mutex_;
+    std::unordered_set<Address> dialed_;  ///< peers we've already dialed
+};
+
+} // namespace librats