librats 1.0.2 → 2.1.4

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

@@ -0,0 +1,343 @@
+#include "librats/transport/connection.h"
+#include "librats/transport/reactor.h"
+#include "librats/core/io_poller.h"
+#include "librats/util/logger.h"
+
+#include <algorithm>
+#include <cerrno>
+#include <cstring>
+
+namespace librats {
+
+namespace {
+
+constexpr size_t kRecvChunk = 16 * 1024;  ///< bytes offered to each recv()
+
+/// Ceiling on how far rx_ may be grown on the strength of a *declared* block length
+/// alone. Sizing the buffer for the whole block up front (as libtorrent does, growing
+/// straight to packet_size) turns a large frame into one allocation instead of a
+/// 1.5x-at-a-time climb that memmoves everything received so far at every step. But
+/// the length is the peer's word: a 4-byte prefix claiming kMaxBlockSize must not
+/// make us allocate 64 MiB for a peer that then sends nothing. Past this, growth
+/// falls back to geometric, so the allocation only ever tracks bytes that really
+/// arrived — a big block still costs a handful of reallocations, not tens.
+constexpr size_t kMaxEagerReserve = 1024 * 1024;
+
+/// Frames up to this size are copied into the send queue rather than moved into a
+/// chunk of their own (see queue_block). Matches the queue's scratch chunk, so a
+/// small frame and its length prefix land in the same allocation.
+constexpr size_t kInlineBlockLimit = ChainedSendBuffer::kScratchCapacity;
+
+} // namespace
+
+Connection::Connection(ConnId id, std::unique_ptr<Link> link, ConnRole role,
+                       Reactor& reactor, ConnectionDelegate& delegate)
+    : id_(id), link_(std::move(link)), role_(role), reactor_(reactor), delegate_(delegate) {}
+
+Connection::~Connection() = default;
+
+IpAddress Connection::remote_ip() const {
+    // The peer's source IP as the transport sees it, with no textual round-trip.
+    // (The source port is not dialable — ephemeral on TCP, NAT-rewritten on UDP —
+    // so it is discarded; identify supplies the real listen port.)
+    const auto ep = link_->remote_endpoint();
+    return ep ? ep->ip : IpAddress{};
+}
+
+uint8_t Connection::reactor_index() const noexcept { return reactor_.index(); }
+
+// ── Outbound application frames ─────────────────────────────────────────────
+
+bool Connection::send(FrameHeader header, ByteView payload) {
+    if (state_ != ConnState::Established) return false;  // frames only flow post-handshake
+
+    Bytes inner;
+    framer::encode_message(inner, header, payload);
+
+    Bytes cipher;
+    if (!session_->encrypt(inner, cipher)) {
+        LOG_ERROR("connection", "Peer " << remote_id_.short_hex() << " encrypt failed");
+        reactor_.close(id_, CloseReason::ProtocolError);
+        return false;
+    }
+
+    queue_block(std::move(cipher));
+
+    const size_t backlog_now = backlog();
+    if (backlog_now > send_high_water_) {
+        LOG_WARN("connection", "Peer " << remote_id_.short_hex() << " over send high-water ("
+                 << backlog_now << " B); closing as slow consumer");
+        close_reason_ = CloseReason::SlowConsumer;
+        state_ = ConnState::Closing;
+        reactor_.close(id_, CloseReason::SlowConsumer);
+        return false;
+    }
+
+    // The queue has grown past what a caller should keep adding to. Everything
+    // still goes out — nothing is dropped here — but the answer to "may I send
+    // more?" becomes no, and stays no until the queue drains back under the mark
+    // and on_writable says so. Without this an application has no way at all to
+    // tell that it is outrunning the link, and the only thing that eventually
+    // tells it is the disconnection above.
+    if (!over_low_water_ && backlog_now > send_low_water_) {
+        over_low_water_ = true;
+        delegate_.on_writable_changed(*this, false);
+    }
+
+    // Aggregate rather than write through. Several frames produced in one batch
+    // of reactor tasks belong in ONE write, and flushing on each of them costs a
+    // system call per frame — measured at roughly ten times the throughput on
+    // small messages, on both transports. The flush happens at the end of the
+    // reactor turn (Reactor::flush_dirty), which is still the same turn: nothing
+    // waits on a timer and no latency is added.
+    //
+    // Past a point, though, waiting buys nothing: a backlog this size already
+    // fills a write, and letting it grow further would only hold memory and
+    // delay the bytes. So a large queue goes out at once, exactly as before.
+    if (tx_.size() >= kCoalesceLimit) {
+        if (!flush()) reactor_.close(id_, close_reason_);
+    } else if (!flush_queued_) {
+        flush_queued_ = true;
+        reactor_.mark_dirty(id_);
+    }
+    return !over_low_water_;
+}
+
+bool Connection::flush_pending() {
+    flush_queued_ = false;
+    return flush();
+}
+
+void Connection::queue_block(Bytes body) {
+    // The length prefix is queued as its own slice instead of being spliced in front
+    // of `body` — gather I/O reunites them in one writev, so framing costs no copy.
+    uint8_t prefix[framer::kLengthPrefixSize];
+    framer::encode_block_header(prefix, body.size());
+    tx_.append(ByteView(prefix, sizeof(prefix)));
+
+    // Small frame: copy it in, so prefix and body share one packed chunk. A memcpy of
+    // a few hundred bytes is cheaper than the allocation it saves — and it keeps a
+    // backlog of small frames from costing a chunk each.
+    // Large frame: move it, so a megabyte-sized payload is never copied to be framed.
+    if (body.size() <= kInlineBlockLimit) tx_.append(ByteView(body));
+    else                                  tx_.append(std::move(body));
+}
+
+// ── Handshake lifecycle ─────────────────────────────────────────────────────
+
+void Connection::start_handshake() {
+    if (state_ == ConnState::Connecting) begin_handshake();
+}
+
+void Connection::begin_handshake() {
+    state_ = ConnState::Handshaking;
+    // The transport is up, so the write-interest raised for the connect itself is
+    // no longer wanted; flush() re-arms it if the handshake outgrows the link.
+    want_write_ = false;
+    link_->want_write(false);
+
+    handshaker_ = reactor_.security().create(role_);
+    Bytes out;
+    if (!handshaker_->start(out)) {
+        reactor_.close(id_, CloseReason::HandshakeFailed);
+        return;
+    }
+    if (!out.empty()) {
+        queue_block(std::move(out));   // initiator's first message
+        if (!flush()) { reactor_.close(id_, close_reason_); return; }
+    }
+}
+
+bool Connection::drive_handshake(ByteView body) {
+    Bytes out;
+    auto outcome = handshaker_->consume(body, out);
+    if (outcome.status == Handshaker::Outcome::Failed) {
+        return fail(CloseReason::HandshakeFailed);
+    }
+    if (!out.empty()) {
+        queue_block(std::move(out));   // reply (responder's message, or initiator's final)
+        if (!flush()) return false;
+    }
+    if (outcome.status == Handshaker::Outcome::Done) {
+        session_   = std::move(outcome.session);
+        remote_id_ = outcome.remote_id;
+        handshaker_.reset();
+        complete_established();
+    }
+    return true;
+}
+
+void Connection::cancel_establish_timer() {
+    if (establish_timer_ != kInvalidTimerId) {
+        reactor_.cancel(establish_timer_);
+        establish_timer_ = kInvalidTimerId;
+    }
+}
+
+void Connection::complete_established() {
+    state_ = ConnState::Established;
+    cancel_establish_timer();
+    LOG_DEBUG("connection", "Peer " << remote_id_.short_hex() << " established ("
+              << (role_ == ConnRole::Inbound ? "inbound" : "outbound")
+              << (is_secure() ? ", encrypted)" : ", plaintext)"));
+    delegate_.on_established(*this);
+}
+
+// ── Inbound ─────────────────────────────────────────────────────────────────
+
+bool Connection::on_readable() {
+    // Drain the kernel buffer (the socket is non-blocking), parsing as we go. The
+    // parse step is inside the loop on purpose: it keeps rx_ down to one in-flight
+    // block no matter how fast the peer sends, where draining first and parsing
+    // afterwards would let rx_ grow to everything the peer managed to deliver.
+    //
+    // We must drain to would-block (or to a short read, which means the kernel
+    // buffer is now empty) — the kqueue backend is edge-triggered, so stopping with
+    // data still queued would leave the connection stalled until the *next* byte.
+    while (true) {
+        const ByteSpan into = rx_.prepare(read_size());
+
+        const Link::IoResult r = link_->read(into);
+        if (r.status == Link::Status::Closed) {
+            if (!process_blocks()) return false;  // deliver what the peer sent before FIN
+            return fail(CloseReason::PeerClosed);
+        }
+        if (r.status == Link::Status::Error)      return fail(link_->error_reason());
+        if (r.status == Link::Status::WouldBlock) break;
+
+        rx_.commit(r.bytes);
+        if (!process_blocks()) return false;
+
+        if (r.bytes < into.size()) break;  // link drained
+    }
+    return true;
+}
+
+size_t Connection::read_size() const {
+    // Not established yet: the peer is still anonymous, so its declared length buys it
+    // nothing. A handshake block is a Noise message plus the protocol id — hundreds of
+    // bytes — so there is no large allocation to save here, while honouring the length
+    // would let four bytes from an unauthenticated socket reserve kMaxEagerReserve. rx_
+    // still grows geometrically to hold whatever actually arrives, so an unusually large
+    // handshake block is served just as correctly, only without the eager reserve.
+    if (state_ != ConnState::Established) return kRecvChunk;
+
+    // Ask for the rest of the block we are mid-way through, so a large frame lands in
+    // one allocation rather than a series of 1.5x growth steps. Bounded by
+    // kMaxEagerReserve, since rx_need_ is a length the *peer* declared.
+    //
+    // Note this asks for the remainder even when it is *smaller* than kRecvChunk. It
+    // is tempting to floor it at kRecvChunk ("read as much as we can anyway"), but
+    // prepare(n) is a demand for n bytes of free tail, and a buffer sized exactly for
+    // the block has no kRecvChunk of tail left near the end of it — so the floor would
+    // force one last 1.5x grow (memcpy'ing the whole block that already arrived) for
+    // room that the block does not need. Nothing is lost by asking for less: prepare()
+    // hands back the *entire* free tail regardless, so the recv() is just as big.
+    if (rx_need_ > rx_.size()) return (std::min)(rx_need_ - rx_.size(), kMaxEagerReserve);
+    return kRecvChunk;
+}
+
+bool Connection::process_blocks() {
+    rx_need_ = 0;  // recomputed below: 0 == no block is mid-flight
+
+    // Body views point into rx_, so each block must be consumed before the next is
+    // decoded (and before any recv() reallocates the buffer under us).
+    while (!rx_.empty()) {
+        const auto block = framer::try_take_block(rx_.data(), rx_.size());
+        if (block.status == framer::Block::Incomplete) {
+            rx_need_ = block.needed;  // 0 while even the length prefix is short
+            break;
+        }
+        if (block.status == framer::Block::Error) return fail(CloseReason::ProtocolError);
+
+        const bool keep = (state_ == ConnState::Handshaking) ? drive_handshake(block.body)
+                                                             : deliver_frame(block.body);
+        rx_.consume(block.consumed);
+        if (!keep) return false;
+        if (state_ == ConnState::Closing || state_ == ConnState::Closed) return false;
+    }
+    return true;
+}
+
+bool Connection::deliver_frame(ByteView body) {
+    if (!session_) return fail(CloseReason::ProtocolError);  // data before handshake
+
+    Bytes plain;
+    if (!session_->decrypt(body, plain)) return fail(CloseReason::ProtocolError);
+
+    auto msg = framer::parse_message(plain);
+    if (!msg.ok) return fail(CloseReason::ProtocolError);
+
+    delegate_.on_frame(*this, msg.frame);
+    return true;
+}
+
+bool Connection::on_writable() {
+    // Finish the transport-level connect (a non-blocking TCP connect, or a Syn
+    // that has just been acknowledged), then begin the handshake.
+    if (state_ == ConnState::Connecting) {
+        if (!link_->connect_completed()) {
+            LOG_DEBUG("connection", "Peer " << id_ << " connect failed");
+            return fail(CloseReason::ConnectFailed);
+        }
+        begin_handshake();
+        if (state_ == ConnState::Closing) return false;
+    }
+    return flush();
+}
+
+bool Connection::on_error() {
+    return fail(link_->error_reason());
+}
+
+// ── Send buffer flush + write interest ──────────────────────────────────────
+
+bool Connection::flush() {
+    while (!tx_.empty()) {
+        // Hand the whole backlog to the kernel at once: a burst of queued frames
+        // (and the length prefix that precedes each one) leaves in a single syscall
+        // instead of one per chunk.
+        ByteView slices[kMaxSendSlices];
+        const size_t count = tx_.gather(slices, kMaxSendSlices);
+
+        const Link::IoResult r = link_->write(slices, count);
+        if (r.status == Link::Status::Ok) { tx_.pop_front(r.bytes); continue; }
+        if (r.status == Link::Status::WouldBlock) break;  // retry on the next writable event
+        return fail(link_->error_reason());
+    }
+
+    if (tx_.empty()) disarm_write();
+    else             arm_write();
+
+    // Drained back under the mark: whoever was told to stop can start again. The
+    // re-entrancy guard is what keeps a handler that answers by sending from
+    // recursing through flush() — it may queue, and the next drain reports the
+    // next opening, but it cannot nest.
+    if (over_low_water_ && !in_writable_ && backlog() <= send_low_water_) {
+        over_low_water_ = false;
+        in_writable_    = true;
+        delegate_.on_writable_changed(*this, true);
+        in_writable_    = false;
+    }
+    return true;
+}
+
+void Connection::arm_write() {
+    if (want_write_) return;
+    want_write_ = true;
+    link_->want_write(true);
+}
+
+void Connection::disarm_write() {
+    if (!want_write_) return;
+    want_write_ = false;
+    link_->want_write(false);
+}
+
+bool Connection::fail(CloseReason reason) {
+    close_reason_ = reason;
+    state_ = ConnState::Closing;
+    return false;  // tells the reactor to tear this connection down
+}
+
+} // namespace librats

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

@@ -0,0 +1,283 @@
+#pragma once
+
+/**
+ * @file connection.h
+ * @brief A single peer connection: byte-stream link, secure handshake, framing.
+ *
+ * A Connection is owned by exactly one Reactor and is only ever touched by that
+ * reactor's thread. Because of that single-threaded ownership it holds NO locks
+ * and uses NO atomics — all synchronisation lives at the reactor boundary (the
+ * task queue). This is the heart of the shared-nothing model.
+ *
+ * It is also transport-agnostic: everything here needs is an ordered, reliable,
+ * non-blocking byte stream, which is exactly what a Link is (see link.h). A
+ * connection over a kernel TCP socket and one over the library's reliable-UDP
+ * stream run the *same* code — same framing, same handshake, same backpressure —
+ * and differ only in which Link they hold.
+ *
+ * Lifecycle: Connecting → Handshaking → Established → Closing/Closed.
+ *   - Connecting:  outbound transport connect in flight (inbound skips this).
+ *   - Handshaking: a Handshaker (from the reactor's SecurityProvider) runs to
+ *                  completion, yielding a Session and the remote PeerId.
+ *   - Established: inbound blocks are decrypted into inner frames and delivered;
+ *                  outbound frames are encrypted and queued.
+ *
+ * The Connection reports events through a ConnectionDelegate and asks its Link
+ * to (dis)arm write-interest; it never touches the poller directly.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/core/types.h"
+#include "librats/core/bytes.h"
+#include "librats/wire/frame.h"
+#include "librats/peer/peer_id.h"
+#include "librats/security/handshaker.h"
+#include "librats/core/receive_buffer.h"
+#include "librats/core/chained_send_buffer.h"
+#include "librats/core/socket.h"
+#include "librats/transport/link.h"
+
+#include <atomic>
+#include <memory>
+
+namespace librats {
+
+class Connection;
+class Reactor;
+
+/**
+ * @brief Sink for connection lifecycle and inbound frames.
+ *
+ * All callbacks run on the owning reactor's thread. `on_established` fires once
+ * the secure handshake completes (so conn.remote_id() is valid). `on_closed` is
+ * the last call and is invoked by the Reactor during teardown, so a delegate may
+ * safely close other connections from within it.
+ */
+class RATS_API ConnectionDelegate {
+public:
+    virtual ~ConnectionDelegate() = default;
+
+    /// Admission gate for a freshly accepted inbound socket, asked by the Reactor
+    /// before it adopts the connection (i.e. before any handshake cost is paid).
+    /// Returning false makes the Reactor close the socket immediately. Runs on the
+    /// acceptor reactor thread. Default: always admit.
+    virtual bool admit_inbound() { return true; }
+
+    virtual void on_established(Connection& conn) = 0;
+    virtual void on_frame(Connection& conn, const Frame& frame) = 0;
+    virtual void on_closed(Connection& conn, CloseReason reason) = 0;
+
+    /// The send queue crossed its low-water mark: `writable` is false when it
+    /// filled past the mark (send() will now answer "no room") and true when it
+    /// has drained back under, so a sender that was told to stop may start again.
+    /// Runs on the reactor thread — from inside send() for the first, from inside
+    /// the flush that emptied the queue for the second — so a handler must not
+    /// block. Default: ignore.
+    virtual void on_writable_changed(Connection& /*conn*/, bool /*writable*/) {}
+
+    /// An outbound dial died before there was ever a Connection to report it on —
+    /// an unresolvable host, no route, no socket. Without this a dial policy that
+    /// reserved the ConnId (see Reactor::connect) would wait out a timeout for an
+    /// attempt that never began. Runs on the reactor thread. Default: ignore.
+    virtual void on_dial_aborted(uint8_t /*reactor_index*/, ConnId /*id*/,
+                                 const std::string& /*host*/, uint16_t /*port*/) {}
+};
+
+class Connection {
+public:
+    /// High-water mark for the memory held by the send queue; exceeding it closes the
+    /// connection with CloseReason::SlowConsumer.
+    static constexpr size_t kDefaultSendHighWater = 8 * 1024 * 1024;
+
+    /// Where send() starts answering "no room". A quarter of the hard limit, so a
+    /// caller that heeds the answer never comes near the point where the
+    /// connection is dropped, and one that ignores it is no worse off than before
+    /// this mark existed. This is the whole difference between a transport that
+    /// can be used correctly and one that merely disconnects you.
+    static constexpr size_t kDefaultSendLowWater = kDefaultSendHighWater / 4;
+
+    /// Queued bytes past which send() stops holding the batch back and writes
+    /// immediately. Aggregating below this is what turns a burst of small frames
+    /// into one system call; above it there is already enough to fill a write, so
+    /// waiting would only cost memory and delay.
+    static constexpr size_t kCoalesceLimit = 64 * 1024;
+
+    Connection(ConnId id, std::unique_ptr<Link> link, ConnRole role,
+               Reactor& reactor, ConnectionDelegate& delegate);
+    ~Connection();
+
+    Connection(const Connection&) = delete;
+    Connection& operator=(const Connection&) = delete;
+
+    // — identity / state (reactor thread) —
+    ConnId        id() const noexcept        { return id_; }
+    uint8_t       reactor_index() const noexcept;  ///< index of the owning reactor
+    Link&         link() const noexcept      { return *link_; }
+    /// The kernel socket behind this connection, or RATS_INVALID_SOCKET when the
+    /// transport has none of its own (UDP streams share the mux's socket).
+    socket_t      socket() const noexcept    { return link_->fd(); }
+    TransportKind transport() const noexcept { return link_->kind(); }
+    ConnRole      role() const noexcept      { return role_; }
+    ConnState     state() const noexcept     { return state_; }
+    CloseReason   close_reason() const noexcept { return close_reason_; }
+    const PeerId& remote_id() const noexcept { return remote_id_; }
+    bool          is_secure() const noexcept { return session_ && session_->is_secure(); }
+
+    /// Queue an application frame for the peer. No-op unless Established.
+    ///
+    /// @return whether there is still room for more. False means the queue is
+    ///         past its low-water mark — this frame is queued like any other,
+    ///         nothing is dropped, but the caller should stop and wait for
+    ///         ConnectionDelegate::on_writable rather than keep piling on until
+    ///         the connection is dropped as a slow consumer.
+    bool send(FrameHeader header, ByteView payload);
+
+    /// Whether the send queue currently has room (see send()).
+    bool writable() const noexcept { return !over_low_water_; }
+
+    /// Adopt the peer's in-transit counter: bytes a caller has handed to this
+    /// reactor that have not reached send() yet (see PeerTable::Entry::owed).
+    ///
+    /// They are as much of the backlog as the queue itself — held in the reactor's
+    /// task queue rather than in tx_, and on their way here — so the marks below
+    /// weigh them together with what is queued. Without that the two halves would
+    /// answer separately: a caller told "no room" because its charge crossed the
+    /// mark would be waiting for an opening from a queue that never crossed
+    /// anything, and so would never be told the room came back.
+    void set_in_transit(std::shared_ptr<const std::atomic<size_t>> owed) noexcept {
+        in_transit_ = std::move(owed);
+    }
+
+    /// What this connection is carrying: queued here plus still on its way.
+    size_t backlog() const noexcept {
+        // Watch the memory the queue actually holds, not just the bytes still owed
+        // to the socket: a partially sent chunk keeps its whole allocation, so
+        // allocated() is what a peer that stops reading can make us carry.
+        return tx_.allocated() +
+               (in_transit_ ? in_transit_->load(std::memory_order_relaxed) : 0);
+    }
+
+    /// Resize the send queue's marks. `high` is where the connection is dropped
+    /// as a slow consumer; the low-water mark send() reports against is derived
+    /// from it, so the two can never be set inconsistently. Called once, right
+    /// after the handshake, when the node's config asks for something other than
+    /// the default.
+    void set_send_high_water(size_t high) noexcept {
+        send_high_water_ = high;
+        send_low_water_  = high / 4;
+    }
+
+    /// Write out what send() queued during this reactor turn. Called by the
+    /// Reactor at the end of the turn; false ⇒ the connection must be torn down.
+    bool flush_pending();
+
+    /// Convenience: send raw bytes on an application channel.
+    bool send(uint16_t channel, ByteView payload) {
+        return send(FrameHeader{MessageType::App, 0, channel}, payload);
+    }
+
+    // — reactor-driven I/O callbacks. Return false to request teardown. —
+    bool on_readable();
+    bool on_writable();
+    bool on_error();
+
+    /// Bring an accepted (inbound) socket up: it is already connected, so begin
+    /// the handshake immediately. Called by the Reactor right after adopt().
+    void start_handshake();
+
+    /// Associate the establishment-timeout timer so it can be cancelled once the
+    /// connection reaches Established. Set by the Reactor after adopt().
+    void set_establish_timer(TimerId id) noexcept { establish_timer_ = id; }
+
+    /// Cancel the establishment-timeout timer if still armed; idempotent. Called
+    /// both on success (complete_established) and on teardown (Reactor::remove) so
+    /// the reaper can never outlive the connection and fire against a reused fd.
+    void cancel_establish_timer();
+
+    /// Periodic housekeeping, driven by the Reactor's maintenance timer. Hands back
+    /// the receive buffer of a peer that has gone quiet — a peer that sent one big
+    /// frame and then fell silent would otherwise sit on that allocation for the life
+    /// of the connection. Reactor thread; never closes the connection.
+    void on_maintenance_tick() { rx_.decay(); }
+
+    /// Record the address this outbound connection was dialed at (so the peer's
+    /// reconnect address is known). Set by the Reactor after adopt(); reactor thread.
+    void set_dial_address(std::string host, uint16_t port) {
+        dial_host_ = std::move(host);
+        dial_port_ = port;
+    }
+    bool               has_dial_address() const noexcept { return dial_port_ != 0; }
+    const std::string& dial_host() const noexcept { return dial_host_; }
+    uint16_t           dial_port() const noexcept { return dial_port_; }
+
+    /// The peer's IP as the link sees it, without the source port (ephemeral on
+    /// TCP, NAT-rewritten on UDP). Combined with the peer's advertised listen port
+    /// by the node's identify exchange to form a dialable address — the only way
+    /// to learn the dialable address of an *inbound* peer. Unspecified on error.
+    IpAddress          remote_ip() const;
+
+    /// The peer's source endpoint as the link sees it, port included.
+    ///
+    /// The port is meaningless on TCP (an ephemeral one the peer's OS picked for an
+    /// outbound socket) but is NOT on a datagram link: there every peer shares one
+    /// socket, so what a NAT rewrote the source port to is exactly the port a third
+    /// party would have to aim at to reach this peer. That is what identify carries
+    /// on to it, and what a hole punch is aimed at. nullopt if the link cannot say.
+    std::optional<Address> remote_endpoint() const { return link_->remote_endpoint(); }
+
+    /// Tell the link the connection is going away, so a transport that owes the
+    /// peer a goodbye (or a last flush) can arrange it. Called by the Reactor
+    /// during teardown, before the Connection is destroyed.
+    void shutdown_link(CloseReason reason) { link_->close(reason); }
+
+private:
+    void begin_handshake();             ///< transport up → Handshaking
+    size_t read_size() const;           ///< bytes to offer the next recv() (see rx_need_)
+    bool process_blocks();              ///< decode every complete block in rx_; false ⇒ teardown
+    bool drive_handshake(ByteView body);///< feed one handshake block; false ⇒ teardown
+    bool deliver_frame(ByteView body);  ///< decrypt+parse+dispatch; false ⇒ teardown
+    void complete_established();         ///< handshake done → Established
+    void queue_block(Bytes body);       ///< length-prefix `body` into the send buffer
+    bool flush();                       ///< drain tx_ to the socket; false ⇒ teardown
+    void arm_write();
+    void disarm_write();
+    bool fail(CloseReason);             ///< record reason, return false (teardown)
+
+    ConnId                id_;
+    std::unique_ptr<Link> link_;
+    ConnRole              role_;
+    ConnState           state_ = ConnState::Connecting;
+    CloseReason         close_reason_ = CloseReason::PeerClosed;
+    Reactor&            reactor_;
+    ConnectionDelegate& delegate_;
+
+    std::unique_ptr<Handshaker> handshaker_;  ///< non-null only while Handshaking
+    std::unique_ptr<Session>    session_;      ///< non-null once Established
+    PeerId                      remote_id_;
+
+    ReceiveBuffer     rx_;  ///< allocates on first read, shrinks back when idle
+    /// Wire size of the block rx_ is mid-way through, once its length prefix has been
+    /// read; 0 when no block is in flight. Lets the next recv() size rx_ for the whole
+    /// block in one go instead of growing into it. Peer-declared, hence capped.
+    size_t            rx_need_ = 0;
+    ChainedSendBuffer tx_;
+    bool              want_write_ = false;
+    /// A flush is already booked for the end of this reactor turn, so further
+    /// frames only need to join the queue rather than book another one.
+    bool              flush_queued_ = false;
+    /// The queue went past its low-water mark and the caller has been told to
+    /// stop; cleared, with a notification, once it drains back under.
+    bool              over_low_water_ = false;
+    /// Inside the on_writable callback — see flush().
+    bool              in_writable_ = false;
+    /// Charged by send() callers on any thread, discharged by the reactor task
+    /// just before the frame reaches send() — see set_in_transit().
+    std::shared_ptr<const std::atomic<size_t>> in_transit_;
+    size_t            send_high_water_ = kDefaultSendHighWater;
+    size_t            send_low_water_  = kDefaultSendLowWater;
+    TimerId           establish_timer_ = kInvalidTimerId;  ///< connect+handshake deadline
+    std::string       dial_host_;                          ///< address we dialed (outbound)
+    uint16_t          dial_port_ = 0;
+};
+
+} // namespace librats