librats 2.2.0 → 2.3.1

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

@@ -11,18 +11,40 @@
  *
  * Replication model — an epidemic LWW broadcast:
  *   - A local put/remove builds a StorageEntry (a delete is a tombstone entry
- *     with `deleted=true`) and broadcasts it to all connected peers.
+ *     with `deleted=true`) and sends it to every connected peer.
  *   - On receiving an entry, a node applies it under LWW. It re-forwards the
  *     entry to its *other* peers ONLY if the entry actually won (carried new
  *     information). A duplicate loses LWW and is not forwarded, so flooding
  *     terminates naturally — no separate dedup table needed.
- *   - On peer connect, both sides exchange a full snapshot (anti-entropy) so a
- *     late joiner catches up. LWW makes the merge order-independent.
+ *   - On peer connect, both sides ask each other for a full snapshot
+ *     (anti-entropy) so a late joiner catches up. LWW makes the merge
+ *     order-independent.
+ *
+ * Backpressure — why a snapshot is a *stream*, not a message:
+ *   A database is unbounded, a peer's send queue is not. One message carrying
+ *   the whole store stops being sendable at the connection's low-water mark,
+ *   gets the peer dropped as a slow consumer past its high-water mark, and is
+ *   not even representable past the block-size ceiling — and since both ends
+ *   request a snapshot on connect, two of them cross on every single link. So
+ *   a snapshot is served as a sequence of bounded SYNC_CHUNK messages walking
+ *   the (ordered) key space, one chunk at a time, and the next chunk is only
+ *   produced while `PeerNetwork::peer_writable()` says there is room. Every
+ *   send() return value is honoured: a peer that fills up stops receiving
+ *   individual entries and is instead owed a fresh snapshot, which the sync
+ *   thread starts once on_peer_writable says the link has drained. Losing live
+ *   updates to a congested peer is safe precisely because the store is LWW —
+ *   the snapshot that follows carries the winning state either way.
+ *
+ *   All of that runs on this module's own sync thread. Serialising even one
+ *   chunk happens off the reactor thread, so a reactor never spends time (or
+ *   holds storage_mutex_) proportional to the size of the database.
  *
  * Wire format (MessageType::Storage payload, opcode in byte 0):
  *   ENTRY:         [1][StorageEntry.serialize()]
  *   SYNC_REQUEST:  [2]
- *   SYNC_RESPONSE: [3][count:u32][StorageEntry.serialize()] * count
+ *   SYNC_CHUNK:    [3][flags:u8][count:u32][StorageEntry.serialize()] * count
+ *                  flags bit0 (LAST) marks the final chunk of a snapshot; a
+ *                  snapshot of an empty store is one chunk with count 0.
  *
  * The class is also usable standalone (no network attached) as a local,
  * persistent key-value store; all network operations no-op until attach().
@@ -38,6 +60,7 @@
 #include <string>
 #include <vector>
 #include <functional>
+#include <map>
 #include <memory>
 #include <mutex>
 #include <unordered_map>
@@ -113,7 +136,23 @@ struct RATS_API StorageEntry {
     // Serialize entry to binary format
     std::vector<uint8_t> serialize() const;
 
-    // Deserialize entry from binary format
+    /// Append the serialized entry to `out`. What serialize() is built on: a
+    /// batch appends entry after entry into one buffer instead of allocating a
+    /// vector per entry only to copy it away again.
+    void serialize_into(std::vector<uint8_t>& out) const;
+
+    /// Serialized size in bytes, without serializing.
+    size_t serialized_size() const;
+
+    /// Deserialize one entry from `data[offset..]`, setting `bytes_read` to the
+    /// bytes it consumed. Every field is bounds-checked against the entry's own
+    /// declared length as well as the buffer, so a hostile length can neither
+    /// read past the buffer nor reach into the entry that follows.
+    static bool deserialize(const uint8_t* data, size_t size, size_t offset,
+                            StorageEntry& entry, size_t& bytes_read);
+
+    /// Vector overload of the above; the wire path uses the pointer form to
+    /// parse straight out of the receive buffer without copying it first.
     static bool deserialize(const std::vector<uint8_t>& data, size_t offset,
                            StorageEntry& entry, size_t& bytes_read);
 
@@ -136,23 +175,51 @@ struct StorageChangeEvent {
 };
 
 /**
- * Storage configuration
+ * Storage configuration.
+ *
+ * The two size limits are not free parameters: both are bounded by what one
+ * peer's send queue can hold. A connection drops its peer as a slow consumer
+ * past its high-water mark (8 MiB by default, NodeConfig::send_queue_limit) and
+ * reports "no room" at a quarter of it, so a single value — and a single
+ * snapshot chunk — must stay well inside that quarter, or the very first one
+ * would kill the link it travels on. Both are clamped to kMaxValueSize /
+ * kMaxSyncBatchBytes on construction and in set_config().
  */
 struct StorageConfig {
+    /// Ceiling on max_value_size: the default connection low-water mark. One
+    /// value at the ceiling makes a peer unwritable and is then waited out,
+    /// rather than counting toward the high-water mark that drops it.
+    static constexpr uint32_t kMaxValueSize      = 2 * 1024 * 1024;
+    /// Ceiling on sync_batch_bytes, for the same reason.
+    static constexpr uint32_t kMaxSyncBatchBytes = 2 * 1024 * 1024;
+    /// Floor on sync_batch_bytes: below this a snapshot costs more in per-message
+    /// framing and round trips than it saves in queue occupancy.
+    static constexpr uint32_t kMinSyncBatchBytes = 16 * 1024;
+
     std::string data_directory;         // Directory for storage files
     std::string database_name;          // Database filename prefix
     bool enable_sync;                   // Enable network synchronization
     uint32_t compaction_threshold;      // Number of tombstones before compaction
-    uint32_t max_value_size;            // Maximum value size in bytes
+    uint32_t max_value_size;            // Maximum value size in bytes (<= kMaxValueSize)
     bool persist_to_disk;               // Whether to persist data to disk
+    /// Target payload size of one snapshot chunk. The walk stops at the first
+    /// entry that takes the buffer past this, so a chunk is this size plus at
+    /// most one entry — which is why max_value_size shares the same ceiling.
+    uint32_t sync_batch_bytes;
+    /// Minimum gap between two snapshots served to the same peer. Bounds what a
+    /// peer can make us spend by asking, and paces the re-sync a peer is owed
+    /// after it has been congested.
+    uint32_t sync_min_interval_ms;
 
     StorageConfig()
         : data_directory("./storage"),
           database_name("rats_storage"),
           enable_sync(true),
           compaction_threshold(1000),
-          max_value_size(16 * 1024 * 1024),  // 16MB max value size
-          persist_to_disk(true) {}
+          max_value_size(1024 * 1024),        // 1 MiB max value size
+          persist_to_disk(true),
+          sync_batch_bytes(256 * 1024),       // 256 KiB per snapshot chunk
+          sync_min_interval_ms(5000) {}
 };
 
 /**
@@ -167,6 +234,9 @@ struct StorageStatistics {
     uint64_t entries_sent;              // Entries sent to peers
     uint64_t sync_requests_received;    // Number of sync requests received
     uint64_t sync_requests_sent;        // Number of sync requests sent
+    uint64_t sync_chunks_sent;          // Snapshot chunks put on the wire
+    uint64_t sync_chunks_received;      // Snapshot chunks applied from peers
+    uint64_t resyncs_scheduled;         // Snapshots owed to peers that filled up
     std::chrono::steady_clock::time_point last_sync_time;  // Last sync timestamp
     StorageSyncStatus sync_status;      // Current sync status
 };
@@ -216,6 +286,9 @@ public:
     // Configuration
     // =========================================================================
 
+    /// Replace the configuration. Size limits are clamped (see StorageConfig).
+    /// Call it before start(): the sync thread reads its tuning once when it
+    /// starts, and the store's other threads read the config without a lock.
     void set_config(const StorageConfig& config);
     const StorageConfig& get_config() const;
 
@@ -287,20 +360,60 @@ private:
     // Network message handlers (run on a reactor thread).
     void on_storage_message(const PeerId& from, ByteView payload);
     void on_peer_connected(const PeerId& peer_id);
+    void on_peer_disconnected(const PeerId& peer_id);
+    void on_peer_writable(const PeerId& peer_id);
 
     PeerNetwork* network_ = nullptr;
     StorageConfig config_;
 
-    // In-memory storage
+    // In-memory storage.
+    //
+    // Ordered, not hashed, and that is load-bearing: a snapshot is streamed one
+    // bounded chunk at a time, and between chunks the only thing carried over is
+    // the last key sent. An ordered map turns that key back into a position with
+    // upper_bound(), so a stream costs nothing to keep alive and cannot be
+    // derailed by concurrent writes — an unordered_map would need either a
+    // materialised key list per peer or iterators that a rehash invalidates.
+    // It also makes keys_with_prefix() a range scan instead of a full walk.
     mutable std::mutex storage_mutex_;
-    std::unordered_map<std::string, StorageEntry> entries_;
+    std::map<std::string, StorageEntry> entries_;
 
-    // Sync state
+    // Sync state.
+    //
+    // Lock order, exactly one rule: storage_mutex_ and sync_mutex_ are never held
+    // at the same time, and neither is ever held across a call into PeerNetwork.
     mutable std::mutex sync_mutex_;
     StorageSyncStatus sync_status_;
     bool initial_sync_complete_;
     std::chrono::steady_clock::time_point last_sync_time_;
 
+    /// What we owe one peer. A snapshot is served as a walk over the key space
+    /// whose whole resumable state is `cursor` — the last key already sent.
+    struct PeerSync {
+        bool                                  streaming = false;  ///< a snapshot is in flight
+        bool                                  started   = false;  ///< cursor is meaningful
+        std::string                           cursor;             ///< last key sent
+        bool                                  owed      = false;  ///< a (re)snapshot is due
+        std::chrono::steady_clock::time_point last_start{};       ///< for sync_min_interval_ms
+    };
+    std::unordered_map<PeerId, PeerSync, PeerId::Hash> peers_;    ///< guarded by sync_mutex_
+    /// Bumped, under sync_mutex_, whenever something the sync thread would act on
+    /// changes — a snapshot scheduled, a link drained, a peer gone. The thread
+    /// reads it before it scans and compares it before it waits, because between
+    /// those two points it is outside the lock (serializing and sending), and a
+    /// notify that arrives there would otherwise be one nobody is waiting for.
+    uint64_t sync_epoch_ = 0;
+
+    // The sync thread: serializes and paces every snapshot chunk, so no reactor
+    // thread ever does work proportional to the size of the database.
+    std::atomic<bool>       sync_running_{false};
+    std::thread             sync_thread_;
+    std::condition_variable sync_cv_;   ///< paired with sync_mutex_
+    // Sync tuning, copied out of the config when the thread starts and read-only
+    // afterwards, so the thread never races a set_config() on another thread.
+    size_t                    batch_bytes_{0};
+    std::chrono::milliseconds sync_interval_{0};
+
     // Statistics
     mutable std::mutex stats_mutex_;
     StorageStatistics stats_;
@@ -317,14 +430,37 @@ private:
     bool dirty_;  // Flag indicating unsaved changes
 
     // Wire opcodes (MessageType::Storage payload, byte 0)
-    static constexpr uint8_t OP_ENTRY         = 1;
-    static constexpr uint8_t OP_SYNC_REQUEST  = 2;
-    static constexpr uint8_t OP_SYNC_RESPONSE = 3;
+    static constexpr uint8_t OP_ENTRY        = 1;
+    static constexpr uint8_t OP_SYNC_REQUEST = 2;
+    static constexpr uint8_t OP_SYNC_CHUNK   = 3;
+
+    // SYNC_CHUNK flags (byte 1)
+    static constexpr uint8_t FLAG_LAST = 0x01;   ///< final chunk of this snapshot
+
+    /// Refuse an inbound Storage message larger than this before parsing it. Our
+    /// own sender never comes near it (one chunk is sync_batch_bytes plus at most
+    /// one value, both capped at 2 MiB), while the block layer would happily hand
+    /// us 64 MiB from a peer that means us harm.
+    static constexpr size_t kMaxInboundMessage = 8 * 1024 * 1024;
 
     // Private methods
     void initialize();
     void shutdown();
     void persistence_thread_loop();
+    void start_sync_thread();
+    void stop_sync_thread();
+    void sync_thread_loop();
+    /// What one turn of a peer's snapshot stream left behind.
+    enum class ChunkResult {
+        Continue,   ///< a chunk went out and the link has room for the next
+        Blocked,    ///< a chunk went out and filled the link; retry when it drains
+        Finished    ///< the snapshot is complete (or the peer is gone)
+    };
+    /// Serialize and send the next chunk of `peer`'s snapshot.
+    ChunkResult stream_snapshot_chunk(const PeerId& peer);
+    /// Note that `peer` is due a snapshot; the sync thread starts it once the
+    /// link has room and the per-peer interval has elapsed.
+    void schedule_snapshot(const PeerId& peer, bool requested_by_peer);
 
     // Internal put with full control
     bool put_internal(const std::string& key, StorageValueType type,
@@ -341,14 +477,20 @@ private:
     double deserialize_double(const std::vector<uint8_t>& data) const;
     std::string deserialize_string(const std::vector<uint8_t>& data) const;
 
-    // Network operations
-    void broadcast_entry(const StorageEntry& entry);              ///< to all peers
-    void forward_entry(const StorageEntry& entry, const PeerId& except);  ///< re-flood
+    // Network operations. Every one of them honours send()'s return value: a peer
+    // that answers "no room" is owed a snapshot instead of further entries.
+    /// Send one entry to every connected peer except `except` (null for none).
+    void replicate_entry(const StorageEntry& entry, const PeerId* except);
+    void broadcast_entry(const StorageEntry& entry) { replicate_entry(entry, nullptr); }
+    void forward_entry(const StorageEntry& entry, const PeerId& except) {
+        replicate_entry(entry, &except);
+    }
     void send_sync_request(const PeerId& peer_id);
-    void send_sync_response(const PeerId& peer_id);
 
     // Apply a remote entry with LWW; fills `out_event` and returns true if applied.
     bool apply_remote_entry(const StorageEntry& entry, StorageChangeEvent* out_event);
+    /// Parse and apply the entries in one SYNC_CHUNK body. @return how many won.
+    uint32_t apply_chunk(const PeerId& from, const uint8_t* data, size_t size, uint32_t count);
 
     // File path helpers
     std::string get_data_file_path() const;
@@ -359,6 +501,8 @@ private:
     bool read_data_file();
 
     // Utility
+    /// Clamp the size limits to what one connection's send queue can carry.
+    static void sanitize_config(StorageConfig& config);
     uint64_t get_current_timestamp_ms() const;
     std::string get_our_peer_id() const;
     void notify_change(const StorageChangeEvent& event);

package/native-src/src/librats/subsystems/file_transfer.cpp

@@ -80,7 +80,7 @@ void FileTransfer::attach(NodeContext& ctx) {
     network_ = &ctx.network;
     network_->on(MessageType::FileChunk,
                  [this](const Peer& peer, ByteView payload) { on_message(peer, payload); });
-    network_->on_peer_disconnected([this](const PeerId& id) {
+    network_->on_peer_disconnected([this](const PeerId& id, CloseReason) {
         // Fail every in-flight transfer with the departed peer and reclaim temps.
         std::vector<std::shared_ptr<Outgoing>> out;
         std::vector<std::shared_ptr<Incoming>> in;

package/native-src/src/librats/subsystems/pubsub.cpp

@@ -106,7 +106,7 @@ void PubSub::attach(NodeContext& ctx) {
     network_->on(MessageType::Gossip,
                          [this](const Peer& peer, ByteView payload) { on_gossip(peer, payload); });
     network_->on_peer_connected([this](const Peer& peer) { on_new_peer(peer); });
-    network_->on_peer_disconnected([this](const PeerId& id) { on_peer_gone(id); });
+    network_->on_peer_disconnected([this](const PeerId& id, CloseReason) { on_peer_gone(id); });
 }
 
 void PubSub::start() {

package/native-src/src/librats/subsystems/reconnection.cpp

@@ -74,7 +74,7 @@ std::vector<Address> ReconnectionService::known_peers(size_t n) const {
 void ReconnectionService::attach(NodeContext& ctx) {
     network_ = &ctx.network;
     network_->on_peer_connected([this](const Peer& peer) { on_connected(peer); });
-    network_->on_peer_disconnected([this](const PeerId& id) { on_disconnected(id); });
+    network_->on_peer_disconnected([this](const PeerId& id, CloseReason) { on_disconnected(id); });
     network_->on_dial_failed([this](const Address& addr) { on_dial_failed(addr); });
 }
 

package/native-src/src/librats/subsystems/relay.cpp

@@ -1072,7 +1072,8 @@ void Relay::attach(NodeContext& ctx) {
     ctx.network.on(MessageType::Relay,
                    [state](const Peer& peer, ByteView payload) { state->handle(peer, payload); });
     ctx.network.on_peer_connected([state](const Peer& peer) { state->on_peer_connected(peer); });
-    ctx.network.on_peer_disconnected([state](const PeerId& id) { state->on_peer_disconnected(id); });
+    ctx.network.on_peer_disconnected(
+        [state](const PeerId& id, CloseReason) { state->on_peer_disconnected(id); });
     ctx.network.on_peer_writable([state](const Peer& peer) { state->on_peer_writable(peer.id()); });
 
     services_ = &ctx.services;

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

@@ -51,6 +51,46 @@ uint8_t Connection::reactor_index() const noexcept { return reactor_.index(); }
 bool Connection::send(FrameHeader header, ByteView payload) {
     if (state_ != ConnState::Established) return false;  // frames only flow post-handshake
 
+    // The one thing that is refused outright rather than queued: a message too
+    // large to be framed at all. The block prefix tops out at kMaxBlockSize and the
+    // peer's decoder rejects anything past it, so queueing this would spend the
+    // link only to have the far end hang up on a protocol error it was handed on
+    // purpose. Waiting cannot help either — no amount of draining makes it fit — so
+    // the honest answer is a refusal, with the frame unqueued and the connection
+    // untouched. Checked before encrypt() because the nonce counters run in
+    // lockstep: a message encrypted and then dropped would break every one after.
+    if (framer::kHeaderSize + payload.size() + session_->overhead() > framer::kMaxBlockSize) {
+        LOG_WARN("connection", "Peer " << remote_id_.short_hex() << " refused a "
+                 << payload.size() << " B message: past the " << framer::kMaxBlockSize
+                 << " B block ceiling; split it");
+        return false;
+    }
+
+    // Weighed on the backlog as it stands BEFORE this message, never after it has
+    // been added. A message is indivisible — there is no queueing half of one — so
+    // judging a caller by the mark its own message has just crossed answers "that
+    // message was bigger than a limit nobody published" with a disconnection, on a
+    // connection that is idle, healthy and draining at full speed. What the mark is
+    // for is a peer that cannot keep up, and the evidence for that is a caller
+    // piling MORE on top of a backlog that is already over it.
+    //
+    // So one message may always be queued, whatever its size — the queue may exceed
+    // the mark by exactly that message and no more — and offering another before it
+    // has drained is what makes a caller a slow consumer. Nothing is ever dropped
+    // or refused here, which is what the layers above rely on: a relayed circuit
+    // (transport/relay_link.cpp) reports bytes as written the moment it hands them
+    // over, and a byte stream cannot survive one of them going missing.
+    const size_t backlog_before = backlog();
+    if (backlog_before > send_high_water_) {
+        LOG_WARN("connection", "Peer " << remote_id_.short_hex() << " offered more with "
+                 << backlog_before << " B still queued past the high-water mark ("
+                 << send_high_water_ << " B); closing as slow consumer");
+        close_reason_ = CloseReason::SlowConsumer;
+        state_ = ConnState::Closing;
+        reactor_.close(id_, CloseReason::SlowConsumer);
+        return false;
+    }
+
     Bytes inner;
     framer::encode_message(inner, header, payload);
 
@@ -64,14 +104,6 @@ bool Connection::send(FrameHeader header, ByteView payload) {
     queue_block(std::move(cipher));
 
     const size_t backlog_now = backlog();
-    if (backlog_now > send_high_water_) {
-        LOG_WARN("connection", "Peer " << remote_id_.short_hex() << " over send high-water ("
-                 << backlog_now << " B); closing as slow consumer");
-        close_reason_ = CloseReason::SlowConsumer;
-        state_ = ConnState::Closing;
-        reactor_.close(id_, CloseReason::SlowConsumer);
-        return false;
-    }
 
     // The queue has grown past what a caller should keep adding to. Everything
     // still goes out — nothing is dropped here — but the answer to "may I send

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

@@ -85,8 +85,11 @@ public:
 
 class Connection {
 public:
-    /// High-water mark for the memory held by the send queue; exceeding it closes the
-    /// connection with CloseReason::SlowConsumer.
+    /// High-water mark for the memory held by the send queue. A caller that offers
+    /// another message while the queue is *still* over it has the connection closed
+    /// with CloseReason::SlowConsumer. The mark is never applied to the message that
+    /// crosses it: one message may always be queued, whatever its size (see send()),
+    /// so the queue's ceiling is this plus one message rather than this exactly.
     static constexpr size_t kDefaultSendHighWater = 8 * 1024 * 1024;
 
     /// Where send() starts answering "no room". A quarter of the hard limit, so a
@@ -125,6 +128,13 @@ public:
 
     /// Queue an application frame for the peer. No-op unless Established.
     ///
+    /// Never refuses and never drops: whatever it is handed is queued, however
+    /// large. The size of a single message is not what the high-water mark is
+    /// about — a message cannot be queued by halves, so a connection that is
+    /// draining perfectly well must not be torn down over one big frame. What
+    /// closes a connection is offering *another* message while the queue is still
+    /// over the mark, which is the actual evidence that the peer is not keeping up.
+    ///
     /// @return whether there is still room for more. False means the queue is
     ///         past its low-water mark — this frame is queued like any other,
     ///         nothing is dropped, but the caller should stop and wait for

package/native-src/src/librats/util/logger.h

@@ -29,6 +29,9 @@
     #endif
 #else
     #include <unistd.h>
+    #if defined(__ANDROID__)
+        #include <android/log.h>
+    #endif
 #endif
 
 namespace librats {
@@ -149,7 +152,24 @@ public:
         if (level < min_level_.load(std::memory_order_relaxed)) {
             return;
         }
-        
+
+#if defined(__ANDROID__)
+        // An Android app's stdout/stderr are discarded by default, so the cout/cerr
+        // sink below is invisible in logcat. Route console output through the platform
+        // logger instead: logcat supplies its own timestamp, level and coloring, so the
+        // bare message goes out under the module name as the tag. The file sink is
+        // unaffected and stays identical to every other platform.
+        if (console_logging_enabled_) {
+            __android_log_print(get_android_priority(level),
+                                module.empty() ? "librats" : module.c_str(),
+                                "%s", message.c_str());
+        }
+        if (file_logging_enabled_ && log_file_.is_open()) {
+            write_to_file(level, module, message);
+        }
+        return;
+#endif
+
         // Prepare console output with colors
         std::ostringstream console_oss;
         
@@ -239,6 +259,18 @@ private:
             default: return "UNKNOWN";
         }
     }
+
+#if defined(__ANDROID__)
+    int get_android_priority(LogLevel level) {
+        switch (level) {
+            case LogLevel::DEBUG: return ANDROID_LOG_DEBUG;
+            case LogLevel::INFO:  return ANDROID_LOG_INFO;
+            case LogLevel::WARN:  return ANDROID_LOG_WARN;
+            case LogLevel::ERROR: return ANDROID_LOG_ERROR;
+            default: return ANDROID_LOG_INFO;
+        }
+    }
+#endif
     
     std::string get_color_code(LogLevel level) {
         if (!colors_enabled_ || !is_terminal_) return "";
@@ -411,10 +443,9 @@ private:
             std::string old_name = log_file_path_ + "." + std::to_string(i);
             std::string new_name = log_file_path_ + "." + std::to_string(i + 1);
             
-            // Delete the oldest file if it exists
-            if (i == max_log_files_ - 1) {
-                std::remove(new_name.c_str());
-            }
+            // std::rename() does not replace an existing destination on Windows,
+            // so clear the target first - not just the oldest file.
+            std::remove(new_name.c_str());
             
             // Rename old file to new name
             std::rename(old_name.c_str(), new_name.c_str());
@@ -422,6 +453,7 @@ private:
         
         // Move current log file to .1
         std::string backup_name = log_file_path_ + ".1";
+        std::remove(backup_name.c_str());
         std::rename(log_file_path_.c_str(), backup_name.c_str());
     }
     

package/native-src/src/librats/util/network_monitor.cpp

@@ -25,7 +25,21 @@
     #include <cerrno>
 #elif defined(__APPLE__) || defined(__FreeBSD__) || defined(__NetBSD__) || \
       defined(__OpenBSD__) || defined(__DragonFly__)
+    #ifdef __APPLE__
+        #include <TargetConditionals.h>
+    #endif
+    // Apple ships <net/route.h> in the macOS SDK only. On iOS the PF_ROUTE
+    // socket itself is usable but the message declarations are not public, so
+    // there is nothing to parse against — those targets take the polling
+    // fallback at the bottom of this file (backend_start() returns false).
+    // A native backend for iOS belongs on Network.framework's nw_path_monitor
+    // rather than on route messages.
+    #if !defined(__APPLE__) || (defined(TARGET_OS_OSX) && TARGET_OS_OSX)
     #define RATS_MONITOR_BSD_ROUTES 1
+    #endif
+#endif
+
+#if defined(RATS_MONITOR_BSD_ROUTES)
     #include <sys/types.h>
     #include <sys/socket.h>
     #include <net/route.h>

package/native-src/src/librats/util/network_utils.cpp

@@ -17,8 +17,17 @@
         #include <ifaddrs.h>
     #endif
 
+    #ifdef __APPLE__
+        #include <TargetConditionals.h>
+    #endif
+
     // macOS / BSD default-gateway lookup via the PF_ROUTE sysctl routing table.
-    #if defined(__APPLE__) || defined(__FreeBSD__) || defined(__NetBSD__) || \
+    // Apple ships <net/route.h> in the macOS SDK only: on iOS (and tvOS/watchOS)
+    // the sysctl still exists but its declarations are not public, so those
+    // targets skip this branch and rely on append_gateway_heuristics() below,
+    // which every platform falls back to anyway.
+    #if (defined(__APPLE__) && defined(TARGET_OS_OSX) && TARGET_OS_OSX) || \
+        defined(__FreeBSD__) || defined(__NetBSD__) || \
         defined(__OpenBSD__) || defined(__DragonFly__)
         #define RATS_HAVE_BSD_ROUTES 1
         #include <sys/types.h>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "librats",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "Node.js bindings for librats - A high-performance peer-to-peer networking library",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",