librats.h

Go to the documentation of this file.

#pragma once
 
#include "socket.h"
#include "dht.h"
#include "mdns.h"
#include "logger.h"
#include "threadmanager.h"
#include "gossipsub.h" // For ValidationResult enum and GossipSub types
#include "file_transfer.h" // File transfer functionality
#include "noise.h" // Noise Protocol encryption
#include "ice.h"   // ICE-lite NAT traversal
#ifdef RATS_STORAGE
#include "storage.h" // Distributed storage functionality
#endif
#ifdef RATS_SEARCH_FEATURES
#include "bittorrent.h" // BitTorrent functionality (optional, requires RATS_SEARCH_FEATURES)
#endif
#include "json.hpp" // nlohmann::json
#include <string>
#include <functional>
#include <thread>
#include <vector>
#include <mutex>
#include <atomic>
#include <unordered_map>
#include <memory>
#include <chrono>
#include <condition_variable>
#include <unordered_set> // Added for unordered_set
#include <cstdint>
#include <cstring>
#include "rats_export.h"
 
namespace librats {
 
struct RatsPeer {
    std::string peer_id;                    // Unique hash ID for the peer
    std::string ip;                         // IP address
    uint16_t port;                          // Port number  
    socket_t socket;                        // Socket handle
    std::string normalized_address;         // Normalized address for duplicate detection (ip:port)
    std::chrono::steady_clock::time_point connected_at; // Connection timestamp
    bool is_outgoing;                       // True if we initiated the connection, false if incoming
    
    // Handshake-related fields
    enum class HandshakeState {
        PENDING,        // Handshake not started
        SENT,           // Handshake sent, waiting for response
        NOISE_PENDING,  // Rats handshake done, Noise handshake in progress
        COMPLETED,      // Handshake completed successfully (including Noise if enabled)
        FAILED          // Handshake failed
    };
    
    HandshakeState handshake_state;         // Current handshake state
    std::string version;                    // Protocol version of remote peer
    std::chrono::steady_clock::time_point handshake_start_time; // When handshake started
    
    // Encryption-related fields
    bool encryption_enabled;                // Whether encryption is enabled for this peer
    bool noise_handshake_completed;         // Whether noise handshake is completed
    std::shared_ptr<rats::NoiseCipherState> send_cipher;   // Cipher for sending encrypted data
    std::shared_ptr<rats::NoiseCipherState> recv_cipher;   // Cipher for receiving encrypted data
    std::vector<uint8_t> remote_static_key;  // Remote peer's static public key (for identity verification)
    
    RatsPeer() : handshake_state(HandshakeState::PENDING), 
                 encryption_enabled(false),
                 noise_handshake_completed(false) {
        connected_at = std::chrono::steady_clock::now();
        handshake_start_time = connected_at;
    }
    
    RatsPeer(const std::string& id, const std::string& peer_ip, uint16_t peer_port, 
             socket_t sock, const std::string& norm_addr, bool outgoing)
        : peer_id(id), ip(peer_ip), port(peer_port), socket(sock), 
          normalized_address(norm_addr), is_outgoing(outgoing),
          handshake_state(HandshakeState::PENDING),
          encryption_enabled(false),
          noise_handshake_completed(false) {
        connected_at = std::chrono::steady_clock::now();
        handshake_start_time = connected_at;
    }
    
    // Check if peer has completed Noise handshake and is ready for encrypted communication
    bool is_noise_encrypted() const { 
        return noise_handshake_completed && send_cipher && recv_cipher; 
    }
    
    // Helper methods
    bool is_handshake_completed() const { return handshake_state == HandshakeState::COMPLETED; }
    bool is_handshake_failed() const { return handshake_state == HandshakeState::FAILED; }
};
 
struct ReconnectConfig {
    int max_attempts = 3;                                      // Maximum number of reconnection attempts
    std::vector<int> retry_intervals_seconds = {5, 30, 120};   // Intervals between attempts (5s, 30s, 2min)
    int stable_connection_threshold_seconds = 60;              // Connection duration to be considered "stable" (1 minute)
    int stable_first_retry_seconds = 2;                        // First retry interval for stable peers (faster)
    bool enabled = true;                                       // Whether auto-reconnection is enabled
};
 
struct ReconnectInfo {
    std::string peer_id;                                       // Peer ID for identification
    std::string ip;                                            // IP address to reconnect to
    uint16_t port;                                             // Port number
    int attempt_count;                                         // Current number of reconnection attempts
    std::chrono::steady_clock::time_point next_attempt_time;   // When to attempt next reconnection
    std::chrono::milliseconds connection_duration;             // How long the peer was connected before disconnect
    bool is_stable;                                            // Whether this was a "stable" connection
    
    ReconnectInfo() : port(0), attempt_count(0), connection_duration(0), is_stable(false) {
        next_attempt_time = std::chrono::steady_clock::now();
    }
    
    ReconnectInfo(const std::string& id, const std::string& peer_ip, uint16_t peer_port,
                  std::chrono::milliseconds duration, bool stable)
        : peer_id(id), ip(peer_ip), port(peer_port), attempt_count(0),
          connection_duration(duration), is_stable(stable) {
        next_attempt_time = std::chrono::steady_clock::now();
    }
};
 
enum class MessageDataType : uint8_t {
    BINARY = 0x01,      // Raw binary data
    STRING = 0x02,      // UTF-8 string data  
    JSON = 0x03         // JSON formatted data
};
 
struct MessageHeader {
    static constexpr uint32_t MAGIC_NUMBER = 0x52415453; // "RATS" in ASCII
    static constexpr size_t HEADER_SIZE = 8;
    
    uint32_t magic;         // Magic number for validation
    MessageDataType type;   // Message data type
    uint8_t reserved[3];    // Reserved bytes for future use
    
    MessageHeader(MessageDataType data_type) : magic(MAGIC_NUMBER), type(data_type) {
        reserved[0] = reserved[1] = reserved[2] = 0;
    }
    
    MessageHeader() : magic(MAGIC_NUMBER), type(MessageDataType::BINARY) {
        reserved[0] = reserved[1] = reserved[2] = 0;
    }
    
    // Serialize header to bytes
    std::vector<uint8_t> serialize() const {
        std::vector<uint8_t> data(HEADER_SIZE);
        uint32_t network_magic = htonl(magic);
        memcpy(data.data(), &network_magic, 4);
        data[4] = static_cast<uint8_t>(type);
        data[5] = reserved[0];
        data[6] = reserved[1]; 
        data[7] = reserved[2];
        return data;
    }
    
    // Deserialize header from bytes
    static bool deserialize(const std::vector<uint8_t>& data, MessageHeader& header) {
        if (data.size() < HEADER_SIZE) {
            return false;
        }
        
        uint32_t network_magic;
        memcpy(&network_magic, data.data(), 4);
        header.magic = ntohl(network_magic);
        
        if (header.magic != MAGIC_NUMBER) {
            return false;
        }
        
        header.type = static_cast<MessageDataType>(data[4]);
        header.reserved[0] = data[5];
        header.reserved[1] = data[6];
        header.reserved[2] = data[7];
        
        return true;
    }
    
    // Validate data type
    bool is_valid_type() const {
        return type == MessageDataType::BINARY || 
               type == MessageDataType::STRING || 
               type == MessageDataType::JSON;
    }
};
 
class RATS_API RatsClient : public ThreadManager {
public:
    // =========================================================================
    // Type Definitions and Callbacks
    // =========================================================================
    using ConnectionCallback = std::function<void(socket_t, const std::string&)>;
    using BinaryDataCallback = std::function<void(socket_t, const std::string&, const std::vector<uint8_t>&)>;
    using StringDataCallback = std::function<void(socket_t, const std::string&, const std::string&)>;
    using JsonDataCallback = std::function<void(socket_t, const std::string&, const nlohmann::json&)>;
    using DisconnectCallback = std::function<void(socket_t, const std::string&)>;
    using MessageCallback = std::function<void(const std::string&, const nlohmann::json&)>;
    using SendCallback = std::function<void(bool, const std::string&)>;
 
    // =========================================================================
    // Constructor and Destructor
    // =========================================================================
    
    RatsClient(int listen_port, int max_peers = 10, const std::string& bind_address = "");
    
    ~RatsClient();
 
    // =========================================================================
    // Core Lifecycle Management
    // =========================================================================
    
    bool start();
 
    void stop();
 
    void shutdown_all_threads();
 
    bool is_running() const;
 
 
    // =========================================================================
    // Utility Methods
    // =========================================================================
 
    int get_listen_port() const;
    
    std::string get_bind_address() const;
 
    // =========================================================================
    // Connection Management
    // =========================================================================
    
    bool connect_to_peer(const std::string& host, int port);
    
    void disconnect_peer(socket_t socket);
 
    void disconnect_peer_by_id(const std::string& peer_id);
 
    // =========================================================================
    // Data Transmission Methods
    // =========================================================================
    
    // Send to specific peer by socket
    bool send_binary_to_peer(socket_t socket, const std::vector<uint8_t>& data, MessageDataType message_type = MessageDataType::BINARY);
 
    bool send_string_to_peer(socket_t socket, const std::string& data);
 
    bool send_json_to_peer(socket_t socket, const nlohmann::json& data);
 
    // Send to specific peer by ID
    bool send_binary_to_peer_id(const std::string& peer_id, const std::vector<uint8_t>& data, MessageDataType message_type = MessageDataType::BINARY);
 
    bool send_string_to_peer_id(const std::string& peer_id, const std::string& data);
 
    bool send_json_to_peer_id(const std::string& peer_id, const nlohmann::json& data);
 
    // Broadcast to all peers
    int broadcast_binary_to_peers(const std::vector<uint8_t>& data, MessageDataType message_type = MessageDataType::BINARY);
 
    int broadcast_string_to_peers(const std::string& data);
 
    int broadcast_json_to_peers(const nlohmann::json& data);
 
    // =========================================================================
    // Peer Information and Management
    // =========================================================================
    
    int get_peer_count() const;
 
 
    std::string get_peer_id(socket_t socket) const;
 
    socket_t get_peer_socket_by_id(const std::string& peer_id) const;
 
    std::string get_our_peer_id() const;
    
    std::vector<RatsPeer> get_all_peers() const;
    
    std::vector<RatsPeer> get_validated_peers() const;
    
    const RatsPeer* get_peer_by_id(const std::string& peer_id) const;
    
    const RatsPeer* get_peer_by_socket(socket_t socket) const;
    
    int get_max_peers() const;
 
    void set_max_peers(int max_peers);
 
    bool is_peer_limit_reached() const;
 
    // =========================================================================
    // Automatic Reconnection
    // =========================================================================
    
    void set_reconnect_enabled(bool enabled);
    
    bool is_reconnect_enabled() const;
    
    void set_reconnect_config(const ReconnectConfig& config);
    
    const ReconnectConfig& get_reconnect_config() const;
    
    size_t get_reconnect_queue_size() const;
    
    void clear_reconnect_queue();
    
    std::vector<ReconnectInfo> get_reconnect_queue() const;
 
    // =========================================================================
    // Callback Registration
    // =========================================================================
    
    void set_connection_callback(ConnectionCallback callback);
 
    void set_binary_data_callback(BinaryDataCallback callback);
 
    void set_string_data_callback(StringDataCallback callback);
 
    void set_json_data_callback(JsonDataCallback callback);
 
    void set_disconnect_callback(DisconnectCallback callback);
 
    // =========================================================================
    // Peer Discovery Methods
    // =========================================================================
    
    // DHT Discovery
    bool start_dht_discovery(int dht_port = 6881);
 
    void stop_dht_discovery();
 
    bool find_peers_by_hash(const std::string& content_hash, 
                           std::function<void(const std::vector<std::string>&)> callback);
 
    bool announce_for_hash(const std::string& content_hash, uint16_t port = 0,
                          std::function<void(const std::vector<std::string>&)> callback = nullptr);
 
    bool is_dht_running() const;
 
    size_t get_dht_routing_table_size() const;
 
    // mDNS Discovery
    bool start_mdns_discovery(const std::string& service_instance_name = "", 
                             const std::map<std::string, std::string>& txt_records = {});
 
    void stop_mdns_discovery();
 
    bool is_mdns_running() const;
 
    void set_mdns_callback(std::function<void(const std::string&, int, const std::string&)> callback);
 
    std::vector<MdnsService> get_mdns_services() const;
 
    bool query_mdns_services();
 
    // Automatic Discovery
    void start_automatic_peer_discovery();
    
    void stop_automatic_peer_discovery();
    
    bool is_automatic_discovery_running() const;
    
    std::chrono::seconds calculate_discovery_interval() const;
    
    std::string get_discovery_hash() const;
    
    static std::string get_rats_peer_discovery_hash();
 
    void add_ignored_address(const std::string& ip_address);
 
    // =========================================================================
    // Protocol Configuration
    // =========================================================================
    
    void set_protocol_name(const std::string& protocol_name);
 
    void set_protocol_version(const std::string& protocol_version);
 
    std::string get_protocol_name() const;
 
    std::string get_protocol_version() const;
 
    // =========================================================================
    // Message Exchange API
    // =========================================================================
    
    void on(const std::string& message_type, MessageCallback callback);
 
    void once(const std::string& message_type, MessageCallback callback);
 
    void off(const std::string& message_type);
 
    void send(const std::string& message_type, const nlohmann::json& data, SendCallback callback = nullptr);
 
    void send(const std::string& peer_id, const std::string& message_type, const nlohmann::json& data, SendCallback callback = nullptr);
 
    bool parse_json_message(const std::string& message, nlohmann::json& out_json);
 
    // =========================================================================
    // Encryption Functionality
    // =========================================================================
    
    bool initialize_encryption(bool enable);
 
    void set_encryption_enabled(bool enabled);
 
    bool is_encryption_enabled() const;
 
    bool is_peer_encrypted(const std::string& peer_id) const;
    
    bool set_noise_static_keypair(const uint8_t private_key[32]);
    
    std::vector<uint8_t> get_noise_static_public_key() const;
    
    std::vector<uint8_t> get_peer_noise_public_key(const std::string& peer_id) const;
    
    std::vector<uint8_t> get_peer_handshake_hash(const std::string& peer_id) const;
 
    // =========================================================================
    // Configuration Persistence
    // =========================================================================
    
    bool load_configuration();
 
    bool save_configuration();
 
    bool set_data_directory(const std::string& directory_path);
 
    std::string get_data_directory() const;
 
    int load_and_reconnect_peers();
 
    bool load_historical_peers();
 
    bool save_historical_peers();
 
    void clear_historical_peers();
 
    std::vector<RatsPeer> get_historical_peers() const;
 
    // =========================================================================
    // Statistics and Information
    // =========================================================================
    
    nlohmann::json get_connection_statistics() const;
 
    // =========================================================================
    // GossipSub Functionality
    // =========================================================================
    
    GossipSub& get_gossipsub();
    
    bool is_gossipsub_available() const;
    
    // Topic Management
    bool subscribe_to_topic(const std::string& topic);
    
    bool unsubscribe_from_topic(const std::string& topic);
    
    bool is_subscribed_to_topic(const std::string& topic) const;
    
    std::vector<std::string> get_subscribed_topics() const;
    
    // Publishing
    bool publish_to_topic(const std::string& topic, const std::string& message);
    
    bool publish_json_to_topic(const std::string& topic, const nlohmann::json& message);
    
    // Event Handlers (Unified API)
    void on_topic_message(const std::string& topic, std::function<void(const std::string&, const std::string&, const std::string&)> callback);
    
    void on_topic_json_message(const std::string& topic, std::function<void(const std::string&, const std::string&, const nlohmann::json&)> callback);
    
    void on_topic_peer_joined(const std::string& topic, std::function<void(const std::string&, const std::string&)> callback);
    
    void on_topic_peer_left(const std::string& topic, std::function<void(const std::string&, const std::string&)> callback);
    
    void set_topic_message_validator(const std::string& topic, std::function<ValidationResult(const std::string&, const std::string&, const std::string&)> validator);
    
    void off_topic(const std::string& topic);
    
    // Information
    std::vector<std::string> get_topic_peers(const std::string& topic) const;
    
    std::vector<std::string> get_topic_mesh_peers(const std::string& topic) const;
    
    nlohmann::json get_gossipsub_statistics() const;
    
    bool is_gossipsub_running() const;
 
    // =========================================================================
    // Logging Control API
    // =========================================================================
    
    void set_console_logging_enabled(bool enabled);
    
    bool is_console_logging_enabled() const;
    
    void set_logging_enabled(bool enabled);
    
    bool is_logging_enabled() const;
    
    void set_log_file_path(const std::string& file_path);
    
    std::string get_log_file_path() const;
    
    void set_log_level(LogLevel level);
    
    void set_log_level(const std::string& level_str);
    
    LogLevel get_log_level() const;
    
    void set_log_colors_enabled(bool enabled);
    
    bool is_log_colors_enabled() const;
    
    void set_log_timestamps_enabled(bool enabled);
    
    bool is_log_timestamps_enabled() const;
    
    void set_log_rotation_size(size_t max_size_bytes);
    
    void set_log_retention_count(int count);
    
    void set_log_rotate_on_startup(bool enabled);
    
    bool is_log_rotate_on_startup_enabled() const;
    
    void clear_log_file();
 
    // =========================================================================
    // File Transfer API
    // =========================================================================
    
    FileTransferManager& get_file_transfer_manager();
    
    bool is_file_transfer_available() const;
    
    // Sending and Requesting
    std::string send_file(const std::string& peer_id, const std::string& file_path, 
                         const std::string& remote_filename = "");
    
    std::string send_directory(const std::string& peer_id, const std::string& directory_path,
                              const std::string& remote_directory_name = "", bool recursive = true);
    
    std::string request_file(const std::string& peer_id, const std::string& remote_file_path,
                            const std::string& local_path);
    
    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
    bool accept_file_transfer(const std::string& transfer_id, const std::string& local_path);
    
    bool reject_file_transfer(const std::string& transfer_id, const std::string& reason = "");
    
    bool accept_directory_transfer(const std::string& transfer_id, const std::string& local_path);
    
    bool reject_directory_transfer(const std::string& transfer_id, const std::string& reason = "");
    
    // Transfer Control
    bool pause_file_transfer(const std::string& transfer_id);
    
    bool resume_file_transfer(const std::string& transfer_id);
    
    bool cancel_file_transfer(const std::string& transfer_id);
    
    // Information and Monitoring
    std::shared_ptr<FileTransferProgress> get_file_transfer_progress(const std::string& transfer_id) const;
    
    std::vector<std::shared_ptr<FileTransferProgress>> get_active_file_transfers() const;
    
    nlohmann::json get_file_transfer_statistics() const;
    
    void set_file_transfer_config(const FileTransferConfig& config);
    
    const FileTransferConfig& get_file_transfer_config() const;
    
    // Event Handlers
    void on_file_transfer_progress(FileTransferProgressCallback callback);
    
    void on_file_transfer_completed(FileTransferCompletedCallback callback);
    
    void on_file_transfer_request(FileTransferRequestCallback callback);
    
    void on_directory_transfer_progress(DirectoryTransferProgressCallback callback);
    
    void on_file_request(FileRequestCallback callback);
    
    void on_directory_request(DirectoryRequestCallback callback);
 
    // =========================================================================
    // ICE (NAT Traversal) API
    // =========================================================================
    
    IceManager& get_ice_manager();
    
    bool is_ice_available() const;
    
    // Server Configuration
    void add_stun_server(const std::string& host, uint16_t port = STUN_DEFAULT_PORT);
    
    void add_turn_server(const std::string& host, uint16_t port,
                         const std::string& username, const std::string& password);
    
    void clear_ice_servers();
    
    // Candidate Gathering
    bool gather_ice_candidates();
    
    std::vector<IceCandidate> get_ice_candidates() const;
    
    bool is_ice_gathering_complete() const;
    
    // Public Address Discovery
    std::optional<std::pair<std::string, uint16_t>> get_public_address() const;
    
    std::optional<StunMappedAddress> discover_public_address(
        const std::string& server = "stun.l.google.com",
        uint16_t port = 19302,
        int timeout_ms = 5000);
    
    // Remote Candidates
    void add_remote_ice_candidate(const IceCandidate& candidate);
    
    void add_remote_ice_candidates_from_sdp(const std::vector<std::string>& sdp_lines);
    
    void end_of_remote_ice_candidates();
    
    // Connectivity
    void start_ice_checks();
    
    IceConnectionState get_ice_connection_state() const;
    
    IceGatheringState get_ice_gathering_state() const;
    
    bool is_ice_connected() const;
    
    std::optional<IceCandidatePair> get_ice_selected_pair() const;
    
    // ICE Event Callbacks
    void on_ice_candidates_gathered(IceCandidatesCallback callback);
    
    void on_ice_new_candidate(IceNewCandidateCallback callback);
    
    void on_ice_gathering_state_changed(IceGatheringStateCallback callback);
    
    void on_ice_connection_state_changed(IceConnectionStateCallback callback);
    
    void on_ice_selected_pair(IceSelectedPairCallback callback);
    
    // ICE Configuration
    void set_ice_config(const IceConfig& config);
    
    const IceConfig& get_ice_config() const;
    
    // ICE Lifecycle
    void close_ice();
    
    void restart_ice();
 
#ifdef RATS_STORAGE
    // =========================================================================
    // Distributed Storage API (requires RATS_STORAGE)
    // =========================================================================
    
    StorageManager& get_storage_manager();
    
    bool is_storage_available() const;
    
    // Put Operations
    bool storage_put(const std::string& key, const std::string& value);
    
    bool storage_put(const std::string& key, int64_t value);
    
    bool storage_put(const std::string& key, double value);
    
    bool storage_put(const std::string& key, const std::vector<uint8_t>& value);
    
    bool storage_put_json(const std::string& key, const nlohmann::json& value);
    
    // Get Operations
    std::optional<std::string> storage_get_string(const std::string& key) const;
    
    std::optional<int64_t> storage_get_int(const std::string& key) const;
    
    std::optional<double> storage_get_double(const std::string& key) const;
    
    std::optional<std::vector<uint8_t>> storage_get_binary(const std::string& key) const;
    
    std::optional<nlohmann::json> storage_get_json(const std::string& key) const;
    
    // Delete and Query Operations
    bool storage_delete(const std::string& key);
    
    bool storage_has(const std::string& key) const;
    
    std::vector<std::string> storage_keys() const;
    
    std::vector<std::string> storage_keys_with_prefix(const std::string& prefix) const;
    
    size_t storage_size() const;
    
    // Synchronization
    bool storage_request_sync();
    
    bool is_storage_synced() const;
    
    // Statistics
    nlohmann::json get_storage_statistics() const;
    
    void set_storage_config(const StorageConfig& config);
    
    const StorageConfig& get_storage_config() const;
    
    // Event Handlers
    void on_storage_change(StorageChangeCallback callback);
    
    void on_storage_sync_complete(StorageSyncCompleteCallback callback);
#endif // RATS_STORAGE
 
#ifdef RATS_SEARCH_FEATURES
    // =========================================================================
    // BitTorrent API (requires RATS_SEARCH_FEATURES)
    // =========================================================================
    
    bool enable_bittorrent(int listen_port = 6881);
    
    void set_resume_data_path(const std::string& path);
    
    void disable_bittorrent();
    
    bool is_bittorrent_enabled() const;
    
    std::shared_ptr<TorrentDownload> add_torrent(const std::string& torrent_file, 
                                                  const std::string& download_path);
    
    std::shared_ptr<TorrentDownload> add_torrent(const TorrentInfo& torrent_info, 
                                                  const std::string& download_path);
    
    std::shared_ptr<TorrentDownload> add_torrent_by_hash(const InfoHash& info_hash, 
                                                          const std::string& download_path);
    
    std::shared_ptr<TorrentDownload> add_torrent_by_hash(const std::string& info_hash_hex, 
                                                          const std::string& download_path);
    
    bool remove_torrent(const InfoHash& info_hash);
    
    std::shared_ptr<TorrentDownload> get_torrent(const InfoHash& info_hash);
    
    std::vector<std::shared_ptr<TorrentDownload>> get_all_torrents();
    
    size_t get_active_torrents_count() const;
    
    std::pair<uint64_t, uint64_t> get_bittorrent_stats() const;
    
    void get_torrent_metadata(const InfoHash& info_hash, 
                             std::function<void(const TorrentInfo&, bool, const std::string&)> callback);
    
    void get_torrent_metadata(const std::string& info_hash_hex, 
                             std::function<void(const TorrentInfo&, bool, const std::string&)> callback);
    
    void get_torrent_metadata_from_peer(const InfoHash& info_hash,
                                        const std::string& peer_ip,
                                        uint16_t peer_port,
                                        std::function<void(const TorrentInfo&, bool, const std::string&)> callback);
    
    void get_torrent_metadata_from_peer(const std::string& info_hash_hex,
                                        const std::string& peer_ip,
                                        uint16_t peer_port,
                                        std::function<void(const TorrentInfo&, bool, const std::string&)> callback);
    
    // =========================================================================
    // Torrent Creation API (requires RATS_SEARCH_FEATURES)
    // =========================================================================
    
    using TorrentCreationProgressCallback = std::function<void(uint32_t current_piece, uint32_t total_pieces)>;
    
    std::optional<TorrentInfo> create_torrent_from_path(
        const std::string& path,
        const std::vector<std::string>& trackers = {},
        const std::string& comment = "",
        TorrentCreationProgressCallback progress_callback = nullptr);
    
    std::vector<uint8_t> create_torrent_data(
        const std::string& path,
        const std::vector<std::string>& trackers = {},
        const std::string& comment = "",
        TorrentCreationProgressCallback progress_callback = nullptr);
    
    bool create_torrent_file(
        const std::string& path,
        const std::string& output_file,
        const std::vector<std::string>& trackers = {},
        const std::string& comment = "",
        TorrentCreationProgressCallback progress_callback = nullptr);
    
    std::shared_ptr<TorrentDownload> create_and_seed_torrent(
        const std::string& path,
        const std::vector<std::string>& trackers = {},
        const std::string& comment = "",
        TorrentCreationProgressCallback progress_callback = nullptr);
    
    // =========================================================================
    // Spider Mode API (requires RATS_SEARCH_FEATURES)
    // =========================================================================
    
    using SpiderAnnounceCallback = std::function<void(const std::string& info_hash, const std::string& peer_address)>;
    
    void set_spider_mode(bool enable);
    
    bool is_spider_mode() const;
    
    void set_spider_announce_callback(SpiderAnnounceCallback callback);
    
    void set_spider_ignore(bool ignore);
    
    bool is_spider_ignoring() const;
    
    void spider_walk();
    
    size_t get_spider_pool_size() const;
    
    size_t get_spider_visited_count() const;
    
    void clear_spider_state();
#endif // RATS_SEARCH_FEATURES
 
private:
    int listen_port_;
    std::string bind_address_;
    int max_peers_;
    socket_t server_socket_;
    std::atomic<bool> running_;
    
    // =========================================================================
    // MUTEX LOCKING ORDER - CRITICAL FOR DEADLOCK PREVENTION
    // =========================================================================
    // When acquiring multiple mutexes, ALWAYS follow this strict order:
    //
    // 1. config_mutex_              (Configuration and peer ID)
    // 2. protocol_config_mutex_      (Protocol name and version)
    // 3. encryption_mutex_           (Encryption settings and keys)
    // 4. local_addresses_mutex_      (Local interface addresses)
    // 5. peers_mutex_                (Peer management - most frequently locked)
    // 6. socket_send_mutexes_mutex_ (Socket send mutex management)
    // 7. message_handlers_mutex_    (Message handler registration)
    // 8. reconnect_mutex_           (Reconnection queue management)
    // =========================================================================
    
    // [1] Configuration persistence (protected by config_mutex_)
    mutable std::mutex config_mutex_;                       // [1] Protects configuration data
    std::string our_peer_id_;                               // Our persistent peer ID
    std::string data_directory_;                            // Directory where data files are stored
    static const std::string CONFIG_FILE_NAME;             // "config.json"
    static const std::string PEERS_FILE_NAME;              // "peers.rats"
    static const std::string PEERS_EVER_FILE_NAME;         // "peers_ever.rats"
    
    // [2] Custom protocol configuration (protected by protocol_config_mutex_)
    mutable std::mutex protocol_config_mutex_;              // [2] Protects protocol configuration
    std::string custom_protocol_name_;                      // Custom protocol name (default: "rats")
    std::string custom_protocol_version_;                   // Custom protocol version (default: "1.0")
    
    // [3] Encryption state (protected by encryption_mutex_)
    mutable std::mutex encryption_mutex_;                   // [3] Protects encryption state
    bool encryption_enabled_;                               // Whether encryption is enabled
    rats::NoiseKeyPair noise_static_keypair_;               // Our static Noise keypair
    bool noise_keypair_initialized_;                        // Whether keypair has been initialized
    
    // [4] Local interface address blocking (protected by local_addresses_mutex_)
    mutable std::mutex local_addresses_mutex_;              // [4] Protects local interface addresses
    std::vector<std::string> local_interface_addresses_;
    
    // [5] Organized peer management using RatsPeer struct (protected by peers_mutex_)
    mutable std::mutex peers_mutex_;                        // [5] Protects peer data (most frequently locked)
    std::unordered_map<std::string, RatsPeer> peers_;          // keyed by peer_id
    std::unordered_map<socket_t, std::string> socket_to_peer_id_;  // for quick socket->peer_id lookup  
    std::unordered_map<std::string, std::string> address_to_peer_id_;  // for duplicate detection (normalized_address->peer_id)
    
    // [6] Per-socket synchronization for thread-safe message sending (protected by socket_send_mutexes_mutex_)
    mutable std::mutex socket_send_mutexes_mutex_;          // [6] Protects socket send mutex map
    std::unordered_map<socket_t, std::shared_ptr<std::mutex>> socket_send_mutexes_;
    
    // Server and client management
    std::thread server_thread_;
    std::thread management_thread_;
    
    ConnectionCallback connection_callback_;
    BinaryDataCallback binary_data_callback_;
    StringDataCallback string_data_callback_;
    JsonDataCallback json_data_callback_;
    DisconnectCallback disconnect_callback_;
    
    // DHT client for peer discovery
    std::unique_ptr<DhtClient> dht_client_;
    
    // mDNS client for local network discovery
    std::unique_ptr<MdnsClient> mdns_client_;
    std::function<void(const std::string&, int, const std::string&)> mdns_callback_;
    
    // GossipSub for publish-subscribe messaging
    std::unique_ptr<GossipSub> gossipsub_;
    
    // File transfer manager
    std::unique_ptr<FileTransferManager> file_transfer_manager_;
    
    // ICE manager for NAT traversal
    std::unique_ptr<IceManager> ice_manager_;
    
#ifdef RATS_STORAGE
    // Distributed storage manager (optional, requires RATS_STORAGE)
    std::unique_ptr<StorageManager> storage_manager_;
#endif
 
#ifdef RATS_SEARCH_FEATURES
    // BitTorrent client (optional, requires RATS_SEARCH_FEATURES)
    std::unique_ptr<BitTorrentClient> bittorrent_client_;
#endif
    
    void initialize_modules();
    void destroy_modules();
 
    void server_loop();
    void management_loop();
    void handle_client(socket_t client_socket, const std::string& peer_hash_id);
    void remove_peer(socket_t socket);
    std::string generate_peer_hash_id(socket_t socket, const std::string& connection_info);
    void handle_dht_peer_discovery(const std::vector<Peer>& peers, const InfoHash& info_hash);
    void handle_mdns_service_discovery(const MdnsService& service, bool is_new);
    
    // Message header helpers
    std::vector<uint8_t> create_message_with_header(const std::vector<uint8_t>& payload, MessageDataType type);
    bool parse_message_with_header(const std::vector<uint8_t>& message, MessageHeader& header, std::vector<uint8_t>& payload) const;
    
    // Peer management methods using RatsPeer
    void add_peer(const RatsPeer& peer);
    void add_peer_unlocked(const RatsPeer& peer);  // Assumes peers_mutex_ is already locked
    void remove_peer_by_id(const std::string& peer_id);
    void remove_peer_by_id_unlocked(const std::string& peer_id);  // Assumes peers_mutex_ is already locked
    bool is_already_connected_to_address(const std::string& normalized_address) const;
    std::string normalize_peer_address(const std::string& ip, int port) const;
    
    // Data transmission helper - assumes peers_mutex_ is already locked or peer data is cached
    bool send_binary_to_peer_unlocked(socket_t socket, const std::vector<uint8_t>& data, 
                                       MessageDataType message_type, 
                                       rats::NoiseCipherState* send_cipher,
                                       const std::string& peer_id_for_logging);
 
    // Local interface address blocking helper functions
    void initialize_local_addresses();
    bool is_blocked_address(const std::string& ip_address) const;
    bool should_ignore_peer(const std::string& ip, int port) const;
    static bool parse_address_string(const std::string& address_str, std::string& out_ip, int& out_port);
    
    // Helper functions that assume mutex is already locked
    int get_peer_count_unlocked() const;  // Helper that assumes peers_mutex_ is already locked
 
    // Handshake protocol
    static constexpr const char* RATS_PROTOCOL_VERSION = "1.0";
    static constexpr int HANDSHAKE_TIMEOUT_SECONDS = 10;
 
    struct HandshakeMessage {
        std::string protocol;
        std::string version;
        std::string peer_id;
        std::string message_type;
        int64_t timestamp;
        bool encryption_enabled;  // Whether peer supports/wants encryption
        uint16_t listen_port;     // Peer's listening port for peer exchange
    };
 
    std::string create_handshake_message(const std::string& message_type, const std::string& our_peer_id) const;
    bool parse_handshake_message(const std::vector<uint8_t>& data, HandshakeMessage& out_msg) const;
    bool validate_handshake_message(const HandshakeMessage& msg) const;
    bool is_handshake_message(const std::vector<uint8_t>& data) const;
    bool send_handshake(socket_t socket, const std::string& our_peer_id);
    bool send_handshake_unlocked(socket_t socket, const std::string& our_peer_id);
    bool handle_handshake_message(socket_t socket, const std::string& peer_hash_id, const std::vector<uint8_t>& data);
    void check_handshake_timeouts();
    void log_handshake_completion_unlocked(const RatsPeer& peer);
 
    // Automatic discovery
    std::atomic<bool> auto_discovery_running_;
    std::thread auto_discovery_thread_;
    void automatic_discovery_loop();
    void announce_rats_peer();
 
    // Message handling system
    nlohmann::json create_rats_message(const std::string& type, const nlohmann::json& payload, const std::string& sender_peer_id);
    void handle_rats_message(socket_t socket, const std::string& peer_hash_id, const nlohmann::json& message);
 
    // Specific message handlers
    void handle_peer_exchange_message(socket_t socket, const std::string& peer_hash_id, const nlohmann::json& payload);
    void handle_peers_request_message(socket_t socket, const std::string& peer_hash_id, const nlohmann::json& payload);
    void handle_peers_response_message(socket_t socket, const std::string& peer_hash_id, const nlohmann::json& payload);
 
    // Message creation and broadcasting
    nlohmann::json create_peer_exchange_message(const RatsPeer& peer);
    void broadcast_peer_exchange_message(const RatsPeer& new_peer);
    nlohmann::json create_peers_request_message(const std::string& sender_peer_id);
    nlohmann::json create_peers_response_message(const std::vector<RatsPeer>& peers, const std::string& sender_peer_id);
    std::vector<RatsPeer> get_random_peers(int max_count, const std::string& exclude_peer_id = "") const;
    void send_peers_request(socket_t socket, const std::string& our_peer_id);
 
    int broadcast_rats_message(const nlohmann::json& message, const std::string& exclude_peer_id = "");
    int broadcast_rats_message_to_validated_peers(const nlohmann::json& message, const std::string& exclude_peer_id = "");
    
    // [7] Message exchange API implementation (protected by message_handlers_mutex_)
    mutable std::mutex message_handlers_mutex_;             // [7] Protects message handlers
    struct MessageHandler {
        MessageCallback callback;
        bool is_once;
        
        MessageHandler(MessageCallback cb, bool once) : callback(cb), is_once(once) {}
    };
    std::unordered_map<std::string, std::vector<MessageHandler>> message_handlers_;
    
    void call_message_handlers(const std::string& message_type, const std::string& peer_id, const nlohmann::json& data);
 
    // [8] Automatic reconnection system (protected by reconnect_mutex_)
    mutable std::mutex reconnect_mutex_;                    // [8] Protects reconnection queue
    std::unordered_map<std::string, ReconnectInfo> reconnect_queue_;  // keyed by peer_id
    ReconnectConfig reconnect_config_;                      // Reconnection configuration
    std::unordered_set<std::string> manual_disconnect_peers_;  // Peers that were manually disconnected (don't reconnect)
    
    // Reconnection helper methods
    void schedule_reconnect(const RatsPeer& peer);
    void process_reconnect_queue();
    void remove_from_reconnect_queue(const std::string& peer_id);
    int get_retry_interval_seconds(int attempt, bool is_stable) const;
 
    // Per-socket synchronization helpers
    std::shared_ptr<std::mutex> get_socket_send_mutex(socket_t socket);
    void cleanup_socket_send_mutex(socket_t socket);
 
    // Configuration persistence helpers
    std::string generate_persistent_peer_id() const;
    nlohmann::json serialize_peer_for_persistence(const RatsPeer& peer) const;
    bool deserialize_peer_from_persistence(const nlohmann::json& json, std::string& ip, int& port, std::string& peer_id) const;
    std::string get_config_file_path() const;
    std::string get_peers_file_path() const;
    std::string get_peers_ever_file_path() const;
    bool save_peers_to_file();
    bool append_peer_to_historical_file(const RatsPeer& peer);
    int load_and_reconnect_historical_peers();
    
    // Noise Protocol encryption helpers
    void initialize_noise_keypair();
    bool perform_noise_handshake(socket_t socket, const std::string& peer_id, bool is_initiator);
    bool send_noise_message(socket_t socket, const uint8_t* data, size_t len);
    bool recv_noise_message(socket_t socket, std::vector<uint8_t>& out_data, int timeout_ms = 10000);
    bool encrypt_and_send(socket_t socket, const std::string& peer_id, const std::vector<uint8_t>& plaintext);
    bool receive_and_decrypt(socket_t socket, const std::string& peer_id, std::vector<uint8_t>& plaintext);
};
 
// Utility functions
std::unique_ptr<RatsClient> create_rats_client(int listen_port);
 
// Library version query (stable, binding-friendly)
RATS_API const char* rats_get_library_version_string();
RATS_API void rats_get_library_version(int* major, int* minor, int* patch, int* build);
RATS_API const char* rats_get_library_git_describe();
RATS_API uint32_t rats_get_library_abi(); // packed as (major<<16)|(minor<<8)|patch
 
} // namespace librats