librats 2.1.4 → 2.2.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;
 
@@ -165,7 +171,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).
@@ -207,6 +213,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()`. */
@@ -250,6 +251,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
@@ -649,6 +655,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 +672,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
@@ -299,6 +301,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 +363,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,8 +45,12 @@ 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;
 
 /* Bitmask of transports (see rats_transports / rats_peer_transports). */
@@ -192,6 +196,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

@@ -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.

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

@@ -0,0 +1,84 @@
+#pragma once
+
+/**
+ * @file circuit_service.h
+ * @brief Turning a relayed byte stream into a peer connection — the capability a
+ *        relay module needs and PeerNetwork deliberately does not offer.
+ *
+ * A relay module speaks a protocol (who forwards what to whom) and owns the byte
+ * stream that comes out of it (transport/relay_link.h). What it cannot do on its
+ * own is the one remaining step: making that stream a Connection, so the ordinary
+ * Noise handshake, framing, identify and peer table all run over it and the peer
+ * at the far end becomes an ordinary peer. That step needs the reactor pool, which
+ * a Subsystem has no business holding.
+ *
+ * So this is the narrow escape hatch, published by the Node in its ServiceRegistry
+ * next to DialService, and resolved by whoever needs it:
+ *
+ *     if (auto* circuits = ctx.services.get<CircuitService>())
+ *         auto route = circuits->adopt_circuit(relay_id, std::move(link),
+ *                                              ConnRole::Outbound, false);
+ *
+ * ── One thread, chosen for you ──────────────────────────────────────────────
+ * The node places the circuit on the reactor that owns the CARRIER's connection,
+ * and that is the whole reason this call exists rather than a bare "adopt this
+ * link somewhere". Every byte of a circuit arrives on the carrier's connection and
+ * leaves through it, so putting the two on one thread means the entire relayed
+ * path is handled without a lock, a queue or a hand-off — the same shared-nothing
+ * property every other connection has. Any other placement would move bytes
+ * between reactor threads twice per message.
+ *
+ * The route comes back synchronously (the ConnId is reserved before the adoption
+ * is posted, exactly as Reactor::connect does), so the caller can wake and close
+ * the circuit from the moment it asks for one.
+ *
+ * ── What is deliberately NOT here ───────────────────────────────────────────
+ * Nothing about relaying: no relay selection, no protocol, no policy about when a
+ * circuit is worth opening. Those belong to the module. This interface would serve
+ * any transport that arrives from outside the reactor pool.
+ */
+
+#include "librats/core/types.h"
+#include "librats/peer/peer_id.h"
+#include "librats/peer/peer_table.h"   // PeerRoute
+#include "librats/transport/link.h"
+
+#include <cstdint>
+#include <memory>
+#include <optional>
+
+namespace librats {
+
+class CircuitService {
+public:
+    virtual ~CircuitService() = default;
+
+    /// Adopt `link` as a connection carried by the peer `carrier`, on the reactor
+    /// that owns the carrier's own connection.
+    ///
+    /// @param role      Outbound for a circuit we opened, Inbound for one opened to
+    ///                  us. It is what the secure handshake and the peer table's
+    ///                  duplicate resolution read, so it must say who asked.
+    /// @param connected whether the far end is already there. An inbound circuit is
+    ///                  (the opener would not have sent it otherwise); an outbound
+    ///                  one is not until its acceptance arrives, and until then the
+    ///                  connection waits in Connecting for a PollOut.
+    /// @return the new connection's route, or nullopt when the carrier is no longer
+    ///         a peer, or when an inbound circuit would push this node past its peer
+    ///         limit. Nothing is started in that case and `link` is released.
+    virtual std::optional<PeerRoute> adopt_circuit(const PeerId& carrier,
+                                                   std::unique_ptr<Link> link,
+                                                   ConnRole role, bool connected) = 0;
+
+    /// Deliver poll-equivalent events (PollIn / PollOut / PollErr, see
+    /// core/io_poller.h) to a circuit connection — the events a socket-backed link
+    /// would have got from the poller. Thread-safe, and a no-op for a route that is
+    /// already gone.
+    virtual void wake_circuit(PeerRoute route, uint32_t events) = 0;
+
+    /// Tear a circuit connection down. Thread-safe; a no-op for a route that is
+    /// already gone.
+    virtual void close_circuit(PeerRoute route, CloseReason reason) = 0;
+};
+
+} // namespace librats

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

@@ -94,6 +94,7 @@ Node::Node(NodeConfig config)
     // are narrow capabilities a module asks for by interface (see
     // node/dial_service.h, node/nat_status.h).
     services_.provide<DialService>(this);
+    services_.provide<CircuitService>(this);
     services_.provide<ExternalAddressService>(&nat_status_);
 }
 
@@ -402,6 +403,9 @@ bool Node::dial_direct(const Address& addr, TransportKind kind, const DialProfil
     if (!addr.is_valid()) return false;
     if (kind == TransportKind::Udp && !reactors_->has_udp()) return false;
     if (kind == TransportKind::Tcp && !config_.enable_tcp)   return false;
+    // A relayed circuit is not dialed: it is negotiated with a third node and then
+    // adopted (see node/circuit_service.h). There is no address to aim at here.
+    if (kind == TransportKind::Relay) return false;
 
     // Straight to the reactor, deliberately around the Dialer: this dial is not a
     // race and must not become one (see node/dial_service.h). The Dialer is left
@@ -412,6 +416,41 @@ bool Node::dial_direct(const Address& addr, TransportKind kind, const DialProfil
     return id != kInvalidConnId;
 }
 
+// ── CircuitService: a relayed byte stream becomes a peer connection ─────────
+
+std::optional<PeerRoute> Node::adopt_circuit(const PeerId& carrier, std::unique_ptr<Link> link,
+                                             ConnRole role, bool connected) {
+    if (!link) return std::nullopt;
+
+    // The carrier has to still be a peer: it is the only thing this circuit's bytes
+    // can travel through, and a connection whose carrier is already gone would
+    // simply sit there until the establish deadline reaped it.
+    const auto carrier_route = peers_.route(carrier);
+    if (!carrier_route) return std::nullopt;
+
+    // Inbound circuits go through the same admission gate as an accepted socket.
+    // A relayed connection is cheaper for whoever opens it than a direct one — no
+    // NAT to get through, someone else's bandwidth — so if anything it deserves the
+    // gate more, not less.
+    if (role == ConnRole::Inbound && !admit_inbound()) return std::nullopt;
+
+    Reactor& reactor = reactors_->by_index(carrier_route->reactor);
+    // Same reactor as the carrier, which is the whole point: every byte of this
+    // circuit arrives on the carrier's connection and leaves through it, so the two
+    // share a thread and the relayed path needs no locks and no hand-offs.
+    const ConnId id = reactor.reserve_conn_id();
+    reactor.adopt_link(id, std::move(link), role, connected);
+    return PeerRoute{carrier_route->reactor, id};
+}
+
+void Node::wake_circuit(PeerRoute route, uint32_t events) {
+    reactors_->by_index(route.reactor).wake(route.conn, events);
+}
+
+void Node::close_circuit(PeerRoute route, CloseReason reason) {
+    reactors_->by_index(route.reactor).close(route.conn, reason);
+}
+
 void Node::report_dial_failed(const std::string& host, uint16_t port) {
     // Only a numeric target can be handed on as an Address; a dial by hostname has
     // no dialable Address to report (peers cannot use our resolver), and the

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

@@ -48,6 +48,7 @@
 #include "librats/peer/peer_info.h"
 #include "librats/security/identity.h"
 #include "librats/security/handshaker.h"  // SecurityProvider
+#include "librats/node/circuit_service.h"
 #include "librats/node/config.h"
 #include "librats/node/dial_service.h"
 #include "librats/node/dialer.h"
@@ -74,7 +75,10 @@ namespace librats {
 class NetworkMonitor;  // util/network_monitor.h — owned via unique_ptr, included in node.cpp
 class MessageJson;     // subsystems/message_json.h — reached via json() (json.h stays out of node.h)
 
-class RATS_API Node final : public ConnectionDelegate, public PeerNetwork, public DialService {
+class RATS_API Node final : public ConnectionDelegate,
+                            public PeerNetwork,
+                            public DialService,
+                            public CircuitService {
 public:
     /// Construct a node from its configuration (see NodeConfig). This only loads
     /// the identity and prepares the layers; no socket is opened until start().
@@ -163,6 +167,13 @@ public:
     bool dial_direct(const Address& addr, TransportKind kind,
                      const DialProfile& profile) override;
 
+    // — CircuitService: make a relayed byte stream an ordinary peer connection
+    //   (see node/circuit_service.h; used by the relay module) —
+    std::optional<PeerRoute> adopt_circuit(const PeerId& carrier, std::unique_ptr<Link> link,
+                                           ConnRole role, bool connected) override;
+    void                     wake_circuit(PeerRoute route, uint32_t events) override;
+    void                     close_circuit(PeerRoute route, CloseReason reason) override;
+
     // — peer admission limit (0 = unlimited; guards inbound, not our own dials) —
     size_t max_peers() const noexcept { return max_peers_.load(std::memory_order_relaxed); }
     void   set_max_peers(size_t n) noexcept { max_peers_.store(n, std::memory_order_relaxed); }

package/native-src/src/librats/peer/peer_table.cpp

@@ -5,6 +5,30 @@
 
 namespace librats {
 
+namespace {
+
+/// How much a transport is worth when two connections to the same peer have to be
+/// ranked. Both ends see the same pair of transports and apply the same order, so
+/// they converge on the same survivor without exchanging a word.
+///
+///   Udp   — one socket, one NAT mapping, a source port that can be dialed back
+///           (see dialer.h). The best link there is.
+///   Tcp   — a direct link all the same, just a less useful one to a NAT.
+///   Relay — not a direct link at all: every byte costs a third node bandwidth and
+///           a round trip. Ranked last here for completeness; in practice a relayed
+///           link is settled before this by the rule in add(), which lets ANY direct
+///           link beat it regardless of role.
+int transport_rank(TransportKind t) noexcept {
+    switch (t) {
+        case TransportKind::Udp:   return 2;
+        case TransportKind::Tcp:   return 1;
+        case TransportKind::Relay: return 0;
+    }
+    return 0;
+}
+
+} // namespace
+
 PeerTable::AddOutcome PeerTable::add(const PeerInfo& info, PeerRoute route,
                                              bool prefer_outbound) {
     std::unique_lock<std::shared_mutex> lock(mutex_);
@@ -26,23 +50,32 @@ PeerTable::AddOutcome PeerTable::add(const PeerInfo& info, PeerRoute route,
     // first" gets a different answer at each end, and two ends that each keep the
     // link the other just dropped are left with no link at all.
     //
+    //   one relayed, one not ⇒ not a race at all but an upgrade (or a late relay
+    //                        arriving under a direct link): the direct one wins,
+    //                        whatever the roles. Ranked FIRST, ahead of the role
+    //                        rule, because a relayed link that won on role would
+    //                        keep costing a third node bandwidth for the life of a
+    //                        peer we can reach ourselves. Both ends see the same
+    //                        pair of transports, so both reach this same verdict.
     //   opposite roles     ⇒ cross-connect: keep the link started by the smaller id
     //                        (prefer_outbound, opposite at each end by construction).
     //   different wires    ⇒ a dial race whose attempts both got through. Both ends
-    //                        see the transports, and there is a right answer: the
-    //                        datagram link (one socket, one NAT mapping, a source
-    //                        port that can be dialed back — see dialer.h). "Is it
-    //                        UDP" ranks the pair only because there are exactly two
-    //                        wires; a third would need an explicit order, or the two
-    //                        ends could rank the same pair differently.
+    //                        see the transports and rank them by the same explicit
+    //                        order (transport_rank above), so neither can rank the
+    //                        same pair differently.
     //   same role and wire ⇒ a reconnect, not a simultaneous pair: the old link is
     //                        stale or already dead, so the newcomer is the live one.
+    const bool cur_relayed = cur.info.transport == TransportKind::Relay;
+    const bool new_relayed = info.transport == TransportKind::Relay;
+
     bool keep_new = true;
-    if (cur.info.direction != info.direction) {
+    if (cur_relayed != new_relayed) {
+        keep_new = !new_relayed;
+    } else if (cur.info.direction != info.direction) {
         const ConnRole survivor = prefer_outbound ? ConnRole::Outbound : ConnRole::Inbound;
         keep_new = (info.direction == survivor);
     } else if (cur.info.transport != info.transport) {
-        keep_new = (info.transport == TransportKind::Udp);
+        keep_new = transport_rank(info.transport) > transport_rank(cur.info.transport);
     }
 
     if (keep_new) {