connection.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2024, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include "congestion_controller.h"
#include "kcenon/network/detail/protocols/quic/connection_id.h"
#include "connection_id_manager.h"
#include "crypto.h"
#include "flow_control.h"
#include "frame.h"
#include "loss_detector.h"
#include "packet.h"
#include "pmtud_controller.h"
#include "rtt_estimator.h"
#include "stream_manager.h"
#include "transport_params.h"
#include "kcenon/network/detail/utils/result_types.h"
 
#include <chrono>
#include <deque>
#include <functional>
#include <map>
#include <memory>
#include <mutex>
#include <optional>
#include <span>
#include <string>
#include <vector>
 
#if defined(NETWORK_ENABLE_TEST_INJECTION)
namespace kcenon::network::tests::support
{
    class quic_connection_test_access;
} // namespace kcenon::network::tests::support
#endif
 
namespace kcenon::network::protocols::quic
{
 
// ============================================================================
// Connection State Enums
// ============================================================================
 
enum class connection_state
{
    idle,        
    handshaking, 
    connected,   
    closing,     
    draining,    
    closed,      
};
 
enum class handshake_state
{
    initial,              
    waiting_server_hello, 
    waiting_finished,     
    complete,             
};
 
[[nodiscard]] auto connection_state_to_string(connection_state state) -> const char*;
 
[[nodiscard]] auto handshake_state_to_string(handshake_state state) -> const char*;
 
// ============================================================================
// Connection Error Codes
// ============================================================================
 
namespace connection_error
{
    constexpr int not_established = -730;
    constexpr int handshake_failed = -731;
    constexpr int invalid_state = -732;
    constexpr int protocol_violation = -733;
    constexpr int connection_refused = -734;
    constexpr int idle_timeout = -735;
    constexpr int connection_closed = -736;
} // namespace connection_error
 
// ============================================================================
// Sent Packet Tracking
// ============================================================================
 
struct sent_packet_info
{
    uint64_t packet_number{0};
    std::chrono::steady_clock::time_point sent_time;
    size_t sent_bytes{0};
    bool ack_eliciting{false};
    bool in_flight{false};
    encryption_level level{encryption_level::initial};
 
    // Frames included in this packet (for retransmission)
    std::vector<frame> frames;
};
 
// ============================================================================
// Packet Number Space
// ============================================================================
 
struct packet_number_space
{
    uint64_t next_pn{0};
 
    uint64_t largest_acked{0};
 
    uint64_t largest_received{0};
 
    std::chrono::steady_clock::time_point largest_received_time;
 
    std::map<uint64_t, sent_packet_info> sent_packets;
 
    bool ack_needed{false};
 
    std::chrono::microseconds ack_delay{0};
};
 
// ============================================================================
// Connection Class
// ============================================================================
 
class connection
{
public:
    connection(bool is_server, const connection_id& initial_dcid);
 
    ~connection();
 
    // Non-copyable and non-movable (members are not movable)
    connection(const connection&) = delete;
    auto operator=(const connection&) -> connection& = delete;
    connection(connection&&) = delete;
    auto operator=(connection&&) -> connection& = delete;
 
    // ========================================================================
    // Connection State
    // ========================================================================
 
    [[nodiscard]] auto state() const noexcept -> connection_state { return state_; }
 
    [[nodiscard]] auto handshake_state() const noexcept -> enum handshake_state
    {
        return hs_state_;
    }
 
    [[nodiscard]] auto is_established() const noexcept -> bool
    {
        return state_ == connection_state::connected;
    }
 
    [[nodiscard]] auto is_draining() const noexcept -> bool
    {
        return state_ == connection_state::draining ||
               state_ == connection_state::closing;
    }
 
    [[nodiscard]] auto is_closed() const noexcept -> bool
    {
        return state_ == connection_state::closed;
    }
 
    [[nodiscard]] auto is_server() const noexcept -> bool { return is_server_; }
 
    // ========================================================================
    // Connection IDs
    // ========================================================================
 
    [[nodiscard]] auto local_cid() const -> const connection_id& { return local_cid_; }
 
    [[nodiscard]] auto remote_cid() const -> const connection_id& { return remote_cid_; }
 
    [[nodiscard]] auto initial_dcid() const -> const connection_id& { return initial_dcid_; }
 
    [[nodiscard]] auto add_local_cid(const connection_id& cid, uint64_t sequence)
        -> VoidResult;
 
    [[nodiscard]] auto retire_cid(uint64_t sequence) -> VoidResult;
 
    [[nodiscard]] auto peer_cid_manager() -> connection_id_manager&
    {
        return peer_cid_manager_;
    }
 
    [[nodiscard]] auto peer_cid_manager() const -> const connection_id_manager&
    {
        return peer_cid_manager_;
    }
 
    [[nodiscard]] auto active_peer_cid() const -> const connection_id&;
 
    [[nodiscard]] auto rotate_peer_cid() -> VoidResult;
 
    // ========================================================================
    // Transport Parameters
    // ========================================================================
 
    void set_local_params(const transport_parameters& params);
 
    void set_remote_params(const transport_parameters& params);
 
    [[nodiscard]] auto local_params() const -> const transport_parameters&
    {
        return local_params_;
    }
 
    [[nodiscard]] auto remote_params() const -> const transport_parameters&
    {
        return remote_params_;
    }
 
    // ========================================================================
    // Handshake
    // ========================================================================
 
    [[nodiscard]] auto start_handshake(const std::string& server_name)
        -> Result<std::vector<uint8_t>>;
 
    [[nodiscard]] auto init_server_handshake(const std::string& cert_file,
                                               const std::string& key_file) -> VoidResult;
 
    // ========================================================================
    // Packet Processing
    // ========================================================================
 
    [[nodiscard]] auto receive_packet(std::span<const uint8_t> data) -> VoidResult;
 
    [[nodiscard]] auto generate_packets() -> std::vector<std::vector<uint8_t>>;
 
    [[nodiscard]] auto has_pending_data() const -> bool;
 
    // ========================================================================
    // Stream Access
    // ========================================================================
 
    [[nodiscard]] auto streams() -> stream_manager& { return stream_mgr_; }
 
    [[nodiscard]] auto streams() const -> const stream_manager& { return stream_mgr_; }
 
    // ========================================================================
    // Flow Control
    // ========================================================================
 
    [[nodiscard]] auto flow_control() -> flow_controller& { return flow_ctrl_; }
 
    [[nodiscard]] auto flow_control() const -> const flow_controller& { return flow_ctrl_; }
 
    // ========================================================================
    // Connection Close
    // ========================================================================
 
    [[nodiscard]] auto close(uint64_t error_code, const std::string& reason = "")
        -> VoidResult;
 
    [[nodiscard]] auto close_application(uint64_t error_code,
                                          const std::string& reason = "") -> VoidResult;
 
    [[nodiscard]] auto close_error_code() const -> std::optional<uint64_t>
    {
        return close_error_code_;
    }
 
    [[nodiscard]] auto close_reason() const -> const std::string& { return close_reason_; }
 
    // ========================================================================
    // Timers
    // ========================================================================
 
    [[nodiscard]] auto next_timeout() const
        -> std::optional<std::chrono::steady_clock::time_point>;
 
    void on_timeout();
 
    [[nodiscard]] auto idle_deadline() const -> std::chrono::steady_clock::time_point
    {
        return idle_deadline_;
    }
 
    // ========================================================================
    // Crypto Access
    // ========================================================================
 
    [[nodiscard]] auto crypto() -> quic_crypto& { return crypto_; }
 
    [[nodiscard]] auto crypto() const -> const quic_crypto& { return crypto_; }
 
    // ========================================================================
    // Path MTU Discovery (RFC 9000 Section 14, RFC 8899)
    // ========================================================================
 
    [[nodiscard]] auto path_mtu() const noexcept -> size_t;
 
    void enable_pmtud();
 
    void disable_pmtud();
 
    [[nodiscard]] auto pmtud_enabled() const noexcept -> bool;
 
    [[nodiscard]] auto pmtud() -> pmtud_controller& { return pmtud_controller_; }
 
    [[nodiscard]] auto pmtud() const -> const pmtud_controller& { return pmtud_controller_; }
 
    // ========================================================================
    // Statistics
    // ========================================================================
 
    [[nodiscard]] auto bytes_sent() const noexcept -> uint64_t { return bytes_sent_; }
 
    [[nodiscard]] auto bytes_received() const noexcept -> uint64_t { return bytes_received_; }
 
    [[nodiscard]] auto packets_sent() const noexcept -> uint64_t { return packets_sent_; }
 
    [[nodiscard]] auto packets_received() const noexcept -> uint64_t
    {
        return packets_received_;
    }
 
private:
    // ========================================================================
    // Private Members
    // ========================================================================
 
    bool is_server_;
    connection_state state_{connection_state::idle};
    enum handshake_state hs_state_ { handshake_state::initial };
 
    // Connection IDs
    connection_id local_cid_;
    connection_id remote_cid_;
    connection_id initial_dcid_;  // For initial key derivation
    std::vector<std::pair<uint64_t, connection_id>> local_cids_;
    uint64_t next_cid_sequence_{1};
    connection_id_manager peer_cid_manager_;  // Manages peer CIDs (RFC 9000 Section 5.1)
 
    // Transport parameters
    transport_parameters local_params_;
    transport_parameters remote_params_;
 
    // Subsystems
    quic_crypto crypto_;
    stream_manager stream_mgr_;
    flow_controller flow_ctrl_;
 
    // Loss detection and congestion control (RFC 9002)
    rtt_estimator rtt_estimator_;
    loss_detector loss_detector_;
    congestion_controller congestion_controller_;
 
    // Path MTU Discovery (RFC 8899)
    pmtud_controller pmtud_controller_;
 
    // Packet number spaces
    packet_number_space initial_space_;
    packet_number_space handshake_space_;
    packet_number_space app_space_;
 
    // Pending crypto data per encryption level
    std::deque<std::vector<uint8_t>> pending_crypto_initial_;
    std::deque<std::vector<uint8_t>> pending_crypto_handshake_;
    std::deque<std::vector<uint8_t>> pending_crypto_app_;
 
    // Pending ACKs per encryption level
    bool pending_ack_initial_{false};
    bool pending_ack_handshake_{false};
    bool pending_ack_app_{false};
 
    // Pending frames to send
    std::deque<frame> pending_frames_;
 
    // Close state
    bool close_sent_{false};
    bool close_received_{false};
    std::optional<uint64_t> close_error_code_;
    std::string close_reason_;
    bool application_close_{false};
 
    // Timers
    std::chrono::steady_clock::time_point idle_deadline_;
    std::chrono::steady_clock::time_point pto_deadline_;
    std::chrono::steady_clock::time_point drain_deadline_;
 
    // Statistics
    uint64_t bytes_sent_{0};
    uint64_t bytes_received_{0};
    uint64_t packets_sent_{0};
    uint64_t packets_received_{0};
 
    // ========================================================================
    // Private Methods
    // ========================================================================
 
    [[nodiscard]] auto process_long_header_packet(const long_header& hdr,
                                                   std::span<const uint8_t> payload)
        -> VoidResult;
 
    [[nodiscard]] auto process_short_header_packet(const short_header& hdr,
                                                    std::span<const uint8_t> payload)
        -> VoidResult;
 
    [[nodiscard]] auto process_frames(std::span<const uint8_t> payload,
                                       encryption_level level) -> VoidResult;
 
    [[nodiscard]] auto handle_frame(const frame& frame, encryption_level level)
        -> VoidResult;
 
    [[nodiscard]] auto build_packet(encryption_level level) -> std::vector<uint8_t>;
 
    [[nodiscard]] auto get_pn_space(encryption_level level) -> packet_number_space&;
    [[nodiscard]] auto get_pn_space(encryption_level level) const
        -> const packet_number_space&;
 
    void update_state();
 
    void reset_idle_timer();
 
    void enter_draining();
 
    void enter_closing();
 
    void apply_remote_params();
 
    [[nodiscard]] auto generate_ack_frame(const packet_number_space& space)
        -> std::optional<ack_frame>;
 
    void handle_loss_detection_result(const loss_detection_result& result);
 
    void generate_probe_packets();
 
    void queue_frames_for_retransmission(const sent_packet& lost_packet);
 
    [[nodiscard]] auto to_sent_packet(const sent_packet_info& info) const -> sent_packet;
 
#if defined(NETWORK_ENABLE_TEST_INJECTION)
    // Test-only: grants tests/support/quic_connection_test_access access to
    // private dispatch helpers (handle_frame, process_frames, build_packet,
    // generate_ack_frame, handle_loss_detection_result, generate_probe_packets,
    // queue_frames_for_retransmission, update_state) and member fields so
    // tests can drive branches that are otherwise reachable only after a
    // full TLS handshake. The handshake exceeds the wait_for budget under
    // -fprofile-arcs -ftest-coverage instrumentation (Issue #1111 / #1145).
    friend class kcenon::network::tests::support::quic_connection_test_access;
#endif
};
 
} // namespace kcenon::network::protocols::quic