librats 0.8.0 → 0.9.1

package/native-src/src/librats.h

@@ -1166,185 +1166,88 @@ public:
     // =========================================================================
     // File Transfer API
     // =========================================================================
-    
+    //
+    // Streams files and directory trees to connected peers. A transfer is
+    // offered to the peer, who accepts (choosing a destination) or rejects it.
+    // See file_transfer.h for the FileTransferManager that implements it.
+
     /**
-     * Get the file transfer manager instance
-     * @return Reference to the file transfer manager
+     * Get the file transfer manager instance.
      */
     FileTransferManager& get_file_transfer_manager();
-    
+
     /**
-     * Check if file transfer is available
-     * @return true if file transfer manager is initialized
+     * Check whether the file transfer manager is initialized.
      */
     bool is_file_transfer_available() const;
-    
-    // Sending and Requesting
+
     /**
-     * Send a file to a peer
-     * @param peer_id Target peer ID
-     * @param file_path Local file path to send
-     * @param remote_filename Optional remote filename (default: use local name)
-     * @return Transfer ID if successful, empty string if failed
+     * Send a file to a peer.
+     * @param peer_id        Target peer ID
+     * @param file_path      Local file to send
+     * @param remote_filename Optional name to present to the peer
+     * @return Transfer ID, or empty string on immediate failure
      */
-    std::string send_file(const std::string& peer_id, const std::string& file_path, 
-                         const std::string& remote_filename = "");
-    
+    std::string send_file(const std::string& peer_id, const std::string& file_path,
+                          const std::string& remote_filename = "");
+
     /**
-     * Send an entire directory to a peer
-     * @param peer_id Target peer ID
-     * @param directory_path Local directory path to send
-     * @param remote_directory_name Optional remote directory name
-     * @param recursive Whether to include subdirectories (default: true)
-     * @return Transfer ID if successful, empty string if failed
+     * Send a directory tree (recursively) to a peer.
+     * @param peer_id        Target peer ID
+     * @param directory_path Local directory to send
+     * @param remote_name    Optional name to present to the peer
+     * @return Transfer ID, or empty string on immediate failure
      */
     std::string send_directory(const std::string& peer_id, const std::string& directory_path,
-                              const std::string& remote_directory_name = "", bool recursive = true);
-    
-    /**
-     * Request a file from a remote peer
-     * @param peer_id Target peer ID
-     * @param remote_file_path Path to file on remote peer
-     * @param local_path Local path where file should be saved
-     * @return Transfer ID if successful, empty string if failed
-     */
-    std::string request_file(const std::string& peer_id, const std::string& remote_file_path,
-                            const std::string& local_path);
-    
-    /**
-     * Request a directory from a remote peer
-     * @param peer_id Target peer ID
-     * @param remote_directory_path Path to directory on remote peer
-     * @param local_directory_path Local path where directory should be saved
-     * @param recursive Whether to include subdirectories (default: true)
-     * @return Transfer ID if successful, empty string if failed
-     */
-    std::string request_directory(const std::string& peer_id, const std::string& remote_directory_path,
-                                 const std::string& local_directory_path, bool recursive = true);
-    
-    // Accept/Reject Operations
+                               const std::string& remote_name = "");
+
     /**
-     * Accept an incoming file transfer
-     * @param transfer_id Transfer identifier from request
-     * @param local_path Local path where file should be saved
-     * @return true if accepted successfully
+     * Accept an incoming transfer. For a file, local_path is the destination
+     * file path; for a directory, it is the destination directory.
      */
     bool accept_file_transfer(const std::string& transfer_id, const std::string& local_path);
-    
+
     /**
-     * Reject an incoming file transfer
-     * @param transfer_id Transfer identifier from request
-     * @param reason Optional reason for rejection
-     * @return true if rejected successfully
+     * Reject an incoming transfer.
      */
     bool reject_file_transfer(const std::string& transfer_id, const std::string& reason = "");
-    
-    /**
-     * Accept an incoming directory transfer
-     * @param transfer_id Transfer identifier from request
-     * @param local_path Local path where directory should be saved
-     * @return true if accepted successfully
-     */
-    bool accept_directory_transfer(const std::string& transfer_id, const std::string& local_path);
-    
-    /**
-     * Reject an incoming directory transfer
-     * @param transfer_id Transfer identifier from request
-     * @param reason Optional reason for rejection
-     * @return true if rejected successfully
-     */
-    bool reject_directory_transfer(const std::string& transfer_id, const std::string& reason = "");
-    
-    // Transfer Control
-    /**
-     * Pause an active file transfer
-     * @param transfer_id Transfer to pause
-     * @return true if paused successfully
-     */
+
+    /** Pause an active transfer (either direction). */
     bool pause_file_transfer(const std::string& transfer_id);
-    
-    /**
-     * Resume a paused file transfer
-     * @param transfer_id Transfer to resume
-     * @return true if resumed successfully
-     */
+
+    /** Resume a paused transfer. */
     bool resume_file_transfer(const std::string& transfer_id);
-    
-    /**
-     * Cancel an active or paused file transfer
-     * @param transfer_id Transfer to cancel
-     * @return true if cancelled successfully
-     */
+
+    /** Cancel an active or paused transfer. */
     bool cancel_file_transfer(const std::string& transfer_id);
-    
-    // Information and Monitoring
-    /**
-     * Get file transfer progress information
-     * @param transfer_id Transfer to query
-     * @return Progress information or nullptr if not found
-     */
+
+    /** Get a progress snapshot, or nullptr if the transfer is unknown. */
     std::shared_ptr<FileTransferProgress> get_file_transfer_progress(const std::string& transfer_id) const;
-    
-    /**
-     * Get all active file transfers
-     * @return Vector of transfer progress objects
-     */
+
+    /** Get progress snapshots for all non-finished transfers. */
     std::vector<std::shared_ptr<FileTransferProgress>> get_active_file_transfers() const;
-    
-    /**
-     * Get file transfer statistics
-     * @return JSON object with transfer statistics
-     */
+
+    /** Get aggregate file transfer statistics as JSON. */
     nlohmann::json get_file_transfer_statistics() const;
-    
-    /**
-     * Set file transfer configuration
-     * @param config Transfer configuration settings
-     */
+
+    /** Replace the file transfer configuration. */
     void set_file_transfer_config(const FileTransferConfig& config);
-    
-    /**
-     * Get current file transfer configuration
-     * @return Current configuration settings
-     */
+
+    /** Get the current file transfer configuration. */
     FileTransferConfig get_file_transfer_config() const;
-    
-    // Event Handlers
-    /**
-     * Set file transfer progress callback
-     * @param callback Function to call with progress updates
-     */
-    void on_file_transfer_progress(FileTransferProgressCallback callback);
-    
-    /**
-     * Set file transfer completion callback
-     * @param callback Function to call when transfers complete
-     */
-    void on_file_transfer_completed(FileTransferCompletedCallback callback);
-    
-    /**
-     * Set incoming file transfer request callback
-     * @param callback Function to call when receiving transfer requests
-     */
-    void on_file_transfer_request(FileTransferRequestCallback callback);
-    
-    /**
-     * Set directory transfer progress callback
-     * @param callback Function to call with directory transfer progress
-     */
-    void on_directory_transfer_progress(DirectoryTransferProgressCallback callback);
-    
-    /**
-     * Set file request callback (called when receiving file requests)
-     * @param callback Function to call when receiving file requests
-     */
-    void on_file_request(FileRequestCallback callback);
-    
+
+    /** Set the progress callback (fires for both directions). */
+    void on_file_transfer_progress(TransferProgressCallback callback);
+
+    /** Set the completion callback (fires once per transfer). */
+    void on_file_transfer_completed(TransferCompletedCallback callback);
+
     /**
-     * Set directory request callback (called when receiving directory requests)
-     * @param callback Function to call when receiving directory requests
+     * Set the incoming-offer callback. The handler should call
+     * accept_file_transfer()/reject_file_transfer(). Without it, offers are
+     * auto-rejected.
      */
-    void on_directory_request(DirectoryRequestCallback callback);
+    void on_file_transfer_request(TransferOfferCallback callback);
 
     // =========================================================================
     // ICE (NAT Traversal) API
@@ -2059,9 +1962,13 @@ private:
     JsonDataCallback json_data_callback_;
     DisconnectCallback disconnect_callback_;
     
-    // DHT client for peer discovery
+    // DHT clients for peer discovery. IPv4 and IPv6 are separate Kademlia networks
+    // (BEP 32), so each family runs its own client. dht_client_ (IPv4) is also the one
+    // shared with the BitTorrent subsystem; dht_client_v6_ is created best-effort when
+    // IPv6 is available.
     std::unique_ptr<DhtClient> dht_client_;
-    
+    std::unique_ptr<DhtClient> dht_client_v6_;
+
     // mDNS client for local network discovery
     std::unique_ptr<MdnsClient> mdns_client_;
     std::function<void(const std::string&, int, const std::string&)> mdns_callback_;

package/native-src/src/librats_c.cpp

@@ -679,42 +679,36 @@ char* rats_send_directory(rats_client_t handle, const char* peer_id, const char*
     rats_client_wrapper* wrap = static_cast<rats_client_wrapper*>(handle);
     
     std::string remote_name = remote_directory_name ? std::string(remote_directory_name) : std::string("");
-    std::string transfer_id = wrap->client->send_directory(std::string(peer_id), std::string(directory_path), remote_name, recursive != 0);
-    
+    (void)recursive; // directory transfers are always recursive
+    std::string transfer_id = wrap->client->send_directory(std::string(peer_id), std::string(directory_path), remote_name);
+
     return transfer_id.empty() ? nullptr : rats_strdup_owned(transfer_id);
 }
 
+// Pull-style requests are not supported in this version; transfers are push-only.
 char* rats_request_file(rats_client_t handle, const char* peer_id, const char* remote_file_path, const char* local_path) {
-    if (!handle || !peer_id || !remote_file_path || !local_path) return nullptr;
-    rats_client_wrapper* wrap = static_cast<rats_client_wrapper*>(handle);
-    
-    std::string transfer_id = wrap->client->request_file(std::string(peer_id), std::string(remote_file_path), std::string(local_path));
-    
-    return transfer_id.empty() ? nullptr : rats_strdup_owned(transfer_id);
+    (void)handle; (void)peer_id; (void)remote_file_path; (void)local_path;
+    return nullptr;
 }
 
 char* rats_request_directory(rats_client_t handle, const char* peer_id, const char* remote_directory_path, const char* local_directory_path, int recursive) {
-    if (!handle || !peer_id || !remote_directory_path || !local_directory_path) return nullptr;
-    rats_client_wrapper* wrap = static_cast<rats_client_wrapper*>(handle);
-    
-    std::string transfer_id = wrap->client->request_directory(std::string(peer_id), std::string(remote_directory_path), std::string(local_directory_path), recursive != 0);
-    
-    return transfer_id.empty() ? nullptr : rats_strdup_owned(transfer_id);
+    (void)handle; (void)peer_id; (void)remote_directory_path; (void)local_directory_path; (void)recursive;
+    return nullptr;
 }
 
 rats_error_t rats_accept_directory_transfer(rats_client_t handle, const char* transfer_id, const char* local_path) {
     if (!handle || !transfer_id || !local_path) return RATS_ERROR_INVALID_PARAMETER;
     rats_client_wrapper* wrap = static_cast<rats_client_wrapper*>(handle);
-    
-    return wrap->client->accept_directory_transfer(std::string(transfer_id), std::string(local_path)) ? RATS_SUCCESS : RATS_ERROR_OPERATION_FAILED;
+
+    return wrap->client->accept_file_transfer(std::string(transfer_id), std::string(local_path)) ? RATS_SUCCESS : RATS_ERROR_OPERATION_FAILED;
 }
 
 rats_error_t rats_reject_directory_transfer(rats_client_t handle, const char* transfer_id, const char* reason) {
     if (!handle || !transfer_id) return RATS_ERROR_INVALID_PARAMETER;
     rats_client_wrapper* wrap = static_cast<rats_client_wrapper*>(handle);
-    
+
     std::string reject_reason = reason ? std::string(reason) : std::string("");
-    return wrap->client->reject_directory_transfer(std::string(transfer_id), reject_reason) ? RATS_SUCCESS : RATS_ERROR_OPERATION_FAILED;
+    return wrap->client->reject_file_transfer(std::string(transfer_id), reject_reason) ? RATS_SUCCESS : RATS_ERROR_OPERATION_FAILED;
 }
 
 rats_error_t rats_pause_file_transfer(rats_client_t handle, const char* transfer_id) {
@@ -768,44 +762,33 @@ void rats_set_file_request_callback(rats_client_t handle, rats_file_request_cb c
     wrap->file_request_ud = user_data;
     
     if (cb) {
-        wrap->client->on_file_request([wrap](const std::string& peer_id, const std::string& file_path, const std::string& transfer_id) {
+        // Fires for every incoming offer (file or directory). The C app should
+        // then call rats_accept_file_transfer()/rats_reject_file_transfer().
+        wrap->client->on_file_transfer_request([wrap](const IncomingTransferOffer& offer) {
             if (wrap->file_request_cb) {
-                wrap->file_request_cb(wrap->file_request_ud, peer_id.c_str(), transfer_id.c_str(), file_path.c_str(), "");
+                wrap->file_request_cb(wrap->file_request_ud, offer.peer_id.c_str(),
+                                      offer.transfer_id.c_str(), "", offer.name.c_str());
             }
-            return true; // Accept the file request
         });
     }
 }
 
+// Directory offers arrive through the unified file-request callback above;
+// this setter is kept for ABI compatibility and simply records the callback.
 void rats_set_directory_request_callback(rats_client_t handle, rats_directory_request_cb cb, void* user_data) {
     if (!handle) return;
     rats_client_wrapper* wrap = static_cast<rats_client_wrapper*>(handle);
     wrap->directory_request_cb = cb;
     wrap->directory_request_ud = user_data;
-    
-    if (cb) {
-        wrap->client->on_directory_request([wrap](const std::string& peer_id, const std::string& directory_path, bool recursive, const std::string& transfer_id) {
-            if (wrap->directory_request_cb) {
-                wrap->directory_request_cb(wrap->directory_request_ud, peer_id.c_str(), transfer_id.c_str(), directory_path.c_str(), "");
-            }
-            return true; // Accept the directory request
-        });
-    }
 }
 
+// Directory progress arrives through the unified file-progress callback above;
+// this setter is kept for ABI compatibility and simply records the callback.
 void rats_set_directory_progress_callback(rats_client_t handle, rats_directory_progress_cb cb, void* user_data) {
     if (!handle) return;
     rats_client_wrapper* wrap = static_cast<rats_client_wrapper*>(handle);
     wrap->directory_progress_cb = cb;
     wrap->directory_progress_ud = user_data;
-    
-    if (cb) {
-        wrap->client->on_directory_transfer_progress([wrap](const std::string& transfer_id, const std::string& current_file, uint64_t files_completed, uint64_t total_files, uint64_t bytes_completed, uint64_t total_bytes) {
-            if (wrap->directory_progress_cb) {
-                wrap->directory_progress_cb(wrap->directory_progress_ud, transfer_id.c_str(), static_cast<int>(files_completed), static_cast<int>(total_files), current_file.c_str());
-            }
-        });
-    }
 }
 
 // Peer information

package/native-src/src/librats_discovery.cpp

@@ -13,94 +13,124 @@ bool RatsClient::start_dht_discovery(int dht_port) {
         LOG_CLIENT_WARN("DHT discovery is already running");
         return true;
     }
-    
+
     LOG_CLIENT_INFO("Starting DHT discovery on port " << dht_port <<
                    (bind_address_.empty() ? "" : " bound to " + bind_address_));
-    
-    dht_client_ = std::make_unique<DhtClient>(dht_port, bind_address_, data_directory_);
+
+    auto bootstrap_nodes = DhtClient::get_default_bootstrap_nodes();
+
+    // IPv4 DHT (also shared with the BitTorrent subsystem) - required.
+    dht_client_ = std::make_unique<DhtClient>(dht_port, bind_address_, data_directory_, AddressFamily::IPv4);
     if (!dht_client_->start()) {
-        LOG_CLIENT_ERROR("Failed to start DHT client");
+        LOG_CLIENT_ERROR("Failed to start IPv4 DHT client");
         dht_client_.reset();
         return false;
     }
-    
-    // Bootstrap with default nodes
-    auto bootstrap_nodes = DhtClient::get_default_bootstrap_nodes();
     if (!dht_client_->bootstrap(bootstrap_nodes)) {
-        LOG_CLIENT_WARN("Failed to bootstrap DHT");
+        LOG_CLIENT_WARN("Failed to bootstrap IPv4 DHT");
     }
-    
-    // Start automatic peer discovery
+
+    // IPv6 DHT - best effort. Shares the same port via a V6ONLY socket. If the host has
+    // no usable IPv6 stack, socket creation fails and we simply run IPv4-only.
+    dht_client_v6_ = std::make_unique<DhtClient>(dht_port, bind_address_, data_directory_, AddressFamily::IPv6);
+    if (dht_client_v6_->start()) {
+        if (!dht_client_v6_->bootstrap(bootstrap_nodes)) {
+            LOG_CLIENT_WARN("Failed to bootstrap IPv6 DHT");
+        }
+        LOG_CLIENT_INFO("IPv6 DHT client started");
+    } else {
+        LOG_CLIENT_INFO("IPv6 DHT unavailable on this host, running IPv4-only");
+        dht_client_v6_.reset();
+    }
+
+    // Start automatic peer discovery (this thread also performs the best-effort STUN probe
+    // that derives our BEP 42 node ID — see automatic_discovery_loop).
     start_automatic_peer_discovery();
-    
+
     LOG_CLIENT_INFO("DHT discovery started successfully");
     return true;
 }
 
 void RatsClient::stop_dht_discovery() {
-    if (!dht_client_) {
+    if (!dht_client_ && !dht_client_v6_) {
         return;
     }
-    
+
     LOG_CLIENT_INFO("Stopping DHT discovery");
-    
+
     // Stop automatic peer discovery
     stop_automatic_peer_discovery();
-    
-    dht_client_->stop();
-    dht_client_.reset();
+
+    if (dht_client_) {
+        dht_client_->stop();
+        dht_client_.reset();
+    }
+    if (dht_client_v6_) {
+        dht_client_v6_->stop();
+        dht_client_v6_.reset();
+    }
     LOG_CLIENT_INFO("DHT discovery stopped");
 }
 
 bool RatsClient::find_peers_by_hash(const std::string& content_hash, std::function<void(const std::vector<std::string>&)> callback) {
-    if (!dht_client_ || !dht_client_->is_running()) {
+    if (!is_dht_running()) {
         LOG_CLIENT_ERROR("DHT client not running");
         return false;
     }
-    
+
     if (content_hash.length() != CONTENT_HASH_HEX_LENGTH) {
         LOG_CLIENT_ERROR("Invalid content hash length: " << content_hash.length() << " (expected " << CONTENT_HASH_HEX_LENGTH << ")");
         return false;
     }
-    
+
     LOG_CLIENT_INFO("Finding peers for content hash: " << content_hash);
-    
+
     InfoHash info_hash = hex_to_node_id(content_hash);
-    
-    return dht_client_->find_peers(info_hash, [this, callback](const std::vector<Peer>& peers, const InfoHash& info_hash) {
-        // Convert Peer to string addresses for callback
+
+    // Shared wrapper: discovered peers (IPv4 or IPv6) are delivered through the same callback.
+    PeerDiscoveryCallback peer_callback = [callback](const std::vector<Peer>& peers, const InfoHash&) {
         std::vector<std::string> peer_addresses;
+        peer_addresses.reserve(peers.size());
         for (const auto& peer : peers) {
             peer_addresses.emplace_back(peer.ip + ":" + std::to_string(peer.port));
         }
-        
         if (callback) {
             callback(peer_addresses);
         }
-    });
+    };
+
+    // Fan out to both Kademlia networks; succeed if at least one accepts the search.
+    bool started = false;
+    if (dht_client_ && dht_client_->is_running()) {
+        started |= dht_client_->find_peers(info_hash, peer_callback);
+    }
+    if (dht_client_v6_ && dht_client_v6_->is_running()) {
+        started |= dht_client_v6_->find_peers(info_hash, peer_callback);
+    }
+    return started;
 }
 
 bool RatsClient::announce_for_hash(const std::string& content_hash, uint16_t port,
                                    std::function<void(const std::vector<std::string>&)> callback) {
-    if (!dht_client_ || !dht_client_->is_running()) {
+    if (!is_dht_running()) {
         LOG_CLIENT_ERROR("DHT client not running");
         return false;
     }
-    
+
     if (content_hash.length() != CONTENT_HASH_HEX_LENGTH) {
         LOG_CLIENT_ERROR("Invalid content hash length: " << content_hash.length() << " (expected " << CONTENT_HASH_HEX_LENGTH << ")");
         return false;
     }
-    
+
     if (port == 0) {
         port = listen_port_;
     }
-    
+
     LOG_CLIENT_INFO("Announcing for content hash: " << content_hash << " on port " << port
                    << (callback ? " with peer callback" : ""));
-    
+
     InfoHash info_hash = hex_to_node_id(content_hash);
-    
+
     // Create wrapper callback that converts Peer to string addresses (if callback provided)
     PeerDiscoveryCallback peer_callback = nullptr;
     if (callback) {
@@ -113,19 +143,32 @@ bool RatsClient::announce_for_hash(const std::string& content_hash, uint16_t por
             callback(peer_addresses);
         };
     }
-    
-    return dht_client_->announce_peer(info_hash, port, peer_callback);
+
+    // Announce on both Kademlia networks so IPv4 and IPv6 peers can both find us.
+    bool started = false;
+    if (dht_client_ && dht_client_->is_running()) {
+        started |= dht_client_->announce_peer(info_hash, port, peer_callback);
+    }
+    if (dht_client_v6_ && dht_client_v6_->is_running()) {
+        started |= dht_client_v6_->announce_peer(info_hash, port, peer_callback);
+    }
+    return started;
 }
 
 bool RatsClient::is_dht_running() const {
-    return dht_client_ && dht_client_->is_running();
+    return (dht_client_ && dht_client_->is_running()) ||
+           (dht_client_v6_ && dht_client_v6_->is_running());
 }
 
 size_t RatsClient::get_dht_routing_table_size() const {
-    if (!dht_client_) {
-        return 0;
+    size_t total = 0;
+    if (dht_client_) {
+        total += dht_client_->get_routing_table_size();
+    }
+    if (dht_client_v6_) {
+        total += dht_client_v6_->get_routing_table_size();
     }
-    return dht_client_->get_routing_table_size();
+    return total;
 }
 
 void RatsClient::handle_dht_peer_discovery(const std::vector<Peer>& peers, const InfoHash& info_hash) {
@@ -219,6 +262,27 @@ void RatsClient::automatic_discovery_loop() {
         }
     }
 
+    // Best-effort: discover our public IP via STUN and derive a BEP 42 node ID from it before
+    // we announce, so we announce under the correct ID. This runs on the discovery thread (not
+    // a standalone one) on purpose: stop_dht_discovery() joins this thread via
+    // stop_automatic_peer_discovery() BEFORE resetting the DHT clients, so set_external_ip()
+    // can never touch a destroyed DhtClient. It complements the in-DHT "ip"-field voting, which
+    // keeps the node ID correct if the address changes or STUN is unavailable.
+    if (auto_discovery_running_.load() && running_.load()) {
+        auto mapped = discover_public_address("stun.l.google.com", 19302, 4000);
+        if (mapped) {
+            // set_external_ip validates the address family, so feeding both instances is safe:
+            // only the matching-family DHT adopts it. (A default IPv4 STUN server yields an IPv4
+            // address; the IPv6 node ID is learned organically from IPv6 DHT responses.)
+            if (dht_client_) {
+                dht_client_->set_external_ip(mapped->address);
+            }
+            if (dht_client_v6_) {
+                dht_client_v6_->set_external_ip(mapped->address);
+            }
+        }
+    }
+
     // Announce immediately - this also discovers peers during traversal
     announce_rats_peer();
 
@@ -261,7 +325,11 @@ void RatsClient::announce_rats_peer() {
     
     InfoHash info_hash = hex_to_node_id(discovery_hash);
 
-    if (dht_client_->is_announce_active(info_hash)) {
+    // Skip only if every running DHT network already has this announce in flight.
+    // (announce_peer() also dedups internally, so this is just to avoid redundant work.)
+    bool v4_busy = !dht_client_ || !dht_client_->is_running() || dht_client_->is_announce_active(info_hash);
+    bool v6_busy = !dht_client_v6_ || !dht_client_v6_->is_running() || dht_client_v6_->is_announce_active(info_hash);
+    if (v4_busy && v6_busy) {
         LOG_CLIENT_WARN("Announce already in progress for info hash: " << node_id_to_hex(info_hash));
         return;
     }