librats 2.2.0 → 2.3.1

package/lib/index.d.ts

@@ -91,9 +91,23 @@ declare module 'librats' {
     preferredTransport?: TransportValue;
     /** Delay before the other transport is raced alongside; 0 disables. Default 1200. */
     transportFallbackMs?: number;
+    /**
+     * Bytes a peer's send queue may hold before an app that keeps sending anyway
+     * has that peer dropped with reason `RATS_CLOSE_SLOW_CONSUMER`. 0 (default)
+     * uses the library's 8 MiB. A quarter of it is where `peerWritable()` starts
+     * returning false. Not a maximum message size.
+     */
+    sendQueueLimit?: number;
   }
 
   export type PeerHandler = (peerId: string) => void;
+  /**
+   * `reason` is why the peer went — "RATS_CLOSE_PEER_CLOSED",
+   * "RATS_CLOSE_SLOW_CONSUMER" and so on. Worth branching on: a peer that left is
+   * one to redial, while SLOW_CONSUMER means *you* were sending faster than the
+   * link drained, and redialing that one just repeats the overload.
+   */
+  export type PeerDisconnectHandler = (peerId: string, reason: string) => void;
   export type MessageHandler = (peerId: string, data: Buffer) => void;
   export type TopicHandler = (peerId: string, topic: string, data: Buffer) => void;
   export type JsonHandler = (peerId: string, value: any) => void;
@@ -180,17 +194,31 @@ declare module 'librats' {
 
     // ---- raw channel messaging ----
 
-    /** Send raw bytes on a named channel to one peer. */
+    /**
+     * Send raw bytes on a named channel to one peer. Returning means the message
+     * was queued, never that it arrived — if you send in bulk, follow it with
+     * `peerWritable()`.
+     */
     send(peerId: string, channel: string, data: string | Buffer): void;
     /** Broadcast raw bytes on a named channel to every connected peer. */
     broadcast(channel: string, data: string | Buffer): void;
+    /**
+     * Whether this peer's send queue still has room (false also when it is not
+     * connected). False means stop: what you just sent was queued like anything
+     * else and nothing was dropped, but keep piling on and the peer is dropped
+     * with reason `RATS_CLOSE_SLOW_CONSUMER`. Wait for `onPeerWritable`, or poll
+     * this. Not a size limit — one message of any size is always queued.
+     */
+    peerWritable(peerId: string): boolean;
     /** Register a handler for a named channel. Additive; register before `start()`. */
     on(channel: string, handler: MessageHandler): void;
 
     // ---- peer events (register before start) ----
 
     onPeerConnected(handler: PeerHandler): void;
-    onPeerDisconnected(handler: PeerHandler): void;
+    onPeerDisconnected(handler: PeerDisconnectHandler): void;
+    /** A peer whose queue had filled has drained back under its mark. */
+    onPeerWritable(handler: PeerHandler): void;
 
     // ---- discovery (enable before start) ----
 

package/lib/index.js

@@ -193,6 +193,14 @@ class RatsNode {
    */
   broadcast(channel, data) { this._native.broadcast(channel, data); }
 
+  /**
+   * Whether this peer's send queue still has room. False means pause and wait for
+   * `onPeerWritable` — keep sending regardless and the peer is dropped with
+   * reason `RATS_CLOSE_SLOW_CONSUMER`.
+   * @param {string} peerId @returns {boolean}
+   */
+  peerWritable(peerId) { return this._native.peerWritable(peerId); }
+
   /**
    * Register a handler for a named channel. Additive; register before `start()`.
    * @param {string} channel
@@ -205,9 +213,16 @@ class RatsNode {
   /** @param {(peerId: string) => void} handler fired when a peer connects. */
   onPeerConnected(handler) { this._native.onPeerConnected(handler); }
 
-  /** @param {(peerId: string) => void} handler fired when a peer disconnects. */
+  /**
+   * @param {(peerId: string, reason: string) => void} handler fired when a peer
+   * disconnects. `reason` is a name like "RATS_CLOSE_SLOW_CONSUMER", which means
+   * this node was sending faster than the link drained.
+   */
   onPeerDisconnected(handler) { this._native.onPeerDisconnected(handler); }
 
+  /** @param {(peerId: string) => void} handler fired when a full queue drained. */
+  onPeerWritable(handler) { this._native.onPeerWritable(handler); }
+
   // ---- discovery (enable before start) ----
 
   /**

package/native-src/CMakeLists.txt

@@ -492,16 +492,58 @@ if(WIN32)
     target_link_libraries(rats ws2_32 iphlpapi bcrypt advapi32)
 endif()
 
-if(ANDROID)
+# Android can be built two ways, and only one of them sets CMake's ANDROID variable:
+# through the NDK's android.toolchain.cmake (sets ANDROID / ANDROID_PLATFORM), or by
+# simply pointing CC/CXX at the NDK's <triple><api>-clang wrappers, which is what the
+# Android CI does. The compiler is the only thing that knows in both cases, so ask it
+# rather than trusting a toolchain-file-only variable.
+if(NOT ANDROID)
+    check_cxx_source_compiles("
+#ifndef __ANDROID__
+#error not android
+#endif
+int main() { return 0; }
+" RATS_TARGET_IS_ANDROID)
+else()
+    set(RATS_TARGET_IS_ANDROID TRUE)
+endif()
+
+if(RATS_TARGET_IS_ANDROID)
+    # The logger routes console output through __android_log_print, because an app's
+    # stdout/stderr go nowhere on Android. This is used from librats/util/logger.h,
+    # i.e. from consumers of the static library too, so the dependency is PUBLIC.
+    # Only search for it when the NDK toolchain file configured a sysroot to search;
+    # with a bare NDK clang, find_library would look at host paths, so let the driver
+    # resolve -llog out of its own sysroot instead.
+    if(ANDROID)
+        find_library(log-lib log)
+        target_link_libraries(rats ${log-lib})
+    else()
+        target_link_libraries(rats log)
+    endif()
+
+    # API level: from the toolchain file when it set one, otherwise from the compiler.
     if(DEFINED ANDROID_PLATFORM)
         string(REGEX REPLACE "android-" "" ANDROID_API_LEVEL ${ANDROID_PLATFORM})
         math(EXPR ANDROID_API_LEVEL "${ANDROID_API_LEVEL}")
         message(STATUS "Android API level detected: ${ANDROID_API_LEVEL}")
+        if(ANDROID_API_LEVEL LESS 24)
+            set(RATS_ANDROID_NEEDS_IFADDRS TRUE)
+        endif()
     else()
-        message(FATAL_ERROR "ANDROID_PLATFORM is not defined!")
+        check_cxx_source_compiles("
+#include <android/api-level.h>
+#if __ANDROID_API__ < 24
+#error too old
+#endif
+int main() { return 0; }
+" RATS_ANDROID_API_24_OR_NEWER)
+        if(NOT RATS_ANDROID_API_24_OR_NEWER)
+            set(RATS_ANDROID_NEEDS_IFADDRS TRUE)
+        endif()
     endif()
 
-    if(ANDROID_API_LEVEL LESS 24)
+    if(RATS_ANDROID_NEEDS_IFADDRS)
         target_sources(rats PRIVATE ${PROJECT_SOURCE_DIR}/3rdparty/android/ifaddrs-android.c)
         target_include_directories(rats
             PRIVATE

package/native-src/src/librats/bindings/rats.cpp

@@ -85,6 +85,24 @@ char* dup_string(const std::string& s) {
     return out;
 }
 
+rats_close_reason_t to_c_reason(CloseReason r) {
+    switch (r) {
+        case CloseReason::LocalClose:      return RATS_CLOSE_LOCAL;
+        case CloseReason::PeerClosed:      return RATS_CLOSE_PEER_CLOSED;
+        case CloseReason::PeerReset:       return RATS_CLOSE_PEER_RESET;
+        case CloseReason::ConnectFailed:   return RATS_CLOSE_CONNECT_FAILED;
+        case CloseReason::HandshakeFailed: return RATS_CLOSE_HANDSHAKE_FAILED;
+        case CloseReason::ProtocolError:   return RATS_CLOSE_PROTOCOL_ERROR;
+        case CloseReason::SlowConsumer:    return RATS_CLOSE_SLOW_CONSUMER;
+        case CloseReason::ReactorShutdown: return RATS_CLOSE_SHUTDOWN;
+        case CloseReason::DuplicateConn:   return RATS_CLOSE_DUPLICATE;
+        case CloseReason::PeerLimit:       return RATS_CLOSE_PEER_LIMIT;
+        case CloseReason::IdleTimeout:     return RATS_CLOSE_IDLE_TIMEOUT;
+        case CloseReason::DialSuperseded:  return RATS_CLOSE_DIAL_SUPERSEDED;
+    }
+    return RATS_CLOSE_PEER_CLOSED;
+}
+
 } // namespace
 
 extern "C" {
@@ -103,6 +121,24 @@ const char* rats_error_str(rats_error_t err) {
     return "RATS_ERR_UNKNOWN";
 }
 
+const char* rats_close_reason_str(rats_close_reason_t reason) {
+    switch (reason) {
+        case RATS_CLOSE_LOCAL:            return "RATS_CLOSE_LOCAL";
+        case RATS_CLOSE_PEER_CLOSED:      return "RATS_CLOSE_PEER_CLOSED";
+        case RATS_CLOSE_PEER_RESET:       return "RATS_CLOSE_PEER_RESET";
+        case RATS_CLOSE_CONNECT_FAILED:   return "RATS_CLOSE_CONNECT_FAILED";
+        case RATS_CLOSE_HANDSHAKE_FAILED: return "RATS_CLOSE_HANDSHAKE_FAILED";
+        case RATS_CLOSE_PROTOCOL_ERROR:   return "RATS_CLOSE_PROTOCOL_ERROR";
+        case RATS_CLOSE_SLOW_CONSUMER:    return "RATS_CLOSE_SLOW_CONSUMER";
+        case RATS_CLOSE_SHUTDOWN:         return "RATS_CLOSE_SHUTDOWN";
+        case RATS_CLOSE_DUPLICATE:        return "RATS_CLOSE_DUPLICATE";
+        case RATS_CLOSE_PEER_LIMIT:       return "RATS_CLOSE_PEER_LIMIT";
+        case RATS_CLOSE_IDLE_TIMEOUT:     return "RATS_CLOSE_IDLE_TIMEOUT";
+        case RATS_CLOSE_DIAL_SUPERSEDED:  return "RATS_CLOSE_DIAL_SUPERSEDED";
+    }
+    return "RATS_CLOSE_UNKNOWN";
+}
+
 /* — construction / lifecycle — */
 
 rats_config_t rats_config_default(void) {
@@ -118,6 +154,7 @@ rats_config_t rats_config_default(void) {
     c.enable_udp            = 1;
     c.preferred_transport   = RATS_TRANSPORT_UDP;
     c.transport_fallback_ms = 1200;
+    c.send_queue_limit      = 0;
     return c;
 }
 
@@ -153,6 +190,7 @@ rats_t rats_create_config(const rats_config_t* cfg) {
                                          ? TransportKind::Tcp
                                          : TransportKind::Udp;
         config.transport_fallback_ms = cfg->transport_fallback_ms;
+        config.send_queue_limit      = cfg->send_queue_limit;
     }
     return make_handle(std::move(config));
 }
@@ -224,6 +262,13 @@ rats_error_t rats_send(rats_t node, const char* peer_id_hex,
     return RATS_OK;
 }
 
+int rats_peer_writable(rats_t node, const char* peer_id_hex) {
+    if (!peer_id_hex) return 0;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return 0;
+    return node_of(node)->peer_writable(*id) ? 1 : 0;
+}
+
 rats_error_t rats_broadcast(rats_t node, const char* channel, const void* data, size_t len) {
     if (!channel) return RATS_ERR_INVALID_ARG;
     node_of(node)->broadcast(channel, ByteView(static_cast<const uint8_t*>(data), len));
@@ -238,10 +283,18 @@ rats_error_t rats_on_peer_connected(rats_t node, rats_peer_cb cb, void* user) {
     return RATS_OK;
 }
 
-rats_error_t rats_on_peer_disconnected(rats_t node, rats_peer_cb cb, void* user) {
+rats_error_t rats_on_peer_disconnected(rats_t node, rats_peer_disconnect_cb cb, void* user) {
+    if (!cb) return RATS_ERR_INVALID_ARG;
+    node_of(node)->on_peer_disconnected([cb, user](const PeerId& id, CloseReason reason) {
+        cb(user, id.to_hex().c_str(), to_c_reason(reason));
+    });
+    return RATS_OK;
+}
+
+rats_error_t rats_on_peer_writable(rats_t node, rats_peer_cb cb, void* user) {
     if (!cb) return RATS_ERR_INVALID_ARG;
-    node_of(node)->on_peer_disconnected([cb, user](const PeerId& id) {
-        cb(user, id.to_hex().c_str());
+    node_of(node)->on_peer_writable([cb, user](const Peer& peer) {
+        cb(user, peer.id().to_hex().c_str());
     });
     return RATS_OK;
 }

package/native-src/src/librats/bindings/rats.h

@@ -53,6 +53,33 @@ typedef enum {
     RATS_TRANSPORT_RELAY = 2
 } rats_transport_t;
 
+/* Why a peer connection ended, handed to rats_on_peer_disconnected(). The
+ * reason is what tells "I was sending too fast" apart from "the peer left" —
+ * without it both look the same and the usual answer to either is to reconnect
+ * and repeat whatever caused it. Use rats_close_reason_str() for a name. */
+typedef enum {
+    RATS_CLOSE_LOCAL            = 0,  /* we asked to disconnect */
+    RATS_CLOSE_PEER_CLOSED      = 1,  /* the peer closed cleanly */
+    RATS_CLOSE_PEER_RESET       = 2,  /* connection reset / socket error */
+    RATS_CLOSE_CONNECT_FAILED   = 3,  /* the dial never completed */
+    RATS_CLOSE_HANDSHAKE_FAILED = 4,  /* secure handshake failed or timed out */
+    RATS_CLOSE_PROTOCOL_ERROR   = 5,  /* malformed frame / decryption failure */
+    /* We kept sending while this peer's queue was already past its limit. THE
+     * ONE REASON THE APPLICATION CAN PREVENT: heed rats_send()'s answer and
+     * rats_peer_writable(), and wait for the writable callback. It does NOT mean
+     * a single message was too big — one message is always accepted whatever its
+     * size; only piling more on a full queue gets a peer dropped. */
+    RATS_CLOSE_SLOW_CONSUMER    = 6,
+    RATS_CLOSE_SHUTDOWN         = 7,  /* the node is stopping */
+    RATS_CLOSE_DUPLICATE        = 8,  /* superseded by another link to the same peer */
+    RATS_CLOSE_PEER_LIMIT       = 9,  /* inbound refused: peer limit reached */
+    RATS_CLOSE_IDLE_TIMEOUT     = 10, /* datagram link went silent */
+    RATS_CLOSE_DIAL_SUPERSEDED  = 11  /* a racing dial over the other transport won */
+} rats_close_reason_t;
+
+/** Static human-readable name for a close reason (never NULL, never freed). */
+RATS_API const char* rats_close_reason_str(rats_close_reason_t reason);
+
 /* Bitmask of transports (see rats_transports / rats_peer_transports). */
 #define RATS_TRANSPORT_MASK_TCP 0x1u
 #define RATS_TRANSPORT_MASK_UDP 0x2u
@@ -102,6 +129,14 @@ typedef struct {
     rats_transport_t preferred_transport;     /* tried first when dialing (default UDP) */
     uint32_t         transport_fallback_ms;   /* delay before racing the other transport;
                                                * 0 = never fall back (default 1200) */
+
+    /* Bytes a peer's send queue may hold before an application that keeps sending
+     * anyway has that peer dropped with RATS_CLOSE_SLOW_CONSUMER. 0 = the library
+     * default (8 MiB). A quarter of it is where rats_peer_writable() starts
+     * answering 0, so lowering this makes an application feel backpressure sooner.
+     * It is NOT a maximum message size: one message is always queued whatever its
+     * size. */
+    size_t           send_queue_limit;
 } rats_config_t;
 
 /** A config pre-filled with the library defaults (listening, Noise, ephemeral
@@ -153,18 +188,44 @@ RATS_API size_t rats_max_peers(rats_t node);
 
 /* — messaging (named application channel, raw bytes) — */
 
+/** Queue bytes for one peer on a named channel. RATS_OK means accepted and
+ *  queued, never that it arrived. Pair it with rats_peer_writable() below if you
+ *  send in bulk — that is the only way to learn you are outrunning the link
+ *  before the peer is dropped for it. */
 RATS_API rats_error_t rats_send(rats_t node, const char* peer_id_hex,
                                           const char* channel, const void* data, size_t len);
 RATS_API rats_error_t rats_broadcast(rats_t node, const char* channel,
                                                const void* data, size_t len);
 
+/** Whether this peer's send queue still has room — the same question rats_send()
+ *  answers, asked without sending. Returns 1 for room, 0 for none (and 0 for a
+ *  peer that is not connected).
+ *
+ *  A 0 says "stop". The message you just sent was queued like any other and
+ *  nothing was dropped, but keep piling on and this peer is dropped with
+ *  RATS_CLOSE_SLOW_CONSUMER. Wait for the callback registered with
+ *  rats_on_peer_writable(), or poll this from a thread of your own.
+ *
+ *  Ask it right after rats_send(): the bytes you just handed over are already
+ *  counted, so the answer covers your own send and not just what the reactor has
+ *  got round to. It is NOT a size limit — a single message of any size is always
+ *  accepted; only sending more on top of a full queue drops a peer. */
+RATS_API int rats_peer_writable(rats_t node, const char* peer_id_hex);
+
 /* — callbacks (register before start; invoked on a reactor thread) — */
 
 typedef void (*rats_peer_cb)(void* user, const char* peer_id_hex);
+typedef void (*rats_peer_disconnect_cb)(void* user, const char* peer_id_hex,
+                                        rats_close_reason_t reason);
 typedef void (*rats_message_cb)(void* user, const char* peer_id_hex, const void* data, size_t len);
 
 RATS_API rats_error_t rats_on_peer_connected(rats_t node, rats_peer_cb cb, void* user);
-RATS_API rats_error_t rats_on_peer_disconnected(rats_t node, rats_peer_cb cb, void* user);
+RATS_API rats_error_t rats_on_peer_disconnected(rats_t node, rats_peer_disconnect_cb cb,
+                                                          void* user);
+/** "This peer can be written to again" — fired when a peer whose queue had filled
+ *  past its mark has drained back under it. The other half of rats_send()
+ *  reporting 0; an application that never asks never needs this. */
+RATS_API rats_error_t rats_on_peer_writable(rats_t node, rats_peer_cb cb, void* user);
 RATS_API rats_error_t rats_on(rats_t node, const char* channel, rats_message_cb cb, void* user);
 
 /* — optional subsystems (enable before start) — */

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

@@ -13,7 +13,7 @@ const char* to_string(ConnState s) noexcept {
     return "?";
 }
 
-const char* to_string(CloseReason r) noexcept {
+RATS_API const char* to_string(CloseReason r) noexcept {
     switch (r) {
         case CloseReason::LocalClose:      return "LocalClose";
         case CloseReason::PeerClosed:      return "PeerClosed";

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

@@ -84,7 +84,9 @@ enum class CloseReason {
     ConnectFailed,     ///< Outbound transport connect never completed.
     HandshakeFailed,   ///< Secure-channel handshake failed or timed out.
     ProtocolError,     ///< Malformed frame / decryption failure on the wire.
-    SlowConsumer,      ///< Send buffer exceeded its high-water mark.
+    SlowConsumer,      ///< Kept sending with the queue already past its high-water
+                       ///< mark. Not "a message was too large": one message is
+                       ///< always queued whatever its size (Connection::send).
     ReactorShutdown,   ///< Reactor is stopping.
     DuplicateConn,     ///< Redundant connection to a peer we already hold; superseded.
     PeerLimit,         ///< Inbound rejected: the configured peer limit is reached.
@@ -93,11 +95,12 @@ enum class CloseReason {
 };
 
 const char* to_string(ConnState) noexcept;
-const char* to_string(CloseReason) noexcept;
-/// Exported, unlike its siblings above: TransportKind is part of the public
-/// surface (NodeConfig::preferred_transport, PeerInfo::transport), so a consumer
-/// of the shared build needs to be able to render one. ConnState/CloseReason only
-/// ever appear on Connection, which does not cross the library boundary.
+/// Exported: a CloseReason is handed to every on_peer_disconnected handler, so a
+/// consumer of the shared build has to be able to render one. (ConnState above is
+/// not — it never leaves Connection.)
+RATS_API const char* to_string(CloseReason) noexcept;
+/// Exported for the same reason: TransportKind is part of the public surface
+/// (NodeConfig::preferred_transport, PeerInfo::transport).
 RATS_API const char* to_string(TransportKind) noexcept;
 
 } // namespace librats

package/native-src/src/librats/node/config.h

@@ -52,8 +52,15 @@ struct RATS_API NodeConfig {
     /// connection. 0 disables the fallback: only the preferred transport is tried.
     uint32_t transport_fallback_ms = 1200;
 
-    /// Bytes a peer's send queue may hold before the peer is dropped as a slow
-    /// consumer. 0 uses the library default (8 MiB).
+    /// Bytes a peer's send queue may hold before an application that keeps
+    /// sending anyway has the peer dropped as a slow consumer. 0 uses the library
+    /// default (8 MiB).
+    ///
+    /// It is not a maximum message size. A single message is always queued
+    /// whatever its size — a message cannot be sent by halves, and a healthy
+    /// connection must not die over one large frame — so the queue's real ceiling
+    /// is this plus one message. What gets a peer dropped is offering *another*
+    /// message while the queue is still over the mark.
     ///
     /// A quarter of this is the mark at which send() starts answering "no room"
     /// and on_peer_writable is what says the room is back — so lowering it makes

package/native-src/src/librats/node/node.cpp

@@ -488,7 +488,15 @@ bool Node::send(const PeerId& to, std::string_view channel, ByteView payload) {
 
 bool Node::peer_writable(const PeerId& id) const {
     const auto dest = peers_.destination(id);
-    return dest && dest->writable;
+    if (!dest) return false;
+    // Both halves of the backlog, exactly as send() weighs them: what the reactor
+    // has already queued (`writable`) *and* what a caller has handed over that the
+    // reactor has not taken up yet (`owed`). Reporting only the first would answer
+    // "there is room" to a caller that has just filled the queue itself and is
+    // waiting to hear otherwise — the queue it filled has not been looked at yet,
+    // so nothing about it has changed, and no event is coming either.
+    return dest->writable &&
+           dest->owed->load(std::memory_order_relaxed) <= send_low_water();
 }
 
 bool Node::broadcast(std::string_view channel, ByteView payload) {
@@ -682,7 +690,7 @@ void Node::on_closed(Connection& conn, CloseReason reason) {
     // let a long-gone peer keep voting on how our NAT behaves.
     nat_status_.forget(id);
     LOG_INFO("node", "Peer " << id.short_hex() << " disconnected (" << to_string(reason) << ")");
-    for (auto& cb : peer_disconnected_) cb(id);
+    for (auto& cb : peer_disconnected_) cb(id, reason);
 }
 
 void Node::on_writable_changed(Connection& conn, bool writable) {
@@ -849,9 +857,16 @@ std::vector<Address> Node::observed_addresses() const {
 
 // ── Peer handle methods (defined here for the full Node type) ────────────────
 
-void Peer::send(std::string_view channel, ByteView payload) const {
-    node_->route_send(route_, FrameHeader{MessageType::App, 0, MessageRouter::channel_id(channel)},
-                      payload.to_bytes());
+bool Peer::send(std::string_view channel, ByteView payload) const {
+    // Deliberately by id, not by this handle's route. The route existed to skip the
+    // directory lookup on the reply path — but answering "is there room?" needs the
+    // peer's writability and its in-transit counter, both of which live in the
+    // directory, so the lookup is unavoidable the moment send() has an answer to
+    // give. Once it is being paid anyway, the captured route buys nothing and can
+    // only be wrong: a handle outlives its connection (a relayed link superseded by
+    // a direct one, a dial race, a reconnect), and sending on the superseded one
+    // drops the message with nothing said. The peer is what the caller means.
+    return node_->send(id_, channel, payload);
 }
 
 void Peer::disconnect() const {

package/native-src/src/librats/node/node.h

@@ -193,6 +193,14 @@ public:
     ///         low-water mark, and an application that keeps going regardless
     ///         will eventually have the peer dropped as a slow consumer. Wait for
     ///         on_peer_writable instead. Also false if the peer is not connected.
+    ///
+    ///         "Stop" is meant literally, and yielding is part of it: the mark is
+    ///         re-tested inside the reactor task this call hands off to, and it is
+    ///         that test which flips the peer to unwritable and later raises
+    ///         on_peer_writable. A caller that answers a false by looping straight
+    ///         back into send() therefore starves the very thread that would tell
+    ///         it to stop — the queue keeps growing while the signal it is waiting
+    ///         for never gets a turn to be produced.
     bool send(const PeerId& to, std::string_view channel, ByteView payload);
     /// Send raw bytes on a named channel to every connected peer.
     /// @return whether *every* one of them still has room — a fan-out can only
@@ -205,12 +213,24 @@ public:
     /// transfer, a large stream — address peers individually with send().
     bool broadcast(std::string_view channel, ByteView payload);
 
-    /// Whether a peer's send queue currently has room — the same answer send()
-    /// returns, without sending anything. False for a peer that is not connected.
-    /// Note that the answer describes the queue as the reactor last left it: a
-    /// message handed over a moment ago may not be counted yet, which is why the
-    /// signal to stop is the *return of send()* rather than a poll before it.
-    bool peer_writable(const PeerId& id) const;
+    /// Whether a peer's send queue has room for more. False for a peer that is
+    /// not connected.
+    ///
+    /// The same question send() answers, asked without sending anything: it
+    /// weighs both halves of what the peer is carrying — the bytes the reactor
+    /// has queued, and the bytes a caller has handed to send() that the reactor
+    /// has not taken up yet. So it is safe to poll: a caller that has just filled
+    /// the queue in a tight loop keeps being told "no room" until the reactor has
+    /// actually looked at what it was given, rather than being told "go on"
+    /// because nothing observable has changed yet.
+    ///
+    /// It stays a hint about a queue that drains as it is read, so the ordinary
+    /// flow is unchanged: the signal to stop is the return of send(), and the
+    /// signal to resume is on_peer_writable. This is for a caller that must wait
+    /// for room on a thread of its own — the event alone cannot serve it, because
+    /// a queue that filled *only* with bytes still in transit never crossed
+    /// anything on the connection and so raises no event when they drain.
+    bool peer_writable(const PeerId& id) const override;
 
     // — events (register before start(); invoked on a reactor thread). Multiple
     //   listeners are supported, so subsystems and the app can both subscribe. —

package/native-src/src/librats/node/peer_network.h

@@ -17,6 +17,7 @@
 #include "librats/peer/peer_id.h"
 #include "librats/peer/peer_info.h"
 #include "librats/core/address.h"
+#include "librats/core/types.h"  // CloseReason
 
 #include <cstdint>
 #include <functional>
@@ -33,7 +34,12 @@ public:
     using MessageHandler = std::function<void(const Peer&, ByteView)>;
 
     using PeerEventHandler       = std::function<void(const Peer&)>;
-    using PeerDisconnectHandler  = std::function<void(const PeerId&)>;
+    /// A peer went away, and why. The reason matters as much as the event: an
+    /// application dropped as a slow consumer (CloseReason::SlowConsumer) has to
+    /// slow down, while one whose peer simply left should reconnect — and without
+    /// the reason those look identical, so the usual answer to both is to redial
+    /// and repeat whatever caused it.
+    using PeerDisconnectHandler  = std::function<void(const PeerId&, CloseReason)>;
     using DialFailedHandler      = std::function<void(const Address&)>;
 
     virtual const PeerId&       local_id() const = 0;
@@ -49,7 +55,9 @@ public:
     /// Send to one peer. @return whether that peer's send queue still has room;
     /// false means "stop and wait for on_peer_writable" — the message is queued
     /// either way, but continuing past this is what gets a peer dropped as a slow
-    /// consumer. Also false if the peer is not connected.
+    /// consumer. Also false if the peer is not connected. Wait on the event and
+    /// not on a poll of the queue's state: the answer is re-derived on the reactor
+    /// thread, so a caller that spins instead of yielding never lets it change.
     virtual bool                send(const PeerId& to, MessageType type, ByteView payload) = 0;
     /// Send to every connected peer. @return whether *every* one of them still
     /// has room, so a subsystem that fans out can pause on the slowest.
@@ -72,6 +80,15 @@ public:
     /// subsystem that never checks that return never needs this either. Runs on a
     /// reactor thread. Default: not offered (nothing subscribes).
     virtual void                on_peer_writable(PeerEventHandler /*handler*/) {}
+    /// The same question send() answers — "has this peer room for more?" — asked
+    /// without sending anything. For a subsystem that paces a long fan-out from a
+    /// thread of its own (StorageManager streaming a snapshot): the event alone
+    /// cannot serve it, because a queue filled *only* with bytes handed to send()
+    /// that the reactor has not taken up yet never crossed anything on the
+    /// connection, so nothing raises on_peer_writable when they drain. Safe to
+    /// poll — it weighs those in-flight bytes too. False for an unknown peer.
+    /// Default: always writable, all a mock that merely moves messages can claim.
+    virtual bool                peer_writable(const PeerId& /*id*/) const { return true; }
 };
 
 struct NodeContext;  // node/node_context.h — bundles network + events + services

package/native-src/src/librats/peer/peer.h

@@ -4,10 +4,12 @@
  * @file peer.h
  * @brief A lightweight handle to a connected peer.
  *
- * Peer is a value passed to callbacks. It carries the peer's id and its
- * route (which reactor + connection), so send()/disconnect() reach the right
- * reactor directly — no PeerTable lookup on the reply path. info() does
- * consult the directory, on demand, for metadata.
+ * Peer is a value passed to callbacks. It carries the peer's id and its route
+ * (which reactor + connection). disconnect() uses the route, reaching that exact
+ * connection with no directory lookup. send() goes by id instead: it has to
+ * consult the directory anyway for the backpressure answer it returns, and by
+ * then the peer's *current* route is the better destination — a handle can
+ * outlive the link it names. info() consults the directory on demand too.
  */
 
 #include "librats/util/rats_export.h"
@@ -27,8 +29,17 @@ class RATS_API Peer {
 public:
     const PeerId& id() const noexcept { return id_; }
 
-    /// Send bytes on a named application channel.
-    void send(std::string_view channel, ByteView payload) const;
+    /// Send bytes on a named application channel, to this peer over whichever
+    /// connection currently serves it.
+    ///
+    /// @return whether that peer's queue still has room — the same answer, and the
+    ///         same contract, as Node::send(): false means stop and wait for
+    ///         on_peer_writable rather than keep going. A handler that replies
+    ///         through this handle is the most ordinary way to write to a peer, so
+    ///         it has to be able to feel backpressure like any other sender; while
+    ///         this returned void it could not, and the bytes it queued were
+    ///         invisible to peer_writable() into the bargain.
+    bool send(std::string_view channel, ByteView payload) const;
 
     /// Request this peer be disconnected.
     void disconnect() const;

package/native-src/src/librats/security/noise_security.cpp

@@ -44,6 +44,8 @@ public:
         return true;
     }
 
+    size_t overhead() const noexcept override { return librats::NOISE_TAG_SIZE; }
+
     const PeerId& remote_id() const override { return remote_id_; }
     bool is_secure() const override { return true; }
 

package/native-src/src/librats/security/plaintext_security.h

@@ -32,6 +32,7 @@ class PlaintextSession final : public Session {
 public:
     explicit PlaintextSession(PeerId remote) : remote_id_(remote) {}
     bool encrypt(ByteView plain, Bytes& out) override { out.assign(plain.begin(), plain.end()); return true; }
+    size_t overhead() const noexcept override { return 0; }
     bool decrypt(ByteView cipher, Bytes& out) override { out.assign(cipher.begin(), cipher.end()); return true; }
     const PeerId& remote_id() const override { return remote_id_; }
     bool is_secure() const override { return false; }

package/native-src/src/librats/security/session.h

@@ -30,6 +30,13 @@ public:
     /// The remote peer's identity, proven during the handshake.
     virtual const PeerId& remote_id() const = 0;
 
+    /// Bytes encrypt() adds to a plaintext of any size (an AEAD tag, typically).
+    /// The send path needs the ciphertext's size *before* encrypting it, because
+    /// a message it turns out it cannot frame must be refused without a nonce
+    /// having been spent on it — the counters run in lockstep at both ends, so a
+    /// message encrypted and then not sent would break every one after it.
+    virtual size_t overhead() const noexcept = 0;
+
     /// True if traffic is actually encrypted (false for the plaintext passthrough).
     virtual bool is_secure() const = 0;
 };