librats 0.5.4 → 0.6.0

package/lib/index.d.ts

@@ -2,7 +2,7 @@
  * LibRats Node.js Bindings - TypeScript Definitions
  * 
  * High-performance peer-to-peer networking library with support for DHT, GossipSub,
- * file transfer, NAT traversal, and more.
+ * file transfer, and more.
  */
 
 /**
@@ -15,22 +15,6 @@ export interface VersionInfo {
   build: number;
 }
 
-/**
- * Connection strategy options for connecting to peers
- */
-export enum ConnectionStrategy {
-  /** Direct connection only, no NAT traversal */
-  DIRECT_ONLY = 0,
-  /** STUN-assisted connection */
-  STUN_ASSISTED = 1,
-  /** Full ICE negotiation with STUN and connection checks */
-  ICE_FULL = 2,
-  /** TURN relay connection */
-  TURN_RELAY = 3,
-  /** Automatic strategy selection based on network conditions */
-  AUTO_ADAPTIVE = 4
-}
-
 /**
  * Error codes returned by various operations
  */
@@ -53,6 +37,39 @@ export enum ErrorCodes {
   JSON_PARSE = -7
 }
 
+/**
+ * ICE connection states
+ */
+export enum IceConnectionState {
+  NEW = 0,
+  GATHERING = 1,
+  CHECKING = 2,
+  CONNECTED = 3,
+  COMPLETED = 4,
+  FAILED = 5,
+  DISCONNECTED = 6,
+  CLOSED = 7
+}
+
+/**
+ * ICE gathering states
+ */
+export enum IceGatheringState {
+  NEW = 0,
+  GATHERING = 1,
+  COMPLETE = 2
+}
+
+/**
+ * ICE candidate types
+ */
+export enum IceCandidateType {
+  HOST = 0,
+  SRFLX = 1,
+  PRFLX = 2,
+  RELAY = 3
+}
+
 /**
  * Main RatsClient class for peer-to-peer networking
  */
@@ -84,15 +101,6 @@ export class RatsClient {
    */
   connect(host: string, port: number): boolean;
 
-  /**
-   * Connect to a peer with a specific connection strategy
-   * @param host - IP address or hostname of the peer
-   * @param port - Port number of the peer
-   * @param strategy - Connection strategy to use
-   * @returns true if connection initiated successfully
-   */
-  connectWithStrategy(host: string, port: number, strategy: ConnectionStrategy): boolean;
-
   /**
    * Disconnect from a peer
    * @param peerId - ID of the peer to disconnect from
@@ -101,6 +109,12 @@ export class RatsClient {
 
   // ============ Information ============
 
+  /**
+   * Get the port the client is listening on
+   * @returns Listen port number
+   */
+  getListenPort(): number;
+
   /**
    * Get the number of connected peers
    * @returns Number of connected peers
@@ -276,6 +290,13 @@ export class RatsClient {
    */
   resumeFileTransfer(transferId: string): boolean;
 
+  /**
+   * Get file transfer progress information as JSON string
+   * @param transferId - ID of the transfer to query
+   * @returns JSON string with progress info, or null if not found
+   */
+  getFileTransferProgress(transferId: string): string | null;
+
   // ============ GossipSub ============
 
   /**
@@ -340,6 +361,12 @@ export class RatsClient {
    */
   getTopicPeers(topic: string): string[];
 
+  /**
+   * Get GossipSub statistics as JSON string
+   * @returns JSON string with statistics, or null if unavailable
+   */
+  getGossipsubStatistics(): string | null;
+
   // ============ DHT ============
 
   /**
@@ -395,6 +422,20 @@ export class RatsClient {
    */
   isMdnsRunning(): boolean;
 
+  /**
+   * Query for mDNS services
+   * @returns true if query sent successfully
+   */
+  queryMdnsServices(): boolean;
+
+  // ============ Address Blocking ============
+
+  /**
+   * Add an IP address to the ignore list
+   * @param ipAddress - IP address to ignore
+   */
+  addIgnoredAddress(ipAddress: string): void;
+
   // ============ Encryption ============
 
   /**
@@ -411,23 +452,157 @@ export class RatsClient {
   isEncryptionEnabled(): boolean;
 
   /**
-   * Generate a new encryption key
-   * @returns Hex-encoded encryption key, or null if failed
+   * Initialize encryption system
+   * @param enable - Whether to enable encryption
+   * @returns true if initialized successfully
    */
-  generateEncryptionKey(): string | null;
+  initializeEncryption(enable: boolean): boolean;
 
   /**
-   * Set the encryption key
-   * @param keyHex - Hex-encoded encryption key
+   * Check if a specific peer connection is encrypted
+   * @param peerId - Peer ID to check
+   * @returns true if peer connection is encrypted
+   */
+  isPeerEncrypted(peerId: string): boolean;
+
+  /**
+   * Set custom Noise Protocol static keypair
+   * @param privateKeyHex - 32-byte private key as 64-char hex string
    * @returns true if set successfully
    */
-  setEncryptionKey(keyHex: string): boolean;
+  setNoiseStaticKeypair(privateKeyHex: string): boolean;
+
+  /**
+   * Get our Noise Protocol static public key
+   * @returns 64-char hex string, or null if not available
+   */
+  getNoiseStaticPublicKey(): string | null;
+
+  /**
+   * Get remote peer's Noise static public key
+   * @param peerId - Peer ID to query
+   * @returns 64-char hex string, or null if not available
+   */
+  getPeerNoisePublicKey(peerId: string): string | null;
+
+  /**
+   * Get handshake hash for channel binding
+   * @param peerId - Peer ID to query
+   * @returns 64-char hex string, or null if not available
+   */
+  getPeerHandshakeHash(peerId: string): string | null;
+
+  // ============ ICE (NAT Traversal) ============
+
+  /**
+   * Check if ICE is available
+   * @returns true if ICE is available
+   */
+  isIceAvailable(): boolean;
+
+  /**
+   * Add a STUN server for NAT traversal
+   * @param host - STUN server hostname or IP
+   * @param port - STUN server port (default: 3478)
+   */
+  addStunServer(host: string, port?: number): void;
+
+  /**
+   * Add a TURN server for relay-based NAT traversal
+   * @param host - TURN server hostname or IP
+   * @param port - TURN server port
+   * @param username - TURN username
+   * @param password - TURN password
+   */
+  addTurnServer(host: string, port: number, username: string, password: string): void;
+
+  /**
+   * Clear all ICE (STUN/TURN) servers
+   */
+  clearIceServers(): void;
+
+  /**
+   * Start gathering ICE candidates
+   * @returns true if gathering started successfully
+   */
+  gatherIceCandidates(): boolean;
+
+  /**
+   * Get local ICE candidates as JSON string
+   * @returns JSON string of candidates, or null if unavailable
+   */
+  getIceCandidates(): string | null;
+
+  /**
+   * Check if ICE candidate gathering is complete
+   * @returns true if gathering is complete
+   */
+  isIceGatheringComplete(): boolean;
+
+  /**
+   * Get public address discovered via STUN
+   * @returns Address string (ip:port), or null if not discovered
+   */
+  getPublicAddress(): string | null;
+
+  /**
+   * Perform a simple STUN binding request to discover public address
+   * @param stunServer - STUN server hostname (default: "stun.l.google.com")
+   * @param port - STUN server port (default: 19302)
+   * @param timeoutMs - Timeout in milliseconds (default: 5000)
+   * @returns Address string (ip:port), or null on failure
+   */
+  discoverPublicAddress(stunServer?: string, port?: number, timeoutMs?: number): string | null;
+
+  /**
+   * Add a remote ICE candidate from SDP
+   * @param candidateSdp - SDP candidate string
+   */
+  addRemoteIceCandidate(candidateSdp: string): void;
+
+  /**
+   * Signal end of remote ICE candidates (trickle ICE complete)
+   */
+  endOfRemoteIceCandidates(): void;
+
+  /**
+   * Start ICE connectivity checks
+   */
+  startIceChecks(): void;
+
+  /**
+   * Get current ICE connection state
+   * @returns ICE connection state value
+   */
+  getIceConnectionState(): number;
+
+  /**
+   * Get ICE gathering state
+   * @returns ICE gathering state value
+   */
+  getIceGatheringState(): number;
+
+  /**
+   * Check if ICE is connected
+   * @returns true if ICE connection is established
+   */
+  isIceConnected(): boolean;
+
+  /**
+   * Get the selected ICE candidate pair as JSON string
+   * @returns JSON string of selected pair, or null if unavailable
+   */
+  getIceSelectedPair(): string | null;
+
+  /**
+   * Close ICE manager and release resources
+   */
+  closeIce(): void;
 
   /**
-   * Get the current encryption key
-   * @returns Hex-encoded encryption key, or null if not set
+   * Restart ICE (re-gather candidates and restart checks)
    */
-  getEncryptionKey(): string | null;
+  restartIce(): void;
 
   // ============ Configuration Persistence ============
 

package/native-src/CMakeLists.txt

@@ -82,6 +82,7 @@ option(RATS_CROSSCOMPILING "Force cross-compilation flags" OFF)
 option(RATS_SHARED_LIBRARY "Build as shared library" OFF)
 option(RATS_STATIC_LIBRARY "Build as static library" ON)
 option(RATS_SEARCH_FEATURES "Features related to rats-search project (like bittorrent)" OFF)
+option(RATS_STORAGE "Enable distributed storage module" OFF)
 
 # Validate library type options
 if(RATS_SHARED_LIBRARY AND RATS_STATIC_LIBRARY)
@@ -128,30 +129,20 @@ set(LIBRARY_SOURCES
     src/krpc.h
     src/librats.cpp
     src/librats_logging.cpp
+    src/librats_encryption.cpp
     src/librats_file_transfer.cpp
     src/librats_gossipsub.cpp
-    src/librats_nat.cpp
-    src/librats_ice.cpp
     src/librats_mdns.cpp
     src/librats_persistence.cpp
-    src/librats_encryption.cpp
     src/librats.h
     src/sha1.cpp
     src/sha1.h
     src/os.cpp
     src/os.h
-    src/stun.cpp
-    src/stun.h
-    src/ice.cpp
-    src/ice.h
     src/fs.cpp
     src/fs.h
     src/logger.h
     src/logger.cpp
-    src/noise.cpp
-    src/noise.h
-    src/encrypted_socket.cpp
-    src/encrypted_socket.h
     src/mdns.cpp
     src/mdns.h
     src/threadmanager.cpp
@@ -163,6 +154,40 @@ set(LIBRARY_SOURCES
     src/version.cpp
     src/rats_export.h
     ${PROJECT_BINARY_DIR}/src/version.h
+
+# Cypto algorithms including Noise Protocol needed
+    src/crypto/curve25519.c
+    src/crypto/curve25519.h
+    src/crypto/chacha.c
+    src/crypto/chacha.h
+    src/crypto/poly1305.c
+    src/crypto/poly1305.h
+    src/crypto/chachapoly.c
+    src/crypto/chachapoly.h
+    src/crypto/sha256.c
+    src/crypto/sha256.h
+    src/crypto/sha512.c
+    src/crypto/sha512.h
+    src/crypto/hkdf.c
+    src/crypto/hkdf.h
+    src/crypto/blake2s.c
+    src/crypto/blake2s.h
+    src/crypto/blake2b.c
+    src/crypto/blake2b.h
+    src/crypto/blake2_endian.h
+
+# Noise Protocol implementation
+    src/noise.cpp
+    src/noise.h
+
+# NAT traversal (STUN/TURN/ICE)
+    src/stun.cpp
+    src/stun.h
+    src/turn.cpp
+    src/turn.h
+    src/ice.cpp
+    src/ice.h
+    src/librats_ice.cpp
 )
 
 # Add BitTorrent sources if RATS_SEARCH_FEATURES is enabled
@@ -176,6 +201,17 @@ if(RATS_SEARCH_FEATURES)
     )
 endif()
 
+# Add Storage sources if RATS_STORAGE is enabled
+if(RATS_STORAGE)
+    list(APPEND LIBRARY_SOURCES
+        src/crc32.cpp
+        src/crc32.h
+        src/storage.cpp
+        src/storage.h
+        src/librats_storage.cpp
+    )
+endif()
+
 if(RATS_BINDINGS)
     list(APPEND LIBRARY_SOURCES 
         src/librats_c.cpp
@@ -200,6 +236,7 @@ set_target_properties(rats PROPERTIES POSITION_INDEPENDENT_CODE ON)
 
 # Include directories
 target_include_directories(rats PUBLIC ${PROJECT_BINARY_DIR}/src src)
+target_include_directories(rats PUBLIC ${PROJECT_SOURCE_DIR}/src/crypto)
 
 # Find and link threading support
 find_package(Threads REQUIRED)
@@ -235,6 +272,11 @@ if(RATS_SEARCH_FEATURES)
     target_compile_definitions(rats PUBLIC RATS_SEARCH_FEATURES)
 endif(RATS_SEARCH_FEATURES)
 
+if(RATS_STORAGE)
+    message(STATUS "Enable distributed storage module")
+    target_compile_definitions(rats PUBLIC RATS_STORAGE)
+endif(RATS_STORAGE)
+
 # Create the main executable
 if(RATS_BUILD_EXAMPLES)
     add_executable(rats-client src/main.cpp)
@@ -311,16 +353,23 @@ if(RATS_BUILD_TESTS)
         tests/test_dht.cpp
         tests/test_rats_client.cpp
         tests/test_os.cpp
-        tests/test_stun.cpp
-        tests/test_ice.cpp
         tests/test_fs.cpp
         tests/test_config_persistence.cpp
         tests/test_main.cpp
         tests/test_message_exchange.cpp
-        tests/test_noise.cpp
         tests/test_gossipsub.cpp
         tests/test_logging_api_gtest.cpp
         tests/test_file_transfer.cpp
+# Noise Protocol Crypto tests
+        tests/test_crypto_curve25519.cpp
+        tests/test_crypto_chacha_poly.cpp
+        tests/test_crypto_sha2.cpp
+        tests/test_crypto_blake2.cpp
+        tests/test_noise.cpp
+# NAT traversal tests (STUN/TURN/ICE)
+        tests/test_stun.cpp
+        tests/test_turn.cpp
+        tests/test_ice.cpp
     )
     
     # Add BitTorrent tests if RATS_SEARCH_FEATURES is enabled
@@ -331,6 +380,14 @@ if(RATS_BUILD_TESTS)
         )
     endif()
 
+    # Add Storage tests if RATS_STORAGE is enabled
+    if(RATS_STORAGE)
+        list(APPEND TEST_SOURCES 
+            tests/test_crc32.cpp
+            tests/test_storage.cpp
+        )
+    endif()
+
     if(RATS_BINDINGS)
         list(APPEND TEST_SOURCES 
             tests/test_librats_c_api.cpp

package/native-src/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 librats contributors
+Copyright (c) 2026 librats contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/native-src/src/bittorrent.cpp

@@ -487,12 +487,15 @@ void PeerConnection::connection_loop() {
     // Create socket if not already provided (outgoing connection)
     // This is done in the thread to avoid blocking the caller
     if (!is_valid_socket(socket_)) {
+        LOG_BT_DEBUG("Creating TCP connection to " << peer_info_.ip << ":" << peer_info_.port << " (5s timeout)");
         socket_ = create_tcp_client(peer_info_.ip, peer_info_.port, 5000); // 5-second timeout for faster failure
         if (!is_valid_socket(socket_)) {
-            LOG_BT_ERROR("Failed to create connection to " << peer_info_.ip << ":" << peer_info_.port);
+            LOG_BT_ERROR("Failed to create connection to " << peer_info_.ip << ":" << peer_info_.port 
+                        << " - connection timed out or refused");
             state_.store(PeerState::ERROR);
             return;
         }
+        LOG_BT_DEBUG("TCP connection established to " << peer_info_.ip << ":" << peer_info_.port);
     }
     
     // Perform handshake only if not already completed (for outgoing connections)
@@ -3566,6 +3569,155 @@ void BitTorrentClient::get_torrent_metadata_by_hash(const std::string& info_hash
     get_torrent_metadata_by_hash(info_hash, callback);
 }
 
+void BitTorrentClient::get_torrent_metadata_from_peer(const InfoHash& info_hash, 
+                                                       const std::string& peer_ip, 
+                                                       uint16_t peer_port,
+                                                       MetadataRetrievalCallback callback) {
+    if (!running_.load()) {
+        LOG_BT_ERROR("BitTorrent client is not running");
+        if (callback) {
+            callback(TorrentInfo(), false, "BitTorrent client is not running");
+        }
+        return;
+    }
+    
+    LOG_BT_INFO("Retrieving metadata for hash " << info_hash_to_hex(info_hash) 
+               << " directly from peer " << peer_ip << ":" << peer_port);
+    
+    // Check if metadata retrieval already in progress for this hash
+    {
+        std::lock_guard<std::mutex> lock(metadata_mutex_);
+        if (metadata_only_torrents_.find(info_hash) != metadata_only_torrents_.end()) {
+            LOG_BT_DEBUG("Metadata retrieval already in progress for hash: " << info_hash_to_hex(info_hash));
+            // Just add this peer to the existing download attempt
+            auto it = metadata_only_torrents_.find(info_hash);
+            if (it != metadata_only_torrents_.end()) {
+                Peer peer{peer_ip, peer_port};
+                it->second->add_peer(peer);
+                LOG_BT_INFO("Added peer " << peer_ip << ":" << peer_port << " to existing metadata download");
+            }
+            return;
+        }
+        
+        // Store the callback
+        metadata_retrieval_callbacks_[info_hash] = callback;
+    }
+    
+    // Create a minimal TorrentInfo for metadata exchange
+    TorrentInfo metadata_torrent_info = TorrentInfo::create_for_metadata_exchange(info_hash);
+    
+    // Create a temporary torrent download for metadata exchange only
+    auto metadata_torrent = std::make_shared<TorrentDownload>(metadata_torrent_info, ""); // No download path needed
+    
+    // Set up metadata completion callback
+    // IMPORTANT: This callback is invoked from within a PeerConnection's thread, so we must NOT
+    // call stop() directly (which would try to join the calling thread, causing a deadlock).
+    // Instead, we defer the cleanup to a detached thread.
+    metadata_torrent->set_metadata_complete_callback([this, info_hash](const TorrentInfo& torrent_info) {
+        LOG_BT_INFO("Metadata retrieval (direct) completed for " << torrent_info.get_name());
+        
+        // Capture torrent_info by value since we're deferring to another thread
+        TorrentInfo captured_info = torrent_info;
+        
+        // Defer stop() and cleanup to a separate thread to avoid deadlock
+        std::thread([this, info_hash, captured_info]() {
+            MetadataRetrievalCallback user_callback;
+            std::shared_ptr<TorrentDownload> temp_torrent;
+            
+            // Get callback and cleanup
+            {
+                std::lock_guard<std::mutex> lock(metadata_mutex_);
+                auto it = metadata_retrieval_callbacks_.find(info_hash);
+                if (it != metadata_retrieval_callbacks_.end()) {
+                    user_callback = it->second;
+                    metadata_retrieval_callbacks_.erase(it);
+                }
+                
+                // Get temporary torrent to stop it
+                auto torrent_it = metadata_only_torrents_.find(info_hash);
+                if (torrent_it != metadata_only_torrents_.end()) {
+                    temp_torrent = torrent_it->second;
+                    metadata_only_torrents_.erase(torrent_it);
+                }
+            }
+            
+            // Stop the temporary torrent
+            if (temp_torrent) {
+                temp_torrent->stop();
+            }
+            
+            // Call user callback with success
+            if (user_callback) {
+                user_callback(captured_info, true, "");
+            }
+        }).detach();
+    });
+    
+    // Store the temporary torrent
+    {
+        std::lock_guard<std::mutex> lock(metadata_mutex_);
+        metadata_only_torrents_[info_hash] = metadata_torrent;
+    }
+    
+    // Start the metadata torrent (just for peer connections)
+    if (!metadata_torrent->start()) {
+        LOG_BT_ERROR("Failed to start metadata retrieval torrent");
+        
+        // Cleanup and call callback with error
+        {
+            std::lock_guard<std::mutex> lock(metadata_mutex_);
+            metadata_only_torrents_.erase(info_hash);
+            auto it = metadata_retrieval_callbacks_.find(info_hash);
+            if (it != metadata_retrieval_callbacks_.end()) {
+                if (it->second) {
+                    it->second(TorrentInfo(), false, "Failed to start metadata retrieval");
+                }
+                metadata_retrieval_callbacks_.erase(it);
+            }
+        }
+        return;
+    }
+    
+    // Directly connect to the specified peer - no DHT search needed!
+    Peer peer{peer_ip, peer_port};
+    LOG_BT_INFO("Connecting directly to peer " << peer_ip << ":" << peer_port << " for metadata exchange");
+    
+    if (metadata_torrent->add_peer(peer)) {
+        LOG_BT_INFO("Successfully initiated connection to peer " << peer_ip << ":" << peer_port);
+    } else {
+        LOG_BT_WARN("Failed to add peer " << peer_ip << ":" << peer_port << " - metadata retrieval may fail");
+        // Don't fail immediately - the peer connection might still work
+    }
+    
+    LOG_BT_INFO("Metadata retrieval (direct) initiated for hash " << info_hash_to_hex(info_hash));
+}
+
+void BitTorrentClient::get_torrent_metadata_from_peer(const std::string& info_hash_hex,
+                                                       const std::string& peer_ip,
+                                                       uint16_t peer_port,
+                                                       MetadataRetrievalCallback callback) {
+    InfoHash info_hash = hex_to_info_hash(info_hash_hex);
+    
+    // Validate the parsed hash
+    bool is_zero = true;
+    for (const auto& byte : info_hash) {
+        if (byte != 0) {
+            is_zero = false;
+            break;
+        }
+    }
+    
+    if (is_zero && info_hash_hex.length() == 40) {
+        LOG_BT_ERROR("Invalid info hash format: " << info_hash_hex);
+        if (callback) {
+            callback(TorrentInfo(), false, "Invalid info hash format");
+        }
+        return;
+    }
+    
+    get_torrent_metadata_from_peer(info_hash, peer_ip, peer_port, callback);
+}
+
 //=============================================================================
 // Utility Functions Implementation
 //=============================================================================

package/native-src/src/bittorrent.h

@@ -679,6 +679,31 @@ public:
     void get_torrent_metadata_by_hash(const InfoHash& info_hash, MetadataRetrievalCallback callback);
     void get_torrent_metadata_by_hash(const std::string& info_hash_hex, MetadataRetrievalCallback callback);
     
+    /**
+     * Get torrent metadata directly from a specific peer (fast path - no DHT search needed)
+     * This is more efficient when you already know a peer that has the torrent (e.g., from announce_peer)
+     * @param info_hash Info hash of the torrent
+     * @param peer_ip IP address of the peer
+     * @param peer_port Port of the peer
+     * @param callback Function called when metadata is retrieved (torrent_info, success, error_message)
+     */
+    void get_torrent_metadata_from_peer(const InfoHash& info_hash, 
+                                        const std::string& peer_ip, 
+                                        uint16_t peer_port,
+                                        MetadataRetrievalCallback callback);
+    
+    /**
+     * Get torrent metadata directly from a specific peer by hex string (fast path)
+     * @param info_hash_hex Info hash as 40-character hex string
+     * @param peer_ip IP address of the peer
+     * @param peer_port Port of the peer
+     * @param callback Function called when metadata is retrieved (torrent_info, success, error_message)
+     */
+    void get_torrent_metadata_from_peer(const std::string& info_hash_hex,
+                                        const std::string& peer_ip,
+                                        uint16_t peer_port,
+                                        MetadataRetrievalCallback callback);
+    
 private:
     std::atomic<bool> running_;
     int listen_port_;