librats 1.0.2 → 2.2.0

package/native-src/src/{mdns.cpp → librats/mdns/mdns.cpp}

@@ -1,7 +1,8 @@
-#include "mdns.h"
-#include "network_utils.h"
-#include "os.h"
-#include "socket.h"
+#include "librats/mdns/mdns.h"
+#include "librats/mdns/log.h"
+#include "librats/util/network_utils.h"
+#include "librats/util/os.h"
+#include "librats/core/socket.h"
 #include <algorithm>
 #include <random>
 #include <sstream>
@@ -26,7 +27,7 @@ MdnsClient::MdnsClient(const std::string& service_instance_name, uint16_t servic
     : service_instance_name_(service_instance_name),
       service_port_(service_port),
       service_type_(LIBRATS_SERVICE_TYPE),  // Default service type
-      multicast_socket_(INVALID_SOCKET_VALUE),
+      multicast_socket_(RATS_INVALID_SOCKET),
       running_(false),
       announcing_(false),
       discovering_(false),
@@ -90,11 +91,11 @@ void MdnsClient::stop() {
     
     // Trigger immediate shutdown of all background threads
     shutdown_immediate();
-    
-    // Close socket to break receiver loop
-    close_multicast_socket();
-    
-    // Wait for threads to finish
+
+    // Wait for threads to finish. They must be gone before the socket is closed:
+    // the receiver is waiting on it, so closing it first would race with that wait.
+    // shutdown_immediate() has already signalled the wakeup pipe, so the wait is
+    // over as soon as the scheduler gets to it rather than at the next timeout.
     if (receiver_thread_.joinable()) {
         receiver_thread_.join();
     }
@@ -106,6 +107,9 @@ void MdnsClient::stop() {
     if (querier_thread_.joinable()) {
         querier_thread_.join();
     }
+
+    // Now that nothing else touches it, close the socket
+    close_multicast_socket();
     
     // Clear discovered services
     {
@@ -124,8 +128,11 @@ void MdnsClient::shutdown_immediate() {
     discovering_.store(false);
     running_.store(false);
     
-    // Notify all waiting threads to wake up immediately
+    // Notify all waiting threads to wake up immediately. The announcer and querier
+    // sleep on the condition variable; the receiver is parked in a select() on the
+    // multicast socket and only the wakeup pipe can break that.
     shutdown_cv_.notify_all();
+    receiver_wakeup_.signal();
 }
 
 bool MdnsClient::is_running() const {
@@ -324,7 +331,7 @@ bool MdnsClient::create_multicast_socket() {
         LOG_MDNS_ERROR("Failed to bind to mDNS port " << MDNS_PORT << " (error: " << strerror(errno) << ")");
 #endif
         close_socket(multicast_socket_);
-        multicast_socket_ = INVALID_SOCKET_VALUE;
+        multicast_socket_ = RATS_INVALID_SOCKET;
         return false;
     }
     
@@ -419,46 +426,74 @@ void MdnsClient::close_multicast_socket() {
     if (librats::is_valid_socket(multicast_socket_)) {
         leave_multicast_group();
         librats::close_socket(multicast_socket_, true);
-        multicast_socket_ = INVALID_SOCKET_VALUE;
+        multicast_socket_ = RATS_INVALID_SOCKET;
     }
 }
 
 void MdnsClient::receiver_loop() {
     LOG_MDNS_DEBUG("mDNS receiver loop started");
-    
-    std::vector<uint8_t> buffer(4096);
-    sockaddr_in sender_addr{};
-    socklen_t addr_len = sizeof(sender_addr);
-    
+
+    // stop() must be able to wind this loop down and join it *before* the socket is
+    // closed — closing an fd out from under a blocked recvfrom() races with it, since
+    // the number can be handed to another thread's socket()/open() the moment it is
+    // freed. The wakeup pipe is what makes that possible without polling: the wait
+    // watches it alongside the multicast socket, and shutdown_immediate() signals it.
+    //
+    // Waiting on a timeout instead would cost a wakeup per interval for the entire
+    // life of the process. On an idle node that is the *only* work being done, and it
+    // is paid per MdnsClient — measured at ~0.1 % of a core each with a 100 ms poll.
+    const socket_t interrupt_fd = receiver_wakeup_.fd();
+
+    // Only if the pipe could not be created: then there is nothing to interrupt the
+    // wait, so fall back to polling rather than to a blocking receive that stop()
+    // could not get out of.
+    constexpr int kFallbackTimeoutMs = 100;
+    const int receive_timeout_ms = is_valid_socket(interrupt_fd) ? -1 : kFallbackTimeoutMs;
+
+    // A single failed receive is not fatal (a signal, a transient ICMP error), but a
+    // socket that is genuinely dead fails instantly every time — without a bound the
+    // loop below degenerates into a busy spin that never ends. Give up after a short
+    // run of back-to-back failures; the old blocking loop bailed on the first one.
+    constexpr int kMaxConsecutiveErrors = 10;
+    int consecutive_errors = 0;
+
     while (running_.load()) {
-        if (!librats::is_valid_socket(multicast_socket_)) {
-            break;
-        }
-        
-        int received = recvfrom(multicast_socket_, reinterpret_cast<char*>(buffer.data()), 
-                                static_cast<int>(buffer.size()), 0, reinterpret_cast<sockaddr*>(&sender_addr), &addr_len);
-        
-        if (received <= 0) {
-            if (running_.load()) {
-                LOG_MDNS_ERROR("Failed to receive multicast packet");
+        Address sender;
+        bool receive_failed = false;
+        std::vector<uint8_t> packet = librats::receive_udp_data(
+            multicast_socket_, 4096, sender, receive_timeout_ms, interrupt_fd, &receive_failed);
+
+        if (receive_failed) {
+            if (++consecutive_errors >= kMaxConsecutiveErrors) {
+                if (running_.load()) {
+                    LOG_MDNS_ERROR("mDNS receive failed " << consecutive_errors
+                                   << " times in a row, stopping receiver loop");
+                }
+                break;
             }
-            break;
+            continue;
         }
-        
-        // Get sender IP address
-        char sender_ip[INET_ADDRSTRLEN];
-        inet_ntop(AF_INET, &sender_addr.sin_addr, sender_ip, INET_ADDRSTRLEN);
-        
+
+        consecutive_errors = 0;
+
+        if (packet.empty()) {
+            // Either the wait was interrupted or (in the degraded fallback) it timed
+            // out. Consume the wakeup byte — an unread one keeps the pipe readable and
+            // would turn the next wait into a spin — then re-check running_.
+            receiver_wakeup_.drain();
+            continue;
+        }
+
+        std::string sender_ip = sender.ip.to_string();
+
         // Ignore packets from ourselves
-        if (std::string(sender_ip) == local_ip_address_) {
+        if (sender_ip == local_ip_address_) {
             continue;
         }
-        
-        // Process the received packet
-        std::vector<uint8_t> packet(buffer.begin(), buffer.begin() + received);
-        handle_received_packet(packet, std::string(sender_ip));
+
+        handle_received_packet(packet, sender_ip);
     }
-    
+
     LOG_MDNS_DEBUG("mDNS receiver loop ended");
 }
 

package/native-src/src/{mdns.h → librats/mdns/mdns.h}

@@ -1,7 +1,7 @@
 #pragma once
 
-#include "socket.h"
-#include "logger.h"
+#include "librats/core/socket.h"
+#include "librats/core/wakeup_pipe.h"
 #include <string>
 #include <vector>
 #include <memory>
@@ -17,11 +17,6 @@
 
 namespace librats {
 
-#define LOG_MDNS_DEBUG(message) LOG_DEBUG("mdns", message)
-#define LOG_MDNS_INFO(message)  LOG_INFO("mdns", message)
-#define LOG_MDNS_WARN(message)  LOG_WARN("mdns", message)
-#define LOG_MDNS_ERROR(message) LOG_ERROR("mdns", message)
-
 // mDNS protocol constants
 const uint16_t MDNS_PORT = 5353;
 const std::string MDNS_MULTICAST_IPv4 = "224.0.0.251";
@@ -176,7 +171,13 @@ private:
     std::thread receiver_thread_;
     std::thread announcer_thread_;
     std::thread querier_thread_;
-    
+
+    /// Lets stop() interrupt the receiver's blocking wait. Without it the loop
+    /// would have to poll the multicast socket on a timeout just to notice that
+    /// running_ went false, which costs a wakeup per interval forever — on a
+    /// client that is otherwise completely idle, that is the only work it does.
+    WakeupPipe receiver_wakeup_;
+
     // Conditional variables for immediate shutdown
     std::condition_variable shutdown_cv_;
     std::mutex shutdown_mutex_;

package/native-src/src/{natpmp.cpp → librats/nat/natpmp.cpp}

@@ -3,9 +3,9 @@
  * @brief NAT-PMP (RFC 6886) client implementation
  */
 
-#include "natpmp.h"
-#include "network_utils.h"
-#include "logger.h"
+#include "librats/nat/natpmp.h"
+#include "librats/util/network_utils.h"
+#include "librats/util/logger.h"
 
 #include <cstring>
 
@@ -174,14 +174,15 @@ bool NatPmpClient::ensure_gateway() {
         socket_t sock = create_udp_socket(0, "", AddressFamily::IPv4);
         if (!is_valid_socket(sock)) continue;
 
+        const auto gw_ip = IpAddress::parse(gw);  // gateway is a numeric literal; parse once, compare by bytes
         std::vector<uint8_t> req = { NATPMP_VERSION, OP_EXTERNAL_IP };
         bool answered = false;
         for (int timeout : kRetryTimeouts) {
             if (stop_requested_.load()) { close_socket(sock); return false; }
             if (send_udp_data(sock, req, gw, NATPMP_PORT, AddressFamily::IPv4) < 0) break;
-            Peer from;
+            Address from;
             auto resp = receive_udp_data(sock, 64, from, timeout, wakeup_.fd());
-            if (resp.size() >= 12 && from.ip == gw && resp[0] == NATPMP_VERSION &&
+            if (resp.size() >= 12 && gw_ip && from.ip == *gw_ip && resp[0] == NATPMP_VERSION &&
                 resp[1] == (OP_EXTERNAL_IP | OP_RESPONSE_BIT)) {
                 uint16_t result = get_u16(&resp[2]);
                 if (result == 0) {
@@ -224,14 +225,15 @@ bool NatPmpClient::request_external_ip(socket_t sock) {
         gw = gateway_;
     }
     if (gw.empty()) return false;
+    const auto gw_ip = IpAddress::parse(gw);  // numeric literal; parse once, compare by bytes
 
     std::vector<uint8_t> req = { NATPMP_VERSION, OP_EXTERNAL_IP };
     for (int timeout : kRetryTimeouts) {
         if (stop_requested_.load()) return false;
         if (send_udp_data(sock, req, gw, NATPMP_PORT, AddressFamily::IPv4) < 0) return false;
-        Peer from;
+        Address from;
         auto resp = receive_udp_data(sock, 64, from, timeout, wakeup_.fd());
-        if (resp.size() >= 12 && from.ip == gw && resp[0] == NATPMP_VERSION &&
+        if (resp.size() >= 12 && gw_ip && from.ip == *gw_ip && resp[0] == NATPMP_VERSION &&
             resp[1] == (OP_EXTERNAL_IP | OP_RESPONSE_BIT) && get_u16(&resp[2]) == 0) {
             char ip[INET_ADDRSTRLEN];
             struct in_addr addr;
@@ -253,6 +255,7 @@ bool NatPmpClient::send_map_request(socket_t sock, Mapping& m, bool remove) {
         gw = gateway_;
     }
     if (gw.empty()) return false;
+    const auto gw_ip = IpAddress::parse(gw);  // numeric literal; parse once, compare by bytes
 
     const uint32_t lifetime = remove ? 0 : lease_duration_;
     const uint16_t requested_external = remove ? 0 : m.external_port;
@@ -291,9 +294,9 @@ bool NatPmpClient::send_map_request(socket_t sock, Mapping& m, bool remove) {
         if (stop_requested_.load()) return false;
         if (send_udp_data(sock, req, gw, NATPMP_PORT, AddressFamily::IPv4) < 0) return false;
 
-        Peer from;
+        Address from;
         auto resp = receive_udp_data(sock, 64, from, timeout, wakeup_.fd());
-        if (resp.size() < 16 || from.ip != gw) continue;
+        if (resp.size() < 16 || !gw_ip || from.ip != *gw_ip) continue;
         if (resp[0] != NATPMP_VERSION || resp[1] != expected_opcode) continue;
 
         uint16_t result = get_u16(&resp[2]);

package/native-src/src/{natpmp.h → librats/nat/natpmp.h}

@@ -24,9 +24,9 @@
  * @endcode
  */
 
-#include "port_mapping.h"
-#include "socket.h"
-#include "wakeup_pipe.h"
+#include "librats/nat/port_mapping.h"
+#include "librats/core/socket.h"
+#include "librats/core/wakeup_pipe.h"
 
 #include <atomic>
 #include <condition_variable>

package/native-src/src/{port_mapping.h → librats/nat/port_mapping.h}

@@ -8,7 +8,8 @@
  * home router to forward an external (WAN) port to a local (LAN) port so that
  * inbound peer connections can reach a host behind NAT. They share the small set
  * of vocabulary types defined here: the transport protocol of the mapping, which
- * backend produced a result, and the result/callback shape RatsClient consumes.
+ * backend produced a result, and the result/callback shape PortMappingService
+ * consumes.
  */
 
 #include <cstdint>
@@ -63,7 +64,7 @@ struct PortMapResult {
 using PortMapCallback = std::function<void(const PortMapResult&)>;
 
 /**
- * Configuration for RatsClient's automatic port forwarding.
+ * Configuration for automatic port forwarding (see PortMappingService).
  *
  * Both backends run in parallel by default; whichever the router supports
  * succeeds. Disabling one (or all) of them is a matter of flipping a flag.

package/native-src/src/{stun.cpp → librats/nat/stun.cpp}

@@ -5,9 +5,9 @@
  * Implements RFC 5389 - STUN protocol for NAT traversal.
  */
 
-#include "stun.h"
-#include "logger.h"
-#include "network_utils.h"
+#include "librats/nat/stun.h"
+#include "librats/util/logger.h"
+#include "librats/util/network_utils.h"
 #include <cstring>
 #include <algorithm>
 #include <chrono>
@@ -1057,7 +1057,7 @@ std::optional<StunMessage> StunClient::send_request(socket_t socket,
         
         // Wait for response with current RTO
         int wait_time = (std::min)(rto, timeout_ms - total_time);
-        Peer sender;
+        Address sender;
         
         auto response_data = receive_udp_data(socket, STUN_MAX_MESSAGE_SIZE, sender, wait_time);
         

package/native-src/src/{stun.h → librats/nat/stun.h}

@@ -8,7 +8,7 @@
  * Provides functionality to discover public IP address and port mappings.
  */
 
-#include "socket.h"
+#include "librats/core/socket.h"
 #include <array>
 #include <vector>
 #include <string>

package/native-src/src/{upnp.cpp → librats/nat/upnp.cpp}

@@ -3,9 +3,9 @@
  * @brief UPnP IGD port mapping client implementation
  */
 
-#include "upnp.h"
-#include "socket.h"
-#include "logger.h"
+#include "librats/nat/upnp.h"
+#include "librats/core/socket.h"
+#include "librats/util/logger.h"
 
 #include <cstring>
 #include <cstdio>
@@ -313,7 +313,7 @@ bool UpnpClient::discover_device(Device& out) {
 
         auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds(2);
         while (std::chrono::steady_clock::now() < deadline && !stop_requested_.load()) {
-            Peer from;
+            Address from;
             auto resp = receive_udp_data(sock, 2048, from, 1000, wakeup_.fd());
             if (resp.empty()) continue;
 
@@ -334,8 +334,8 @@ bool UpnpClient::discover_device(Device& out) {
             if (std::find(tried.begin(), tried.end(), location) != tried.end()) continue;
             tried.push_back(location);
 
-            std::string local_ip = local_ip_for_destination(from.ip, from.port);
-            LOG_UPNP_DEBUG("SSDP reply from " << from.ip << " location=" << location);
+            std::string local_ip = local_ip_for_destination(from.ip.to_string(), from.port);
+            LOG_UPNP_DEBUG("SSDP reply from " << from.ip.to_string() << " location=" << location);
             if (fetch_description(location, local_ip, out)) {
                 found = true;
                 break;

package/native-src/src/{upnp.h → librats/nat/upnp.h}

@@ -18,8 +18,8 @@
  * external XML/HTTP libraries) using librats' own socket primitives.
  */
 
-#include "port_mapping.h"
-#include "wakeup_pipe.h"
+#include "librats/nat/port_mapping.h"
+#include "librats/core/wakeup_pipe.h"
 
 #include <atomic>
 #include <condition_variable>

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/config.h

@@ -0,0 +1,110 @@
+#pragma once
+
+/**
+ * @file config.h
+ * @brief Node construction options.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/core/types.h"   // TransportKind
+
+#include <cstdint>
+#include <string>
+
+namespace librats {
+
+struct RATS_API NodeConfig {
+    /// Listen port for inbound peers. 0 picks an ephemeral port. Ignored if
+    /// enable_listen is false (client-only node). Both transports use this same
+    /// port, so one advertised address is dialable over either.
+    uint16_t listen_port = 0;
+    bool     enable_listen = true;
+
+    // ── Transports ──────────────────────────────────────────────────────────
+    //
+    // TCP and UDP are equal citizens here: identical framing, identical Noise
+    // handshake, identical guarantees. They differ only in how the ordered,
+    // reliable byte stream underneath is obtained — the kernel's TCP stack, or
+    // the library's own reliability layer over datagrams (transport/udp_stream.h).
+    // A node normally offers both and lets each dial pick.
+
+    /// Accept and dial over TCP.
+    bool enable_tcp = true;
+    /// Accept and dial over the datagram transport. Also gives a dial-only node a
+    /// single UDP socket to dial from, which is what keeps one NAT mapping open
+    /// for every peer instead of one per peer.
+    bool enable_udp = true;
+
+    /// Which transport a dial tries first.
+    ///
+    /// UDP is the default because it is the better fit for peer-to-peer: every
+    /// peer shares one socket and therefore one NAT mapping, the port a peer sees
+    /// us send from is the port it can dial back, which is what makes hole
+    /// punching possible at all, and no middlebox holds per-connection state that
+    /// can be exhausted or timed out from under us. TCP remains a first-class
+    /// equal, and is what the fallback below exists for — some networks block or
+    /// throttle UDP outright.
+    TransportKind preferred_transport = TransportKind::Udp;
+
+    /// How long the preferred transport dials alone before the other one is
+    /// raced alongside it. The first to complete its handshake wins and the loser
+    /// is dropped, so a UDP-blocking network costs this delay rather than a failed
+    /// 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).
+    ///
+    /// 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
+    /// an application feel backpressure sooner, and raising it lets a bursty one
+    /// buffer more before anything is said. The two move together on purpose:
+    /// a warning that arrives at the same moment as the disconnection is no
+    /// warning at all.
+    size_t send_queue_limit = 0;
+
+    /// Interface to bind the listener to. The address family is derived from it:
+    ///   - ""  or "::"      → dual-stack wildcard: reachable over both IPv6 and IPv4
+    ///                        (IPv4-mapped) on all interfaces. This is the default.
+    ///   - "0.0.0.0"        → IPv4 on all interfaces.
+    ///   - an IPv6 literal  → IPv6-only, that interface (e.g. "::1" for v6 loopback).
+    ///   - an IPv4 literal  → IPv4, that interface (e.g. "127.0.0.1" for v4 loopback).
+    /// Bare IPv6 literals are written without brackets here; peer endpoints rendered
+    /// as text use bracketed "[ip]:port" form (see core/address.h).
+    std::string bind_address = "";
+
+    /// Number of reactor threads. 1 is plenty for thousands of peers; larger
+    /// pools shard outbound connections across cores.
+    size_t reactor_threads = 1;
+
+    /// Maximum number of established peers. 0 means unlimited. The limit guards
+    /// inbound connections (a flood is refused at accept, before any handshake);
+    /// outbound dials we initiate are always honored. Runtime-adjustable via
+    /// Node::set_max_peers().
+    size_t max_peers = 0;
+
+    /// Secure channel to use for peer connections.
+    enum class Security { Noise, Plaintext };
+    Security security = Security::Noise;
+
+    /// Application protocol identity, bound into the Noise handshake prologue, so
+    /// two nodes whose protocol differs cannot complete a handshake — a cheap,
+    /// cryptographically-enforced way to keep separate apps (or app versions)
+    /// from cross-connecting. An opaque string compared for exact equality; by
+    /// convention "<name>/<version>". Both peers must match. (Under Plaintext it
+    /// is still checked, but not cryptographically bound — see PlaintextSecurity.)
+    std::string protocol = "librats/1.0";
+
+    /// Directory for persistent state. Empty = ephemeral (a fresh random
+    /// identity each run). When set, the node's Noise keypair is loaded from /
+    /// saved to "<data_dir>/identity.key", giving a stable PeerId across restarts.
+    std::string data_dir = "";
+
+    /// Watch the host for network configuration changes (interface up/down, IP
+    /// add/remove, route flip, wake-from-sleep) and publish NetworkChanged on the
+    /// node's EventBus so subsystems can renew port mappings, re-run STUN and
+    /// re-announce. Costs one mostly-idle monitor thread. See node/host_events.h.
+    bool enable_network_monitor = true;
+};
+
+} // namespace librats

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

@@ -0,0 +1,54 @@
+#pragma once
+
+/**
+ * @file dial_service.h
+ * @brief Dialing a specific endpoint over a specific wire — the capability a
+ *        NAT-traversal module needs and the ordinary connect() cannot express.
+ *
+ * PeerNetwork::connect(Address) is deliberately opinionated: it hands the target to
+ * the Dialer, which picks a transport, races the other one in after the fallback
+ * delay, and remembers what it learned for next time (see node/dialer.h). That is
+ * exactly right for "connect me to this peer" and exactly wrong for a hole punch,
+ * which needs three things the race cannot give:
+ *
+ *   - the datagram wire and nothing else. A punch is only possible on the shared
+ *     UDP socket; racing TCP alongside it spends a connect attempt on a path that
+ *     a NAT will refuse by construction.
+ *   - a dial that starts NOW, at a moment agreed with the peer. A punch works
+ *     because two Syns cross mid-path; a fallback delay measured from our own clock
+ *     has nothing to do with that instant.
+ *   - a different retry shape (see DialProfile) — dense probes rather than a long
+ *     patient tail, because the early Syns are *expected* to die on the peer's NAT.
+ *
+ * So this is the narrow escape hatch, published by the Node in its ServiceRegistry
+ * and resolved by whoever needs it:
+ *
+ *     if (auto* dial = ctx.services.get<DialService>())
+ *         dial->dial_direct(addr, TransportKind::Udp, DialProfile::punch());
+ *
+ * It is deliberately *not* on PeerNetwork: every subsystem sees that interface, and
+ * "dial exactly this, exactly this way" is a capability one module needs rather than
+ * a contract all of them should have. Everything else about the resulting connection
+ * is ordinary — the same handshake, the same identify, the same duplicate resolution
+ * in PeerTable if the peer dialed us back at the same moment.
+ */
+
+#include "librats/core/address.h"
+#include "librats/core/types.h"
+
+namespace librats {
+
+class DialService {
+public:
+    virtual ~DialService() = default;
+
+    /// Start exactly one dial to `addr` over `kind`, bypassing the transport race.
+    /// Non-blocking; the outcome surfaces through the node's ordinary peer-connected
+    /// event. Returns false when the node cannot carry that transport at all (no
+    /// datagram socket, or an address family the one socket cannot reach), in which
+    /// case nothing was started and no failure event will follow.
+    virtual bool dial_direct(const Address& addr, TransportKind kind,
+                             const DialProfile& profile) = 0;
+};
+
+} // namespace librats