ice.h

Go to the documentation of this file.

#pragma once
 
#include "stun.h"
#include "turn.h"
#include "socket.h"
#include <vector>
#include <string>
#include <optional>
#include <memory>
#include <mutex>
#include <functional>
#include <chrono>
#include <atomic>
#include <thread>
 
namespace librats {
 
// ============================================================================
// ICE Constants
// ============================================================================
 
constexpr uint32_t ICE_PRIORITY_HOST = 126;
 
constexpr uint32_t ICE_PRIORITY_SRFLX = 100;
 
constexpr uint32_t ICE_PRIORITY_RELAY = 0;
 
constexpr int ICE_CHECK_TIMEOUT_MS = 500;
 
constexpr int ICE_CHECK_MAX_RETRIES = 5;
 
// ============================================================================
// ICE Data Structures
// ============================================================================
 
enum class IceCandidateType {
    Host,           
    ServerReflexive,
    PeerReflexive,  
    Relay           
};
 
enum class IceTransportProtocol {
    UDP,
    TCP
};
 
enum class IceConnectionState {
    New,            
    Gathering,      
    Checking,       
    Connected,      
    Completed,      
    Failed,         
    Disconnected,   
    Closed          
};
 
enum class IceGatheringState {
    New,            
    Gathering,      
    Complete        
};
 
struct IceCandidate {
    IceCandidateType type;
    std::string foundation;         
    uint32_t component_id;          
    IceTransportProtocol transport;
    uint32_t priority;              
    std::string address;            
    uint16_t port;                  
    std::string related_address;    
    uint16_t related_port;          
    
    IceCandidate() : type(IceCandidateType::Host), component_id(1), 
                     transport(IceTransportProtocol::UDP), priority(0),
                     port(0), related_port(0) {}
    
    static uint32_t compute_priority(IceCandidateType type, 
                                     uint32_t local_preference = 65535,
                                     uint32_t component_id = 1);
    
    static std::string generate_foundation(IceCandidateType type,
                                           const std::string& base_address,
                                           const std::string& server_address = "");
    
    std::string to_sdp_attribute() const;
    
    static std::optional<IceCandidate> from_sdp_attribute(const std::string& sdp);
    
    std::string type_string() const;
    
    std::string address_string() const {
        return address + ":" + std::to_string(port);
    }
    
    bool operator==(const IceCandidate& other) const {
        return type == other.type && address == other.address && 
               port == other.port && transport == other.transport;
    }
};
 
enum class IceCandidatePairState {
    Frozen,     
    Waiting,    
    InProgress, 
    Succeeded,  
    Failed      
};
 
struct IceCandidatePair {
    IceCandidate local;
    IceCandidate remote;
    IceCandidatePairState state;
    uint64_t priority;          
    bool nominated;             
    int check_count;            
    std::chrono::steady_clock::time_point last_check;
    
    IceCandidatePair() : state(IceCandidatePairState::Frozen), 
                         priority(0), nominated(false), check_count(0) {}
    
    static uint64_t compute_priority(uint32_t controlling_priority,
                                     uint32_t controlled_priority,
                                     bool is_controlling);
    
    std::string key() const {
        return local.address_string() + "->" + remote.address_string();
    }
};
 
struct IceServer {
    std::string url;            
    std::string username;       
    std::string password;       
    
    IceServer() = default;
    IceServer(const std::string& u) : url(u) {}
    IceServer(const std::string& u, const std::string& user, const std::string& pass)
        : url(u), username(user), password(pass) {}
    
    bool is_stun() const { return url.find("stun:") == 0; }
    
    bool is_turn() const { return url.find("turn:") == 0 || url.find("turns:") == 0; }
    
    bool parse_url(std::string& host, uint16_t& port) const;
};
 
struct IceConfig {
    std::vector<IceServer> ice_servers;     
    bool gather_host_candidates = true;      
    bool gather_srflx_candidates = true;     
    bool gather_relay_candidates = false;    
    int gathering_timeout_ms = 5000;         
    int check_timeout_ms = ICE_CHECK_TIMEOUT_MS;    
    int check_max_retries = ICE_CHECK_MAX_RETRIES;  
    std::string software = "librats";        
    
    IceConfig() = default;
    
    void add_stun_server(const std::string& host, uint16_t port = STUN_DEFAULT_PORT) {
        ice_servers.emplace_back("stun:" + host + ":" + std::to_string(port));
    }
    
    void add_turn_server(const std::string& host, uint16_t port,
                         const std::string& username, const std::string& password) {
        ice_servers.emplace_back("turn:" + host + ":" + std::to_string(port),
                                 username, password);
    }
};
 
// ============================================================================
// ICE Callbacks
// ============================================================================
 
using IceCandidatesCallback = std::function<void(const std::vector<IceCandidate>&)>;
 
using IceGatheringStateCallback = std::function<void(IceGatheringState)>;
 
using IceConnectionStateCallback = std::function<void(IceConnectionState)>;
 
using IceNewCandidateCallback = std::function<void(const IceCandidate&)>;
 
using IceSelectedPairCallback = std::function<void(const IceCandidatePair&)>;
 
// ============================================================================
// ICE Manager
// ============================================================================
 
class IceManager {
public:
    IceManager();
    explicit IceManager(const IceConfig& config);
    ~IceManager();
    
    // Non-copyable
    IceManager(const IceManager&) = delete;
    IceManager& operator=(const IceManager&) = delete;
    
    // =========================================================================
    // Configuration
    // =========================================================================
    
    void set_config(const IceConfig& config);
    
    const IceConfig& config() const { return config_; }
    
    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_candidates();
    
    std::vector<IceCandidate> get_local_candidates() const;
    
    IceGatheringState get_gathering_state() const { return gathering_state_; }
    
    bool is_gathering_complete() const { 
        return gathering_state_ == IceGatheringState::Complete;
    }
    
    // =========================================================================
    // Remote Candidates
    // =========================================================================
    
    void add_remote_candidate(const IceCandidate& candidate);
    
    void add_remote_candidates_from_sdp(const std::vector<std::string>& sdp_lines);
    
    std::vector<IceCandidate> get_remote_candidates() const;
    
    void end_of_remote_candidates();
    
    // =========================================================================
    // Connectivity Checks
    // =========================================================================
    
    void start_checks();
    
    void stop_checks();
    
    std::vector<IceCandidatePair> get_candidate_pairs() const;
    
    std::optional<IceCandidatePair> get_selected_pair() const;
    
    // =========================================================================
    // Connection State
    // =========================================================================
    
    IceConnectionState get_connection_state() const { return connection_state_; }
    
    bool is_connected() const {
        return connection_state_ == IceConnectionState::Connected ||
               connection_state_ == IceConnectionState::Completed;
    }
    
    // =========================================================================
    // Public Address Discovery
    // =========================================================================
    
    std::optional<std::pair<std::string, uint16_t>> get_public_address() const;
    
    // =========================================================================
    // Socket Access
    // =========================================================================
    
    socket_t get_socket() const { return socket_; }
    
    uint16_t get_local_port() const { return local_port_; }
    
    // =========================================================================
    // Callbacks
    // =========================================================================
    
    void set_on_candidates_gathered(IceCandidatesCallback callback);
    void set_on_new_candidate(IceNewCandidateCallback callback);
    void set_on_gathering_state_changed(IceGatheringStateCallback callback);
    void set_on_connection_state_changed(IceConnectionStateCallback callback);
    void set_on_selected_pair(IceSelectedPairCallback callback);
    
    // =========================================================================
    // Lifecycle
    // =========================================================================
    
    void close();
    
    void restart();
    
private:
    // Configuration
    IceConfig config_;
    
    // Network
    socket_t socket_ = INVALID_SOCKET_VALUE;
    uint16_t local_port_ = 0;
    
    // STUN/TURN clients
    std::unique_ptr<StunClient> stun_client_;
    std::unique_ptr<TurnClient> turn_client_;
    
    // State
    mutable std::mutex mutex_;
    IceGatheringState gathering_state_ = IceGatheringState::New;
    IceConnectionState connection_state_ = IceConnectionState::New;
    
    // Candidates
    std::vector<IceCandidate> local_candidates_;
    std::vector<IceCandidate> remote_candidates_;
    std::vector<IceCandidatePair> candidate_pairs_;
    std::optional<IceCandidatePair> selected_pair_;
    
    // Flags
    std::atomic<bool> gathering_ {false};
    std::atomic<bool> checking_ {false};
    bool remote_candidates_complete_ = false;
    
    // Threads
    std::thread gathering_thread_;
    std::thread checking_thread_;
    
    // Callbacks
    IceCandidatesCallback on_candidates_gathered_;
    IceNewCandidateCallback on_new_candidate_;
    IceGatheringStateCallback on_gathering_state_changed_;
    IceConnectionStateCallback on_connection_state_changed_;
    IceSelectedPairCallback on_selected_pair_;
    
    // Internal methods
    bool ensure_socket();
    void gather_host_candidates();
    void gather_srflx_candidates();
    void gather_relay_candidates();
    void gathering_complete();
    void add_local_candidate(const IceCandidate& candidate);
    void form_candidate_pairs();
    void perform_connectivity_checks();
    bool perform_check(IceCandidatePair& pair);
    void update_connection_state();
    void select_best_pair();
    void set_gathering_state(IceGatheringState state);
    void set_connection_state(IceConnectionState state);
};
 
} // namespace librats