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
#include "upnp.h"  // UPnP IGD automatic port forwarding
#include "natpmp.h" // NAT-PMP automatic port forwarding
#include "io_poller.h" // Platform-optimal I/O multiplexing
#include "receive_buffer.h" // Efficient receive buffer for async I/O
#include "chained_send_buffer.h" // Zero-copy chained send buffer
#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 <unordered_set>
#include <cstdint>
#include <cstring>
#include <optional>
#include "rats_export.h"
 
namespace librats {
 
// Detects host network configuration changes (defined in network_monitor.h).
// Forward-declared here; only used via unique_ptr, so RatsClient's destructor
// (defined in librats.cpp, which includes network_monitor.h) sees the full type.
class NetworkMonitor;
 
struct PeerIOContext {
    ReceiveBuffer recv_buffer{8192};
    ChainedSendBuffer send_buffer;
 
    // Async Noise handshake (only valid while handshake_state == NOISE_PENDING)
    std::unique_ptr<rats::NoiseHandshakeState> noise_hs;
    int noise_step = 0;   // XX pattern: 0→initial, advances per message
};
 
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)
    
    // Async I/O context (per-peer buffers for non-blocking I/O)
    PeerIOContext io_;
    
    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;
    }
    
    // Custom copy: copies all fields except io_ (non-copyable due to unique_ptr).
    // Copies are used for snapshots passed to callbacks – they never need the IO context.
    RatsPeer(const RatsPeer& o)
        : peer_id(o.peer_id), ip(o.ip), port(o.port), socket(o.socket),
          normalized_address(o.normalized_address), connected_at(o.connected_at),
          is_outgoing(o.is_outgoing), handshake_state(o.handshake_state),
          version(o.version), handshake_start_time(o.handshake_start_time),
          encryption_enabled(o.encryption_enabled),
          noise_handshake_completed(o.noise_handshake_completed),
          send_cipher(o.send_cipher), recv_cipher(o.recv_cipher),
          remote_static_key(o.remote_static_key)
          /* io_ default-constructed (fresh, empty) */ {}
    
    RatsPeer& operator=(const RatsPeer& o) {
        if (this != &o) {
            peer_id = o.peer_id;
            ip = o.ip;
            port = o.port;
            socket = o.socket;
            normalized_address = o.normalized_address;
            connected_at = o.connected_at;
            is_outgoing = o.is_outgoing;
            handshake_state = o.handshake_state;
            version = o.version;
            handshake_start_time = o.handshake_start_time;
            encryption_enabled = o.encryption_enabled;
            noise_handshake_completed = o.noise_handshake_completed;
            send_cipher = o.send_cipher;
            recv_cipher = o.recv_cipher;
            remote_static_key = o.remote_static_key;
            // io_ left unchanged in the destination (no copy)
        }
        return *this;
    }
    
    // Default move operations are fine
    RatsPeer(RatsPeer&&) = default;
    RatsPeer& operator=(RatsPeer&&) = default;
    
    // 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&)>;
    // Fired when the host's network configuration changes (interface up/down, IP
    // added/removed, default route change). The argument is the new full list of
    // local interface addresses. See on_network_changed().
    using NetworkChangeCallback = std::function<void(const std::vector<std::string>& local_addresses)>;
 
    // =========================================================================
    // 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;
    
    std::optional<RatsPeer> get_peer_by_id(const std::string& peer_id) const;
    
    std::optional<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);
    
    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);
 
    // =========================================================================
    // 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
    // =========================================================================
    //
    // 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.
 
    FileTransferManager& get_file_transfer_manager();
 
    bool is_file_transfer_available() const;
 
    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_name = "");
 
    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 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);
 
    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);
 
    FileTransferConfig get_file_transfer_config() const;
 
    void on_file_transfer_progress(TransferProgressCallback callback);
 
    void on_file_transfer_completed(TransferCompletedCallback callback);
 
    void on_file_transfer_request(TransferOfferCallback 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);
    
    IceConfig get_ice_config() const;
    
    // ICE Lifecycle
    void close_ice();
    
    void restart_ice();
 
    // =========================================================================
    // Automatic Port Forwarding API (UPnP IGD + NAT-PMP)
    // =========================================================================
    //
    // When enabled (the default), RatsClient asks the home router to forward the
    // TCP listen port on startup, using UPnP and NAT-PMP in parallel (whichever
    // the router supports wins). Mappings are refreshed automatically and removed
    // on stop(). This lets peers behind a NAT accept inbound connections without
    // manual router configuration.
 
    void set_port_mapping_enabled(bool enabled);
 
    bool is_port_mapping_enabled() const;
 
    void set_port_mapping_config(const PortMappingConfig& config);
 
    PortMappingConfig get_port_mapping_config() const;
 
    void add_port_mapping(PortMapProtocol protocol, uint16_t port);
 
    std::optional<std::pair<std::string, uint16_t>> get_mapped_public_address() const;
 
    void on_port_mapping(PortMapCallback callback);
 
    // =========================================================================
    // Network change detection
    // =========================================================================
    //
    // A long-lived node must notice when the host's connectivity changes (a new
    // interface, an IP added/removed, the default route flipping between Wi-Fi
    // and cellular, dock/undock, VPN up/down, wake-from-sleep) and recover:
    // renew router port mappings, re-discover its public address via STUN, and
    // re-announce to the DHT. Otherwise it keeps advertising a stale endpoint
    // until the next periodic refresh. Enabled by default. Implemented in
    // librats_portmap.cpp on top of the platform-specific NetworkMonitor.
 
    void set_network_change_detection_enabled(bool enabled);
    bool is_network_change_detection_enabled() const;
 
    void on_network_changed(NetworkChangeCallback callback);
 
#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. io_mutex_                  (I/O poller and send buffer access)
    // 7. message_handlers_mutex_    (Message handler registration)
    // 8. reconnect_mutex_           (Reconnection queue management)
    // 9. port_mapping_mutex_        (UPnP/NAT-PMP backends and mapped address)
    // 10. network_monitor_mutex_ / network_recovery_mutex_ (network-change state)
    //
    // (9) and (10) are leaf locks: they are never held while acquiring any lock
    // above, so they impose no additional ordering constraints.
    // =========================================================================
    
    // [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::unordered_set<std::string> local_interface_addresses_;
    // Subset of local_interface_addresses_ that came from interface enumeration.
    // Tracked separately so a network-change refresh can drop only stale auto
    // entries without evicting localhost or externally-discovered addresses
    // (STUN reflexive, mapped external IP, user add_ignored_address()).
    std::unordered_set<std::string> auto_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)
    std::atomic<int> validated_peer_count_{0};              // Cached count of peers with COMPLETED handshake
    
    // [6] Async I/O (poller + io thread)
    std::unique_ptr<IOPoller> poller_;
    std::mutex io_mutex_;                                    // Protects poller_ and send-buffer writes from non-IO threads
    std::thread io_thread_;
    std::thread management_thread_;
    
    ConnectionCallback connection_callback_;
    BinaryDataCallback binary_data_callback_;
    StringDataCallback string_data_callback_;
    JsonDataCallback json_data_callback_;
    DisconnectCallback disconnect_callback_;
    
    // 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_;
    
    // 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_;
 
    // Automatic port forwarding (UPnP IGD + NAT-PMP). Implemented in librats_portmap.cpp.
    mutable std::mutex port_mapping_mutex_;        // guards the fields below
    PortMappingConfig port_mapping_config_;
    std::unique_ptr<UpnpClient> upnp_client_;
    std::unique_ptr<NatPmpClient> natpmp_client_;
    PortMapCallback port_mapping_callback_;
    // Public address discovered by the backends. The external port is tracked per
    // protocol (like libtorrent's per-listen-socket tcp/udp port mappings): the TCP
    // mapping forwards the peer listen port, the UDP mapping forwards the DHT port.
    // A single field would let the two backend callbacks clobber each other.
    std::string mapped_external_ip_;
    uint16_t mapped_external_tcp_port_ = 0;  // public port for the TCP peer-listen port
    uint16_t mapped_external_udp_port_ = 0;  // public port for the UDP DHT port
    // Set once we warn that the gateway's reported external IP is itself private
    // (double-NAT), so the warning isn't repeated on every lease refresh.
    bool double_nat_warning_logged_ = false;
 
    // Start/stop the port mapping backends (no-ops if disabled). Called from
    // start()/stop(); safe to call repeatedly.
    void start_port_mapping();
    void stop_port_mapping();
    void handle_port_mapping_result(const PortMapResult& result);
    // Public TCP port to advertise to peers/DHT: the mapped external port once a
    // TCP mapping is established, otherwise the local listen port.
    uint16_t get_advertised_port() const;
 
    // Network change detection (implemented in librats_portmap.cpp). Monitor runs
    // a platform watcher; on a real address-set change it refreshes the self-
    // address set inline and wakes the recovery worker, which re-maps ports,
    // re-discovers the public IP and re-announces. These mutexes are last in the
    // lock order (after [8]) and are never held while calling into other
    // subsystems, so they introduce no new ordering constraints.
    std::unique_ptr<NetworkMonitor> network_monitor_;
    bool network_change_detection_enabled_ = true;          // start the monitor on start()
    mutable std::mutex network_monitor_mutex_;              // guards the user callback below
    NetworkChangeCallback network_change_callback_;
    // Dedicated recovery worker: serialises the slow recovery work (STUN can
    // block for seconds) off the monitor thread and coalesces rapid changes.
    std::thread network_recovery_thread_;
    std::mutex network_recovery_mutex_;
    std::condition_variable network_recovery_cv_;
    bool network_recovery_pending_ = false;
    bool network_recovery_stop_ = false;
 
    void start_network_monitor();
    void stop_network_monitor();
    void network_recovery_loop();
    void handle_network_change(const std::vector<std::string>& current_addresses);
    void recover_after_network_change();
 
#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();
 
    // Async I/O loop (single thread for all sockets)
    void io_loop();
    void management_loop();
    
    // I/O event handlers (called from io_loop)
    void accept_incoming();
    bool handle_readable(socket_t socket);
    bool handle_writable(socket_t socket);
    void handle_disconnect(socket_t socket);
    
    // Poller registration helpers
    void poller_add(socket_t fd, uint32_t events);
    void poller_modify(socket_t fd, uint32_t events);
    void poller_remove(socket_t fd);
    
    // Helpers – post-handshake and message routing
    void handle_post_handshake_completion(socket_t socket, const RatsPeer& peer_copy);
    void process_message(socket_t socket, const std::vector<uint8_t>& data, const std::string& peer_id);
    
    // Peer lookup helper (assumes peers_mutex_ is already locked)
    std::unordered_map<std::string, RatsPeer>::iterator find_peer_by_socket_unlocked(socket_t socket);
    std::unordered_map<std::string, RatsPeer>::const_iterator find_peer_by_socket_unlocked(socket_t socket) const;
    
    void remove_peer(socket_t socket);
    std::string generate_temporary_peer_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_unlocked(const RatsPeer& peer);  // Assumes peers_mutex_ is already locked
    void remove_peer_by_id_unlocked(const std::string& peer_id);  // Assumes peers_mutex_ is already locked
    void mark_manual_disconnect(const std::string& peer_id);
    static std::vector<uint8_t> json_to_binary(const nlohmann::json& data);
    bool is_already_connected_to_address(const std::string& normalized_address) const;
    std::string normalize_peer_address(const std::string& ip, int port) const;
    
    // Async send – enqueues a framed (length-prefixed) message into the peer's
    // ChainedSendBuffer and arms PollOut.  Thread-safe (acquires io_mutex_).
    // Returns false if the peer was not found.
    bool enqueue_message(socket_t socket, const std::vector<uint8_t>& data);
    // Unlocked variant – caller must hold peers_mutex_
    bool enqueue_message_unlocked(RatsPeer& peer, const std::vector<uint8_t>& data);
 
    // Lightweight snapshot of peer data needed for sending (avoids holding peers_mutex_ during enqueue)
    struct PeerSendTarget {
        socket_t socket;
        std::string peer_id;
        std::shared_ptr<rats::NoiseCipherState> send_cipher;
    };
    
    bool send_binary_to_peer_unlocked(socket_t socket, const std::vector<uint8_t>& data, 
                                       MessageDataType message_type, 
                                       std::shared_ptr<rats::NoiseCipherState> send_cipher,
                                       const std::string& peer_id_for_logging);
    
    // Async Noise handshake – processes one Noise XX message received from peer.
    // Returns false if peer should be disconnected.  Called from handle_readable.
    bool handle_noise_frame(RatsPeer& peer);
    // Kick-off: initialises noise_hs and writes first outgoing message if initiator.
    void start_noise_handshake_async(RatsPeer& peer);
 
    // 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;
    bool can_connect_to_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
 
    // Protocol constants
    static constexpr const char* RATS_PROTOCOL_VERSION = "1.0";
    static constexpr int HANDSHAKE_TIMEOUT_SECONDS = 10;
    static constexpr int TCP_CONNECT_TIMEOUT_MS = 10000;        // 10 second TCP connection timeout
    static constexpr int IO_POLL_TIMEOUT_MS = 100;              // IO poller tick interval (ms)
    static constexpr size_t MAX_FRAME_SIZE = 100 * 1024 * 1024; // 100 MB max single frame
    static constexpr int PEER_RECONNECT_DELAY_MS = 100;         // Delay before reconnecting saved peers
    static constexpr int HISTORICAL_RECONNECT_DELAY_MS = 500;   // Delay before reconnecting historical peers
    static constexpr int MANAGEMENT_LOOP_INTERVAL_SECONDS = 2;  // Management loop tick interval
    static constexpr int THREAD_CLEANUP_INTERVAL_SECONDS = 30;  // Thread cleanup interval
    static constexpr int INITIAL_DISCOVERY_DELAY_SECONDS = 5;   // DHT bootstrap delay
    static constexpr int MAX_PEERS_REQUEST_COUNT = 5;            // Max peers to request/respond
    static constexpr int CONTENT_HASH_HEX_LENGTH = 40;          // 160-bit hash as hex
    static constexpr int64_t TIMESTAMP_SKEW_TOLERANCE_MS = 10LL * 60LL * 1000LL; // 10 minutes
 
    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_unlocked(RatsPeer& peer, const std::string& our_peer_id);  // enqueues via send buffer (peers_mutex_ held)
    bool handle_handshake_message(socket_t socket, const std::string& initial_peer_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_id, const nlohmann::json& message);
 
    // Specific message handlers
    void handle_peer_exchange_message(socket_t socket, const std::string& peer_id, const nlohmann::json& payload);
    void handle_peers_request_message(socket_t socket, const std::string& peer_id, const nlohmann::json& payload);
    void handle_peers_response_message(socket_t socket, const std::string& peer_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 = "", bool validated_only = true);
    
    // [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;
 
    // 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();
};
 
// 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