librats 2.3.2 → 2.3.4

package/lib/index.d.ts

@@ -127,6 +127,7 @@ declare module 'librats' {
   ) => void;
   export type FileCompleteHandler = (
     transferId: number,
+    peerId: string,
     success: boolean,
     path: string
   ) => void;

package/native-src/CMakeLists.txt

@@ -379,6 +379,15 @@ if(RATS_SEARCH_FEATURES)
         src/librats/bittorrent/piece_picker.cpp
         src/librats/bittorrent/reactor.h
         src/librats/bittorrent/reactor.cpp
+        src/librats/bittorrent/mse.h
+        src/librats/bittorrent/mse.cpp
+        src/librats/bittorrent/utp_packet.h
+        src/librats/bittorrent/utp_stream.h
+        src/librats/bittorrent/utp_stream.cpp
+        src/librats/bittorrent/utp_manager.h
+        src/librats/bittorrent/utp_manager.cpp
+        src/librats/bittorrent/peer_link.h
+        src/librats/bittorrent/peer_link.cpp
         src/librats/bittorrent/peer_connection.h
         src/librats/bittorrent/peer_connection.cpp
         src/librats/bittorrent/choker.h
@@ -736,14 +745,20 @@ if(RATS_BUILD_TESTS)
             tests/test_bt_piece_picker.cpp
             # Phase 4 — reactor + peer wire protocol
             tests/test_bt_reactor.cpp
+            tests/test_bt_mse.cpp
+            tests/test_bt_utp.cpp
             tests/test_bt_peer_connection.cpp
             # Phase 5 — torrent + client + choker
             tests/test_bt_choker.cpp
             tests/test_bt_download.cpp
+            tests/test_bt_mse_wire.cpp
+            tests/test_bt_utp_wire.cpp
             tests/test_bt_stall_metadata.cpp
+            tests/test_bt_connect_timeout.cpp
             # Phase 6 — extension protocol + metadata exchange + discovery
             tests/test_bt_extensions.cpp
             tests/test_bt_magnet_fetch.cpp
+            tests/test_bt_dht_peer_sources.cpp
             tests/test_bt_peer_list.cpp
             tests/test_bt_pex.cpp
             tests/test_bt_tracker.cpp

package/native-src/src/librats/bindings/rats.cpp

@@ -46,6 +46,12 @@ struct RatsHandle {
     Relay*               relay     = nullptr;
 #ifdef RATS_SEARCH_FEATURES
     Bittorrent*          bittorrent = nullptr;
+    /// MSE/PE policy for the BitTorrent session, applied when it is enabled.
+    /// Defaults match the C++ side: obfuscate outgoing dials first, accept both.
+    bittorrent::EncPolicy bt_out_enc = bittorrent::EncPolicy::Enabled;
+    bittorrent::EncPolicy bt_in_enc  = bittorrent::EncPolicy::Enabled;
+    bool bt_out_utp = true;
+    bool bt_in_utp  = true;
 #endif
     std::string data_dir;  ///< copied from NodeConfig so subsystems can co-locate state
     bool dht_enabled     = false;
@@ -574,8 +580,9 @@ rats_error_t rats_on_file_complete(rats_t node, rats_file_complete_cb cb, void*
     if (!cb) return RATS_ERR_INVALID_ARG;
     auto* h = as_handle(node);
     if (!h->files) return RATS_ERR_NOT_ENABLED;
-    h->files->on_complete([cb, user](uint64_t id, bool success, const std::string& path) {
-        cb(user, id, success ? 1 : 0, path.c_str());
+    h->files->on_complete([cb, user](const PeerId& peer, uint64_t id, bool success, const std::string& path) {
+        const std::string hex = peer.to_hex();
+        cb(user, id, hex.c_str(), success ? 1 : 0, path.c_str());
     });
     return RATS_OK;
 }
@@ -686,8 +693,12 @@ rats_error_t rats_enable_bittorrent(rats_t node, uint16_t listen_port, const cha
     if (h->started) return RATS_ERR_ALREADY_STARTED;
     if (!h->bittorrent) {
         Bittorrent::Config cfg;
-        cfg.client.listen_port   = listen_port;
-        cfg.client.download_path = download_path ? download_path : ".";
+        cfg.client.listen_port    = listen_port;
+        cfg.client.download_path  = download_path ? download_path : ".";
+        cfg.client.out_enc_policy      = h->bt_out_enc;
+        cfg.client.in_enc_policy       = h->bt_in_enc;
+        cfg.client.enable_outgoing_utp = h->bt_out_utp;
+        cfg.client.enable_incoming_utp = h->bt_in_utp;
         h->bittorrent = h->node->add_subsystem(std::make_unique<Bittorrent>(cfg));
     }
     return RATS_OK;
@@ -697,6 +708,53 @@ rats_error_t rats_enable_bittorrent(rats_t node, uint16_t listen_port, const cha
 #endif
 }
 
+rats_error_t rats_bt_set_encryption(rats_t node, rats_bt_enc_policy_t out_policy,
+                                    rats_bt_enc_policy_t in_policy) {
+#ifdef RATS_SEARCH_FEATURES
+    auto to_policy = [](rats_bt_enc_policy_t p, bool& ok) {
+        switch (p) {
+            case RATS_BT_ENC_FORCED:   return bittorrent::EncPolicy::Forced;
+            case RATS_BT_ENC_ENABLED:  return bittorrent::EncPolicy::Enabled;
+            case RATS_BT_ENC_DISABLED: return bittorrent::EncPolicy::Disabled;
+        }
+        ok = false;
+        return bittorrent::EncPolicy::Enabled;
+    };
+    bool ok = true;
+    auto* h = as_handle(node);
+    if (h->started)    return RATS_ERR_ALREADY_STARTED;
+    // The policy is baked into the session's config when it is created, so asking
+    // for it afterwards would silently do nothing — say so instead.
+    if (h->bittorrent) return RATS_ERR_ALREADY_STARTED;
+    const auto out = to_policy(out_policy, ok);
+    const auto in  = to_policy(in_policy, ok);
+    if (!ok) return RATS_ERR_INVALID_ARG;
+    h->bt_out_enc = out;
+    h->bt_in_enc  = in;
+    return RATS_OK;
+#else
+    (void)node; (void)out_policy; (void)in_policy;
+    return RATS_ERR_NOT_ENABLED;
+#endif
+}
+
+rats_error_t rats_bt_set_utp(rats_t node, int enable_outgoing, int enable_incoming) {
+#ifdef RATS_SEARCH_FEATURES
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    // Same reasoning as rats_bt_set_encryption: the setting is baked into the
+    // session's config when it is created, so accepting it afterwards would
+    // silently do nothing.
+    if (h->bittorrent) return RATS_ERR_ALREADY_STARTED;
+    h->bt_out_utp = enable_outgoing != 0;
+    h->bt_in_utp  = enable_incoming != 0;
+    return RATS_OK;
+#else
+    (void)node; (void)enable_outgoing; (void)enable_incoming;
+    return RATS_ERR_NOT_ENABLED;
+#endif
+}
+
 rats_error_t rats_bt_add_magnet(rats_t node, const char* magnet_uri, const char* save_path) {
 #ifdef RATS_SEARCH_FEATURES
     if (!magnet_uri) return RATS_ERR_INVALID_ARG;

package/native-src/src/librats/bindings/rats.h

@@ -345,7 +345,8 @@ typedef void (*rats_file_offer_cb)(void* user, const char* peer_id_hex, uint64_t
                                    const char* name, uint64_t size, int is_directory);
 typedef void (*rats_file_progress_cb)(void* user, uint64_t transfer_id, const char* peer_id_hex,
                                       uint64_t bytes_transferred, uint64_t total_bytes, int status);
-typedef void (*rats_file_complete_cb)(void* user, uint64_t transfer_id, int success, const char* path);
+typedef void (*rats_file_complete_cb)(void* user, uint64_t transfer_id, const char* peer_id_hex,
+                                      int success, const char* path);
 
 /** Enable the file-transfer subsystem. `temp_dir` holds in-progress downloads
  *  (NULL → current directory). Call before start(). */
@@ -400,6 +401,36 @@ RATS_API rats_error_t rats_remove_reconnect(rats_t node, const char* host, uint1
 /** Enable BitTorrent. listen_port 0 picks an ephemeral port; download_path is the
  *  default save directory (NULL = "."). Enable DHT first to share the node's DHT. */
 RATS_API rats_error_t rats_enable_bittorrent(rats_t node, uint16_t listen_port, const char* download_path);
+
+/** MSE/PE connection obfuscation policy (see librats/bittorrent/mse.h). */
+typedef enum {
+    RATS_BT_ENC_FORCED   = 0,  /**< obfuscated connections only, both directions */
+    RATS_BT_ENC_ENABLED  = 1,  /**< default: obfuscate first, fall back to plaintext */
+    RATS_BT_ENC_DISABLED = 2,  /**< plaintext only */
+} rats_bt_enc_policy_t;
+
+/**
+ * Set the BitTorrent encryption policy. Optional — the default (ENABLED for both)
+ * already dials obfuscated first, which is what reaches the large part of the swarm
+ * that refuses plaintext. Must be called BEFORE rats_enable_bittorrent, since the
+ * policy is fixed when the session is created.
+ */
+RATS_API rats_error_t rats_bt_set_encryption(rats_t node, rats_bt_enc_policy_t out_policy,
+                                             rats_bt_enc_policy_t in_policy);
+
+/**
+ * Turn uTP (BEP 29) on or off, per direction. Optional — both are on by default,
+ * which is what every modern client ships: uTP's delay-based congestion control
+ * yields to other traffic instead of saturating the user's uplink, and much of the
+ * swarm answers UDP more readily than TCP. A peer with no uTP costs one connect
+ * timeout before the dial falls back to TCP, and is remembered.
+ *
+ * Pass non-zero to enable each direction. Turning outgoing uTP off makes every dial TCP. Turning incoming off still dials
+ * out over uTP but never answers, which is what a blocked inbound UDP port looks
+ * like anyway. Must be called BEFORE rats_enable_bittorrent, since the setting is
+ * fixed when the session is created.
+ */
+RATS_API rats_error_t rats_bt_set_utp(rats_t node, int enable_outgoing, int enable_incoming);
 /** Start downloading a magnet link (metadata is fetched from peers). */
 RATS_API rats_error_t rats_bt_add_magnet(rats_t node, const char* magnet_uri, const char* save_path);
 /** Start a torrent from a .torrent file on disk. */

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

@@ -12,6 +12,7 @@ Client::Client() : Client(Config{}) {}
 
 Client::Client(Config config)
     : config_(std::move(config))
+    , utp_(reactor_)
     , peer_id_(generate_peer_id(config_.peer_id_prefix)) {}
 
 Client::~Client() {
@@ -52,9 +53,15 @@ void Client::stop() {
     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); }
+    for (const auto& [s, deadline] : pending_connects_) {
+        reactor_.cancel(deadline);
+        reactor_.remove(s);
+        close_socket(s);
+    }
     pending_connects_.clear();
     if (is_valid_socket(listener_)) { reactor_.remove(listener_); close_socket(listener_); listener_ = RATS_INVALID_SOCKET; }
+    // After connections_, so every UtpPeerLink has already handed its stream back.
+    utp_.close();
     // 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.
@@ -62,16 +69,73 @@ void Client::stop() {
 }
 
 void Client::open_listener() {
-    listener_ = create_tcp_server(config_.listen_port, 16, "", AddressFamily::IPv4);
+    const bool want_utp = config_.enable_outgoing_utp || config_.enable_incoming_utp;
+
+    // TCP and uTP must answer on the *same* port: a peer learns one number for us
+    // (from the tracker, the DHT or PEX) and has to be able to reach us with it
+    // over either wire. When the port is ephemeral the TCP bind picks it and the
+    // UDP bind may then find that number already taken by something else, so the
+    // pair is acquired as a pair and retried as one.
+    constexpr int kPairAttempts = 8;
+    for (int attempt = 0; attempt < kPairAttempts; ++attempt) {
+        const socket_t tcp = create_tcp_server(config_.listen_port, 16, "", AddressFamily::IPv4);
+        if (!is_valid_socket(tcp)) break;
+        const std::uint16_t port = std::uint16_t(get_bound_port(tcp));
+        // Keep this TCP socket when the pair came up, when a fixed port leaves us
+        // nowhere to move, or when this was the last go — running out of attempts
+        // must not cost us a listener we already hold. Only a retry that is really
+        // going to happen may throw one away.
+        if (!want_utp || utp_.open(port) || config_.listen_port != 0
+            || attempt + 1 == kPairAttempts) {
+            listener_    = tcp;
+            actual_port_ = port;
+            break;
+        }
+        close_socket(tcp);
+    }
+
+    // The matching UDP port was taken — most often by our own DHT, which by mainline
+    // convention serves the torrent port. An ephemeral one is still worth having:
+    // an outgoing dial is answered on the source port of its own SYN, so it does not
+    // care what that number is. Only inbound uTP needs the advertised port, and it is
+    // the half we give up here. Nothing is lost by trying — with outgoing uTP off
+    // there is nothing left for a mux to do, so we do not open one.
+    if (want_utp && !utp_.is_open() && config_.enable_outgoing_utp) {
+        if (!utp_.open(0)) {
+            LOG_WARN("bt.client", "no UDP port available — running without uTP");
+        } else if (actual_port_ != 0) {
+            LOG_WARN("bt.client", "UDP port " << actual_port_ << " is held by another socket — "
+                                  "uTP on port " << utp_.port() << " instead: dialling out works, "
+                                  "inbound uTP does not");
+        } else {
+            // No listener at all, so there is no advertised number to have missed.
+            LOG_WARN("bt.client", "uTP on port " << utp_.port() << ", outgoing only");
+        }
+    }
+
+    // Inbound uTP only means anything on the port peers are told about. On any other
+    // number nothing would ever arrive, so say so rather than pretend to listen.
+    const bool utp_inbound = utp_.is_open() && utp_.port() == actual_port_
+                             && config_.enable_incoming_utp;
+    if (utp_.is_open()) {
+        utp_.set_accept_incoming(utp_inbound);
+        utp_.set_accept_handler([this](utp::Stream& s) { on_utp_accept(s); });
+    }
+
     if (!is_valid_socket(listener_)) {
+        // Outgoing uTP may well be up, so this is not the end of the session — but
+        // nobody can reach us, which is worth an error either way.
         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_);
+
+    LOG_INFO("bt.client", "listening on port " << actual_port_
+                          << (utp_inbound              ? " (TCP + uTP)"
+                              : utp_.is_open()         ? " (TCP, uTP outgoing only)"
+                                                       : " (TCP)"));
 }
 
 void Client::on_accept() {
@@ -102,24 +166,122 @@ void Client::on_accept() {
             }
         }
 
-        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;
+        adopt_inbound(std::make_unique<TcpPeerLink>(reactor_, s), std::move(ip), port);
+    }
+}
+
+void Client::adopt_inbound(std::unique_ptr<PeerLink> link, std::string ip, std::uint16_t port) {
+    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;
+    };
+    // An inbound peer may open either protocol; the connection sniffs which and
+    // enforces in_enc_policy. The stream-key resolver is what lets an obfuscated
+    // peer name its torrent without ever putting the info-hash on the wire.
+    mse::Handshake::SkeyResolver skey =
+        [this](const std::uint8_t* obfuscated, const std::uint8_t* req3, InfoHash& out) {
+            return resolve_mse_skey(obfuscated, req3, out);
         };
-        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();
+    LOG_DEBUG("bt.client", "inbound connection from " << ip << ':' << port);
+    auto pc = std::make_unique<PeerConnection>(reactor_, std::move(link), peer_id_,
+                                               std::move(resolver), std::move(ip), port,
+                                               config_.in_enc_policy, std::move(skey));
+    PeerConnection* raw = pc.get();
+    connections_.push_back(std::move(pc));
+    raw->start();
+}
+
+void Client::on_utp_accept(utp::Stream& stream) {
+    // The stream cap is the manager's; this is the session-wide connection cap. A
+    // stream we refuse here is simply left without an observer, which is exactly
+    // what tells the manager to reap it on its next pass.
+    if (connections_.size() >= kMaxConnections) {
+        LOG_DEBUG("bt.client", "connection cap " << kMaxConnections
+                               << " reached, dropping inbound uTP");
+        return;
+    }
+    const Address& from = stream.remote();
+    adopt_inbound(std::make_unique<UtpPeerLink>(utp_, stream), from.ip.to_string(), from.port);
+}
+
+bool Client::dial_encrypted(bool prefer_encrypted) const noexcept {
+    switch (config_.out_enc_policy) {
+        case EncPolicy::Forced:   return true;
+        case EncPolicy::Disabled: return false;
+        case EncPolicy::Enabled:  break;
     }
+    return prefer_encrypted;
 }
 
-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; }
+bool Client::resolve_mse_skey(const std::uint8_t* obfuscated, const std::uint8_t* req3_hash,
+                              InfoHash& out) const {
+    // Linear over the session's torrents: the stream key is deliberately not
+    // reversible, so guess-and-check is the only way, and a node holds few enough
+    // torrents for one SHA-1 each to be nothing next to the DH that just ran.
+    for (const auto& [ih, t] : torrents_) {
+        if (mse::skey_matches(obfuscated, req3_hash, ih)) { out = ih; return true; }
+    }
+    return false;
+}
+
+void Client::connect_peer(Torrent& torrent, const PeerList::Endpoint& peer) {
+    if (connections_.size() >= kMaxConnections) {
+        torrent.on_connect_failed(peer.ip, peer.port);
+        return;
+    }
+
+    DialOptions opts;
+    opts.obfuscate = dial_encrypted(peer.prefer_encrypted);
+    // Only an alternating policy has a second encryption form to fall back to. Under
+    // Forced or Disabled there is nothing else to try there, so a refusal is a plain
+    // failure and the peer should serve its usual backoff.
+    const bool enc_alternates = config_.out_enc_policy == EncPolicy::Enabled;
+
+    if (config_.enable_outgoing_utp && peer.prefer_utp && utp_.is_open()) {
+        // A uTP dial that never reaches a handshake is worth retrying immediately —
+        // over TCP if we have it, otherwise with the other encryption form.
+        opts.retry_other_form_on_failure = enc_alternates || config_.enable_outgoing_tcp;
+        if (connect_peer_utp(torrent, peer, opts)) return;
+    }
+    if (!config_.enable_outgoing_tcp) {
+        torrent.on_connect_failed(peer.ip, peer.port);
+        return;
+    }
+    opts.retry_other_form_on_failure = enc_alternates;
+    connect_peer_tcp(torrent, peer, opts);
+}
+
+bool Client::connect_peer_utp(Torrent& torrent, const PeerList::Endpoint& peer, DialOptions opts) {
+    // IpAddress::parse rather than the Address(string, port) constructor: that one
+    // asserts on anything non-numeric, and while every peer source we have hands us
+    // numeric addresses, a dial is not the place to discover otherwise.
+    const auto ip = IpAddress::parse(peer.ip);
+    if (!ip) return false;
+    utp::Stream* stream = utp_.connect(Address(*ip, peer.port));
+    if (stream == nullptr) return false;
+
+    // No pending-connect bookkeeping, unlike TCP: the stream accepts the handshake
+    // bytes immediately and holds them until its SYN is answered, so there is no
+    // half-open state for the Client to track. The stream's own connect timeout and
+    // the connection's handshake deadline both still apply.
+    auto pc = std::make_unique<PeerConnection>(reactor_,
+                                               std::make_unique<UtpPeerLink>(utp_, *stream),
+                                               /*outgoing=*/true, torrent.info_hash(), peer_id_,
+                                               torrent.num_pieces(), &torrent,
+                                               peer.ip, peer.port, opts);
+    LOG_DEBUG("bt.client", "dialing " << peer.ip << ':' << peer.port << " over uTP");
+    PeerConnection* raw = pc.get();
+    connections_.push_back(std::move(pc));
+    raw->start();
+    return true;
+}
+
+void Client::connect_peer_tcp(Torrent& torrent, const PeerList::Endpoint& endpoint, DialOptions enc) {
+    const std::string   ip   = endpoint.ip;
+    const std::uint16_t port = endpoint.port;
     socket_t s = tcp_connect_start(ip, int(port));
     if (!is_valid_socket(s)) { torrent.on_connect_failed(ip, port); return; }
 
@@ -128,10 +290,27 @@ void Client::connect_peer(Torrent& torrent, const std::string& ip, std::uint16_t
     // 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) {
+
+    // The connect deadline. Whichever of the two fires first takes the socket out
+    // of pending_connects_; the other then finds it gone and does nothing, so the
+    // fd is closed exactly once and the peer is reported to the torrent once.
+    const TimerId deadline = reactor_.schedule(config_.connect_timeout, [this, s, ih, ip, port] {
+        if (pending_connects_.erase(s) == 0) return;  // the connect already completed
+        reactor_.remove(s);
+        close_socket(s);
+        LOG_DEBUG("bt.client", "connect to " << ip << ':' << port << " timed out after "
+                               << config_.connect_timeout.count() << " ms");
+        auto it = torrents_.find(ih);
+        if (it != torrents_.end()) it->second->on_connect_failed(ip, port);
+    });
+    pending_connects_.emplace(s, deadline);
+
+    reactor_.add(s, PollOut, [this, ih, s, ip, port, enc](std::uint32_t) {
+        auto pending = pending_connects_.find(s);
+        if (pending == pending_connects_.end()) return;  // the deadline already reclaimed it
+        reactor_.cancel(pending->second);
+        pending_connects_.erase(pending);
         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) {
@@ -139,9 +318,10 @@ void Client::connect_peer(Torrent& torrent, const std::string& ip, std::uint16_t
             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);
+        auto pc = std::make_unique<PeerConnection>(reactor_,
+                                                   std::make_unique<TcpPeerLink>(reactor_, s),
+                                                   /*outgoing=*/true, t->info_hash(), peer_id_,
+                                                   t->num_pieces(), t, ip, port, enc);
         PeerConnection* raw = pc.get();
         connections_.push_back(std::move(pc));
         raw->start();
@@ -172,10 +352,25 @@ void Client::find_peers_via_dht(const InfoHash& info_hash,
     });
 }
 
-void Client::announce_to_dht(const InfoHash& info_hash, std::uint16_t port) {
+void Client::announce_to_dht(const InfoHash& info_hash, std::uint16_t port,
+                             std::function<void(const std::string&, std::uint16_t)> on_peer) {
     // 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);
+    if (!dht_ || !dht_->is_running()) return;
+    if (!on_peer) { dht_->announce_peer(info_hash, port); return; }
+    // An announce runs a get_peers traversal of its own, so it discovers the same
+    // peers a find_peers would. Deliver them through the identical guarded marshal
+    // as find_peers_via_dht (see the reasoning there) instead of discarding them.
+    dht_->announce_peer(info_hash, port,
+                        [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);
+        });
+    });
 }
 
 Torrent* Client::add_torrent(const TorrentInfo& info, const std::string& save_path) {

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

@@ -18,6 +18,7 @@
 #include "librats/util/rats_export.h"
 #include "librats/bittorrent/peer_connection.h"
 #include "librats/bittorrent/reactor.h"
+#include "librats/bittorrent/utp_manager.h"
 #include "librats/bittorrent/torrent.h"
 #include "librats/bittorrent/torrent_info.h"
 #include "librats/bittorrent/types.h"
@@ -35,6 +36,7 @@
 #include <mutex>
 #include <string>
 #include <type_traits>
+#include <unordered_map>
 #include <unordered_set>
 #include <vector>
 
@@ -65,6 +67,39 @@ public:
         std::uint16_t listen_port    = 6881;   ///< 0 = ephemeral
         std::string   download_path;           ///< default save directory
         std::string   peer_id_prefix = "-LR0001-";
+        /// How long an outbound TCP connect may stay pending before we give up on
+        /// the address. Without a deadline of our own, the only thing that ever
+        /// abandons an unreachable peer is the OS SYN retry — ~21 s on Windows,
+        /// longer still on Linux — and for all that time the peer sits `connecting`
+        /// in the PeerList: not retried, not penalised, holding a socket. Most DHT
+        /// peers are behind a NAT with no forwarded TCP port, so a magnet has to
+        /// work through a lot of dead addresses before it reaches one that answers;
+        /// this bound is what decides how many it gets through. Matches
+        /// libtorrent's peer_connect_timeout default.
+        std::chrono::milliseconds connect_timeout{std::chrono::seconds(15)};
+
+        /// How we dial. Enabled (the default, as in libtorrent) alternates per
+        /// attempt starting with MSE, so a peer that refuses obfuscation is still
+        /// reached on its next turn and one that refuses plaintext — a large and
+        /// growing part of the swarm — is reached at all.
+        EncPolicy out_enc_policy = EncPolicy::Enabled;
+        /// What we accept. Enabled takes both; Forced turns away plaintext peers;
+        /// Disabled turns away obfuscated ones.
+        EncPolicy in_enc_policy  = EncPolicy::Enabled;
+
+        /// Dial peers over uTP (BEP 29) when they look like they support it. On by
+        /// default, as in every modern client: it is what keeps a saturated swarm
+        /// from making the rest of the user's connection unusable, and most of the
+        /// swarm now answers UDP more readily than TCP. A peer that does not answer
+        /// costs exactly one round trip before we fall back (see
+        /// PeerList::note_utp_dial_failed).
+        bool enable_outgoing_utp = true;
+        /// Answer inbound uTP connections. Off means we still dial out over uTP but
+        /// never accept — the equivalent of a firewalled UDP port.
+        bool enable_incoming_utp = true;
+        /// Dial peers over TCP. Turning it off makes uTP the only outgoing
+        /// transport, which is only sensible on a link where TCP is the problem.
+        bool enable_outgoing_tcp = true;
     };
 
     Client();
@@ -84,6 +119,10 @@ public:
 
     bool          is_running()  const noexcept { return opened_; }
     std::uint16_t listen_port() const noexcept { return actual_port_; }
+    /// The port the uTP mux actually got, or 0 if there is none. Normally equal to
+    /// listen_port(); it differs when that number's UDP half was already taken, in
+    /// which case uTP can dial out but nothing can dial in over it.
+    std::uint16_t utp_port() const noexcept { return utp_.port(); }
     Reactor&      reactor() noexcept { return reactor_; }
 
     Torrent* add_torrent(const TorrentInfo& info, const std::string& save_path = "");
@@ -130,6 +169,10 @@ public:
 
     // ---- aggregate stats (for status lines / UI) ----
     std::size_t   num_torrents() const noexcept { return torrents_.size(); }
+    /// Outbound connects still waiting on the TCP handshake. Reactor-thread only;
+    /// exposed so a caller (and the tests for the connect deadline) can see that a
+    /// dead address is actually being reclaimed rather than held forever.
+    std::size_t   num_pending_connects() const noexcept { return pending_connects_.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.
@@ -142,11 +185,12 @@ public:
     DhtClient* get_dht_client() const noexcept { return dht_; }
 
     // ---- TorrentHost ----
-    void          connect_peer(Torrent& torrent, const std::string& ip, std::uint16_t port) override;
+    void          connect_peer(Torrent& torrent, const PeerList::Endpoint& peer) 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;
+    void          announce_to_dht(const InfoHash& info_hash, std::uint16_t port,
+                                  std::function<void(const std::string& ip, std::uint16_t port)> on_peer = {}) 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
@@ -156,6 +200,23 @@ public:
 private:
     void open_listener();
     void on_accept();
+    /// Build the resolver + stream-key pair every inbound connection needs, and
+    /// wrap @p link in a PeerConnection. Shared by the TCP and uTP accept paths,
+    /// which differ in nothing but how the bytes arrive.
+    void adopt_inbound(std::unique_ptr<PeerLink> link, std::string ip, std::uint16_t port);
+    /// An inbound uTP stream completed its handshake; give it a PeerConnection.
+    void on_utp_accept(utp::Stream& stream);
+    /// Dial @p peer over uTP. Returns false if uTP is unavailable, so the caller
+    /// falls back to TCP.
+    bool connect_peer_utp(Torrent& torrent, const PeerList::Endpoint& peer, DialOptions opts);
+    void connect_peer_tcp(Torrent& torrent, const PeerList::Endpoint& peer, DialOptions opts);
+    /// Should this dial be obfuscated? Policy decides outright unless it is
+    /// Enabled, in which case the peer's own alternation does.
+    bool dial_encrypted(bool prefer_encrypted) const noexcept;
+    /// MSE stream-key resolver handed to every inbound connection: try each
+    /// torrent we hold against the obfuscated hash the peer sent.
+    bool resolve_mse_skey(const std::uint8_t* obfuscated, const std::uint8_t* req3_hash,
+                          InfoHash& out) const;
     void schedule_reap();
     void reap_closed();
     void sample_rates();  ///< recompute down_rate_/up_rate_ from per-torrent byte counters
@@ -187,6 +248,10 @@ private:
 
     Reactor       reactor_;
     Config        config_;
+    /// The one shared UDP socket every uTP peer rides, bound to the same port as
+    /// the TCP listener (see open_listener). Empty of streams — and cheap — when
+    /// uTP is switched off on both sides.
+    utp::Manager  utp_;
     PeerId        peer_id_;
     socket_t      listener_     = RATS_INVALID_SOCKET;
     std::uint16_t actual_port_  = 0;
@@ -211,10 +276,12 @@ private:
 
     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_;
+    /// Outbound sockets still waiting for connect() to complete, each mapped to the
+    /// timer that abandons it at Config::connect_timeout. Tracked so a mid-connect
+    /// stop() can close them, so the completion looks the torrent up by info-hash
+    /// rather than holding a raw Torrent* that may have been removed, and so the
+    /// deadline and the completion can each tell whether the other got there first.
+    std::unordered_map<socket_t, TimerId>             pending_connects_;
 
     // Rate sampling (updated on the reactor thread once per second).
     std::atomic<std::uint64_t>            down_rate_{0};