librats 1.0.2 → 2.2.0

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

@@ -0,0 +1,413 @@
+#include "librats/bittorrent/client.h"
+#include "librats/bittorrent/log.h"
+
+#include <algorithm>
+#include <chrono>
+#include <mutex>
+#include <utility>
+
+namespace librats::bittorrent {
+
+Client::Client() : Client(Config{}) {}
+
+Client::Client(Config config)
+    : config_(std::move(config))
+    , peer_id_(generate_peer_id(config_.peer_id_prefix)) {}
+
+Client::~Client() {
+    stop();
+}
+
+void Client::open() {
+    if (opened_) return;
+    opened_ = true;
+    open_listener();
+    schedule_reap();
+}
+
+void Client::start() {
+    open();
+    reactor_.start();
+}
+
+void Client::stop() {
+    if (!opened_) return;
+    // Disarm the DHT callbacks BEFORE the reactor goes away: the shared DHT keeps
+    // running after us (node teardown is reverse-attach order) and a get_peers reply
+    // for a torrent we are about to drop would otherwise post to a destroyed reactor.
+    {
+        std::lock_guard<std::mutex> lock(dht_guard_->mutex);
+        dht_guard_->alive = false;
+    }
+    reactor_.stop();  // join the loop thread first so nothing touches state concurrently
+    opened_ = false;
+    if (reap_timer_ != kInvalidTimerId) { reactor_.cancel(reap_timer_); reap_timer_ = kInvalidTimerId; }
+    for (auto& [hash, t] : torrents_) {
+        // Drop the traversal too: nothing consumes its result any more, and it would
+        // keep hammering the DHT for a torrent that no longer exists.
+        if (dht_) dht_->cancel_search(hash);
+        t->stop();
+    }
+    torrents_.clear();
+    connections_.clear();
+    // Reclaim any outbound sockets still mid-connect (their completion lambda will
+    // never run now that the reactor is stopped).
+    for (socket_t s : pending_connects_) { reactor_.remove(s); close_socket(s); }
+    pending_connects_.clear();
+    if (is_valid_socket(listener_)) { reactor_.remove(listener_); close_socket(listener_); listener_ = RATS_INVALID_SOCKET; }
+    // Fresh token, so a Client that is start()ed again gets DHT peers delivered.
+    // Safe to swap unsynchronised: the reactor thread is joined and the old token is
+    // kept alive by whatever callbacks still hold it.
+    dht_guard_ = std::make_shared<DhtCallbackGuard>();
+}
+
+void Client::open_listener() {
+    listener_ = create_tcp_server(config_.listen_port, 16, "", AddressFamily::IPv4);
+    if (!is_valid_socket(listener_)) {
+        LOG_ERROR("bt.client", "failed to bind listen port " << config_.listen_port
+                               << " — inbound peers disabled");
+        return;
+    }
+    set_socket_nonblocking(listener_);
+    actual_port_ = std::uint16_t(get_bound_port(listener_));
+    reactor_.add(listener_, PollIn, [this](std::uint32_t) { on_accept(); });
+    LOG_INFO("bt.client", "listening on port " << actual_port_);
+}
+
+void Client::on_accept() {
+    for (;;) {
+        // Raw accept so a non-blocking EWOULDBLOCK drain is quiet (accept_client
+        // logs it as an error). nullptr addr: we read the peer address elsewhere.
+        socket_t s = ::accept(listener_, nullptr, nullptr);
+        if (!is_valid_socket(s)) break;  // drained (non-blocking listener)
+        suppress_sigpipe(s);  // not inherited from the listener; raw accept()
+        // Cap total connections so an inbound flood can't exhaust memory / fds (H3).
+        // Keep draining the accept queue, but immediately drop anything over the cap.
+        if (connections_.size() >= kMaxConnections) {
+            LOG_DEBUG("bt.client", "connection cap " << kMaxConnections << " reached, dropping inbound");
+            close_socket(s);
+            continue;
+        }
+        set_socket_nonblocking(s);
+
+        // Remote source endpoint (for logging / PEX). The peer's *listen* port is
+        // learned later from its extended handshake; this is the ephemeral source.
+        std::string ip;
+        std::uint16_t port = 0;
+        if (const std::string ep = get_peer_address(s); !ep.empty()) {
+            const std::size_t colon = ep.rfind(':');
+            if (colon != std::string::npos) {
+                ip   = ep.substr(0, colon);
+                port = std::uint16_t(std::atoi(ep.c_str() + colon + 1));
+            }
+        }
+
+        auto resolver = [this](const InfoHash& ih, PeerConnection::Binding& out) -> bool {
+            auto it = torrents_.find(ih);
+            if (it == torrents_.end() || !it->second) return false;
+            out.observer   = it->second.get();
+            out.num_pieces = it->second->num_pieces();
+            return true;
+        };
+        auto pc = std::make_unique<PeerConnection>(reactor_, s, peer_id_, std::move(resolver),
+                                                   std::move(ip), port);
+        LOG_DEBUG("bt.client", "inbound connection from " << ip << ':' << port);
+        PeerConnection* raw = pc.get();
+        connections_.push_back(std::move(pc));
+        raw->start();
+    }
+}
+
+void Client::connect_peer(Torrent& torrent, const std::string& ip, std::uint16_t port) {
+    if (connections_.size() >= kMaxConnections) { torrent.on_connect_failed(ip, port); return; }
+    socket_t s = tcp_connect_start(ip, int(port));
+    if (!is_valid_socket(s)) { torrent.on_connect_failed(ip, port); return; }
+
+    // Capture the info-hash, not a raw Torrent*: the torrent may be removed before
+    // the connect completes, so we re-resolve it (and bail if it's gone) rather
+    // than dereference a dangling pointer (H10). The socket is tracked so a
+    // mid-connect stop() can reclaim it.
+    const InfoHash ih = torrent.info_hash();
+    pending_connects_.insert(s);
+    reactor_.add(s, PollOut, [this, ih, s, ip, port](std::uint32_t) {
+        reactor_.remove(s);  // done watching for connect completion
+        pending_connects_.erase(s);
+        auto it = torrents_.find(ih);
+        Torrent* t = (it != torrents_.end()) ? it->second.get() : nullptr;
+        if (tcp_connect_result(s) != 0 || !t) {
+            close_socket(s);
+            if (t) t->on_connect_failed(ip, port);
+            return;
+        }
+        auto pc = std::make_unique<PeerConnection>(reactor_, s, /*outgoing=*/true,
+                                                   t->info_hash(), peer_id_, t->num_pieces(), t,
+                                                   ip, port);
+        PeerConnection* raw = pc.get();
+        connections_.push_back(std::move(pc));
+        raw->start();
+    });
+}
+
+void Client::find_peers_via_dht(const InfoHash& info_hash,
+                                std::function<void(const std::string&, std::uint16_t)> on_peer) {
+    if (!dht_ || !dht_->is_running()) return;
+    // DhtClient delivers results on its own thread; marshal them onto the reactor.
+    // Re-resolve the torrent by info-hash before invoking on_peer: the torrent may
+    // have been removed between the get_peers request and its (seconds-later) reply,
+    // and on_peer captures the Torrent by pointer — dereferencing it after removal is
+    // a use-after-free of peer_list_ (same H10 hazard fixed in connect_peer). Removal
+    // happens only on the reactor thread, so a torrent present here stays alive for
+    // the whole callback.
+    // The guard covers the *other* half of that hazard: the whole Client may be gone
+    // by the time the reply lands, since the shared DHT is torn down after us. Held
+    // for the post() only — the work itself still runs on the reactor.
+    dht_->find_peers(info_hash, [this, guard = dht_guard_, info_hash, on_peer](const std::vector<Address>& peers,
+                                                                              const InfoHash&) {
+        std::lock_guard<std::mutex> lock(guard->mutex);
+        if (!guard->alive) return;  // Client stopped/destroyed — its reactor is gone
+        reactor_.post([this, info_hash, peers, on_peer] {
+            if (torrents_.find(info_hash) == torrents_.end()) return;  // torrent gone
+            for (const Address& a : peers) on_peer(a.ip.to_string(), a.port);
+        });
+    });
+}
+
+void Client::announce_to_dht(const InfoHash& info_hash, std::uint16_t port) {
+    // Publish ourselves to the info-hash's DHT nodes so other clients' get_peers
+    // find us (BEP 5). DhtClient is the node's shared, thread-safe instance.
+    if (dht_ && dht_->is_running()) dht_->announce_peer(info_hash, port);
+}
+
+Torrent* Client::add_torrent(const TorrentInfo& info, const std::string& save_path) {
+    return run_on_reactor([&] { return add_torrent_impl(info, save_path); });
+}
+
+Torrent* Client::add_torrent_impl(const TorrentInfo& info, const std::string& save_path) {
+    if (!info.is_valid() || !info.has_metadata()) {
+        LOG_WARN("bt.client", "rejected invalid/incomplete torrent");
+        return nullptr;
+    }
+    const InfoHash ih = info.info_hash();
+    if (torrents_.count(ih)) return torrents_[ih].get();
+
+    const std::string path = save_path.empty() ? config_.download_path : save_path;
+    auto t = std::make_unique<Torrent>(reactor_, *this, info, path);
+    Torrent* raw = t.get();
+    torrents_.emplace(ih, std::move(t));
+    LOG_INFO("bt.client", "added torrent " << short_hash(ih) << " \"" << info.name() << "\" → " << path);
+    raw->start();
+    return raw;
+}
+
+Torrent* Client::add_magnet(const std::string& magnet_uri, const std::string& save_path) {
+    return run_on_reactor([&] { return add_magnet_impl(magnet_uri, save_path, /*resume=*/false); });
+}
+
+Torrent* Client::add_magnet_resumed(const std::string& magnet_uri, const std::string& save_path) {
+    return run_on_reactor([&] { return add_magnet_impl(magnet_uri, save_path, /*resume=*/true); });
+}
+
+Torrent* Client::add_magnet_impl(const std::string& magnet_uri, const std::string& save_path, bool resume) {
+    auto info = TorrentInfo::from_magnet(magnet_uri);
+    if (!info || !info->is_valid()) {
+        LOG_WARN("bt.client", "rejected invalid magnet uri");
+        return nullptr;
+    }
+    const InfoHash ih = info->info_hash();
+    if (torrents_.count(ih)) return torrents_[ih].get();
+
+    const std::string path = save_path.empty() ? config_.download_path : save_path;
+    auto t = std::make_unique<Torrent>(reactor_, *this, *info, path);
+    Torrent* raw = t.get();
+    torrents_.emplace(ih, std::move(t));
+    // Resume must be applied before start(); it completes the metadata + trusted have
+    // set if a resume file exists next to the download.
+    if (resume && raw->try_load_resume_data())
+        LOG_INFO("bt.client", "restored resume data for " << short_hash(ih));
+    LOG_INFO("bt.client", "added magnet" << (resume ? " (resumed) " : " ") << short_hash(ih) << " → " << path);
+    raw->start();
+    return raw;
+}
+
+Torrent* Client::add_torrent_with_resume(const TorrentInfo& info, const ResumeData& resume,
+                                         const std::string& save_path) {
+    return run_on_reactor([&] { return add_torrent_with_resume_impl(info, resume, save_path); });
+}
+
+Torrent* Client::add_torrent_with_resume_impl(const TorrentInfo& info, const ResumeData& resume,
+                                              const std::string& save_path) {
+    if (!info.is_valid()) return nullptr;
+    const InfoHash ih = info.info_hash();
+    if (torrents_.count(ih)) return torrents_[ih].get();
+
+    const std::string path = save_path.empty() ? config_.download_path : save_path;
+    auto t = std::make_unique<Torrent>(reactor_, *this, info, path);
+    Torrent* raw = t.get();
+    torrents_.emplace(ih, std::move(t));
+    raw->load_resume_data(resume);  // must precede start()
+    raw->start();
+    return raw;
+}
+
+Torrent* Client::add_torrent_for_seeding(const TorrentInfo& info, const std::string& save_path) {
+    return run_on_reactor([&]() -> Torrent* {
+        if (!info.is_valid() || !info.has_metadata()) return nullptr;
+        ResumeData rd;
+        rd.info_hash = info.info_hash();
+        rd.have      = Bitfield(info.num_pieces(), true);  // assume every piece is present
+        return add_torrent_with_resume_impl(info, rd, save_path);
+    });
+}
+
+void Client::save_all_resume_data() {
+    run_on_reactor([&] { for (auto& [hash, t] : torrents_) t->save_resume_data(); });
+}
+
+Torrent* Client::get_torrent(const InfoHash& info_hash) {
+    auto it = torrents_.find(info_hash);
+    return it == torrents_.end() ? nullptr : it->second.get();
+}
+
+void Client::remove_torrent(const InfoHash& info_hash, bool /*delete_files*/) {
+    run_on_reactor([&] { remove_torrent_impl(info_hash); });
+}
+
+void Client::remove_torrent_impl(const InfoHash& info_hash) {
+    auto it = torrents_.find(info_hash);
+    if (it == torrents_.end()) return;
+    LOG_INFO("bt.client", "removed torrent " << short_hash(info_hash));
+    it->second->stop();  // closes the peers the torrent has registered in its peer list
+    // stop() only closes connections the torrent knows about (its peers_ list). An
+    // *outgoing* connection that has completed connect() but not yet the wire
+    // handshake holds obs_ = this torrent, yet is not in peers_ until on_handshake —
+    // so stop() misses it. Erasing the torrent now would leave that live connection
+    // with a dangling observer, and its next message (handshake reply + payload in
+    // one segment) dereferences the freed Torrent → use-after-free crashing in
+    // dispatch(). Close every remaining live connection bound to this info-hash
+    // while the torrent is still alive (close() fires on_closed() on it).
+    for (auto& pc : connections_)
+        if (!pc->closed() && pc->info_hash() == info_hash) pc->close("torrent removed");
+    torrents_.erase(it);
+    // Stop the DHT traversal started for this torrent: its result has no consumer
+    // left, and letting it run keeps a lookup alive for a hash we no longer hold.
+    if (dht_) dht_->cancel_search(info_hash);
+    // File deletion is not yet implemented; the torrent's data is left on disk.
+}
+
+TorrentStatus Client::torrent_status(const InfoHash& info_hash) {
+    return run_on_reactor([&]() -> TorrentStatus {
+        TorrentStatus s;
+        auto it = torrents_.find(info_hash);
+        if (it == torrents_.end() || !it->second) return s;
+        const Torrent*     t    = it->second.get();
+        const TorrentInfo& info = t->torrent_info();
+        s.exists       = true;
+        s.name         = info.name();
+        s.has_metadata = t->has_metadata();
+        s.is_complete  = t->is_complete();
+        s.paused       = t->is_paused();
+        s.progress     = t->progress();
+        s.downloaded   = t->bytes_downloaded();
+        s.uploaded     = t->bytes_uploaded();
+        s.num_peers    = t->num_peers();
+        if (info.has_metadata()) {
+            s.total_size = std::uint64_t(info.total_size());
+            for (const FileEntry& f : info.files().files())
+                s.files.push_back({f.path, f.size});
+        }
+        return s;
+    });
+}
+
+std::optional<TorrentInfo> Client::torrent_metadata(const InfoHash& info_hash) {
+    return run_on_reactor([&]() -> std::optional<TorrentInfo> {
+        auto it = torrents_.find(info_hash);
+        if (it == torrents_.end() || !it->second) return std::nullopt;
+        const Torrent* t = it->second.get();
+        if (!t->has_metadata()) return std::nullopt;
+        // Copy the info out under reactor ownership; TorrentInfo is a value type,
+        // so the caller gets a standalone snapshot safe to use off-thread.
+        return t->torrent_info();
+    });
+}
+
+void Client::pause_torrent(const InfoHash& info_hash) {
+    run_on_reactor([&] {
+        auto it = torrents_.find(info_hash);
+        if (it != torrents_.end() && it->second) it->second->pause();
+    });
+}
+
+void Client::resume_torrent(const InfoHash& info_hash) {
+    run_on_reactor([&] {
+        auto it = torrents_.find(info_hash);
+        if (it != torrents_.end() && it->second) it->second->resume();
+    });
+}
+
+bool Client::save_resume_data(const InfoHash& info_hash) {
+    return run_on_reactor([&]() -> bool {
+        auto it = torrents_.find(info_hash);
+        return it != torrents_.end() && it->second && it->second->save_resume_data();
+    });
+}
+
+std::vector<Torrent*> Client::torrents() {
+    std::vector<Torrent*> out;
+    out.reserve(torrents_.size());
+    for (auto& [hash, t] : torrents_) out.push_back(t.get());
+    return out;
+}
+
+Torrent* Client::add_torrent_file(const std::string& path, const std::string& save_path) {
+    auto info = TorrentInfo::from_file(path);  // pure parse — safe off the reactor thread
+    if (!info) return nullptr;
+    return run_on_reactor([&] { return add_torrent_impl(*info, save_path); });
+}
+
+std::size_t Client::total_peers() const {
+    std::size_t n = 0;
+    for (const auto& [hash, t] : torrents_) n += t->num_peers();
+    return n;
+}
+
+void Client::schedule_reap() {
+    if (!opened_) return;
+    reap_timer_ = reactor_.schedule(std::chrono::seconds(1), [this] {
+        reap_closed();
+        sample_rates();
+        schedule_reap();
+    });
+}
+
+void Client::reap_closed() {
+    connections_.erase(
+        std::remove_if(connections_.begin(), connections_.end(),
+                       [](const std::unique_ptr<PeerConnection>& pc) { return pc->closed(); }),
+        connections_.end());
+}
+
+void Client::sample_rates() {
+    std::uint64_t down = 0, up = 0;
+    for (auto& [hash, t] : torrents_) {
+        down += t->bytes_downloaded();
+        up   += t->bytes_uploaded();
+    }
+    const auto now = std::chrono::steady_clock::now();
+    if (last_sample_.time_since_epoch().count() != 0) {
+        const double dt = std::chrono::duration<double>(now - last_sample_).count();
+        if (dt > 0) {
+            // Counters are monotonic, but guard against a torrent being removed
+            // between samples (which would make the aggregate drop).
+            const std::uint64_t d_down = down >= last_down_bytes_ ? down - last_down_bytes_ : 0;
+            const std::uint64_t d_up   = up   >= last_up_bytes_   ? up   - last_up_bytes_   : 0;
+            down_rate_.store(std::uint64_t(double(d_down) / dt), std::memory_order_relaxed);
+            up_rate_.store(std::uint64_t(double(d_up) / dt), std::memory_order_relaxed);
+        }
+    }
+    last_down_bytes_ = down;
+    last_up_bytes_   = up;
+    last_sample_     = now;
+}
+
+} // namespace librats::bittorrent

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

@@ -0,0 +1,227 @@
+#pragma once
+
+/**
+ * @file client.h
+ * @brief The BitTorrent session: owns the reactor, the listen socket and the
+ *        set of torrents, and brokers peer connections between them.
+ *
+ * Client is the top-level handle an application drives. It accepts incoming peers
+ * and routes each (by the info-hash in its handshake) to the matching Torrent;
+ * it dials outgoing peers on a Torrent's behalf. All connections are owned here
+ * in one pool and reaped once closed, so torrents only ever hold raw pointers.
+ *
+ * Lifecycle: open() wires up the listener and timers on the reactor thread;
+ * start() additionally runs the reactor on its own thread. Tests instead pump
+ * reactor().run_one() so everything stays single-threaded and deterministic.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/bittorrent/peer_connection.h"
+#include "librats/bittorrent/reactor.h"
+#include "librats/bittorrent/torrent.h"
+#include "librats/bittorrent/torrent_info.h"
+#include "librats/bittorrent/types.h"
+#include "librats/core/socket.h"
+#include "librats/core/types.h"
+#include "librats/dht/dht.h"
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <functional>
+#include <future>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <type_traits>
+#include <unordered_set>
+#include <vector>
+
+namespace librats::bittorrent {
+
+/// A thread-safe snapshot of one torrent's state. Produced by Client::torrent_status
+/// on the reactor thread so callers on any thread get a consistent view without
+/// touching the (lock-free, reactor-owned) Torrent directly.
+struct TorrentStatus {
+    struct File { std::string path; std::int64_t size = 0; };
+
+    bool          exists       = false;  ///< false if no such torrent (rest is default)
+    std::string   name;
+    bool          has_metadata = false;
+    bool          is_complete  = false;
+    bool          paused       = false;
+    double        progress     = 0.0;    ///< 0..1
+    std::uint64_t total_size   = 0;
+    std::uint64_t downloaded   = 0;
+    std::uint64_t uploaded     = 0;
+    std::size_t   num_peers    = 0;
+    std::vector<File> files;             ///< populated once metadata is known
+};
+
+class RATS_API Client final : public TorrentHost {
+public:
+    struct Config {
+        std::uint16_t listen_port    = 6881;   ///< 0 = ephemeral
+        std::string   download_path;           ///< default save directory
+        std::string   peer_id_prefix = "-LR0001-";
+    };
+
+    Client();
+    explicit Client(Config config);
+    ~Client() override;
+
+    Client(const Client&) = delete;
+    Client& operator=(const Client&) = delete;
+
+    /// Wire up the listener + housekeeping timers. Must run on the reactor thread
+    /// (call directly before pumping in tests, or via start()).
+    void open();
+    /// open() + run the reactor on a background thread.
+    void start();
+    /// Stop the reactor (joining its thread) and tear everything down.
+    void stop();
+
+    bool          is_running()  const noexcept { return opened_; }
+    std::uint16_t listen_port() const noexcept { return actual_port_; }
+    Reactor&      reactor() noexcept { return reactor_; }
+
+    Torrent* add_torrent(const TorrentInfo& info, const std::string& save_path = "");
+    /// Add a magnet link — the torrent starts metadata-less and fetches its info
+    /// dict from peers (BEP 9) before downloading.
+    Torrent* add_magnet(const std::string& magnet_uri, const std::string& save_path = "");
+    /// Like add_magnet, but first loads any resume file saved next to @p save_path
+    /// (see Torrent::try_load_resume_data) so a previously-downloaded torrent
+    /// resumes its pieces — and, if the resume file embeds the info dict, skips the
+    /// metadata re-fetch entirely. Used to restore torrents across restarts.
+    Torrent* add_magnet_resumed(const std::string& magnet_uri, const std::string& save_path = "");
+    /// Add a torrent and apply saved resume state (trusts the recorded pieces).
+    Torrent* add_torrent_with_resume(const TorrentInfo& info, const ResumeData& resume,
+                                     const std::string& save_path = "");
+    /// Add a freshly-created torrent whose files already exist at @p save_path,
+    /// trusting every piece so it starts seeding without re-hashing.
+    Torrent* add_torrent_for_seeding(const TorrentInfo& info, const std::string& save_path);
+    /// Load a .torrent file from disk and add it. Returns nullptr if the file
+    /// cannot be read or parsed. Convenience over TorrentInfo::from_file + add_torrent.
+    Torrent* add_torrent_file(const std::string& path, const std::string& save_path = "");
+    Torrent* get_torrent(const InfoHash& info_hash);
+    void     remove_torrent(const InfoHash& info_hash, bool delete_files = false);
+    std::vector<Torrent*> torrents();
+    /// Persist resume data for every torrent to its default path.
+    void     save_all_resume_data();
+
+    // ---- thread-safe control / inspection (marshalled onto the reactor) ----
+    // Prefer these over reaching into a Torrent* from another thread: Torrent state
+    // is lock-free and reactor-owned, so it must only be touched on the reactor.
+
+    /// Consistent snapshot of one torrent (exists=false if not found).
+    TorrentStatus torrent_status(const InfoHash& info_hash);
+    /// Thread-safe copy of a loaded torrent's full metadata, or nullopt when the
+    /// torrent is unknown or its metadata hasn't arrived yet. Marshalled onto the
+    /// reactor, so it is safe to call from any thread — unlike get_torrent(), which
+    /// hands back a reactor-owned Torrent* that must not be touched off-thread.
+    std::optional<TorrentInfo> torrent_metadata(const InfoHash& info_hash);
+    /// Pause / resume a torrent without re-hashing (see Torrent::pause).
+    void          pause_torrent(const InfoHash& info_hash);
+    void          resume_torrent(const InfoHash& info_hash);
+    /// Persist one torrent's resume data to its default path. Returns false if the
+    /// torrent is unknown or the write failed.
+    bool          save_resume_data(const InfoHash& info_hash);
+
+    // ---- aggregate stats (for status lines / UI) ----
+    std::size_t   num_torrents() const noexcept { return torrents_.size(); }
+    std::size_t   total_peers()  const;
+    /// Swarm-wide transfer rates in bytes/sec, sampled once per second by the
+    /// housekeeping timer. Atomic so they can be read from another thread.
+    std::uint64_t total_download_rate() const noexcept { return down_rate_.load(std::memory_order_relaxed); }
+    std::uint64_t total_upload_rate()   const noexcept { return up_rate_.load(std::memory_order_relaxed); }
+
+    /// Share an externally-owned DHT for peer discovery (e.g. the node's). Its
+    /// lifetime is the caller's; Client never starts or stops it.
+    void       set_external_dht(DhtClient* dht) noexcept { dht_ = dht; }
+    DhtClient* get_dht_client() const noexcept { return dht_; }
+
+    // ---- TorrentHost ----
+    void          connect_peer(Torrent& torrent, const std::string& ip, std::uint16_t port) override;
+    const PeerId& peer_id() const override { return peer_id_; }
+    void          find_peers_via_dht(const InfoHash& info_hash,
+                                     std::function<void(const std::string& ip, std::uint16_t port)> on_peer) override;
+    void          announce_to_dht(const InfoHash& info_hash, std::uint16_t port) override;
+
+    /// Largest number of peer connections (in + out) the session will hold at once.
+    /// Beyond this, inbound sockets are accepted and immediately closed so a flood
+    /// of incoming connections can't exhaust memory / file descriptors.
+    static constexpr std::size_t kMaxConnections = 200;
+
+private:
+    void open_listener();
+    void on_accept();
+    void schedule_reap();
+    void reap_closed();
+    void sample_rates();  ///< recompute down_rate_/up_rate_ from per-torrent byte counters
+
+    // Run @p f on the reactor thread and return its result. Executed inline when
+    // already on the reactor thread or when the reactor isn't running its own
+    // thread yet (tests pump run_one); otherwise posted and waited on. This makes
+    // the public mutators below safe to call from any thread (C2).
+    template <class F>
+    std::invoke_result_t<F> run_on_reactor(F f) {
+        using R = std::invoke_result_t<F>;
+        if (reactor_.on_reactor_thread() || !reactor_.running()) return f();
+        std::promise<R> prom;
+        auto fut = prom.get_future();
+        reactor_.post([&] {
+            if constexpr (std::is_void_v<R>) { f(); prom.set_value(); }
+            else                             { prom.set_value(f()); }
+        });
+        return fut.get();
+    }
+
+    // Unsynchronised implementations — only ever run on the reactor thread (either
+    // directly in the single-threaded/test path or via run_on_reactor()).
+    Torrent* add_torrent_impl(const TorrentInfo& info, const std::string& save_path);
+    Torrent* add_magnet_impl(const std::string& magnet_uri, const std::string& save_path, bool resume);
+    Torrent* add_torrent_with_resume_impl(const TorrentInfo& info, const ResumeData& resume,
+                                          const std::string& save_path);
+    void     remove_torrent_impl(const InfoHash& info_hash);
+
+    Reactor       reactor_;
+    Config        config_;
+    PeerId        peer_id_;
+    socket_t      listener_     = RATS_INVALID_SOCKET;
+    std::uint16_t actual_port_  = 0;
+    bool          opened_       = false;
+    TimerId       reap_timer_   = kInvalidTimerId;
+
+    DhtClient*    dht_ = nullptr;   ///< external, non-owning
+
+    /// Keeps DHT callbacks from touching a torn-down Client. A get_peers traversal
+    /// runs for seconds, and the shared DHT is stopped *after* us (node teardown is
+    /// reverse-attach order), so a reply can land once our reactor is gone and this
+    /// object destroyed — dereferencing it then is a use-after-free that hangs the
+    /// DHT loop thread inside Reactor::post, and with it the DHT's own join(). Every
+    /// callback we hand to the DHT captures this token by shared_ptr and does its
+    /// work under `mutex` with `alive` checked; stop() clears the flag under the same
+    /// mutex, so a callback either completes before teardown or does nothing at all.
+    struct DhtCallbackGuard {
+        std::mutex mutex;
+        bool       alive = true;
+    };
+    std::shared_ptr<DhtCallbackGuard> dht_guard_ = std::make_shared<DhtCallbackGuard>();
+
+    std::map<InfoHash, std::unique_ptr<Torrent>>      torrents_;
+    std::vector<std::unique_ptr<PeerConnection>>      connections_;
+    /// Outbound sockets still waiting for connect() to complete. Tracked so a
+    /// mid-connect stop() can close them, and so the completion looks the torrent
+    /// up by info-hash rather than holding a raw Torrent* that may have been removed.
+    std::unordered_set<socket_t>                      pending_connects_;
+
+    // Rate sampling (updated on the reactor thread once per second).
+    std::atomic<std::uint64_t>            down_rate_{0};
+    std::atomic<std::uint64_t>            up_rate_{0};
+    std::uint64_t                         last_down_bytes_ = 0;
+    std::uint64_t                         last_up_bytes_   = 0;
+    std::chrono::steady_clock::time_point last_sample_{};
+};
+
+} // namespace librats::bittorrent