librats 1.0.2 → 2.2.0

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

@@ -0,0 +1,183 @@
+#pragma once
+
+/**
+ * @file chained_send_buffer.h
+ * @brief Outbound byte queue: a chain of heap chunks drained with gather I/O.
+ *
+ * A socket accepts what it accepts; whatever is left over has to wait for the next
+ * writable event. Rather than keeping that backlog in one contiguous buffer (where
+ * every partial write costs an O(n) erase of the sent prefix, and every message
+ * costs a copy into it), the queue is a chain of chunks:
+ *
+ *      chunks_:  [ sent | pending ] → [ pending ] → [ pending ]
+ *                        ^ head_.sent
+ *
+ *   - pop_front() after a send just advances a cursor and drops whole chunks: O(1)
+ *     amortised, no memmove.
+ *   - append(Bytes) takes ownership of a buffer someone else already built, so a
+ *     message the caller allocated (an encrypted frame, a piece read from disk) is
+ *     never copied.
+ *   - gather() exposes the chain as a slice list for writev()/WSASend(), so a
+ *     backlog of N queued messages leaves in ONE syscall instead of N.
+ *
+ * Three things keep small messages cheap, since a chunk-per-message would otherwise
+ * mean a malloc per 5-byte keep-alive:
+ *   - copy-appends are packed into the spare capacity of the tail chunk
+ *     (libtorrent's allocate_appendix), so a burst of small messages costs one
+ *     allocation, not one per message;
+ *   - the last fully-sent small chunk is kept and re-used, so a steady drip of
+ *     small messages settles into allocating nothing at all;
+ *   - the chain itself is a std::vector + a head index, not a std::deque. A deque
+ *     allocates a fresh block every `block_size/sizeof(Chunk)` push_backs (libstdc++:
+ *     one per 16 chunks; MSVC: one per *chunk*, since its block holds a single
+ *     element for any type over 8 bytes) — so the recycled chunk above would hand
+ *     back the payload buffer while the queue kept mallocing the slot to put it in.
+ *     A vector amortises the slots away entirely, and re-uses its storage across
+ *     drains.
+ *
+ * Memory is accounted two ways: size() is what still has to go out, while
+ * allocated() is what the chain actually holds — larger, because a partially sent
+ * chunk keeps its whole allocation and a packed chunk keeps its spare room. A
+ * send high-water mark should watch allocated(): that is the memory a peer who
+ * stops reading can make us carry.
+ *
+ * Not thread-safe: owned and touched by exactly one reactor thread.
+ *
+ * Usage:
+ *   buf.append(std::move(frame));                       // queue, no copy
+ *   ByteView slices[kMaxSendSlices];
+ *   const size_t n = buf.gather(slices, kMaxSendSlices);
+ *   const auto sent = send_vectored(sock, slices, n);   // one syscall
+ *   if (sent > 0) buf.pop_front(size_t(sent));          // O(1)
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/core/bytes.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <type_traits>
+#include <utility>
+#include <vector>
+
+namespace librats {
+
+class RATS_API ChainedSendBuffer {
+public:
+    /// Capacity of a chunk opened for a small copy-append. Sized so a run of
+    /// protocol chatter (keep-alives, HAVEs, REQUESTs, ACKs) packs into one.
+    static constexpr size_t kScratchCapacity = 1024;
+
+    /// Chunks up to this size are kept for re-use when they drain; larger ones
+    /// (payload buffers) are released, so the queue never squats on real memory.
+    static constexpr size_t kMaxRecycledCapacity = 4 * 1024;
+
+    ChainedSendBuffer() = default;
+
+    /// Moving leaves the source empty. A defaulted move would carry pending_ and
+    /// allocated_ over to a source whose chunks_ had been emptied, leaving it claiming
+    /// bytes it no longer holds (empty() false, front() empty — a flush() that never
+    /// finishes).
+    ChainedSendBuffer(ChainedSendBuffer&& other) noexcept { *this = std::move(other); }
+    ChainedSendBuffer& operator=(ChainedSendBuffer&& other) noexcept;
+    ChainedSendBuffer(const ChainedSendBuffer&) = delete;
+    ChainedSendBuffer& operator=(const ChainedSendBuffer&) = delete;
+
+    // ── Queueing ────────────────────────────────────────────────────────────
+
+    /// Queue `data`, taking ownership — the bytes are never copied. Prefer this for
+    /// anything the caller already had to allocate (a framed message, disk block…).
+    void append(Bytes data);
+
+    /// Queue a copy of `bytes`. Small copies land in the tail chunk's spare capacity
+    /// when they fit, so headers and short control messages don't each cost a malloc.
+    void append(ByteView bytes);
+
+    // ── Draining ────────────────────────────────────────────────────────────
+
+    /// Bytes gather() will describe in one go unless told otherwise. A socket accepts
+    /// what fits in its send buffer — a few hundred KiB at most — and every slice past
+    /// that is an iovec entry the kernel copies in and then ignores. Under a backlog
+    /// (the case gather() exists for) the flush loop re-gathers after every partial
+    /// write, so that waste is paid on every syscall, not once. libtorrent bounds its
+    /// build_iovec() by a byte quota for the same reason.
+    static constexpr size_t kMaxGatherBytes = 1024 * 1024;
+
+    /// Fill `out` with up to `max_slices` contiguous runs covering the front of the
+    /// queue, in order, stopping once they cover `max_bytes` (the slice that crosses
+    /// the limit is still included whole, so a single chunk larger than the limit is
+    /// described rather than dropped). Returns the number of slices written. The views
+    /// stay valid until the next pop_front()/clear() — append() never invalidates them,
+    /// because a slice points at a chunk's *heap buffer*, which a vector growth moves
+    /// the owning Chunk around but never reallocates.
+    size_t gather(ByteView* out, size_t max_slices, size_t max_bytes = kMaxGatherBytes) const;
+
+    /// The first contiguous run — the single-slice form of gather(), for a plain
+    /// send(). Empty when the queue is empty.
+    ByteView front() const noexcept;
+
+    /// Drop `bytes` from the front after a successful send. Must not exceed size().
+    void pop_front(size_t bytes);
+
+    // ── State ───────────────────────────────────────────────────────────────
+
+    bool   empty()       const noexcept { return pending_ == 0; }
+    /// Bytes still waiting to go out — what a send high-water mark should watch.
+    size_t size()        const noexcept { return pending_; }
+    /// Heap actually held by the chain: pending bytes, the already-sent prefix of a
+    /// partially sent chunk, spare capacity, and the recycled chunk.
+    size_t allocated()   const noexcept { return allocated_ + recycled_.capacity(); }
+    size_t chunk_count() const noexcept { return chunks_.size() - head_; }
+
+    /// Drop everything and release all chunks.
+    void clear() noexcept;
+
+private:
+    struct Chunk {
+        Bytes  data;
+        size_t sent = 0;  ///< bytes of `data` already handed to the socket
+
+        size_t         remaining() const noexcept { return data.size() - sent; }
+        const uint8_t* head()      const noexcept { return data.data() + sent; }
+    };
+
+    // A gather() slice points into a chunk's heap buffer, and append() may grow
+    // chunks_ while those slices are outstanding. That is only safe because a vector
+    // growth *moves* each Chunk — carrying the heap buffer's address across untouched.
+    // Were the move throwing, vector would fall back to copying: every chunk would get
+    // a fresh buffer, the originals would be freed, and every outstanding slice would
+    // dangle. The guarantee is load-bearing, so assert it rather than assume it.
+    static_assert(std::is_nothrow_move_constructible<Chunk>::value,
+                  "Chunk must move on vector growth, or gather()'s slices would dangle");
+
+    /// The tail chunk if `bytes` fit in its spare capacity (so appending to it
+    /// cannot reallocate, and therefore cannot invalidate outstanding slices).
+    Bytes* coalescable_tail(size_t bytes) noexcept;
+
+    /// A chunk with at least `bytes` of capacity: the recycled one if it fits,
+    /// otherwise a fresh allocation.
+    Bytes  take_chunk(size_t bytes);
+
+    /// Offer a drained chunk back for re-use.
+    void   recycle(Bytes&& chunk) noexcept;
+
+    /// Drop the drained prefix of `chunks_` so the vector cannot creep forever under a
+    /// backlog that never fully empties. Amortised O(1): only ever runs when at least
+    /// half the vector is dead.
+    void   reclaim_drained_slots();
+
+    /// Slots kept across a full drain. Above this the vector hands the memory back —
+    /// an 8 MiB backlog of 1 KiB chunks would otherwise leave 8192 slots resident.
+    static constexpr size_t kMaxRetainedSlots = 64;
+
+    /// Live chunks are `chunks_[head_ .. end)`. A vector + head index rather than a
+    /// deque: see the header comment — a deque mallocs a block per N chunks (N == 1 on
+    /// MSVC), which is exactly the allocation `recycled_` exists to avoid.
+    std::vector<Chunk> chunks_;
+    size_t             head_      = 0;  ///< index of the first live chunk
+    size_t             pending_   = 0;  ///< sum of remaining() over the live chunks
+    size_t             allocated_ = 0;  ///< sum of data.capacity() over the live chunks
+    Bytes              recycled_;       ///< one drained small chunk, kept for re-use
+};
+
+} // namespace librats

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

@@ -0,0 +1,41 @@
+#include "librats/core/endpoint_parse.h"
+
+namespace librats {
+
+std::optional<uint16_t> parse_port(std::string_view text) {
+    if (text.empty()) return std::nullopt;
+    unsigned long port = 0;
+    for (char c : text) {
+        if (c < '0' || c > '9') return std::nullopt;
+        port = port * 10 + static_cast<unsigned>(c - '0');
+        if (port > 65535) return std::nullopt;
+    }
+    if (port == 0) return std::nullopt;
+    return static_cast<uint16_t>(port);
+}
+
+std::optional<std::pair<std::string_view, uint16_t>> split_host_port(std::string_view text) {
+    if (!text.empty() && text.front() == '[') {
+        // Bracketed IPv6: [ip]:port
+        const auto close = text.find(']');
+        if (close == std::string_view::npos || close + 1 >= text.size() || text[close + 1] != ':')
+            return std::nullopt;
+        const auto host = text.substr(1, close - 1);
+        if (host.empty()) return std::nullopt;
+        const auto port = parse_port(text.substr(close + 2));
+        if (!port) return std::nullopt;
+        return std::make_pair(host, *port);
+    }
+    const auto colon = text.rfind(':');
+    if (colon == std::string_view::npos || colon == 0 || colon + 1 == text.size())
+        return std::nullopt;
+    const auto host = text.substr(0, colon);
+    // A bare IPv6 literal carries its own colons; without brackets the port is
+    // ambiguous, so reject it rather than guess.
+    if (host.find(':') != std::string_view::npos) return std::nullopt;
+    const auto port = parse_port(text.substr(colon + 1));
+    if (!port) return std::nullopt;
+    return std::make_pair(host, *port);
+}
+
+} // namespace librats

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

@@ -0,0 +1,31 @@
+#pragma once
+
+/**
+ * @file endpoint_parse.h
+ * @brief Shared textual "host:port" parsing for Address and HostEndpoint.
+ *
+ * Both the numeric Address and the unresolved HostEndpoint accept exactly the same
+ * surface syntax — "host:port" or bracketed "[ipv6]:port" — and reject the same
+ * malformed inputs (missing/invalid port, empty host, a bare unbracketed IPv6 whose
+ * own colons make the port ambiguous). The only difference is what each does with
+ * the host afterwards (parse it as a numeric literal vs. keep it verbatim), so the
+ * structural split lives here once instead of being copy-pasted into each parse().
+ */
+
+#include <cstdint>
+#include <optional>
+#include <string_view>
+#include <utility>
+
+namespace librats {
+
+/// Parse a 1..65535 decimal port. nullopt on empty/non-digit/out-of-range/zero.
+std::optional<uint16_t> parse_port(std::string_view text);
+
+/// Split "host:port" or "[ipv6]:port" into (host, port). Returns nullopt for a
+/// missing/invalid port, an empty host, or a bare (unbracketed) IPv6 literal whose
+/// colons make the port ambiguous. The returned host view points into `text` and is
+/// valid for its lifetime (brackets, if any, are stripped).
+std::optional<std::pair<std::string_view, uint16_t>> split_host_port(std::string_view text);
+
+} // namespace librats

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

@@ -0,0 +1,70 @@
+#pragma once
+
+/**
+ * @file event_bus.h
+ * @brief A tiny typed publish/subscribe hub for decoupled module notifications.
+ *
+ * The "something happened" half of inter-module communication: a publisher emits
+ * an event *value* and every subscriber registered for that event type is invoked.
+ * The publisher neither knows nor names its subscribers — which is exactly what
+ * keeps modules from acquiring direct references to one another (the road back to
+ * a god-class). For the "do X / give me Y" half — a targeted call with a return
+ * value — use ServiceRegistry instead.
+ *
+ * An event type is any value type; subscription and dispatch are keyed by it:
+ *
+ *     struct NetworkChanged { std::vector<std::string> addresses; };
+ *     bus.on<NetworkChanged>([](const NetworkChanged& e){ ... });   // subscribe
+ *     bus.emit(NetworkChanged{addrs});                              // publish → all handlers
+ *
+ * Threading: handlers run synchronously on the thread that calls emit(). The bus
+ * itself is thread-safe (on/emit may be called concurrently), but a handler must
+ * not block that thread for long — if emit() is driven from a latency-sensitive
+ * thread, offload slow work. emit() snapshots the handler list under the lock and
+ * invokes it unlocked, so a handler may itself emit() or on() without deadlocking.
+ *
+ * Convention: subscribe during a subsystem's attach() (single-threaded, before any
+ * reactor runs), the same "configure before start" rule the rest of the node uses.
+ */
+
+#include <functional>
+#include <mutex>
+#include <typeindex>
+#include <typeinfo>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+namespace librats {
+
+class EventBus {
+public:
+    /// Register a handler for events of type E. Additive: multiple handlers may
+    /// coexist and all fire (in registration order) for each emitted event.
+    template <class E>
+    void on(std::function<void(const E&)> handler) {
+        std::lock_guard<std::mutex> lock(mutex_);
+        handlers_[std::type_index(typeid(E))].push_back(
+            [h = std::move(handler)](const void* e) { h(*static_cast<const E*>(e)); });
+    }
+
+    /// Publish an event to every handler registered for its type.
+    template <class E>
+    void emit(const E& event) {
+        std::vector<ErasedHandler> snapshot;
+        {
+            std::lock_guard<std::mutex> lock(mutex_);
+            auto it = handlers_.find(std::type_index(typeid(E)));
+            if (it == handlers_.end()) return;
+            snapshot = it->second;  // copy under lock, then invoke unlocked
+        }
+        for (auto& h : snapshot) h(&event);
+    }
+
+private:
+    using ErasedHandler = std::function<void(const void*)>;
+    std::mutex mutex_;
+    std::unordered_map<std::type_index, std::vector<ErasedHandler>> handlers_;
+};
+
+} // namespace librats

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

@@ -0,0 +1,56 @@
+#pragma once
+
+/**
+ * @file host_endpoint.h
+ * @brief An unresolved dial target: a host (name OR literal) plus a port.
+ *
+ * The textual counterpart to Address. Where Address is a strictly numeric,
+ * already-resolved endpoint you can hand to a socket, a HostEndpoint is what a
+ * user (or a config file) supplies: "router.bittorrent.com:6881", a STUN server,
+ * a tracker host. Its `host` may be a DNS name or an IP literal; it carries no
+ * bytes and does nothing but hold the two fields until the resolver turns it into
+ * one or more Address at the network boundary.
+ *
+ * Keeping this separate is deliberate (see CLAUDE.md): it keeps hostnames — and
+ * the allocation/ambiguity they bring — out of the hot-path Address, which stays
+ * a small trivially-copyable value.
+ */
+
+#include "librats/core/endpoint_parse.h"
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <utility>
+
+namespace librats {
+
+struct HostEndpoint {
+    std::string host;
+    uint16_t    port = 0;
+
+    HostEndpoint() = default;
+    HostEndpoint(std::string host, uint16_t port) : host(std::move(host)), port(port) {}
+
+    /// Parse "host:port" or "[ipv6]:port". Accepts hostnames and IP literals alike;
+    /// only the port is validated here (resolution happens later). Returns nullopt
+    /// if the port is missing/invalid or the host is empty.
+    static std::optional<HostEndpoint> parse(std::string_view text) {
+        const auto hp = split_host_port(text);
+        if (!hp) return std::nullopt;
+        return HostEndpoint{std::string(hp->first), hp->second};
+    }
+
+    /// Bracket a host that looks like an IPv6 literal (contains ':'), else plain.
+    std::string to_string() const {
+        if (host.find(':') != std::string::npos)
+            return "[" + host + "]:" + std::to_string(port);
+        return host + ":" + std::to_string(port);
+    }
+
+    bool operator==(const HostEndpoint& o) const { return port == o.port && host == o.host; }
+    bool operator!=(const HostEndpoint& o) const { return !(*this == o); }
+};
+
+} // namespace librats