quic_client.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
#ifndef KCENON_NETWORK_INTERNAL_EXPERIMENTAL_QUIC_CLIENT_H_
#define KCENON_NETWORK_INTERNAL_EXPERIMENTAL_QUIC_CLIENT_H_
 
// Experimental API marker - users must opt-in to use this header
#include "internal/experimental/experimental_api.h"
NETWORK_REQUIRE_EXPERIMENTAL
 
#include <atomic>
#include <chrono>
#include <functional>
#include <future>
#include <memory>
#include <mutex>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <system_error>
#include <vector>
 
#include <asio.hpp>
 
#include "internal/core/callback_indices.h"
#include "internal/core/network_context.h"
#include "internal/interfaces/i_quic_client.h"
#include "kcenon/network/integration/thread_integration.h"
#include "kcenon/network/detail/utils/callback_manager.h"
#include "kcenon/network/detail/utils/lifecycle_manager.h"
#include "kcenon/network/detail/utils/result_types.h"
 
// Forward declaration
namespace kcenon::network::internal
{
    class quic_socket;
    enum class quic_role : uint8_t;
} // namespace kcenon::network::internal
 
namespace kcenon::network::core
{
 
    struct quic_client_config
    {
        std::optional<std::string> ca_cert_file;
 
        std::optional<std::string> client_cert_file;
 
        std::optional<std::string> client_key_file;
 
        bool verify_server{true};
 
        std::vector<std::string> alpn_protocols;
 
        uint64_t max_idle_timeout_ms{30000};
 
        uint64_t initial_max_data{1048576};
 
        uint64_t initial_max_stream_data{65536};
 
        uint64_t initial_max_streams_bidi{100};
 
        uint64_t initial_max_streams_uni{100};
 
        bool enable_early_data{false};
 
        std::optional<std::vector<uint8_t>> session_ticket;
 
        uint32_t max_early_data_size{16384};
    };
 
    struct quic_connection_stats
    {
        uint64_t bytes_sent{0};              
        uint64_t bytes_received{0};          
        uint64_t packets_sent{0};            
        uint64_t packets_received{0};        
        uint64_t packets_lost{0};            
        std::chrono::microseconds smoothed_rtt{0}; 
        std::chrono::microseconds min_rtt{0};      
        size_t cwnd{0};                      
    };
 
    class messaging_quic_client
        : public std::enable_shared_from_this<messaging_quic_client>
        , public interfaces::i_quic_client
    {
    public:
        using receive_callback_t = std::function<void(const std::vector<uint8_t>&)>;
        using stream_receive_callback_t = std::function<void(uint64_t, const std::vector<uint8_t>&, bool)>;
        using connected_callback_t = std::function<void()>;
        using disconnected_callback_t = std::function<void()>;
        using error_callback_t = std::function<void(std::error_code)>;
 
        explicit messaging_quic_client(std::string_view client_id);
 
        ~messaging_quic_client() noexcept override;
 
        // Non-copyable, non-movable
        messaging_quic_client(const messaging_quic_client&) = delete;
        messaging_quic_client& operator=(const messaging_quic_client&) = delete;
        messaging_quic_client(messaging_quic_client&&) = delete;
        messaging_quic_client& operator=(messaging_quic_client&&) = delete;
 
        // =====================================================================
        // Lifecycle Management
        // =====================================================================
 
        [[nodiscard]] auto start_client(std::string_view host,
                                        unsigned short port) -> VoidResult;
 
        [[nodiscard]] auto start_client(std::string_view host,
                                        unsigned short port,
                                        const quic_client_config& config) -> VoidResult;
 
        [[nodiscard]] auto stop_client() -> VoidResult;
 
        [[nodiscard]] auto client_id() const -> const std::string&;
 
        // =====================================================================
        // Data Transfer (Default Stream)
        // =====================================================================
 
        [[nodiscard]] auto send_packet(std::vector<uint8_t>&& data) -> VoidResult;
 
        [[nodiscard]] auto send_packet(std::string_view data) -> VoidResult;
 
        [[nodiscard]] auto stats() const -> quic_connection_stats;
 
        // =====================================================================
        // i_network_component interface implementation
        // =====================================================================
 
        [[nodiscard]] auto is_running() const -> bool override;
 
        auto wait_for_stop() -> void override;
 
        // =====================================================================
        // i_quic_client interface implementation
        // =====================================================================
 
        [[nodiscard]] auto start(std::string_view host, uint16_t port) -> VoidResult override;
 
        [[nodiscard]] auto stop() -> VoidResult override;
 
        [[nodiscard]] auto is_connected() const -> bool override;
 
        [[nodiscard]] auto is_handshake_complete() const -> bool override;
 
        [[nodiscard]] auto send(std::vector<uint8_t>&& data) -> VoidResult override;
 
        [[nodiscard]] auto create_stream() -> Result<uint64_t> override;
 
        [[nodiscard]] auto create_unidirectional_stream() -> Result<uint64_t> override;
 
        [[nodiscard]] auto send_on_stream(
            uint64_t stream_id,
            std::vector<uint8_t>&& data,
            bool fin = false) -> VoidResult override;
 
        [[nodiscard]] auto close_stream(uint64_t stream_id) -> VoidResult override;
 
        auto set_alpn_protocols(const std::vector<std::string>& protocols) -> void override;
 
        [[nodiscard]] auto alpn_protocol() const -> std::optional<std::string> override;
 
        [[nodiscard]] auto is_early_data_accepted() const -> bool override;
 
        auto set_receive_callback(interfaces::i_quic_client::receive_callback_t callback) -> void override;
 
        auto set_stream_callback(interfaces::i_quic_client::stream_callback_t callback) -> void override;
 
        auto set_connected_callback(interfaces::i_quic_client::connected_callback_t callback) -> void override;
 
        auto set_disconnected_callback(interfaces::i_quic_client::disconnected_callback_t callback) -> void override;
 
        auto set_error_callback(interfaces::i_quic_client::error_callback_t callback) -> void override;
 
        auto set_session_ticket_callback(interfaces::i_quic_client::session_ticket_callback_t callback) -> void override;
 
        auto set_early_data_callback(interfaces::i_quic_client::early_data_callback_t callback) -> void override;
 
        auto set_early_data_accepted_callback(interfaces::i_quic_client::early_data_accepted_callback_t callback) -> void override;
 
        // =====================================================================
        // Legacy API (maintained for backward compatibility)
        // =====================================================================
 
        auto set_stream_receive_callback(stream_receive_callback_t callback) -> void;
 
    private:
        // =====================================================================
        // Internal Implementation Methods
        // =====================================================================
 
        auto do_start_impl(std::string_view host, unsigned short port) -> VoidResult;
 
        auto do_stop_impl() -> VoidResult;
 
        auto do_connect(std::string_view host, unsigned short port) -> void;
 
        auto on_connect() -> void;
 
        auto on_stream_data(uint64_t stream_id,
                            std::span<const uint8_t> data,
                            bool fin) -> void;
 
        auto on_error(std::error_code ec) -> void;
 
        auto on_close(uint64_t error_code, const std::string& reason) -> void;
 
        auto get_socket() const -> std::shared_ptr<internal::quic_socket>;
 
        // =====================================================================
        // Internal Callback Helpers
        // =====================================================================
 
        auto invoke_receive_callback(const std::vector<uint8_t>& data) -> void;
 
        auto invoke_stream_receive_callback(uint64_t stream_id,
                                            const std::vector<uint8_t>& data,
                                            bool fin) -> void;
 
        auto invoke_connected_callback() -> void;
 
        auto invoke_disconnected_callback() -> void;
 
        auto invoke_error_callback(std::error_code ec) -> void;
 
        using callback_index = quic_client_callback;
 
        using callbacks_t = utils::callback_manager<
            receive_callback_t,
            stream_receive_callback_t,
            connected_callback_t,
            disconnected_callback_t,
            error_callback_t
        >;
 
        // =====================================================================
        // Member Variables
        // =====================================================================
 
        std::string client_id_;                          
        utils::lifecycle_manager lifecycle_;             
        callbacks_t callbacks_;                          
        std::atomic<bool> is_connected_{false};          
        std::unique_ptr<asio::io_context> io_context_;  
        std::unique_ptr<asio::executor_work_guard<asio::io_context::executor_type>>
            work_guard_; 
        std::shared_ptr<integration::thread_pool_interface>
            thread_pool_;                        
        std::future<void> io_context_future_;    
 
        mutable std::mutex socket_mutex_;  
        std::shared_ptr<internal::quic_socket> socket_; 
 
        quic_client_config config_;  
        uint64_t default_stream_id_{0}; 
 
        std::atomic<bool> handshake_complete_{false}; 
 
        // 0-RTT callbacks
        interfaces::i_quic_client::session_ticket_callback_t session_ticket_cb_; 
        interfaces::i_quic_client::early_data_callback_t early_data_cb_; 
        interfaces::i_quic_client::early_data_accepted_callback_t early_data_accepted_cb_; 
        std::atomic<bool> early_data_accepted_{false}; 
    };
 
// =====================================================================
// Unified Pattern Type Aliases
// =====================================================================
// These aliases provide a consistent API pattern across all protocols,
// making QUIC clients accessible via the unified template naming.
// See: unified_messaging_client.h for TCP, unified_udp_messaging_client.h for UDP.
 
using quic_client = messaging_quic_client;
 
using secure_quic_client = messaging_quic_client;
 
} // namespace kcenon::network::core
 
#endif // KCENON_NETWORK_INTERNAL_EXPERIMENTAL_QUIC_CLIENT_H_