librats 2.1.4 → 2.3.0

package/README.md

@@ -112,12 +112,20 @@ fails. Both are opt-in, and punching needs peers that relay the rendezvous.
 ```javascript
 node.enablePortMapping();     // UPnP IGD + NAT-PMP
 node.enableHolePunch(true);   // true = also relay other peers' rendezvous
+node.enableRelay(false);      // last resort; true = also carry others' connections
 node.start();
 
 node.punchPeer(peerId);       // success arrives as onPeerConnected
 console.log(node.natMapping); // NatMapping.ENDPOINT_INDEPENDENT ⇒ punchable
 ```
 
+A symmetric NAT cannot be punched at all, and that is what `enableRelay` is for: the
+connection itself is routed through a node both ends already reach. It stays
+encrypted end to end — the relay moves ciphertext — and the peer behaves like any
+other, except that `peerTransport(peerId)` reports `Transport.RELAY`. With both
+enabled the ladder runs itself: a punch that cannot work falls back to a relay, and
+a relayed peer keeps trying to become a direct one.
+
 ## API
 
 ### Construction
@@ -170,6 +178,7 @@ new RatsNode(config)   // full config
 | mDNS discovery | `enableMdns()` | — |
 | NAT port mapping | `enablePortMapping(upnp?, natpmp?)` | — |
 | Hole punching | `enableHolePunch(serveAsRelay?)` | `punchPeer(peerId)`, `natMapping` |
+| Relaying | `enableRelay(serveAsRelay?)` | `connectViaRelay(peerId)` |
 | Pub/sub | `enablePubsub()` | `subscribe(topic, cb)`, `unsubscribe(topic)`, `publish(topic, data)` |
 | Typed JSON | `enableJson()` | `onJson(type, cb)`, `onceJson(type, cb)`, `offJson(type)`, `sendJson(peerId, type, value)`, `broadcastJson(type, value)` |
 | File transfer | `enableFileTransfer(tempDir?)` | `onFileOffer/onFileProgress/onFileComplete`, `sendFile`, `sendDirectory`, `acceptFile`, `rejectFile`, `cancelFile`, `pauseFile`, `resumeFile` |

package/lib/index.d.ts

@@ -19,15 +19,18 @@ declare module 'librats' {
   };
 
   /**
-   * Which wire a peer connection runs on. Both carry the identical protocol and
-   * the identical encrypted handshake; they differ only in how the ordered,
-   * reliable byte stream underneath is obtained.
+   * Which wire a peer connection runs on. TCP and UDP carry the identical protocol
+   * and the identical encrypted handshake, and differ only in how the ordered,
+   * reliable byte stream underneath is obtained; RELAY is that same stream one hop
+   * further away, out of another peer's connection rather than out of a socket.
    */
   export const Transport: {
     /** One kernel socket per peer. */
     readonly TCP: 0;
     /** Reliable stream over the shared UDP socket. */
     readonly UDP: 1;
+    /** Carried through a third node (see `enableRelay`). */
+    readonly RELAY: 2;
   };
 
   /** Bitmask flags used by `node.transports` and `node.peerTransports()`. */
@@ -57,7 +60,10 @@ declare module 'librats' {
   };
 
   export type SecurityValue = 0 | 1;
+  /** A wire a dial can choose: TCP or UDP. A relay is never dialed. */
   export type TransportValue = 0 | 1;
+  /** What a connected peer's link actually runs on, relays included. */
+  export type PeerTransportValue = TransportValue | 2;
   export type NatMappingValue = 0 | 1 | 2 | 3;
   export type LogLevelValue = 0 | 1 | 2 | 3;
 
@@ -85,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;
@@ -165,7 +185,7 @@ declare module 'librats' {
     /** Cap on established peers (0 = unlimited). Settable at any time. */
     maxPeers: number;
     /** Which wire a connected peer's link runs on, or `null` if not connected. */
-    peerTransport(peerId: string): TransportValue | null;
+    peerTransport(peerId: string): PeerTransportValue | null;
     /**
      * Transports a connected peer advertised, as a `TransportMask` bitmask, or
      * `null` if not connected. 0 means the peer did not say (an older build).
@@ -174,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) ----
 
@@ -207,6 +241,17 @@ declare module 'librats' {
      * ordinary `onPeerConnected`.
      */
     punchPeer(peerId: string): void;
+    /**
+     * Enable relaying: reach a peer nothing else could, through a node both ends
+     * are already connected to. `serveAsRelay` (default `false`) also carries
+     * OTHER peers' connections, which spends real bandwidth.
+     */
+    enableRelay(serveAsRelay?: boolean): void;
+    /**
+     * Try to reach a peer through a relay. Non-blocking: success arrives as an
+     * ordinary `onPeerConnected`.
+     */
+    connectViaRelay(peerId: string): void;
     /** A `NatMapping` value describing this node's own NAT. */
     readonly natMapping: NatMappingValue;
 

package/lib/index.js

@@ -59,8 +59,9 @@ const Security = Object.freeze({
  * how the ordered, reliable byte stream underneath is obtained.
  */
 const Transport = Object.freeze({
-  TCP: 0, // one kernel socket per peer
-  UDP: 1, // reliable stream over the shared UDP socket
+  TCP: 0,   // one kernel socket per peer
+  UDP: 1,   // reliable stream over the shared UDP socket
+  RELAY: 2, // carried through a third node (see enableRelay)
 });
 
 /** Bitmask flags used by `node.transports` and `node.peerTransports()`. */
@@ -192,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
@@ -204,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) ----
 
   /**
@@ -250,6 +266,29 @@ class RatsNode {
    */
   punchPeer(peerId) { this._native.punchPeer(peerId); }
 
+  /**
+   * Enable relaying: reach a peer that neither port forwarding nor hole punching
+   * could make reachable, by routing the connection through a node both ends are
+   * already connected to. The peer that comes out is ordinary in every way — the
+   * same end-to-end encryption, the same channels — except that `peerTransport()`
+   * reports it as `Transport.RELAY`.
+   * @param {boolean} [serveAsRelay=false] also carry OTHER peers' connections.
+   *   Unlike a hole-punch rendezvous this spends real bandwidth on somebody else's
+   *   traffic, so it is off by default; a mesh in which nobody serves cannot relay.
+   */
+  enableRelay(serveAsRelay = false) { this._native.enableRelay(serveAsRelay); }
+
+  /**
+   * Try to reach a peer through a relay. Non-blocking: success arrives as an
+   * ordinary `onPeerConnected`. Throws `NO_SUCH_PEER` when there is nothing to do
+   * or nothing to try with — already connected, an attempt already running, in
+   * cooldown, or no peer that could carry the connection. Usually unnecessary:
+   * with hole punching enabled too, a punch that cannot work hands the target over
+   * by itself.
+   * @param {string} peerId
+   */
+  connectViaRelay(peerId) { this._native.connectViaRelay(peerId); }
+
   /** @type {number} a {@link NatMapping} value describing this node's own NAT. */
   get natMapping() { return this._native.natMapping(); }
 

package/native-src/CMakeLists.txt

@@ -206,6 +206,8 @@ set(LIBRARY_SOURCES
     src/librats/transport/udp_stream.cpp
     src/librats/transport/udp_mux.h
     src/librats/transport/udp_mux.cpp
+    src/librats/transport/relay_link.h
+    src/librats/transport/relay_link.cpp
     src/librats/transport/connection.h
     src/librats/transport/connection.cpp
     src/librats/transport/reactor.h
@@ -242,6 +244,7 @@ set(LIBRARY_SOURCES
     src/librats/node/dialer.h
     src/librats/node/dialer.cpp
     src/librats/node/dial_service.h
+    src/librats/node/circuit_service.h
     src/librats/node/nat_status.h
     src/librats/node/nat_status.cpp
 
@@ -268,6 +271,9 @@ set(LIBRARY_SOURCES
     src/librats/subsystems/hole_punch.h
     src/librats/subsystems/hole_punch.cpp
     src/librats/subsystems/hole_punch_service.h
+    src/librats/subsystems/relay.h
+    src/librats/subsystems/relay.cpp
+    src/librats/subsystems/relay_service.h
 
 # dht/ — Kademlia DHT + KRPC (bencode is shared with bittorrent, always built)
     src/librats/dht/dht.h
@@ -487,6 +493,11 @@ if(WIN32)
 endif()
 
 if(ANDROID)
+    # The logger routes console output through __android_log_print, because an app's
+    # stdout/stderr go nowhere on Android.
+    find_library(log-lib log)
+    target_link_libraries(rats ${log-lib})
+
     if(DEFINED ANDROID_PLATFORM)
         string(REGEX REPLACE "android-" "" ANDROID_API_LEVEL ${ANDROID_PLATFORM})
         math(EXPR ANDROID_API_LEVEL "${ANDROID_API_LEVEL}")
@@ -649,6 +660,7 @@ if(RATS_BUILD_TESTS)
         tests/test_frame.cpp
         tests/test_reactor.cpp
         tests/test_transport_udp.cpp
+        tests/test_relay_link.cpp
         tests/test_dialer.cpp
         tests/test_peer_table.cpp
         tests/test_handshake.cpp
@@ -665,6 +677,7 @@ if(RATS_BUILD_TESTS)
         tests/test_reconnection.cpp
         tests/test_nat_status.cpp
         tests/test_hole_punch.cpp
+        tests/test_relay.cpp
         tests/test_logging.cpp
     )
 

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

@@ -6,6 +6,7 @@
 #include "librats/subsystems/mdns_discovery.h"
 #include "librats/subsystems/port_mapping_service.h"
 #include "librats/subsystems/hole_punch.h"
+#include "librats/subsystems/relay.h"
 #include "librats/subsystems/pubsub.h"
 #include "librats/subsystems/message_json.h"
 #include "librats/subsystems/file_transfer.h"
@@ -42,6 +43,7 @@ struct RatsHandle {
     PingService*         ping      = nullptr;
     ReconnectionService* reconnect = nullptr;
     HolePunch*           punch     = nullptr;
+    Relay*               relay     = nullptr;
 #ifdef RATS_SEARCH_FEATURES
     Bittorrent*          bittorrent = nullptr;
 #endif
@@ -83,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" {
@@ -101,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) {
@@ -116,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;
 }
 
@@ -151,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));
 }
@@ -222,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));
@@ -236,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;
 }
@@ -299,6 +354,29 @@ rats_error_t rats_enable_hole_punch(rats_t node, int serve_as_relay) {
     return RATS_OK;
 }
 
+rats_error_t rats_enable_relay(rats_t node, int serve_as_relay) {
+    auto* h = as_handle(node);
+    if (h->started) return RATS_ERR_ALREADY_STARTED;
+    if (!h->relay) {
+        Relay::Config config;
+        config.serve = serve_as_relay != 0;
+        h->relay = h->node->add_subsystem(std::make_unique<Relay>(config));
+    }
+    return RATS_OK;
+}
+
+rats_error_t rats_connect_via_relay(rats_t node, const char* peer_id_hex) {
+    if (!peer_id_hex) return RATS_ERR_INVALID_ARG;
+    auto* h = as_handle(node);
+    if (!h->relay) return RATS_ERR_NOT_ENABLED;
+    auto id = PeerId::from_hex(peer_id_hex);
+    if (!id) return RATS_ERR_INVALID_ARG;
+    // As with punching, every reason an attempt is declined is "nothing to do or
+    // nothing to try with" — already connected, already trying, in cooldown, or no
+    // peer that could carry it — and none of them is separately actionable.
+    return h->relay->connect_via_relay(*id) ? RATS_OK : RATS_ERR_NO_SUCH_PEER;
+}
+
 rats_error_t rats_punch_peer(rats_t node, const char* peer_id_hex) {
     if (!peer_id_hex) return RATS_ERR_INVALID_ARG;
     auto* h = as_handle(node);
@@ -338,9 +416,15 @@ int rats_peer_transport(rats_t node, const char* peer_id_hex) {
     if (!peer_id_hex) return -1;
     auto id = PeerId::from_hex(peer_id_hex);
     if (!id) return -1;
-    for (const PeerInfo& info : node_of(node)->peers())
-        if (info.id == *id)
-            return info.transport == TransportKind::Udp ? RATS_TRANSPORT_UDP : RATS_TRANSPORT_TCP;
+    for (const PeerInfo& info : node_of(node)->peers()) {
+        if (info.id != *id) continue;
+        switch (info.transport) {
+            case TransportKind::Udp:   return RATS_TRANSPORT_UDP;
+            case TransportKind::Relay: return RATS_TRANSPORT_RELAY;
+            case TransportKind::Tcp:   break;
+        }
+        return RATS_TRANSPORT_TCP;
+    }
     return -1;
 }
 

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

@@ -45,10 +45,41 @@ typedef enum {
  * the identical encrypted handshake; they differ only in how the ordered,
  * reliable byte stream underneath is obtained. */
 typedef enum {
-    RATS_TRANSPORT_TCP = 0,  /* one kernel socket per peer */
-    RATS_TRANSPORT_UDP = 1   /* reliable stream over the shared UDP socket */
+    RATS_TRANSPORT_TCP   = 0,  /* one kernel socket per peer */
+    RATS_TRANSPORT_UDP   = 1,  /* reliable stream over the shared UDP socket */
+    /* Carried inside another peer's connection (see rats_enable_relay). Reported
+       by rats_peer_transport(); never a value to put in preferred_transport,
+       which chooses what a DIAL tries and a relay is never dialed. */
+    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
@@ -98,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
@@ -149,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) — */
@@ -192,6 +257,30 @@ RATS_API rats_error_t rats_enable_hole_punch(rats_t node, int serve_as_relay);
  *  its own to advertise (it needs at least one datagram peer first). */
 RATS_API rats_error_t rats_punch_peer(rats_t node, const char* peer_id_hex);
 
+/** Relaying: reach a peer that neither port forwarding nor hole punching could
+ *  make reachable, by routing the connection through a node both ends are already
+ *  connected to. Call before start(). The peer that comes out is ordinary in every
+ *  way — the same end-to-end encryption, the same channels — except that its bytes
+ *  take a detour, which rats_peer_transport() reports as RATS_TRANSPORT_RELAY.
+ *
+ *  `serve_as_relay` (non-zero) also carries OTHER peers' connections. Unlike a
+ *  hole-punch rendezvous, that spends real bandwidth on somebody else's traffic, so
+ *  it is off by default and opted into here; a mesh in which nobody serves cannot
+ *  relay at all. A serving node forwards only between peers it already holds, never
+ *  chains circuits, and caps each one by bytes, duration and count. */
+RATS_API rats_error_t rats_enable_relay(rats_t node, int serve_as_relay);
+
+/** Try to reach `peer_id_hex` through a relay. Non-blocking: success arrives as an
+ *  ordinary peer-connected callback. RATS_OK if an attempt was started;
+ *  RATS_ERR_NOT_ENABLED if relaying is off; RATS_ERR_NO_SUCH_PEER if there is
+ *  nothing to do or nothing to try with — the peer is already connected, an attempt
+ *  is already running, it is in cooldown, or this node has no peer that could carry
+ *  the connection.
+ *
+ *  Usually there is no need to call this: with hole punching enabled too, a punch
+ *  that cannot work hands the target over by itself. */
+RATS_API rats_error_t rats_connect_via_relay(rats_t node, const char* peer_id_hex);
+
 /** What the mesh has shown about this node's own NAT, from the endpoints datagram
  *  peers report seeing its shared UDP socket at. One of the RATS_NAT_* values;
  *  RATS_NAT_ENDPOINT_DEPENDENT means punching cannot work from here. */

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";
@@ -33,8 +33,9 @@ const char* to_string(CloseReason r) noexcept {
 
 const char* to_string(TransportKind t) noexcept {
     switch (t) {
-        case TransportKind::Tcp: return "tcp";
-        case TransportKind::Udp: return "udp";
+        case TransportKind::Tcp:   return "tcp";
+        case TransportKind::Udp:   return "udp";
+        case TransportKind::Relay: return "relay";
     }
     return "?";
 }

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

@@ -26,13 +26,23 @@ enum class ConnRole {
     Outbound,  ///< We dialed out to a remote address.
 };
 
-/// Which wire a connection runs over. Both are first-class: they carry the exact
-/// same block/frame protocol and the same secure handshake, and differ only in how
-/// an ordered, reliable byte stream is obtained — the kernel's TCP stack, or the
-/// library's own reliability layer on top of datagrams (see transport/udp_stream.h).
+/// Which wire a connection runs over. Tcp and Udp are first-class equals: they
+/// carry the exact same block/frame protocol and the same secure handshake, and
+/// differ only in how an ordered, reliable byte stream is obtained — the kernel's
+/// TCP stack, or the library's own reliability layer on top of datagrams (see
+/// transport/udp_stream.h). Relay is a third way of obtaining that same stream —
+/// out of another peer's connection rather than out of a socket — and is a last
+/// resort rather than an equal (see below).
 enum class TransportKind {
-    Tcp,  ///< One kernel socket per peer.
-    Udp,  ///< Reliable ordered stream over the shared UDP socket (NAT-friendly).
+    Tcp,    ///< One kernel socket per peer.
+    Udp,    ///< Reliable ordered stream over the shared UDP socket (NAT-friendly).
+    /// Carried inside another peer's connection: the byte stream is chopped into
+    /// messages a third node forwards between the two ends (see subsystems/relay.h).
+    /// Not a wire of its own — it is one of the two above, one hop further away —
+    /// but it behaves differently enough to be worth naming: it costs the relay
+    /// bandwidth, it cannot be dialed, and it must always lose to a direct link
+    /// (see PeerTable::add). Never a value connect() or the Dialer chooses.
+    Relay,
 };
 
 /// How hard an outbound datagram dial tries before it is called failed.
@@ -74,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.
@@ -83,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