librats 1.0.2 → 2.2.0

package/native-src/src/librats/transport/reactor.h

@@ -0,0 +1,262 @@
+#pragma once
+
+/**
+ * @file reactor.h
+ * @brief Single-threaded I/O reactor owning a shard of connections.
+ *
+ * A Reactor runs one thread that drives an IOPoller and owns every Connection
+ * assigned to it. ALL connection state lives behind this one thread, so the
+ * data path has zero locks. Other threads interact with it only by:
+ *
+ *   - post(task)    — run a closure on the reactor thread (wakes it);
+ *   - execute(task) — same, but runs inline if already on the reactor thread;
+ *   - connect()/close() — convenience wrappers that post the right task.
+ *
+ * The single synchronisation point is the MPSC task queue plus a WakeupPipe to
+ * interrupt the poll wait. Timers (handshake timeouts, backoff) ride on the same
+ * loop via a TimerQueue that also sizes each poll wait.
+ *
+ * ── Two transports, one loop ────────────────────────────────────────────────
+ * Connections are keyed by ConnId, not by socket, because only one of the two
+ * transports has a socket per connection:
+ *
+ *   - TCP: one kernel socket per peer, registered with the poller. A poll event
+ *     names a socket, which the fd → ConnId map turns into a connection.
+ *   - UDP: every peer shares one socket, owned by the UdpMux. A poll event on it
+ *     means "datagrams arrived"; the mux routes them to streams by connection id
+ *     and hands back the same readable/writable/error events the poller would
+ *     have produced. From dispatch_events() down, the two are indistinguishable.
+ *
+ * Both listeners are optional and independent: a reactor can accept TCP, accept
+ * UDP, both, or neither (dial-only). Only the reactor that owns the mux can dial
+ * over UDP, which is why the pool routes UDP dials to it (see reactor_pool.h).
+ *
+ * A ReactorPool (see reactor_pool.h) runs N of these and shards connections
+ * across them; with N == 1 this is a classic single-threaded reactor.
+ */
+
+#include "librats/core/types.h"
+#include "librats/transport/connection.h"
+#include "librats/transport/udp_mux.h"
+#include "librats/core/mpsc_queue.h"
+#include "librats/core/timer_queue.h"
+#include "librats/core/io_poller.h"
+#include "librats/core/notifier.h"
+#include "librats/core/socket.h"
+
+#include <atomic>
+#include <chrono>
+#include <functional>
+#include <memory>
+#include <string>
+#include <thread>
+#include <unordered_map>
+#include <unordered_set>
+#include <vector>
+
+namespace librats {
+
+class Reactor final : public UdpMuxDelegate {
+public:
+    using Task = std::function<void()>;
+
+    /// @param index    This reactor's slot in its pool (for sharding/logging).
+    /// @param delegate Sink for all connection lifecycle/frame events.
+    /// @param security Mints a Handshaker per connection (Noise / plaintext).
+    Reactor(uint8_t index, ConnectionDelegate& delegate, SecurityProvider& security);
+    ~Reactor() override;
+
+    Reactor(const Reactor&) = delete;
+    Reactor& operator=(const Reactor&) = delete;
+
+    /// Adopt an already-bound, listening TCP socket. Call before start().
+    void listen(socket_t server_socket);
+
+    /// Adopt an already-bound UDP socket and run the datagram transport on it.
+    /// Call before start(). This is what makes the reactor able to accept *and*
+    /// dial over UDP; without it, UDP dials are refused.
+    void listen_udp(socket_t udp_socket, AddressFamily family);
+
+    /// Whether this reactor can carry UDP connections (i.e. it owns the mux).
+    bool has_udp() const noexcept { return mux_ != nullptr; }
+
+    void start();  ///< spawn the reactor thread
+    void stop();   ///< signal shutdown and join; closes all connections
+
+    // — cross-thread work submission —
+    void post(Task task);                 ///< enqueue + wake (any thread)
+    void execute(Task task);              ///< inline if on-thread, else post()
+    bool on_reactor_thread() const noexcept;
+
+    /// Begin a non-blocking outbound connection over `kind` (thread-safe).
+    ///
+    /// Returns the ConnId the connection *will* have, reserved synchronously so a
+    /// caller can cancel the attempt with cancel_dial() before it has even started
+    /// — which is what lets the node race a UDP dial against a TCP one and drop the
+    /// loser cleanly. kInvalidConnId if the transport is unavailable here.
+    ///
+    /// `profile` shapes how hard a datagram dial retries its Syn (see DialProfile);
+    /// it has no meaning for TCP, where the kernel owns the connect retries.
+    ConnId connect(std::string host, int port, TransportKind kind = TransportKind::Tcp,
+                   DialProfile profile = {});
+
+    /// Close a connection by id (thread-safe; deferred to the reactor thread).
+    /// Valid for an id whose dial has not started yet — it is cancelled instead.
+    void close(ConnId id, CloseReason reason);
+
+    // — links this reactor did not open itself ──────────────────────────────
+    //
+    // A relayed circuit is a byte stream that comes out of another peer's
+    // connection rather than out of a socket (see transport/relay_link.h), so the
+    // module that speaks the relay protocol builds the Link and hands it over.
+    // These three are that hand-over, and they are deliberately the whole of it:
+    // the reactor learns nothing about relaying, and the module learns nothing
+    // about reactors beyond "connections need to be woken".
+    //
+    // The circuit MUST be given to the reactor that owns its carrier's connection.
+    // That is what keeps every byte of it on one thread, exactly like the streams
+    // the mux hands over above, and it is the caller's job to arrange (see
+    // node/circuit_service.h).
+
+    /// Reserve a ConnId without starting anything. Thread-safe, and synchronous for
+    /// the same reason connect() is: the caller has to be able to name the
+    /// connection — to wake it, to close it — from the moment it asks for one,
+    /// rather than after a task it posted has run.
+    ConnId reserve_conn_id() noexcept {
+        return next_conn_id_.fetch_add(1, std::memory_order_relaxed);
+    }
+
+    /// Adopt an already-built Link under the id `reserve_conn_id()` handed out.
+    /// Thread-safe; the adoption itself runs on the reactor thread (inline when the
+    /// caller is already on it).
+    /// @param connected whether the far end is already there. Such a link starts its
+    ///        handshake at once, like an accepted socket; one that is not waits for
+    ///        a PollOut from wake(), exactly as an outbound connect does.
+    void adopt_link(ConnId id, std::unique_ptr<Link> link, ConnRole role, bool connected);
+
+    /// Deliver poll-equivalent events (PollIn/PollOut/PollErr) to a connection whose
+    /// Link has no socket for the poller to watch. Thread-safe. A no-op for an id
+    /// that is gone, so a late wake for a torn-down circuit costs nothing.
+    void wake(ConnId id, uint32_t events);
+
+    /// Drop a dial that lost its race — but only while it is still a dial. Once an
+    /// attempt has established it is not an attempt any more, it is one of possibly
+    /// several links to a peer, and which of those survives is the peer table's
+    /// call, made identically at both ends. The check happens here because this is
+    /// the one thread that can read the connection's state without racing it.
+    void cancel_dial(ConnId id, CloseReason reason);
+
+    /// Send a frame to every Established connection on this reactor. Thread-safe:
+    /// the iteration runs on the reactor thread. The payload is shared across
+    /// connections (the per-peer encryption still happens in each Connection).
+    void broadcast(FrameHeader header, std::shared_ptr<const Bytes> payload);
+
+    // — timers (reactor thread, or via post/execute) —
+    TimerId schedule(std::chrono::milliseconds delay, Task on_fire);
+    void    cancel(TimerId id);
+
+    /// Look up an owned connection. Reactor thread only.
+    Connection* find(ConnId id) noexcept;
+
+    /// Adjust poll interest for a socket. Called by TcpLink; reactor thread.
+    void set_interest(socket_t sock, uint32_t events);
+
+    /// Book a flush for the end of this turn: `id` has frames queued that have
+    /// not been written yet. Called by Connection::send, which aggregates rather
+    /// than writing through — see the note there. Reactor thread; each connection
+    /// books at most one flush per turn.
+    void mark_dirty(ConnId id) { dirty_.push_back(id); }
+
+    /// The security provider used to mint per-connection handshakers.
+    SecurityProvider& security() noexcept { return security_; }
+
+    /// Approximate live connection count (lock-free, eventually consistent).
+    size_t connection_count() const noexcept {
+        return conn_count_.load(std::memory_order_relaxed);
+    }
+
+    uint8_t index() const noexcept { return index_; }
+
+private:
+    // — UdpMuxDelegate —
+    ConnId adopt_inbound_link(std::unique_ptr<Link> link) override;
+    void   dispatch_link_events(ConnId id, uint32_t events) override;
+
+    void run();
+    void drain_tasks(std::vector<Task>& scratch);
+    void drain_wakeup();
+    void handle_event(const PollResult& ev);
+    void dispatch_events(ConnId id, uint32_t events);
+    void do_accept();
+    void schedule_maintenance();
+    void start_dial(ConnId id, const std::string& host, int port, TransportKind kind,
+                    DialProfile profile);
+    void abort_dial(ConnId id, const std::string& host, int port);
+    Connection* adopt(std::unique_ptr<Link> link, ConnRole role, ConnId id);
+    bool resolve_dial(ConnId id);
+    /// Body of close()/cancel_dial(); `spare_established` makes it a no-op for a
+    /// connection that has already finished its handshake.
+    void close_conn(ConnId id, CloseReason reason, bool spare_established);
+    void mark_for_close(ConnId id, CloseReason reason);
+    void process_pending_close();
+    void flush_dirty();          ///< write out what send() queued this turn
+    void remove(ConnId id, CloseReason reason);
+    void shutdown_connections();
+
+    static constexpr int kMaxEvents = 256;
+    // Idle poll cap. Kept short as a stopgap for an IOCP quirk: connecting
+    // sockets live in WSAPoll-fallback mode and are only re-checked once per
+    // wait() iteration, so connect-completion latency is bounded by this value.
+    // Negligible idle cost; on epoll/kqueue the loop still wakes on real events,
+    // so this only caps idle latency.
+    static constexpr int kMaxPollMs = 50;
+    /// Passes flush_dirty() makes over the connections booked for a write. More than
+    /// one because a write can book another connection's write — see flush_dirty().
+    static constexpr int kMaxFlushPasses = 4;
+    /// Deadline from adopt() to reaching Established (covers connect + handshake).
+    static constexpr std::chrono::milliseconds kEstablishTimeout{15000};
+    /// Cadence of the housekeeping sweep over this reactor's connections (currently
+    /// only Connection::on_maintenance_tick, which ages idle receive buffers). One
+    /// timer per reactor rather than one per connection: the work is a few pointer
+    /// comparisons per peer, so a sweep is cheaper than N timer entries.
+    static constexpr std::chrono::milliseconds kMaintenanceInterval{10000};
+
+    uint8_t                   index_;
+    ConnectionDelegate&       delegate_;
+    SecurityProvider&         security_;
+    std::unique_ptr<IOPoller> poller_;
+    Notifier                  wakeup_;
+    MpscQueue<Task>           tasks_;
+    TimerQueue                timers_;
+
+    // Declared before conns_ so it is destroyed *after* them: every UDP
+    // connection's Link points into the mux and tells it, on destruction, that its
+    // stream may go. Reversing these two would have that run against freed memory.
+    std::unique_ptr<UdpMux> mux_;
+
+    // Connections are keyed by their stable ConnId, since a UDP connection has no
+    // socket of its own; fd_to_conn_ maps the sockets that do exist (TCP, and the
+    // listener) back to that key for poll dispatch.
+    std::unordered_map<ConnId, std::unique_ptr<Connection>> conns_;
+    std::unordered_map<socket_t, ConnId>                    fd_to_conn_;
+    std::unordered_map<ConnId, CloseReason>                 pending_close_;
+    /// Connections with frames queued but not yet written this turn. Holds ids,
+    /// not pointers, so a connection torn down in between is simply not found.
+    std::vector<ConnId>                                     dirty_;
+    /// Dials cancelled before their connect task ran (see connect()/close()).
+    std::unordered_set<ConnId>                              cancelled_dials_;
+    /// Highest ConnId that has already been adopted or abandoned; anything at or
+    /// below it has resolved, so a late close() for it needs no cancellation slot.
+    ConnId                                                  resolved_watermark_ = 0;
+
+    socket_t             server_socket_ = RATS_INVALID_SOCKET;
+    std::atomic<ConnId>  next_conn_id_{1};
+    std::atomic<size_t>  conn_count_{0};
+    std::atomic<bool>    running_{false};
+    std::thread          thread_;
+    // Published with release by the reactor thread in run(), read with acquire by
+    // any thread in on_reactor_thread(); plain access would be a data race.
+    std::atomic<std::thread::id> thread_id_{};
+};
+
+} // namespace librats

package/native-src/src/librats/transport/reactor_pool.h

@@ -0,0 +1,81 @@
+#pragma once
+
+/**
+ * @file reactor_pool.h
+ * @brief A fixed set of reactors; connections are sharded across them.
+ *
+ * Default size 1 — a single reactor, which is plenty for thousands of peers.
+ * Larger pools shard outbound connections round-robin; because each Connection
+ * is pinned to one reactor for life, nothing on the data path needs to change as
+ * the pool grows. (Sharding *inbound* connections across reactors — handing an
+ * accepted fd to a non-acceptor reactor — is a future enhancement; for now a
+ * single reactor accepts and owns inbound connections.)
+ *
+ * UDP is a deliberate exception to the round-robin. Every UDP connection shares
+ * one socket — that is the point of it — so the mux, and therefore every stream
+ * on it, belongs to the single reactor that owns that socket. Sharding those
+ * across threads would mean handing datagrams between reactors on every packet,
+ * which costs more than the parallelism buys. pick() honours that by routing UDP
+ * dials to the mux's reactor and everything else round-robin.
+ */
+
+#include "librats/transport/reactor.h"
+
+#include <atomic>
+#include <cstdint>
+#include <memory>
+#include <vector>
+
+namespace librats {
+
+class ReactorPool {
+public:
+    ReactorPool(size_t count, ConnectionDelegate& delegate, SecurityProvider& security) {
+        if (count == 0) count = 1;
+        reactors_.reserve(count);
+        for (size_t i = 0; i < count; ++i)
+            reactors_.push_back(std::make_unique<Reactor>(static_cast<uint8_t>(i), delegate, security));
+    }
+
+    /// Hand the listening socket to the acceptor reactor (index 0). Before start().
+    void listen(socket_t server_socket) { reactors_[0]->listen(server_socket); }
+
+    /// Hand the shared UDP socket to the acceptor reactor (index 0), which then
+    /// owns every datagram connection. Before start().
+    void listen_udp(socket_t udp_socket, AddressFamily family) {
+        reactors_[0]->listen_udp(udp_socket, family);
+    }
+
+    /// Whether the pool can carry UDP connections at all.
+    bool has_udp() const noexcept { return reactors_[0]->has_udp(); }
+
+    void start() { for (auto& r : reactors_) r->start(); }
+    void stop()  { for (auto& r : reactors_) r->stop(); }
+
+    size_t   size() const noexcept { return reactors_.size(); }
+    Reactor& by_index(uint8_t i) noexcept { return *reactors_[i]; }
+
+    /// Choose a reactor for a new outbound connection over `kind`. UDP always
+    /// lands on the reactor that owns the socket it must go out on; anything else
+    /// is spread round-robin.
+    Reactor& pick(TransportKind kind = TransportKind::Tcp) noexcept {
+        if (kind == TransportKind::Udp) return *reactors_[0];
+        const size_t i = next_.fetch_add(1, std::memory_order_relaxed) % reactors_.size();
+        return *reactors_[i];
+    }
+
+    template <typename F>
+    void for_each(F&& fn) { for (auto& r : reactors_) fn(*r); }
+
+    size_t connection_count() const noexcept {
+        size_t total = 0;
+        for (const auto& r : reactors_) total += r->connection_count();
+        return total;
+    }
+
+private:
+    std::vector<std::unique_ptr<Reactor>> reactors_;
+    std::atomic<size_t>                   next_{0};
+};
+
+} // namespace librats

package/native-src/src/librats/transport/relay_link.cpp

@@ -0,0 +1,208 @@
+#include "librats/transport/relay_link.h"
+
+#include "librats/core/io_poller.h"   // PollIn / PollOut / PollErr
+#include "librats/util/logger.h"
+
+#include <algorithm>
+#include <cstring>
+#include <utility>
+
+namespace librats {
+
+namespace {
+
+/// Slices one data message gathers from the caller's list. The send buffer hands
+/// out a length prefix and a body per queued frame, so this covers a run of frames
+/// rather than a single one; a longer backlog than this simply comes back on the
+/// next turn of Connection::flush.
+constexpr size_t kMaxParts = 16;
+
+} // namespace
+
+Circuit::Circuit(uint32_t id, std::shared_ptr<CircuitCarrier> carrier, bool open,
+                 uint32_t recv_window, uint32_t peer_window)
+    : id_(id),
+      carrier_(std::move(carrier)),
+      state_(open ? State::Open : State::Pending),
+      recv_window_(recv_window == 0 ? kDefaultWindow : recv_window),
+      send_credit_(open ? peer_window : 0) {}
+
+std::shared_ptr<Circuit> Circuit::opening(uint32_t id, std::shared_ptr<CircuitCarrier> carrier,
+                                          uint32_t recv_window) {
+    return std::shared_ptr<Circuit>(
+        new Circuit(id, std::move(carrier), /*open=*/false, recv_window, /*peer_window=*/0));
+}
+
+std::shared_ptr<Circuit> Circuit::accepted(uint32_t id, std::shared_ptr<CircuitCarrier> carrier,
+                                           uint32_t peer_window, uint32_t recv_window) {
+    return std::shared_ptr<Circuit>(
+        new Circuit(id, std::move(carrier), /*open=*/true, recv_window, peer_window));
+}
+
+// ── Fed by the relay module ─────────────────────────────────────────────────
+
+uint32_t Circuit::on_data(ByteView bytes) {
+    if (state_ == State::Closed || bytes.empty()) return 0;
+
+    // The window is the ONE thing bounding what this circuit can cost us and the
+    // relay carrying it, so a peer that sends past what it was granted is not
+    // merely impolite — it is doing the thing the window exists to prevent. Fail
+    // the circuit rather than accept the bytes.
+    if (bytes.size() > recv_window_ - recv_in_flight_) {
+        LOG_WARN("relay", "Circuit " << id_ << " overran its receive window ("
+                 << bytes.size() << " B with " << (recv_window_ - recv_in_flight_)
+                 << " B granted); failing it");
+        return on_closed(CloseReason::ProtocolError, /*orderly=*/false);
+    }
+    recv_in_flight_ += static_cast<uint32_t>(bytes.size());
+
+    // Hand back the consumed prefix before growing: the connection normally drains
+    // the inbox to empty on every readable event, so this is nearly always a reset
+    // of an already-empty buffer rather than a move.
+    if (inbox_read_ == inbox_.size()) {
+        inbox_.clear();
+        inbox_read_ = 0;
+    } else if (inbox_read_ >= kCompactThreshold) {
+        inbox_.erase(inbox_.begin(), inbox_.begin() + static_cast<std::ptrdiff_t>(inbox_read_));
+        inbox_read_ = 0;
+    }
+
+    inbox_.insert(inbox_.end(), bytes.begin(), bytes.end());
+    return PollIn;
+}
+
+uint32_t Circuit::on_accept(uint32_t peer_window) {
+    if (state_ != State::Pending) return 0;
+    state_       = State::Open;
+    send_credit_ = peer_window;
+    // Unconditional, unlike the other openings below: the Connection is still in
+    // Connecting and has nothing queued, so want_write_ is false — yet this is
+    // precisely the event it is waiting for to finish connecting and start its
+    // handshake (see Connection::on_writable).
+    return PollOut;
+}
+
+uint32_t Circuit::on_credit(uint32_t bytes) {
+    if (state_ == State::Closed || bytes == 0) return 0;
+    // Saturate rather than wrap: a far end that grants nonsense should cost us
+    // nothing worse than an over-generous window, and the receiver's own window
+    // check is what actually bounds the traffic.
+    if (bytes > UINT32_MAX - send_credit_) send_credit_ = UINT32_MAX;
+    else                                   send_credit_ += bytes;
+
+    if (!credit_blocked_) return 0;
+    credit_blocked_ = false;
+    return writable_event();
+}
+
+uint32_t Circuit::on_closed(CloseReason reason, bool orderly) {
+    if (state_ == State::Closed) return 0;
+    state_   = State::Closed;
+    reason_  = reason;
+    orderly_ = orderly;
+    // An orderly close still owes the application whatever the far end sent before
+    // it: read() drains the inbox first and only then reports the end of stream, so
+    // what this needs is a readable event, not an error. That is the same contract
+    // the other links keep (see Link::read).
+    return orderly ? PollIn : PollErr;
+}
+
+uint32_t Circuit::on_carrier_writable() {
+    if (!carrier_blocked_) return 0;
+    carrier_blocked_ = false;
+    return writable_event();
+}
+
+uint32_t Circuit::writable_event() const noexcept {
+    if (blocked() || !want_write_ || state_ != State::Open) return 0;
+    return PollOut;
+}
+
+// ── Driven by the Connection ────────────────────────────────────────────────
+
+Link::IoResult Circuit::read(ByteSpan into) {
+    const size_t available = inbox_.size() - inbox_read_;
+    const size_t n = (std::min)(available, into.size());
+    if (n > 0) {
+        std::memcpy(into.data(), inbox_.data() + inbox_read_, n);
+        inbox_read_ += n;
+        if (inbox_read_ == inbox_.size()) {
+            inbox_.clear();
+            inbox_read_ = 0;
+        }
+
+        // These bytes are out of the pipe, so the far end may put that much back
+        // in. Granted in batches: one small message per half-window rather than one
+        // per chunk, which is what keeps the credit scheme's overhead invisible.
+        recv_in_flight_ -= static_cast<uint32_t>(n);
+        recv_ungranted_ += static_cast<uint32_t>(n);
+        if (state_ != State::Closed && recv_ungranted_ >= recv_window_ / kCreditGrantFraction) {
+            carrier_->circuit_send_credit(id_, recv_ungranted_);
+            recv_ungranted_ = 0;
+        }
+        return {n, Link::Status::Ok};
+    }
+
+    // Drained. Only now may the end of the stream be reported — data and
+    // end-of-stream are never delivered together.
+    if (state_ == State::Closed)
+        return {0, orderly_ ? Link::Status::Closed : Link::Status::Error};
+    return {0, Link::Status::WouldBlock};
+}
+
+Link::IoResult Circuit::write(const ByteView* slices, size_t count) {
+    if (state_ == State::Closed) return {0, Link::Status::Error};
+    // Pending: opened but not yet accepted. Nothing may go out — and nothing tries
+    // to, since the Connection is still Connecting.
+    if (state_ != State::Open) return {0, Link::Status::WouldBlock};
+    if (blocked())             return {0, Link::Status::WouldBlock};
+
+    const size_t budget = (std::min)(static_cast<size_t>(send_credit_), kMaxDataChunk);
+    if (budget == 0) {
+        credit_blocked_ = true;
+        return {0, Link::Status::WouldBlock};
+    }
+
+    // One data message per call, gathered across as many of the caller's slices as
+    // fit. Connection::flush loops while a link keeps reporting Ok, so a backlog
+    // larger than one chunk simply comes back around — no loop is needed here, and
+    // each turn of that loop re-checks the credit and the carrier.
+    ByteView parts[kMaxParts];
+    size_t   nparts = 0;
+    size_t   taken  = 0;
+    for (size_t i = 0; i < count && taken < budget && nparts < kMaxParts; ++i) {
+        if (slices[i].empty()) continue;
+        const size_t take = (std::min)(slices[i].size(), budget - taken);
+        parts[nparts++] = ByteView(slices[i].data(), take);
+        taken += take;
+    }
+    if (taken == 0) return {0, Link::Status::WouldBlock};
+
+    send_credit_ -= static_cast<uint32_t>(taken);
+    // The carrier queues what it is given either way; false is "stop and wait", so
+    // the bytes are ours to report as written and the block applies to the NEXT
+    // call (see CircuitCarrier::circuit_send_data).
+    if (!carrier_->circuit_send_data(id_, parts, nparts)) carrier_blocked_ = true;
+    return {taken, Link::Status::Ok};
+}
+
+void Circuit::shutdown(CloseReason reason) {
+    if (!close_sent_) {
+        close_sent_ = true;
+        carrier_->circuit_send_close(id_, reason);
+    }
+    if (state_ != State::Closed) {
+        state_   = State::Closed;
+        reason_  = reason;
+        orderly_ = false;
+    }
+}
+
+void Circuit::release() {
+    if (released_) return;
+    released_ = true;
+    state_    = State::Closed;
+    carrier_->circuit_released(id_);
+}
+
+} // namespace librats