librats 2.3.2 → 2.3.4

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

@@ -8,10 +8,17 @@
  * Every discovery source — tracker, DHT, PEX, LSD, incoming — funnels addresses
  * here; the Torrent then asks for connect_candidates() to dial. The list
  * deduplicates, remembers which sources vouched for a peer, counts connection
- * failures (so hopeless peers drift to the back and eventually drop out), and
- * supports banning. Owned by one torrent on the reactor thread — not thread-safe.
+ * failures (so hopeless peers drift to the back and eventually drop out), applies
+ * a reconnect backoff to peers that have just failed, and supports banning. Owned
+ * by one torrent on the reactor thread — not thread-safe.
+ *
+ * Time is passed in rather than read from the clock so the backoff is testable;
+ * the Torrent supplies Clock::now().
  */
 
+#include "librats/bittorrent/types.h"
+
+#include <chrono>
 #include <cstddef>
 #include <cstdint>
 #include <string>
@@ -31,43 +38,148 @@ enum class PeerSource : std::uint8_t {
 
 class PeerList {
 public:
-    struct Endpoint { std::string ip; std::uint16_t port; };
+    using Clock = std::chrono::steady_clock;
 
-    struct Peer {
+    struct Endpoint {
         std::string   ip;
-        std::uint16_t port       = 0;
-        std::uint8_t  sources    = 0;
-        bool          connected  = false;
-        bool          connecting = false;
-        bool          banned     = false;
-        std::uint32_t fail_count = 0;
+        std::uint16_t port;
+        /// Whether to open this attempt with an MSE handshake. Only consulted when
+        /// the session's policy is EncPolicy::Enabled, where it alternates per
+        /// attempt so a peer that refuses one form is reached with the other.
+        bool          prefer_encrypted = true;
+        /// Whether to dial over uTP rather than TCP. Only consulted when the
+        /// session has outgoing uTP enabled.
+        bool          prefer_utp = true;
+    };
+
+    struct Peer {
+        std::string       ip;
+        std::uint16_t     port       = 0;
+        std::uint8_t      sources    = 0;
+        bool              connected  = false;
+        bool              connecting = false;
+        bool              banned     = false;
+        std::uint32_t     fail_count = 0;
+        /// When our last connection to this peer *ended*. Zero until one does,
+        /// which is what lets a freshly discovered peer be dialed immediately.
+        Clock::time_point last_attempt{};
+        /// Whether the next dial should be obfuscated. Starts true — nearly every
+        /// client in the swarm speaks MSE, and a good part of it accepts nothing
+        /// else — and flips on each attempt so a peer is eventually tried both
+        /// ways. A completed handshake pins it to whatever actually worked.
+        bool              prefer_encrypted = true;
+        /// How many backoff waivers this peer has already been granted; see
+        /// kMaxFastReconnects.
+        std::uint8_t      fast_reconnects  = 0;
+        /// Optimism: assume every peer speaks uTP until one proves otherwise, since
+        /// most of the swarm does and a peer that does not costs exactly one wasted
+        /// dial to discover (which the fast-reconnect waiver then makes free).
+        /// Cleared by the first uTP dial that fails to reach a handshake.
+        bool              supports_utp = true;
+        /// A uTP connection to this peer has actually worked. Outranks the guess
+        /// above and is never withdrawn: a peer that answered uTP once will answer
+        /// it again, and a later failure is far more likely to be the peer being
+        /// gone than the transport being wrong.
+        bool              confirmed_supports_utp = false;
     };
 
     static constexpr std::uint32_t kMaxFails = 5;
 
+    /// Base reconnect delay, scaled by the failure count: a peer is not re-dialed
+    /// until (fail_count + 1) * kMinReconnectInterval has passed since the last
+    /// attempt. Without it a peer that accepts TCP and then drops us — a client
+    /// that requires encryption does exactly this — is re-dialed on every torrent
+    /// tick, once a second, forever, while genuinely useful addresses wait behind
+    /// it. Mirrors libtorrent's min_reconnect_time (60 s) and its
+    /// `session_time - last_connected < (failcount + 1) * min_reconnect_time` gate.
+    static constexpr std::chrono::seconds kMinReconnectInterval{60};
+
+    /// How many times a peer may skip that wait to try the *other* encryption
+    /// form (see Disconnect::FailedRetryNow). Two covers both alternations; past
+    /// that a peer that keeps refusing us waits its turn like any other, which is
+    /// what stops an endless one-second ping-pong with a peer that rejects both.
+    /// Mirrors libtorrent's cap on torrent_peer::fast_reconnects.
+    static constexpr std::uint8_t kMaxFastReconnects = 2;
+
     /// Add or merge a candidate. Returns true if it was newly created.
     bool add(const std::string& ip, std::uint16_t port, PeerSource source);
 
-    /// Up to @p max eligible peers to dial (not connected/connecting/banned, and
-    /// under the failure limit), best first. The returned peers are marked
-    /// `connecting` so they aren't handed out again until resolved.
-    std::vector<Endpoint> connect_candidates(std::size_t max);
+    /// Up to @p max eligible peers to dial (not connected/connecting/banned, under
+    /// the failure limit, and past their reconnect backoff at @p now), best first.
+    /// The returned peers are marked `connecting` so they aren't handed out again
+    /// until the attempt resolves.
+    std::vector<Endpoint> connect_candidates(std::size_t max, Clock::time_point now);
+
+    /// The peer completed its handshake: it is a live connection, and whatever
+    /// failures it accumulated getting here no longer count against it.
+    /// @p encrypted records whether that took MSE, so the next dial starts there
+    /// instead of paying for the alternation again; @p transport does the same for
+    /// the wire it arrived on.
+    void set_connected(const std::string& ip, std::uint16_t port, bool encrypted,
+                       PeerTransport transport = PeerTransport::Tcp);
+
+    /// An outgoing uTP dial to this peer never reached a handshake. Take it as
+    /// evidence the peer has no uTP — the overwhelmingly likely cause, since a peer
+    /// whose TCP port is reachable usually has the UDP one blocked rather than the
+    /// other way round — and dial it over TCP from here on. Paired with
+    /// Disconnect::FailedRetryNow, so the TCP attempt happens immediately rather
+    /// than after the backoff: the whole point is that one wasted dial costs
+    /// nothing but a round trip.
+    void note_utp_dial_failed(const std::string& ip, std::uint16_t port);
+
+    /// Why a connection to this peer ended — the three cases earn different
+    /// treatment on the way back in.
+    enum class Disconnect {
+        /// It never became usable: refused mid-handshake, protocol error, dropped
+        /// before the handshake completed. Penalised and backed off.
+        Failed,
+        /// Failed as above, but we dialed one of two alternating encryption forms
+        /// and the other is worth trying at once — the peer very likely refused
+        /// the handshake we opened with, not us. Penalised like Failed (so a peer
+        /// that rejects both still runs out of chances) but made eligible
+        /// immediately instead of waiting out a minute to learn a one-bit answer.
+        /// Granted at most kMaxFastReconnects times per peer. libtorrent's
+        /// fast_reconnect, which rewinds last_connected for the same reason.
+        FailedRetryNow,
+        /// It carried a real session and then ended. No penalty, but still backed
+        /// off — re-opening a connection the peer just closed helps nobody.
+        Clean,
+        /// *We* dropped it for our own reasons (pausing the torrent), and nothing
+        /// about the peer changed. Neither penalised nor backed off, so a resume
+        /// dials straight back. This is libtorrent's fast_reconnect: it is the one
+        /// case where last_connected is deliberately left unstamped.
+        Release,
+    };
+
+    /// A connection to this peer ended; see Disconnect for how @p how is treated.
+    void on_disconnected(const std::string& ip, std::uint16_t port, Disconnect how,
+                         Clock::time_point now);
+
+    /// The outbound connect itself never completed (refused, unreachable, timed out).
+    void on_connect_failed(const std::string& ip, std::uint16_t port, Clock::time_point now);
 
-    void set_connected(const std::string& ip, std::uint16_t port, bool connected);
-    void on_connect_failed(const std::string& ip, std::uint16_t port);
     void ban(const std::string& ip, std::uint16_t port);
 
-    std::size_t size()           const noexcept { return peers_.size(); }
-    std::size_t num_candidates() const;          ///< count currently eligible to dial
+    std::size_t size() const noexcept { return peers_.size(); }
+    /// Count of peers currently eligible to dial at @p now (backoff included).
+    std::size_t num_candidates(Clock::time_point now) const;
     bool        contains(const std::string& ip, std::uint16_t port) const;
 
 private:
     static std::string key(const std::string& ip, std::uint16_t port) {
         return ip + ":" + std::to_string(port);
     }
+    /// Eligible ignoring time: not already in play, not banned, chances left.
     bool eligible(const Peer& p) const noexcept {
         return !p.connected && !p.connecting && !p.banned && p.fail_count < kMaxFails;
     }
+    /// Eligible *and* past its reconnect backoff. A peer never dialed
+    /// (last_attempt == {}) is always ready.
+    bool ready(const Peer& p, Clock::time_point now) const noexcept {
+        if (!eligible(p)) return false;
+        if (p.last_attempt == Clock::time_point{}) return true;
+        return now - p.last_attempt >= (p.fail_count + 1) * kMinReconnectInterval;
+    }
 
     std::unordered_map<std::string, Peer> peers_;
 };

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

@@ -77,7 +77,12 @@ void Torrent::stop() {
         trackers_->stop();                          // drains the in-flight Stopped announce
         trackers_.reset();
     }
-    for (PeerConnection* pc : peers_) pc->close("torrent stopped");
+    // Snapshot + release, for the same two reasons as pause(): close() runs
+    // on_closed inline and erases from peers_ mid-loop, and a peer we drop on our
+    // own way out has not failed us.
+    releasing_peers_ = true;
+    for (PeerConnection* pc : std::vector<PeerConnection*>(peers_)) pc->close("torrent stopped");
+    releasing_peers_ = false;
     peers_.clear();
     outstanding_.clear();
     recent_down_.clear();
@@ -145,7 +150,14 @@ void Torrent::pause() {
     LOG_INFO("bt.torrent", short_hash(info_hash()) << " paused (" << peers_.size() << " peers dropped)");
     // Drop all peers and their per-peer request state, but keep picker_/disk_ so a
     // later resume() does not have to re-hash what is already on disk.
-    for (PeerConnection* pc : peers_) pc->close("torrent paused");
+    //
+    // These peers did nothing wrong, so release them without the reconnect penalty
+    // — otherwise resume() would sit out the backoff before it could dial the very
+    // peers it just dropped. Iterate a SNAPSHOT: close() runs on_closed inline,
+    // which erases from peers_ (see the same hazard in on_check_complete).
+    releasing_peers_ = true;
+    for (PeerConnection* pc : std::vector<PeerConnection*>(peers_)) pc->close("torrent paused");
+    releasing_peers_ = false;
     peers_.clear();
     outstanding_.clear();
     request_time_.clear();
@@ -176,14 +188,24 @@ void Torrent::add_peer(const std::string& ip, std::uint16_t port) {
         post([this] { try_connect(); });
 }
 
+std::function<void(const std::string&, std::uint16_t)> Torrent::dht_peer_sink() {
+    // Safe to capture `this` bare: the host re-resolves the torrent by info-hash on
+    // the reactor thread before invoking this, and removal happens only there, so a
+    // torrent that is still registered when the sink runs is still alive.
+    return [this](const std::string& ip, std::uint16_t port) {
+        if (peer_list_.add(ip, port, PeerSource::Dht)) try_connect();
+    };
+}
+
 void Torrent::try_connect() {
     if (!running_ || paused_ || peers_.size() >= kMaxPeers) return;
-    auto candidates = peer_list_.connect_candidates(kMaxPeers - peers_.size());
-    for (const auto& c : candidates) host_.connect_peer(*this, c.ip, c.port);
+    auto candidates = peer_list_.connect_candidates(kMaxPeers - peers_.size(),
+                                                    PeerList::Clock::now());
+    for (const auto& c : candidates) host_.connect_peer(*this, c);
 }
 
 void Torrent::on_connect_failed(const std::string& ip, std::uint16_t port) {
-    peer_list_.on_connect_failed(ip, port);
+    peer_list_.on_connect_failed(ip, port, PeerList::Clock::now());
 }
 
 // ---- scheduling ----
@@ -207,16 +229,19 @@ void Torrent::tick() {
     // Ask the DHT for fresh peers periodically (every ~30 s).
     if (tick_count_ % 30 == 1) {
         LOG_DEBUG("bt.torrent", short_hash(info_hash()) << " → DHT get_peers");
-        host_.find_peers_via_dht(info_hash(), [this](const std::string& ip, std::uint16_t port) {
-            if (peer_list_.add(ip, port, PeerSource::Dht)) try_connect();
-        });
+        host_.find_peers_via_dht(info_hash(), dht_peer_sink());
     }
     // Announce ourselves to the DHT so others can find us — promptly on startup,
     // then every ~15 min per BEP 5 (H15). Was previously never done → undiscoverable.
+    //
+    // The announce is a get_peers traversal with an announce_peer at the end, so it
+    // sees the very peers we are looking for. Dropping them meant a magnet waited
+    // for the *next* find_peers round (~30 s) to be told about addresses the node
+    // already had in hand — half the wait before the first live peer, for nothing.
     if (tick_count_ % 900 == 5) {
         LOG_DEBUG("bt.torrent", short_hash(info_hash()) << " → DHT announce_peer port "
                                 << host_.listen_port());
-        host_.announce_to_dht(info_hash(), host_.listen_port());
+        host_.announce_to_dht(info_hash(), host_.listen_port(), dht_peer_sink());
     }
     // Re-announce when the tracker's requested interval has elapsed (H13).
     if (tick_count_ >= next_announce_tick_) {
@@ -253,7 +278,7 @@ void Torrent::on_handshake(PeerConnection& pc, const InfoHash&, const PeerId&) {
     peers_.push_back(&pc);
     outstanding_[&pc] = 0;
     recent_down_[&pc] = 0;
-    peer_list_.set_connected(pc.remote_ip(), pc.remote_port(), true);
+    peer_list_.set_connected(pc.remote_ip(), pc.remote_port(), pc.encrypted(), pc.transport());
     // Milestone: the first peer on a torrent is worth an INFO line; the rest are
     // routine (each peer's handshake is already logged at DEBUG in bt.peer).
     if (peers_.size() == 1)
@@ -512,7 +537,25 @@ void Torrent::on_request(PeerConnection& pc, std::uint32_t piece, std::uint32_t
 }
 
 void Torrent::on_closed(PeerConnection& pc, const std::string&) {
-    peer_list_.set_connected(pc.remote_ip(), pc.remote_port(), false);
+    // A connection that died before the handshake completed never gave us anything;
+    // count it against the peer so it backs off instead of being re-dialed on the
+    // next tick — without the penalty we would hammer it once a second for as long
+    // as the torrent lives. Two exceptions: a peer we dropped ourselves (pause) is
+    // neither penalised nor delayed, and a dial that may simply have opened with the
+    // wrong form of handshake is penalised but not delayed, so the other form can be
+    // tried at once rather than a minute later. See PeerList::Disconnect.
+    const auto how = releasing_peers_      ? PeerList::Disconnect::Release
+                     : pc.handshake_done() ? PeerList::Disconnect::Clean
+                     : pc.fast_reconnect() ? PeerList::Disconnect::FailedRetryNow
+                                           : PeerList::Disconnect::Failed;
+    // A dial we opened over uTP that never reached a handshake says something the
+    // failure count alone does not: this peer probably has no uTP at all. Record it
+    // so the immediate retry above goes out over TCP instead of repeating itself.
+    // Only for outgoing connections — an inbound uTP peer that drops us proves the
+    // transport works, whatever else went wrong.
+    if (pc.outgoing() && pc.transport() == PeerTransport::Utp && !pc.handshake_done())
+        peer_list_.note_utp_dial_failed(pc.remote_ip(), pc.remote_port());
+    peer_list_.on_disconnected(pc.remote_ip(), pc.remote_port(), how, PeerList::Clock::now());
     pex_sent_.erase(&pc);
     remove_peer(&pc);
 }

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

@@ -53,7 +53,10 @@ class Torrent;
 class RATS_API TorrentHost {
 public:
     virtual ~TorrentHost() = default;
-    virtual void          connect_peer(Torrent& torrent, const std::string& ip, std::uint16_t port) = 0;
+    /// Dial a peer for @p torrent. The endpoint carries the PeerList's per-peer
+    /// preferences (MSE alternation, uTP-or-TCP); the host combines them with the
+    /// session's own policy, which may override either.
+    virtual void          connect_peer(Torrent& torrent, const PeerList::Endpoint& peer) = 0;
     virtual const PeerId& peer_id() const = 0;
     virtual std::uint16_t listen_port() const = 0;
     /// Discover peers for @p info_hash via the DHT (if the host has one); each
@@ -61,8 +64,12 @@ public:
     virtual void find_peers_via_dht(const InfoHash& /*info_hash*/,
                                     std::function<void(const std::string& ip, std::uint16_t port)> /*on_peer*/) {}
     /// Announce ourselves to the DHT for @p info_hash on @p port so other clients
-    /// doing get_peers can find us (BEP 5). Default no-op (no DHT attached).
-    virtual void announce_to_dht(const InfoHash& /*info_hash*/, std::uint16_t /*port*/) {}
+    /// doing get_peers can find us (BEP 5). An announce *is* a get_peers traversal
+    /// with a write at the end, so it discovers peers as a side effect; they are
+    /// delivered to @p on_peer on the reactor thread exactly like find_peers_via_dht's
+    /// are, rather than being thrown away. Default no-op (no DHT attached).
+    virtual 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*/ = {}) {}
 };
 
 class RATS_API Torrent final : public PeerConnection::Observer {
@@ -143,6 +150,15 @@ public:
     void on_closed(PeerConnection&, const std::string& reason) override;
 
 private:
+    /// Set while pause() is tearing down its peers, so on_closed can tell "we let
+    /// this peer go" from "this peer failed on us" and skip the reconnect penalty.
+    bool releasing_peers_ = false;
+
+    /// The callback both DHT paths (find_peers and announce) hand to the host:
+    /// merge the address into peer_list_ and dial if it is new. Runs on the
+    /// reactor thread — the host marshals it there.
+    std::function<void(const std::string&, std::uint16_t)> dht_peer_sink();
+
     /// Post @p fn to the reactor, guarded by alive_ so it is dropped if this
     /// torrent has since been destroyed. Disk and tracker completions run on their
     /// own worker threads and marshal back through here; a completion that a worker

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

@@ -32,6 +32,33 @@ using PeerId = std::array<std::uint8_t, kPeerIdSize>;
 /// The 8 reserved bytes exchanged in the BitTorrent handshake.
 using ReservedBytes = std::array<std::uint8_t, 8>;
 
+/// How willing we are to speak MSE/PE (see bittorrent/mse.h). Named and valued
+/// after libtorrent's pe_forced / pe_enabled / pe_disabled so the behaviour is
+/// recognisable to anyone who has configured a BitTorrent client before.
+enum class EncPolicy {
+    /// Obfuscated connections only. Plaintext is refused in both directions.
+    Forced,
+    /// Both are acceptable. Outgoing dials alternate — MSE first, plaintext on the
+    /// peer's next attempt — so a peer that rejects one is reached with the other.
+    Enabled,
+    /// Never speak MSE: dial in plaintext, refuse obfuscated inbound connections.
+    Disabled,
+};
+
+/// Which wire a peer connection is carried on. Both are first-class: the
+/// BitTorrent protocol above them is byte-for-byte identical, and a peer reached
+/// either way is treated the same everywhere except when deciding how to dial it
+/// again (see PeerList::Peer::supports_utp).
+enum class PeerTransport : std::uint8_t {
+    /// A kernel TCP socket. Always available, universally reachable, and rude to
+    /// everything else sharing the uplink.
+    Tcp,
+    /// uTP (BEP 29) over the session's one shared UDP socket: same guarantees,
+    /// delay-based congestion control that yields to TCP instead of competing with
+    /// it, and one NAT mapping for the whole swarm.
+    Utp,
+};
+
 // ---- Protocol constants ----
 constexpr char          kProtocolString[]    = "BitTorrent protocol";  // 19 chars (+NUL)
 constexpr std::size_t   kProtocolStringLen   = 19;

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

@@ -0,0 +1,234 @@
+#include "librats/bittorrent/utp_manager.h"
+
+#include "librats/bittorrent/log.h"
+
+#include <algorithm>
+#include <random>
+
+namespace librats::bittorrent::utp {
+
+namespace {
+
+std::uint16_t random_id() {
+    static thread_local std::mt19937 rng{std::random_device{}()};
+    // Leave room for the +1: the pair must not straddle the wrap, or the two ids
+    // would not be adjacent in the arithmetic every peer uses to derive them.
+    return std::uint16_t(std::uniform_int_distribution<std::uint32_t>(1, 0xfffd)(rng));
+}
+
+/// Datagrams read per readable event before we go back to the poller. Without a
+/// bound, a peer able to fill the socket faster than we drain it would keep the
+/// loop here indefinitely and starve every other connection and timer.
+constexpr int kMaxRecvPerWakeup = 256;
+
+} // namespace
+
+Manager::Manager(Reactor& reactor) : reactor_(reactor) {}
+
+Manager::~Manager() {
+    close();
+}
+
+bool Manager::open(std::uint16_t port, const std::string& bind_address) {
+    if (is_open()) return true;
+    // Exclusive, and this is the one place in the library where that matters. The
+    // port we want by protocol is the torrent port, which the DHT is very often
+    // already serving on UDP — mainline BitTorrent puts them on one number. A
+    // Shared bind succeeds there and then the two sockets split the datagrams
+    // between them: every uTP answer that lands on the DHT socket is a dial that
+    // times out for no visible reason, and every KRPC reply that lands here is a
+    // DHT query that goes unanswered. Failing instead lets the caller take a port
+    // that is really ours.
+    socket_ = create_udp_socket(int(port), bind_address, AddressFamily::IPv4,
+                                UdpPortMode::Exclusive);
+    if (!is_valid_socket(socket_)) return false;
+    set_socket_nonblocking(socket_);
+    port_ = std::uint16_t(get_bound_port(socket_));
+    if (!reactor_.add(socket_, PollIn, [this](std::uint32_t) { on_readable(); })) {
+        close_socket(socket_);
+        socket_ = RATS_INVALID_SOCKET;
+        port_   = 0;
+        return false;
+    }
+    tick_timer_ = reactor_.schedule(kTickInterval, [this] { tick(); });
+    LOG_INFO("bt.utp", "uTP listening on UDP port " << port_);
+    return true;
+}
+
+void Manager::close() {
+    if (tick_timer_ != kInvalidTimerId) {
+        reactor_.cancel(tick_timer_);
+        tick_timer_ = kInvalidTimerId;
+    }
+    if (is_valid_socket(socket_)) {
+        reactor_.remove(socket_);
+        close_socket(socket_);
+        socket_ = RATS_INVALID_SOCKET;
+    }
+    port_ = 0;
+    deferred_.clear();
+    streams_.clear();
+}
+
+// ---- Host --------------------------------------------------------------------
+
+void Manager::utp_send(const Address& to, const std::uint8_t* data, std::size_t len) {
+    if (!is_valid_socket(socket_)) return;
+    // A datagram that will not fit in the socket's send buffer is simply dropped:
+    // that is exactly what a congested link does to it a hop later, and the stream's
+    // retransmission timer is already the recovery path for it.
+    send_udp_to(socket_, data, len, to, AddressFamily::IPv4);
+}
+
+void Manager::utp_defer_ack(Stream& s) {
+    deferred_.push_back(&s);
+}
+
+// ---- Streams -----------------------------------------------------------------
+
+Stream* Manager::find(const Address& from, std::uint16_t id) {
+    auto range = streams_.equal_range(id);
+    for (auto it = range.first; it != range.second; ++it) {
+        if (it->second->matches(from, id)) return it->second.get();
+    }
+    return nullptr;
+}
+
+Stream* Manager::connect(const Address& to) {
+    if (!is_open() || streams_.size() >= kMaxStreams) return nullptr;
+
+    // The initiator picks the id it will *receive* on and derives the send id from
+    // it. Retry a few times so two live connections to the same peer cannot collide
+    // on an id — the pair (id, endpoint) is what identifies a stream.
+    std::uint16_t recv_id = 0;
+    for (int attempt = 0; attempt < 8; ++attempt) {
+        recv_id = random_id();
+        if (find(to, recv_id) == nullptr) break;
+        recv_id = 0;
+    }
+    if (recv_id == 0) return nullptr;
+
+    auto    s   = std::make_unique<Stream>(*this, recv_id, std::uint16_t(recv_id + 1));
+    Stream* raw = s.get();
+    streams_.emplace(recv_id, std::move(s));
+    raw->connect(to, Stream::Clock::now());
+    return raw;
+}
+
+void Manager::release(Stream& s) {
+    s.detach();
+    s.close(Stream::Clock::now());
+    // Not erased here: close() may still owe the peer a FIN, and we may be inside
+    // an iteration over streams_ right now. reap() collects it once it is done.
+}
+
+// ---- I/O ---------------------------------------------------------------------
+
+void Manager::on_readable() {
+    std::uint8_t buf[kMaxRecvDatagram];
+    const auto   now = Stream::Clock::now();
+
+    for (int i = 0; i < kMaxRecvPerWakeup; ++i) {
+        Address              from;
+        const std::ptrdiff_t n = recv_udp_from(socket_, buf, sizeof(buf), from);
+        if (n == kUdpRecvWouldBlock) break;
+        // kUdpRecvError covers an ICMP unreachable for some *other* destination,
+        // reported against the shared socket. It says nothing about this socket, so
+        // keep draining rather than dropping every peer over one dead address.
+        if (n == kUdpRecvError) continue;
+        if (n < std::ptrdiff_t(kHeaderSize)) continue;
+        handle_datagram(buf, std::size_t(n), from, now);
+    }
+
+    flush_deferred_acks(now);
+    reap(now);
+}
+
+void Manager::handle_datagram(const std::uint8_t* data, std::size_t len, const Address& from,
+                              Stream::Clock::time_point now) {
+    Header h;
+    if (!parse_header(data, len, h)) return;
+
+    if (Stream* s = find(from, h.connection_id); s != nullptr) {
+        s->on_packet(data, len, from, now);
+        return;
+    }
+
+    // Nothing is registered under that id. Only a SYN may create a stream; anything
+    // else names a connection that no longer exists. We answer with silence rather
+    // than a reset: the sender is unauthenticated, and a reset would make this
+    // socket a reflector that answers every spoofed datagram with one of its own.
+    if (h.type != PacketType::Syn) return;
+
+    // A retransmitted SYN — the answer to the first one was lost. The stream it
+    // created is registered under id + 1, which is not the id the SYN carries, so
+    // it has to be looked up explicitly. Without this a peer whose SYN-ack went
+    // missing would leave a duplicate stream behind on every retry.
+    if (Stream* s = find(from, std::uint16_t(h.connection_id + 1)); s != nullptr) {
+        s->on_packet(data, len, from, now);
+        return;
+    }
+
+    if (!accept_incoming_ || streams_.size() >= kMaxStreams) return;
+
+    const std::uint16_t send_id = h.connection_id;
+    const std::uint16_t recv_id = std::uint16_t(h.connection_id + 1);
+    auto                s       = std::make_unique<Stream>(*this, recv_id, send_id);
+    Stream*             raw     = s.get();
+    streams_.emplace(recv_id, std::move(s));
+
+    if (!raw->on_packet(data, len, from, now)) {
+        // The SYN did not survive the stream's own checks; drop the stream again
+        // rather than leave an unusable one behind.
+        raw->reset(now);
+        return;
+    }
+    LOG_DEBUG("bt.utp", "inbound uTP stream from " << from.to_string()
+                        << " (id " << recv_id << ')');
+    if (accept_) accept_(*raw);
+
+    // The handler takes ownership by installing an observer. If it declined — the
+    // session-wide connection cap, or no handler at all — the stream would otherwise
+    // sit here connected and unreaped forever, since nothing would ever close it.
+    // Tell the peer rather than let it retransmit into a stream nobody is reading.
+    if (!raw->has_observer()) raw->reset(now);
+}
+
+void Manager::flush_deferred_acks(Stream::Clock::time_point now) {
+    if (deferred_.empty()) return;
+    // A stream may have registered more than once during the drain; the second
+    // flush is a no-op because send_deferred_ack() clears the flag.
+    for (Stream* s : deferred_) s->send_deferred_ack(now);
+    deferred_.clear();
+}
+
+void Manager::tick() {
+    const auto now = Stream::Clock::now();
+
+    // Snapshot first: a stream's timeout fires its observer, which may close a
+    // PeerConnection and release streams back to us mid-iteration.
+    scratch_.clear();
+    scratch_.reserve(streams_.size());
+    for (auto& [id, s] : streams_) scratch_.push_back(s.get());
+    for (Stream* s : scratch_) s->tick(now);
+    scratch_.clear();
+
+    flush_deferred_acks(now);
+    reap(now);
+
+    tick_timer_ = reactor_.schedule(kTickInterval, [this] { tick(); });
+}
+
+void Manager::reap(Stream::Clock::time_point now) {
+    for (auto it = streams_.begin(); it != streams_.end();) {
+        // A stream that still has an observer belongs to a live PeerConnection and
+        // is that connection's to end, however dead it looks from here.
+        if (!it->second->has_observer() && it->second->reapable(now)) {
+            it = streams_.erase(it);
+        } else {
+            ++it;
+        }
+    }
+}
+
+} // namespace librats::bittorrent::utp