librats 1.0.2 → 2.2.0

package/native-src/src/{io_poller.h → librats/core/io_poller.h}

@@ -21,7 +21,8 @@
  *   }
  */
 
-#include "socket.h"
+#include "librats/util/rats_export.h"
+#include "librats/core/socket.h"
 
 #include <memory>
 #include <cstdint>
@@ -67,12 +68,14 @@ struct PollResult {
  * @brief Abstract I/O multiplexer
  * 
  * Thread-safety:
- * - add/modify/remove: Safe to call from any thread (epoll_ctl is thread-safe,
- *   kqueue changes are atomic, WSAPoll rebuilds on wait).
+ * - add/modify/remove: Safe to call from any thread. epoll_ctl is thread-safe on
+ *   its own; the backends that keep a registration table of their own (kqueue,
+ *   IOCP, poll) guard it with a mutex that wait() never takes, so a control call
+ *   cannot stall the event loop.
  * - wait: Should be called from a single I/O thread.
  * - add/modify/remove can be called concurrently with wait().
  */
-class IOPoller {
+class RATS_API IOPoller {
 public:
     virtual ~IOPoller() = default;
     
@@ -88,10 +91,13 @@ public:
     
     /**
      * @brief Add a socket to the poll set
-     * 
+     *
+     * A socket that is already in the set is rejected rather than re-registered:
+     * use modify() to change what an existing registration watches for.
+     *
      * @param fd Socket to monitor
      * @param events Bitmask of PollFlags to watch for
-     * @return true on success
+     * @return true on success, false if fd is already registered or on error
      */
     virtual bool add(socket_t fd, uint32_t events) = 0;
     

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

@@ -0,0 +1,120 @@
+#include "librats/core/ip_address.h"
+#include "librats/core/socket.h"  // brings in the platform sockaddr / inet_ntop / inet_pton
+
+#include <cstring>
+
+namespace librats {
+
+IpAddress IpAddress::from_v4(const std::array<uint8_t, 4>& b) {
+    IpAddress a;
+    std::memcpy(a.bytes_.data(), b.data(), 4);
+    a.family_ = Family::V4;
+    return a;
+}
+
+IpAddress IpAddress::from_v6(const std::array<uint8_t, 16>& b) {
+    IpAddress a;
+    std::memcpy(a.bytes_.data(), b.data(), 16);
+    a.family_ = Family::V6;
+    return a;
+}
+
+std::optional<IpAddress> IpAddress::from_bytes(ByteView bytes) {
+    IpAddress a;
+    if (bytes.size() == 4) {
+        std::memcpy(a.bytes_.data(), bytes.data(), 4);
+        a.family_ = Family::V4;
+    } else if (bytes.size() == 16) {
+        std::memcpy(a.bytes_.data(), bytes.data(), 16);
+        a.family_ = Family::V6;
+    } else {
+        return std::nullopt;
+    }
+    return a;
+}
+
+std::optional<IpAddress> IpAddress::parse(std::string_view literal) {
+    // inet_pton needs a NUL-terminated string; string_view may not be terminated.
+    std::string s(literal);
+
+    std::array<uint8_t, 4> v4{};
+    if (inet_pton(AF_INET, s.c_str(), v4.data()) == 1)
+        return from_v4(v4);
+
+    std::array<uint8_t, 16> v6{};
+    if (inet_pton(AF_INET6, s.c_str(), v6.data()) == 1)
+        return from_v6(v6);
+
+    return std::nullopt;
+}
+
+std::optional<IpAddress> IpAddress::from_sockaddr(const sockaddr* sa) {
+    if (!sa) return std::nullopt;
+    if (sa->sa_family == AF_INET) {
+        const auto* in = reinterpret_cast<const sockaddr_in*>(sa);
+        std::array<uint8_t, 4> b{};
+        std::memcpy(b.data(), &in->sin_addr, 4);
+        return from_v4(b);
+    }
+    if (sa->sa_family == AF_INET6) {
+        const auto* in6 = reinterpret_cast<const sockaddr_in6*>(sa);
+        const auto* raw = reinterpret_cast<const uint8_t*>(&in6->sin6_addr);
+        // Unwrap IPv4-mapped IPv6 (::ffff:a.b.c.d) into a native IPv4 so a dual-stack
+        // socket's view of an IPv4 peer compares/hashes identically to a v4 one.
+        static const uint8_t v4_mapped_prefix[12] = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff};
+        if (std::memcmp(raw, v4_mapped_prefix, 12) == 0) {
+            std::array<uint8_t, 4> b{};
+            std::memcpy(b.data(), raw + 12, 4);
+            return from_v4(b);
+        }
+        std::array<uint8_t, 16> b{};
+        std::memcpy(b.data(), raw, 16);
+        return from_v6(b);
+    }
+    return std::nullopt;
+}
+
+std::string IpAddress::to_string() const {
+    if (family_ == Family::V4) {
+        char buf[INET_ADDRSTRLEN] = {0};
+        in_addr a{};
+        std::memcpy(&a, bytes_.data(), 4);
+        if (inet_ntop(AF_INET, &a, buf, sizeof(buf))) return buf;
+    } else if (family_ == Family::V6) {
+        char buf[INET6_ADDRSTRLEN] = {0};
+        in6_addr a{};
+        std::memcpy(&a, bytes_.data(), 16);
+        if (inet_ntop(AF_INET6, &a, buf, sizeof(buf))) return buf;
+    }
+    return std::string();
+}
+
+size_t IpAddress::to_sockaddr(sockaddr* sa, uint16_t port) const {
+    if (family_ == Family::V4) {
+        auto* in = reinterpret_cast<sockaddr_in*>(sa);
+        std::memset(in, 0, sizeof(*in));
+        in->sin_family = AF_INET;
+        in->sin_port   = htons(port);
+        std::memcpy(&in->sin_addr, bytes_.data(), 4);
+        return sizeof(sockaddr_in);
+    }
+    if (family_ == Family::V6) {
+        auto* in6 = reinterpret_cast<sockaddr_in6*>(sa);
+        std::memset(in6, 0, sizeof(*in6));
+        in6->sin6_family = AF_INET6;
+        in6->sin6_port   = htons(port);
+        std::memcpy(&in6->sin6_addr, bytes_.data(), 16);
+        return sizeof(sockaddr_in6);
+    }
+    return 0;
+}
+
+size_t IpAddress::hash() const noexcept {
+    // FNV-1a over the family tag and all 16 bytes.
+    uint64_t h = 1469598103934665603ull;
+    h = (h ^ static_cast<uint8_t>(family_)) * 1099511628211ull;
+    for (uint8_t b : bytes_) h = (h ^ b) * 1099511628211ull;
+    return static_cast<size_t>(h);
+}
+
+} // namespace librats

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

@@ -0,0 +1,109 @@
+#pragma once
+
+/**
+ * @file ip_address.h
+ * @brief A numeric IP address (IPv4 or IPv6) stored as raw bytes.
+ *
+ * The building block of a dialable endpoint. Unlike a textual "1.2.3.4" this is
+ * a fixed 16-byte value + a family tag — trivially copyable, allocation-free, and
+ * cheap to hash/compare (it is just its bytes). Text only appears at the edges:
+ * parse() on input, to_string() for logs/serialisation. Raw bytes flow straight
+ * through the hot paths (sockaddr conversion, BEP 42, the DHT compact codec).
+ *
+ * An IpAddress is strictly NUMERIC — it never holds a hostname. An unresolved
+ * "host:port" the user typed is a HostEndpoint (core/host_endpoint.h); it becomes
+ * one or more IpAddress only after the resolver runs at the network boundary.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/core/bytes.h"
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <optional>
+#include <string>
+#include <string_view>
+
+struct sockaddr;
+
+namespace librats {
+
+class RATS_API IpAddress {
+public:
+    enum class Family : uint8_t { None, V4, V6 };
+
+    /// The unspecified address (is_unspecified() == true).
+    IpAddress() = default;
+
+    /// Parse a bare numeric literal — "1.2.3.4" or "2001:db8::1" (no brackets, no
+    /// port). nullopt for anything that is not a valid IPv4/IPv6 literal (including
+    /// hostnames — those are a HostEndpoint, not an IpAddress).
+    static std::optional<IpAddress> parse(std::string_view literal);
+
+    static IpAddress from_v4(const std::array<uint8_t, 4>& b);
+    static IpAddress from_v6(const std::array<uint8_t, 16>& b);
+
+    /// Build from raw address bytes: exactly 4 (IPv4) or 16 (IPv6). nullopt for any
+    /// other length. This is the compact/wire form used by the DHT and PEX.
+    static std::optional<IpAddress> from_bytes(ByteView bytes);
+
+    /// Build from a sockaddr (AF_INET / AF_INET6). nullopt for other families.
+    /// An IPv4-mapped IPv6 sockaddr (::ffff:a.b.c.d) is unwrapped to a plain IPv4.
+    static std::optional<IpAddress> from_sockaddr(const sockaddr* sa);
+
+    bool   is_v4()          const noexcept { return family_ == Family::V4; }
+    bool   is_v6()          const noexcept { return family_ == Family::V6; }
+    bool   is_unspecified() const noexcept { return family_ == Family::None; }
+    Family family()         const noexcept { return family_; }
+
+    /// Not a dialable endpoint: either unspecified, or the all-zero wildcard
+    /// (0.0.0.0 / ::) that INADDR_ANY-style "any interface" bindings carry.
+    bool is_any() const noexcept {
+        if (family_ == Family::None) return true;
+        for (size_t i = 0, n = size(); i < n; ++i)
+            if (bytes_[i] != 0) return false;
+        return true;
+    }
+
+    /// The significant address bytes: 4 for IPv4, 16 for IPv6, empty otherwise.
+    /// The view is valid for the lifetime of this IpAddress.
+    ByteView bytes() const noexcept { return ByteView(bytes_.data(), size()); }
+    size_t   size()  const noexcept {
+        return family_ == Family::V6 ? 16 : (family_ == Family::V4 ? 4 : 0);
+    }
+
+    /// Textual form via inet_ntop ("" for the unspecified address).
+    std::string to_string() const;
+
+    /// Fill *sa (must point to storage at least sizeof(sockaddr_in6)) with this
+    /// address and `port`. Returns the sockaddr length written, or 0 if unspecified.
+    size_t to_sockaddr(sockaddr* sa, uint16_t port) const;
+
+    bool operator==(const IpAddress& o) const noexcept {
+        return family_ == o.family_ && bytes_ == o.bytes_;
+    }
+    bool operator!=(const IpAddress& o) const noexcept { return !(*this == o); }
+    bool operator<(const IpAddress& o) const noexcept {
+        return family_ != o.family_ ? family_ < o.family_ : bytes_ < o.bytes_;
+    }
+
+    /// Hash over (family, all 16 bytes). Unused tail bytes are always zero, so this
+    /// is well-defined without masking.
+    size_t hash() const noexcept;
+
+private:
+    // v4 occupies the first 4 bytes (tail kept zero); v6 uses all 16.
+    std::array<uint8_t, 16> bytes_{};
+    Family                  family_ = Family::None;
+};
+
+} // namespace librats
+
+namespace std {
+template <>
+struct hash<librats::IpAddress> {
+    size_t operator()(const librats::IpAddress& a) const noexcept { return a.hash(); }
+};
+} // namespace std

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

@@ -0,0 +1,47 @@
+#pragma once
+
+/**
+ * @file mpsc_queue.h
+ * @brief Multi-producer / single-consumer task queue used to hand work to a Reactor.
+ *
+ * Many threads call push(); exactly one (the reactor thread) calls drain().
+ * drain() swaps the entire backlog out under a single lock, so the consumer
+ * pays one lock per *batch*, not per item — the lock guards the handoff, never
+ * the work itself. This is deliberately simple and correct; it can be swapped
+ * for an intrusive lock-free MPSC later without touching callers.
+ */
+
+#include <mutex>
+#include <vector>
+
+namespace librats {
+
+template <typename T>
+class MpscQueue {
+public:
+    /// Enqueue an item. Safe to call from any thread.
+    void push(T item) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        queue_.push_back(std::move(item));
+    }
+
+    /// Move the entire backlog into `out` (cleared first). Single consumer only.
+    /// Returns the number of items handed over.
+    size_t drain(std::vector<T>& out) {
+        out.clear();
+        std::lock_guard<std::mutex> lock(mutex_);
+        out.swap(queue_);
+        return out.size();
+    }
+
+    bool empty() const {
+        std::lock_guard<std::mutex> lock(mutex_);
+        return queue_.empty();
+    }
+
+private:
+    mutable std::mutex mutex_;
+    std::vector<T>     queue_;
+};
+
+} // namespace librats

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

@@ -0,0 +1,74 @@
+#pragma once
+
+/**
+ * @file notifier.h
+ * @brief Reliable cross-platform wakeup for a poller-driven reactor.
+ *
+ * A reactor blocks in IOPoller::wait(); to make it run a freshly-posted task
+ * promptly we need to interrupt that wait from another thread. Notifier is a
+ * self-pipe built from a *connected TCP loopback pair*:
+ *
+ *   reader_  ── registered in the poller for PollIn, drained on wake
+ *   writer_  ── signal() writes one byte, making reader_ readable
+ *
+ * A connected TCP socket is the happy path for every backend — epoll, kqueue,
+ * and crucially IOCP (where a bare UDP socket does not give reliable readiness).
+ * If construction fails the notifier degrades to a no-op: fd() is invalid and
+ * signal() does nothing, so the reactor simply falls back to its poll timeout.
+ */
+
+#include "librats/core/socket.h"
+
+#include <cstdint>
+
+namespace librats {
+
+class Notifier {
+public:
+    Notifier() {
+        socket_t listener = create_tcp_server(0, 1, "127.0.0.1", AddressFamily::IPv4);
+        if (!is_valid_socket(listener)) return;
+
+        const int port = get_bound_port(listener);
+        writer_ = create_tcp_client("127.0.0.1", port, /*timeout_ms=*/2000);
+        if (is_valid_socket(writer_)) {
+            reader_ = accept_client(listener);  // accept our own loopback connect
+        }
+        close_socket(listener);
+
+        if (is_valid_socket(reader_)) set_socket_nonblocking(reader_);
+        if (is_valid_socket(writer_)) set_socket_nonblocking(writer_);
+    }
+
+    ~Notifier() {
+        if (is_valid_socket(reader_)) close_socket(reader_);
+        if (is_valid_socket(writer_)) close_socket(writer_);
+    }
+
+    Notifier(const Notifier&) = delete;
+    Notifier& operator=(const Notifier&) = delete;
+
+    /// The pollable end; register this for PollIn. INVALID if construction failed.
+    socket_t fd() const noexcept { return reader_; }
+
+    /// Wake the reactor. Coalescing-friendly: many signals drain as one. Any thread.
+    void signal() {
+        if (!is_valid_socket(writer_)) return;
+        const uint8_t byte = 1;
+        ::send(writer_, reinterpret_cast<const char*>(&byte), 1, 0);
+    }
+
+    /// Discard pending wake bytes. Called by the reactor when reader_ is readable.
+    void drain() {
+        uint8_t scratch[64];
+        while (::recv(reader_, reinterpret_cast<char*>(scratch), sizeof(scratch), 0) > 0) {
+            // discard
+        }
+    }
+
+private:
+    socket_t reader_ = RATS_INVALID_SOCKET;
+    socket_t writer_ = RATS_INVALID_SOCKET;
+};
+
+} // namespace librats

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

@@ -0,0 +1,219 @@
+#include "librats/core/receive_buffer.h"
+
+#include <algorithm>
+#include <cassert>
+#include <cstring>
+
+namespace librats {
+
+namespace {
+
+/// Weight of one sample in the usage average: watermark += (peak - watermark) / 16.
+/// Slow enough that a single quiet moment can't shrink a busy buffer, fast enough
+/// that a connection that saw one big message releases it within a few messages.
+constexpr size_t kUsageAverageShift = 4;  // 1/16
+
+/// Allocations are rounded up to this, so a chain of 1.5x growth steps lands on
+/// allocator-friendly sizes rather than 17496-byte oddities.
+constexpr size_t kAllocGranularity = 256;
+
+constexpr size_t round_up(size_t n, size_t granularity) noexcept {
+    return (n + granularity - 1) / granularity * granularity;
+}
+
+} // namespace
+
+ReceiveBuffer::ReceiveBuffer(size_t initial_capacity) {
+    if (initial_capacity > 0) grow_to(round_up(initial_capacity, kAllocGranularity));
+}
+
+ReceiveBuffer& ReceiveBuffer::operator=(ReceiveBuffer&& other) noexcept {
+    if (this == &other) return *this;
+
+    // Every cursor moves with the allocation. Zeroing the source is what makes it a
+    // valid *empty* buffer rather than one that still claims cap_/end_ bytes it no
+    // longer owns — the state the compiler-generated move would have left behind.
+    buf_       = std::move(other.buf_);
+    cap_       = std::exchange(other.cap_, 0);
+    start_     = std::exchange(other.start_, 0);
+    end_       = std::exchange(other.end_, 0);
+    peak_      = std::exchange(other.peak_, 0);
+    watermark_ = std::exchange(other.watermark_, 0);
+    received_since_decay_ = std::exchange(other.received_since_decay_, false);
+    return *this;
+}
+
+// ── Write side ──────────────────────────────────────────────────────────────
+
+ByteSpan ReceiveBuffer::prepare(size_t min_bytes) {
+    if (cap_ - end_ < min_bytes) make_room(min_bytes);
+
+    // Fold the *demand* into the peak, not just the bytes that end up arriving. A
+    // caller reads with a fixed chunk size (16 KiB here, 64 KiB in the BitTorrent
+    // peer), so an allocation too small to serve the next prepare() is not idle
+    // memory — no matter how little the last message actually used. Sampling only
+    // the live bytes would let the average sink below the read size, shrink the
+    // buffer, and have the very next prepare() grow it straight back.
+    // (libtorrent samples max(recv_end, packet_size) for the same reason.)
+    peak_ = (std::max)(peak_, size() + min_bytes);
+
+    return ByteSpan(buf_.get() + end_, cap_ - end_);
+}
+
+void ReceiveBuffer::commit(size_t bytes) {
+    assert(bytes <= cap_ - end_ && "commit() past the span handed out by prepare()");
+    end_ += bytes;
+    peak_ = (std::max)(peak_, size());
+    received_since_decay_ = true;  // this tick saw traffic; decay() must leave us alone
+}
+
+void ReceiveBuffer::make_room(size_t bytes) {
+    const size_t live = size();
+
+    // Reclaiming the consumed prefix is enough: a memmove of the live bytes beats
+    // an allocation. Only reachable when something has been consumed, so it costs
+    // at most one memmove per bufferful of traffic.
+    if (cap_ - live >= bytes) {
+        compact();
+        return;
+    }
+    grow_to(grown_capacity(live + bytes));
+}
+
+void ReceiveBuffer::grow_to(size_t new_capacity) {
+    reallocate(new_capacity);
+    // Restart the usage average at the new size: the buffer just grew for a reason,
+    // and judging it oversized on the next drained message would only make it flap
+    // between two sizes. Demand has to fall for a while before it shrinks again.
+    watermark_ = cap_;
+    peak_      = size();
+}
+
+size_t ReceiveBuffer::grown_capacity(size_t needed) const noexcept {
+    size_t next = cap_ + cap_ / 2;              // 1.5x, as libtorrent does
+    if (next < kMinCapacity) next = kMinCapacity;
+    if (next < needed)       next = needed;     // a single big message may outrun 1.5x
+    return round_up(next, kAllocGranularity);
+}
+
+void ReceiveBuffer::reallocate(size_t new_capacity) {
+    const size_t live = size();
+    assert(new_capacity >= live);
+
+    // Deliberately uninitialised (`new uint8_t[n]` default-initialises scalars,
+    // i.e. does nothing): every byte is about to be overwritten by recv().
+    std::unique_ptr<uint8_t[]> fresh(new uint8_t[new_capacity]);
+    if (live > 0) std::memcpy(fresh.get(), data(), live);
+
+    buf_   = std::move(fresh);
+    cap_   = new_capacity;
+    start_ = 0;
+    end_   = live;
+}
+
+// ── Read side ───────────────────────────────────────────────────────────────
+
+void ReceiveBuffer::consume(size_t bytes) {
+    assert(bytes <= size() && "consume() past the live data");
+    start_ += bytes;
+    if (start_ != end_) return;
+
+    // Fully drained — the common case. Rewinding both cursors keeps the buffer
+    // normalised for free, so the steady state never memmoves.
+    start_ = end_ = 0;
+    sample_usage();
+    maybe_shrink();
+}
+
+// ── Maintenance ─────────────────────────────────────────────────────────────
+
+void ReceiveBuffer::compact() {
+    if (start_ == 0) return;
+
+    const size_t live = size();
+    if (live > 0) std::memmove(buf_.get(), buf_.get() + start_, live);
+    start_ = 0;
+    end_   = live;
+    sample_usage();
+}
+
+void ReceiveBuffer::decay() {
+    // Nothing to reclaim below the floor.
+    if (cap_ <= kMinCapacity) return;
+
+    // Traffic since the last tick: consume() already sampled it (or a partial message
+    // is still streaming in), and this connection is sized for a reason. Aging it as
+    // well would shrink it below its read size only for the next prepare() to grow it
+    // straight back.
+    if (std::exchange(received_since_decay_, false)) return;
+
+    // Silent for a whole tick. Halving (rather than folding in one more zero sample)
+    // is what makes this converge in seconds rather than minutes: maybe_shrink() wants
+    // the allocation to be more than twice the watermark, so halving the watermark
+    // halves the allocation every couple of ticks until it is back at the floor.
+    //
+    // This runs even when a partial message is still live (empty() is false). A peer
+    // that sends a length prefix — or the first slice of a large frame — and then
+    // stalls would otherwise pin the whole eager allocation for the life of the
+    // connection, and decay() is the only thing that ever visits an idle one.
+    // maybe_shrink() never drops below the live bytes, so the stalled data is kept;
+    // only the unused tail is handed back.
+    //
+    // Unless the live bytes already fill more than half the allocation: the tail worth
+    // reclaiming is then smaller than the memcpy of the data we have to keep, and the
+    // next byte the peer sends grows us straight back — copying it a second time. A
+    // stalled peer could otherwise trickle one byte per few ticks and have us memcpy its
+    // half-arrived block up and down forever. Pinning only ever comes from the *eager*
+    // reserve (a declared length that never arrived), where the live bytes are a tiny
+    // fraction of cap_, so bailing here costs no reclaim that mattered — it merely caps
+    // the unreclaimed slack at the size of the data itself, the same 2x any geometric
+    // buffer accepts. (Drained buffers reach maybe_shrink() via consume(), where
+    // size() == 0, so this never holds them up.)
+    if (size() * 2 > cap_) return;
+
+    watermark_ /= 2;
+    maybe_shrink();
+}
+
+void ReceiveBuffer::clear() noexcept {
+    start_ = end_ = 0;
+    peak_  = 0;
+}
+
+void ReceiveBuffer::reset() noexcept {
+    buf_.reset();
+    cap_ = start_ = end_ = peak_ = watermark_ = 0;
+}
+
+void ReceiveBuffer::sample_usage() noexcept {
+    // Exponential average; the +(N-1) rounds up so the average still tracks a
+    // rising peak instead of stalling below it on integer division.
+    constexpr size_t n = size_t{1} << kUsageAverageShift;
+    watermark_ = (watermark_ * (n - 1) + peak_ + (n - 1)) / n;
+    peak_      = size();
+}
+
+void ReceiveBuffer::maybe_shrink() {
+    // Only when the allocation is worth reclaiming *and* recent demand has clearly
+    // moved on — otherwise a buffer merely sitting between two messages would free
+    // and re-allocate itself on every single message.
+    if (cap_ <= kMinCapacity || cap_ / 2 <= watermark_) return;
+
+    // Fall back to what recent demand actually says, not to a padded version of it:
+    // the trigger above guarantees that halves the allocation at least, so a buffer
+    // that ballooned for one huge message is back to normal in a handful of steps
+    // (at most log2(cap) reallocations), not by creeping down a few percent at a
+    // time. Growth is geometric and cheap if demand returns.
+    //
+    // Never below the bytes still live: a partial message caught mid-stream keeps its
+    // storage — reallocate() moves those bytes to the front — so a stalled peer's data
+    // is preserved while its unused tail is reclaimed. On a drained buffer size() is 0,
+    // so this is exactly the plain watermark target.
+    // The watermark is deliberately NOT reset here (unlike after a grow): it is the
+    // decaying memory of demand that has to keep falling to shrink us further.
+    const size_t floor  = (std::max)(kMinCapacity, size());
+    const size_t target = round_up((std::max)(floor, watermark_), kAllocGranularity);
+    if (target < cap_) reallocate(target);
+}
+
+} // namespace librats