librats 1.0.2 → 2.2.0

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

@@ -0,0 +1,206 @@
+#include "librats/bittorrent/types.h"
+
+#include <cstdio>
+#include <cstring>
+#include <random>
+
+namespace librats::bittorrent {
+
+// =============================================================================
+// Hex / identity helpers
+// =============================================================================
+
+std::string to_hex(const std::uint8_t* data, std::size_t len) {
+    static const char digits[] = "0123456789abcdef";
+    std::string out;
+    out.resize(len * 2);
+    for (std::size_t i = 0; i < len; ++i) {
+        out[i * 2]     = digits[data[i] >> 4];
+        out[i * 2 + 1] = digits[data[i] & 0x0F];
+    }
+    return out;
+}
+
+std::optional<InfoHash> info_hash_from_hex(const std::string& hex) {
+    if (hex.size() != kInfoHashSize * 2) return std::nullopt;
+
+    auto nibble = [](char c) -> int {
+        if (c >= '0' && c <= '9') return c - '0';
+        if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+        if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+        return -1;
+    };
+
+    InfoHash out{};
+    for (std::size_t i = 0; i < kInfoHashSize; ++i) {
+        const int hi = nibble(hex[i * 2]);
+        const int lo = nibble(hex[i * 2 + 1]);
+        if (hi < 0 || lo < 0) return std::nullopt;
+        out[i] = std::uint8_t(hi << 4 | lo);
+    }
+    return out;
+}
+
+bool is_all_zero(const std::array<std::uint8_t, 20>& id) noexcept {
+    for (std::uint8_t b : id) if (b != 0) return false;
+    return true;
+}
+
+PeerId generate_peer_id(const std::string& client_prefix) {
+    PeerId id{};
+    const std::size_t prefix_len = (std::min)(client_prefix.size(), kPeerIdSize);
+    for (std::size_t i = 0; i < prefix_len; ++i) id[i] = std::uint8_t(client_prefix[i]);
+
+    std::random_device rd;
+    std::mt19937 gen(rd());
+    std::uniform_int_distribution<int> dist(0, 255);
+    for (std::size_t i = prefix_len; i < kPeerIdSize; ++i) id[i] = std::uint8_t(dist(gen));
+
+    return id;
+}
+
+// =============================================================================
+// Client identification (BEP 20)
+//
+// Ported from the prior librats implementation: recognises the Azureus,
+// Shadow and Mainline encodings plus a long table of non-standard clients.
+// =============================================================================
+
+namespace {
+
+int decode_version_digit(std::uint8_t c) {
+    if (c >= '0' && c <= '9') return c - '0';
+    if (c >= 'A' && c <= 'Z') return c - 'A' + 10;
+    if (c >= 'a' && c <= 'z') return c - 'a' + 10;
+    return 0;
+}
+
+const char* lookup_az_client(const char* code) {
+    struct Entry { const char* code; const char* name; };
+    static const Entry entries[] = {
+        {"7T","aTorrent"},{"AB","AnyEvent BitTorrent"},{"AG","Ares"},{"AR","Arctic Torrent"},
+        {"AT","Artemis"},{"AV","Avicora"},{"AX","BitPump"},{"AZ","Azureus"},{"A~","Ares"},
+        {"BB","BitBuddy"},{"BC","BitComet"},{"BE","baretorrent"},{"BF","Bitflu"},{"BG","BTG"},
+        {"BI","BiglyBT"},{"BL","BitBlinder"},{"BP","BitTorrent Pro"},{"BR","BitRocket"},
+        {"BS","BTSlave"},{"BT","BitTorrent"},{"BU","BigUp"},{"BW","BitWombat"},{"BX","BittorrentX"},
+        {"CD","Enhanced CTorrent"},{"CT","CTorrent"},{"DE","Deluge"},{"DP","Propagate Data Client"},
+        {"EB","EBit"},{"ES","electric sheep"},{"FC","FileCroc"},{"FT","FoxTorrent"},{"FW","FrostWire"},
+        {"FX","Freebox BitTorrent"},{"GS","GSTorrent"},{"HK","Hekate"},{"HL","Halite"},{"HN","Hydranode"},
+        {"IL","iLivid"},{"KC","Koinonein"},{"KG","KGet"},{"KT","KTorrent"},{"LC","LeechCraft"},
+        {"LH","LH-ABC"},{"LK","Linkage"},{"LP","lphant"},{"LR","librats"},{"LT","libtorrent"},
+        {"LW","Limewire"},{"ML","MLDonkey"},{"MO","Mono Torrent"},{"MP","MooPolice"},{"MR","Miro"},
+        {"MT","Moonlight Torrent"},{"NX","Net Transport"},{"OS","OneSwarm"},{"OT","OmegaTorrent"},
+        {"PD","Pando"},{"QD","QQDownload"},{"QT","Qt 4"},{"RT","Retriever"},{"RZ","RezTorrent"},
+        {"SB","Swiftbit"},{"SD","Xunlei"},{"SK","spark"},{"SN","ShareNet"},{"SS","SwarmScope"},
+        {"ST","SymTorrent"},{"SZ","Shareaza"},{"S~","Shareaza (beta)"},{"TB","Torch"},{"TL","Tribler"},
+        {"TN","Torrent.NET"},{"TR","Transmission"},{"TS","TorrentStorm"},{"TT","TuoTu"},{"UL","uLeecher"},
+        {"UM","uTorrent Mac"},{"UT","uTorrent"},{"VG","Vagaa"},{"WT","BitLet"},{"WY","FireTorrent"},
+        {"XF","Xfplay"},{"XL","Xunlei"},{"XS","XSwifter"},{"XT","XanTorrent"},{"XX","Xtorrent"},
+        {"ZO","Zona"},{"ZT","ZipTorrent"},{"lt","rTorrent"},{"pX","pHoeniX"},{"qB","qBittorrent"},
+        {"st","SharkTorrent"},
+    };
+    for (const auto& e : entries) {
+        if (e.code[0] == code[0] && e.code[1] == code[1]) return e.name;
+    }
+    return nullptr;
+}
+
+const char* lookup_generic_client(const std::uint8_t* id) {
+    struct Entry { int offset; const char* pattern; const char* name; };
+    static const Entry entries[] = {
+        {0,"Deadman Walking-","Deadman"},{5,"Azureus","Azureus 2.0.3.2"},{0,"DansClient","XanTorrent"},
+        {4,"btfans","SimpleBT"},{0,"PRC.P---","Bittorrent Plus! II"},{0,"P87.P---","Bittorrent Plus!"},
+        {0,"S587Plus","Bittorrent Plus!"},{0,"martini","Martini Man"},{0,"Plus---","Bittorrent Plus"},
+        {0,"turbobt","TurboBT"},{0,"a00---0","Swarmy"},{0,"a02---0","Swarmy"},{0,"T00---0","Teeweety"},
+        {0,"BTDWV-","Deadman Walking"},{2,"BS","BitSpirit"},{0,"-SP","BitSpirit 3.6"},{0,"Pando-","Pando"},
+        {0,"LIME","LimeWire"},{0,"btuga","BTugaXP"},{0,"oernu","BTugaXP"},{0,"Mbrst","Burst!"},
+        {0,"PEERAPP","PeerApp"},{0,"Plus","Plus!"},{0,"-Qt-","Qt"},{0,"exbc","BitComet"},
+        {0,"DNA","BitTorrent DNA"},{0,"-G3","G3 Torrent"},{0,"-FG","FlashGet"},{0,"-ML","MLdonkey"},
+        {0,"-MG","Media Get"},{0,"XBT","XBT"},{0,"OP","Opera"},{2,"RS","Rufus"},{0,"AZ2500BT","BitTyrant"},
+        {0,"btpd/","BitTorrent Protocol Daemon"},{0,"TIX","Tixati"},{0,"QVOD","Qvod"},
+    };
+    for (const auto& e : entries) {
+        const std::size_t len = std::strlen(e.pattern);
+        if (std::size_t(e.offset) + len <= kPeerIdSize &&
+            std::memcmp(id + e.offset, e.pattern, len) == 0) {
+            return e.name;
+        }
+    }
+    return nullptr;
+}
+
+} // namespace
+
+std::string identify_client(const PeerId& id) {
+    if (is_all_zero(id)) return "Unknown";
+
+    if (const char* generic = lookup_generic_client(id.data())) return generic;
+
+    // Bits on Wheels special case: "-BOW...-"
+    if (id[0] == '-' && id[1] == 'B' && id[2] == 'O' && id[3] == 'W' && id[7] == '-') {
+        return "Bits on Wheels " + std::string(reinterpret_cast<const char*>(id.data()) + 4, 3);
+    }
+
+    // Azureus-style: -XX1234-
+    if (id[0] == '-' && id[7] == '-' &&
+        id[3] >= '0' && id[4] >= '0' && id[5] >= '0' && id[6] >= '0') {
+        const char code[3] = {char(id[1]), char(id[2]), '\0'};
+        const int v1 = decode_version_digit(id[3]);
+        const int v2 = decode_version_digit(id[4]);
+        const int v3 = decode_version_digit(id[5]);
+        const int v4 = decode_version_digit(id[6]);
+
+        const char* name = lookup_az_client(code);
+        std::string client = name ? name : std::string("Unknown (") + code + ")";
+        std::string version = std::to_string(v1) + "." + std::to_string(v2) + "." + std::to_string(v3);
+        if (v4 != 0) version += "." + std::to_string(v4);
+        return client + " " + version;
+    }
+
+    // Shadow-style: X + 3 version chars + "--", and Mainline-style: M1-2-3--
+    if ((id[0] >= 'A' && id[0] <= 'Z') || (id[0] >= 'a' && id[0] <= 'z')) {
+        if (id[4] == '-' && id[5] == '-' && id[1] >= '0' && id[2] >= '0' && id[3] >= '0') {
+            const char* name = nullptr;
+            switch (char(id[0])) {
+                case 'A': name = "ABC"; break;
+                case 'M': name = "Mainline"; break;
+                case 'O': name = "Osprey Permaseed"; break;
+                case 'Q': name = "BTQueue"; break;
+                case 'R': name = "Tribler"; break;
+                case 'S': name = "Shadow"; break;
+                case 'T': name = "BitTornado"; break;
+                case 'U': name = "UPnP"; break;
+                default: break;
+            }
+            if (name) {
+                return std::string(name) + " " + std::to_string(decode_version_digit(id[1])) + "." +
+                       std::to_string(decode_version_digit(id[2])) + "." +
+                       std::to_string(decode_version_digit(id[3]));
+            }
+        }
+
+        char ids[21];
+        std::memcpy(ids, id.data(), 20);
+        ids[20] = '\0';
+        char name_ch = '\0';
+        int v1 = 0, v2 = 0, v3 = 0;
+        if (std::sscanf(ids, "%c%3d-%3d-%3d--", &name_ch, &v1, &v2, &v3) == 4 && name_ch == 'M') {
+            return "Mainline " + std::to_string(v1) + "." + std::to_string(v2) + "." + std::to_string(v3);
+        }
+    }
+
+    bool first_12_zero = true;
+    for (int i = 0; i < 12; ++i) if (id[i] != 0) { first_12_zero = false; break; }
+    if (first_12_zero) {
+        if (id[12] == 0x97) return "Experimental 3.2.1b2";
+        if (id[12] == 0x00) return "Experimental 3.1";
+        return "Generic";
+    }
+
+    std::string unknown("Unknown [");
+    for (std::uint8_t c : id) unknown += (c >= 32 && c < 127) ? char(c) : '.';
+    unknown += "]";
+    return unknown;
+}
+
+} // namespace librats::bittorrent

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

@@ -0,0 +1,86 @@
+#pragma once
+
+/**
+ * @file types.h
+ * @brief Core BitTorrent identifiers, constants and small identity helpers.
+ *
+ * Everything BitTorrent-specific lives in namespace librats::bittorrent. The
+ * 20-byte InfoHash is intentionally the *same* std::array type as the DHT's
+ * librats::InfoHash, so handing an info-hash to DhtClient::find_peers /
+ * announce_peer is a zero-conversion pass-through — no glue, no copying.
+ */
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <optional>
+#include <string>
+
+namespace librats::bittorrent {
+
+// ---- Sizes (bytes) ----
+constexpr std::size_t kPeerIdSize   = 20;   ///< BEP 20 peer id length
+constexpr std::size_t kInfoHashSize = 20;   ///< SHA-1 of the bencoded info dictionary
+
+/// 20-byte info hash. Same underlying type as librats::InfoHash (std::array<uint8_t,20>),
+/// so it passes straight into DhtClient without conversion.
+using InfoHash = std::array<std::uint8_t, kInfoHashSize>;
+
+/// 20-byte peer identifier (BEP 20).
+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>;
+
+// ---- Protocol constants ----
+constexpr char          kProtocolString[]    = "BitTorrent protocol";  // 19 chars (+NUL)
+constexpr std::size_t   kProtocolStringLen   = 19;
+constexpr std::size_t   kHandshakeSize       = 68;          ///< 1 + 19 + 8 + 20 + 20
+constexpr std::uint32_t kBlockSize           = 16 * 1024;   ///< standard request block (16 KiB)
+constexpr std::uint32_t kMaxBlockSize        = 32 * 1024;   ///< largest block we will serve
+constexpr std::uint32_t kDefaultPieceLength  = 256 * 1024;  ///< default for created torrents
+constexpr std::uint32_t kMetadataPieceSize   = 16 * 1024;   ///< BEP 9 metadata block size
+/// Largest ut_metadata (BEP 9) info dict we will accept from a peer. The size is
+/// self-reported in the peer's extended handshake, so it must be capped before we
+/// allocate a buffer for it — otherwise a hostile peer advertising ~4 GiB triggers
+/// an out-of-memory allocation. libtorrent uses the same 4 MiB ceiling.
+constexpr std::uint32_t kMaxMetadataSize     = 4 * 1024 * 1024;
+
+// ---- Reserved-bit negotiation (handshake) ----
+// Each capability is a single bit in a specific reserved byte, per the relevant BEP.
+namespace reserved {
+    inline void enable_dht(ReservedBytes& r)        noexcept { r[7] |= 0x01; }  // BEP 5  DHT
+    inline void enable_fast(ReservedBytes& r)       noexcept { r[7] |= 0x04; }  // BEP 6  Fast
+    inline void enable_extensions(ReservedBytes& r) noexcept { r[5] |= 0x10; }  // BEP 10 Extension protocol
+
+    inline bool has_dht(const ReservedBytes& r)        noexcept { return (r[7] & 0x01) != 0; }
+    inline bool has_fast(const ReservedBytes& r)       noexcept { return (r[7] & 0x04) != 0; }
+    inline bool has_extensions(const ReservedBytes& r) noexcept { return (r[5] & 0x10) != 0; }
+} // namespace reserved
+
+// ---- Hex / identity helpers (defined in types.cpp) ----
+
+/// Lowercase hex of an arbitrary byte run.
+std::string to_hex(const std::uint8_t* data, std::size_t len);
+
+/// Lowercase hex of any 20-byte id (InfoHash or PeerId — they share the type).
+inline std::string to_hex(const std::array<std::uint8_t, 20>& id) {
+    return to_hex(id.data(), id.size());
+}
+
+/// Parse a 40-character hex string into an InfoHash. nullopt if the length is wrong
+/// or a non-hex character is present.
+std::optional<InfoHash> info_hash_from_hex(const std::string& hex);
+
+/// True when every byte is zero (an unset / invalid hash).
+bool is_all_zero(const std::array<std::uint8_t, 20>& id) noexcept;
+
+/// Generate an Azureus-style peer id: a prefix (≤8 chars, e.g. "-LR0001-" for
+/// librats v0.0.0.1) followed by a random tail filling the 20 bytes.
+PeerId generate_peer_id(const std::string& client_prefix = "-LR0001-");
+
+/// Best-effort human-readable client name + version from a peer id (BEP 20).
+/// Returns "Unknown [...]" for unrecognised ids.
+std::string identify_client(const PeerId& id);
+
+} // namespace librats::bittorrent

package/native-src/src/librats/core/address.cpp

@@ -0,0 +1,35 @@
+#include "librats/core/address.h"
+#include "librats/core/endpoint_parse.h"
+
+#include <cassert>
+
+namespace librats {
+
+Address::Address(std::string_view numeric_ip, uint16_t port) : port(port) {
+    if (auto a = IpAddress::parse(numeric_ip)) {
+        ip = *a;
+    } else {
+        // A hostname or garbage reached the numeric-only Address constructor. In
+        // release builds we leave ip unspecified (is_valid() will report false);
+        // in debug we trip so the offending call site is caught early.
+        assert(false && "Address(string, port): not a numeric IP literal — use HostEndpoint");
+    }
+}
+
+std::optional<Address> Address::parse(std::string_view text) {
+    const auto hp = split_host_port(text);
+    if (!hp) return std::nullopt;
+    // Address is strictly numeric: a hostname host reaches here only as a parse
+    // failure, which is exactly the rejection we want (that input is a HostEndpoint).
+    auto addr = IpAddress::parse(hp->first);
+    if (!addr) return std::nullopt;
+    return Address{*addr, hp->second};
+}
+
+std::string Address::to_string() const {
+    std::string s = ip.to_string();
+    if (ip.is_v6()) return "[" + s + "]:" + std::to_string(port);
+    return s + ":" + std::to_string(port);
+}
+
+} // namespace librats

package/native-src/src/librats/core/address.h

@@ -0,0 +1,78 @@
+#pragma once
+
+/**
+ * @file address.h
+ * @brief A dialable transport endpoint: a numeric IP + port.
+ *
+ * The single ip+port endpoint type used throughout the library — by the node
+ * layer (dialing, peer info, reconnection) and by the lower-level engines (DHT,
+ * BitTorrent trackers, STUN/TURN). It lives in core/ because it is a foundational
+ * transport primitive that every layer above depends on.
+ *
+ * `ip` is an IpAddress: a strictly numeric, resolved address stored as raw bytes
+ * (see core/ip_address.h) — NOT a hostname and NOT a string. An unresolved
+ * "host:port" a user typed is a HostEndpoint (core/host_endpoint.h) and only
+ * becomes an Address once the resolver runs. This keeps Address a small,
+ * allocation-free, trivially-copyable value that hashes and compares by its bytes.
+ *
+ * IPv4 endpoints serialise as `host:port`; IPv6 endpoints serialise in bracketed
+ * `[ip]:port` form so the colons in the address are never confused with the port
+ * separator. parse() accepts both forms and is the exact inverse of to_string().
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/core/ip_address.h"
+
+#include <cstdint>
+#include <functional>
+#include <optional>
+#include <string>
+#include <string_view>
+
+namespace librats {
+
+struct RATS_API Address {
+    IpAddress ip;
+    uint16_t  port = 0;
+
+    Address() = default;
+    Address(IpAddress ip, uint16_t port) : ip(ip), port(port) {}
+
+    /// Build from a numeric IP literal + port. The literal MUST be a valid
+    /// IPv4/IPv6 address (hostnames belong in a HostEndpoint); an invalid literal
+    /// yields an unspecified ip (asserts in debug builds). Kept for the many call
+    /// sites of the form Address{"1.2.3.4", 80}.
+    Address(std::string_view numeric_ip, uint16_t port);
+
+    /// Parse "host:port" or "[ipv6]:port". Returns nullopt if the port is
+    /// missing/invalid, if the host is not a numeric IP literal, or for a bare
+    /// (unbracketed) IPv6 literal whose own colons make the port ambiguous.
+    /// Exact inverse of to_string().
+    static std::optional<Address> parse(std::string_view text);
+
+    /// IPv6 endpoints serialise bracketed; everything else plain. "" ip → ":port".
+    std::string to_string() const;
+
+    /// A usable dial target: a specified ip and a non-zero port.
+    bool is_valid() const noexcept { return !ip.is_unspecified() && port != 0; }
+
+    bool operator==(const Address& o) const noexcept { return port == o.port && ip == o.ip; }
+    bool operator!=(const Address& o) const noexcept { return !(*this == o); }
+    bool operator<(const Address& o) const noexcept {
+        return ip != o.ip ? ip < o.ip : port < o.port;
+    }
+};
+
+} // namespace librats
+
+namespace std {
+template <>
+struct hash<librats::Address> {
+    std::size_t operator()(const librats::Address& a) const noexcept {
+        // Fold the port into the ip hash (FNV-style) — no temporary string.
+        std::size_t h = a.ip.hash();
+        h ^= (static_cast<std::size_t>(a.port) + 0x9e3779b97f4a7c15ull + (h << 6) + (h >> 2));
+        return h;
+    }
+};
+} // namespace std

package/native-src/src/librats/core/bytes.h

@@ -0,0 +1,69 @@
+#pragma once
+
+/**
+ * @file bytes.h
+ * @brief Lightweight byte container aliases and a non-owning byte view.
+ *
+ * `ByteView` is a C++17 stand-in for std::span<const uint8_t>: a cheap
+ * (pointer, length) pair used to pass payloads around without copying. It does
+ * NOT own its storage — the referenced bytes must outlive the view. On the
+ * receive path views point straight into the connection's ReceiveBuffer and are
+ * only valid until the buffer is consumed.
+ *
+ * `ByteSpan` is the mutable counterpart (std::span<uint8_t>), handed out by
+ * ReceiveBuffer::prepare() as the destination of a recv().
+ */
+
+#include <cstdint>
+#include <cstddef>
+#include <vector>
+#include <string>
+
+namespace librats {
+
+using Bytes = std::vector<uint8_t>;
+
+/// Non-owning view over a contiguous run of bytes.
+class ByteView {
+public:
+    constexpr ByteView() = default;
+    constexpr ByteView(const uint8_t* data, size_t size) : data_(data), size_(size) {}
+    ByteView(const Bytes& b) : data_(b.data()), size_(b.size()) {}
+    ByteView(const std::string& s)
+        : data_(reinterpret_cast<const uint8_t*>(s.data())), size_(s.size()) {}
+
+    const uint8_t* data()  const noexcept { return data_; }
+    size_t         size()  const noexcept { return size_; }
+    bool           empty() const noexcept { return size_ == 0; }
+
+    const uint8_t* begin() const noexcept { return data_; }
+    const uint8_t* end()   const noexcept { return data_ + size_; }
+
+    Bytes to_bytes() const { return Bytes(data_, data_ + size_); }
+
+private:
+    const uint8_t* data_ = nullptr;
+    size_t         size_ = 0;
+};
+
+/// Non-owning view over a contiguous run of *writable* bytes.
+class ByteSpan {
+public:
+    constexpr ByteSpan() = default;
+    constexpr ByteSpan(uint8_t* data, size_t size) : data_(data), size_(size) {}
+
+    uint8_t* data()  const noexcept { return data_; }
+    size_t   size()  const noexcept { return size_; }
+    bool     empty() const noexcept { return size_ == 0; }
+
+    uint8_t* begin() const noexcept { return data_; }
+    uint8_t* end()   const noexcept { return data_ + size_; }
+
+    operator ByteView() const noexcept { return ByteView(data_, size_); }
+
+private:
+    uint8_t* data_ = nullptr;
+    size_t   size_ = 0;
+};
+
+} // namespace librats

package/native-src/src/librats/core/chained_send_buffer.cpp

@@ -0,0 +1,172 @@
+#include "librats/core/chained_send_buffer.h"
+
+#include <algorithm>
+#include <cassert>
+
+namespace librats {
+
+ChainedSendBuffer& ChainedSendBuffer::operator=(ChainedSendBuffer&& other) noexcept {
+    if (this == &other) return *this;
+
+    // clear() the source rather than relying on the containers' moved-from state: a
+    // moved-from vector is only guaranteed *valid*, not empty, and the counters must
+    // be zeroed to match whatever it ends up holding.
+    chunks_    = std::move(other.chunks_);
+    recycled_  = std::move(other.recycled_);
+    head_      = std::exchange(other.head_, 0);
+    pending_   = std::exchange(other.pending_, 0);
+    allocated_ = std::exchange(other.allocated_, 0);
+    other.clear();
+    return *this;
+}
+
+// ── Queueing ────────────────────────────────────────────────────────────────
+
+void ChainedSendBuffer::append(Bytes data) {
+    if (data.empty()) return;
+
+    pending_   += data.size();
+    allocated_ += data.capacity();
+    chunks_.push_back(Chunk{std::move(data), 0});
+}
+
+void ChainedSendBuffer::append(ByteView bytes) {
+    if (bytes.empty()) return;
+
+    // Pack into the tail chunk when it has the room. The capacity check guarantees
+    // the insert cannot reallocate, so slices handed out by gather() — including one
+    // pointing into this very chunk — stay valid.
+    if (Bytes* tail = coalescable_tail(bytes.size())) {
+        tail->insert(tail->end(), bytes.begin(), bytes.end());
+        pending_ += bytes.size();
+        return;
+    }
+
+    Bytes chunk = take_chunk(bytes.size());
+    chunk.assign(bytes.begin(), bytes.end());
+    append(std::move(chunk));
+}
+
+Bytes* ChainedSendBuffer::coalescable_tail(size_t bytes) noexcept {
+    if (head_ == chunks_.size()) return nullptr;  // no live chunk to pack into
+    Bytes& tail = chunks_.back().data;
+    return tail.capacity() - tail.size() >= bytes ? &tail : nullptr;
+}
+
+Bytes ChainedSendBuffer::take_chunk(size_t bytes) {
+    if (recycled_.capacity() >= bytes) {
+        Bytes chunk = std::move(recycled_);
+        recycled_ = Bytes{};  // a moved-from vector is only guaranteed *valid*, not empty
+        return chunk;
+    }
+
+    // A small message opens a chunk with spare room, so the messages behind it can
+    // be packed in for free (see coalescable_tail). A large one is sized exactly —
+    // padding a payload buffer would only waste memory.
+    Bytes chunk;
+    chunk.reserve((std::max)(bytes, kScratchCapacity));
+    return chunk;
+}
+
+void ChainedSendBuffer::recycle(Bytes&& chunk) noexcept {
+    // Take ownership unconditionally, so a chunk we decline is freed *here* rather
+    // than lingering in its (already dead, but not yet swept) slot. pop_front() has
+    // just subtracted this chunk's capacity from allocated_, and allocated() is what
+    // the send high-water mark watches — leaving the buffer alive until
+    // reclaim_drained_slots() gets round to it would let the queue hold up to twice
+    // the mark while reporting that it is under it.
+    Bytes dead = std::move(chunk);
+
+    // Keep at most one drained chunk, and only a small one: holding on to a piece-
+    // sized payload buffer would trade a malloc for permanently resident memory.
+    if (dead.capacity() > kMaxRecycledCapacity) return;
+    if (dead.capacity() <= recycled_.capacity()) return;
+
+    recycled_ = std::move(dead);
+    recycled_.clear();  // keeps the capacity
+}
+
+// ── Draining ────────────────────────────────────────────────────────────────
+
+size_t ChainedSendBuffer::gather(ByteView* out, size_t max_slices, size_t max_bytes) const {
+    size_t n     = 0;
+    size_t bytes = 0;
+    for (size_t i = head_; i < chunks_.size() && n < max_slices; ++i) {
+        const Chunk& chunk = chunks_[i];
+        out[n++] = ByteView(chunk.head(), chunk.remaining());
+
+        // Checked *after* taking the slice, so the first one is always described even
+        // if it alone exceeds the budget — a chunk larger than max_bytes must still be
+        // sendable, and a short iovec never loses data: whatever the kernel does not
+        // take this round goes out on the next.
+        bytes += chunk.remaining();
+        if (bytes >= max_bytes) break;
+    }
+    return n;
+}
+
+ByteView ChainedSendBuffer::front() const noexcept {
+    if (head_ == chunks_.size()) return {};
+    const Chunk& head = chunks_[head_];
+    return ByteView(head.head(), head.remaining());
+}
+
+void ChainedSendBuffer::pop_front(size_t bytes) {
+    assert(bytes <= pending_ && "pop_front() past the queued bytes");
+
+    while (bytes > 0 && head_ < chunks_.size()) {
+        Chunk& head = chunks_[head_];
+        const size_t left = head.remaining();
+
+        if (bytes < left) {  // chunk partially sent: just advance its cursor
+            head.sent += bytes;
+            pending_  -= bytes;
+            break;  // NOT return — the drained slots behind us still need sweeping
+        }
+
+        bytes      -= left;
+        pending_   -= left;
+        allocated_ -= head.data.capacity();
+        recycle(std::move(head.data));
+        ++head_;  // the slot stays; reclaim_drained_slots() sweeps it up in bulk
+    }
+    reclaim_drained_slots();
+}
+
+void ChainedSendBuffer::reclaim_drained_slots() {
+    if (head_ == 0) return;
+
+    if (head_ == chunks_.size()) {
+        // Fully drained — the common case. Rewinding to 0 keeps the vector's storage
+        // for the next burst, so a steady drip of messages allocates nothing at all:
+        // neither a payload buffer (recycled_) nor a slot to hang it off.
+        chunks_.clear();
+        head_ = 0;
+        if (chunks_.capacity() > kMaxRetainedSlots) {
+            chunks_.shrink_to_fit();             // hand back the array a backlog grew
+            chunks_.reserve(kMaxRetainedSlots);  // …but not the steady-state working set
+        }
+        return;
+    }
+
+    // A backlog that never fully empties: drop the dead prefix once it is at least
+    // half the vector, so the moves are paid for by the slots they retire (amortised
+    // O(1) per chunk) rather than run on every pop.
+    if (head_ * 2 >= chunks_.size()) {
+        chunks_.erase(chunks_.begin(), chunks_.begin() + static_cast<std::ptrdiff_t>(head_));
+        head_ = 0;
+    }
+}
+
+void ChainedSendBuffer::clear() noexcept {
+    // swap-with-empty rather than clear()+shrink_to_fit(): constructing an empty
+    // vector cannot allocate, so this releases the storage without the throwing
+    // reallocation shrink_to_fit() is allowed to perform (this function is noexcept).
+    std::vector<Chunk>().swap(chunks_);
+    Bytes().swap(recycled_);
+    head_      = 0;
+    pending_   = 0;
+    allocated_ = 0;
+}
+
+} // namespace librats