quic_server.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
 
// Experimental API marker - users must opt-in to use this header
#include "internal/experimental/experimental_api.h"
NETWORK_REQUIRE_EXPERIMENTAL
 
#include <kcenon/network/detail/config/feature_flags.h>
 
#include "internal/core/callback_indices.h"
#include "internal/experimental/quic_client.h"
#include "internal/core/network_context.h"
#include "internal/interfaces/i_quic_server.h"
#include "kcenon/network/integration/thread_integration.h"
#include "kcenon/network/detail/protocols/quic/connection_id.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"
 
#include <array>
#include <atomic>
#include <functional>
#include <future>
#include <map>
#include <memory>
#include <mutex>
#include <optional>
#include <shared_mutex>
#include <span>
#include <string>
#include <string_view>
#include <system_error>
#include <vector>
 
#include <asio.hpp>
 
// Optional monitoring support via common_system
#if KCENON_WITH_COMMON_SYSTEM
    #include <kcenon/common/interfaces/monitoring_interface.h>
#endif // KCENON_WITH_COMMON_SYSTEM
 
namespace kcenon::network::internal
{
    class quic_socket;
} // namespace kcenon::network::internal
 
namespace kcenon::network::session
{
    class quic_session;
} // namespace kcenon::network::session
 
#if defined(NETWORK_ENABLE_TEST_INJECTION)
namespace kcenon::network::tests::support
{
    class quic_server_probe;
} // namespace kcenon::network::tests::support
#endif
 
namespace kcenon::network::core
{
 
    struct quic_server_config
    {
        std::string cert_file;
 
        std::string key_file;
 
        std::optional<std::string> ca_cert_file;
 
        bool require_client_cert{false};
 
        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};
 
        size_t max_connections{10000};
 
        bool enable_retry{true};
 
        std::vector<uint8_t> retry_key;
    };
 
    class messaging_quic_server
        : public std::enable_shared_from_this<messaging_quic_server>
        , public interfaces::i_quic_server
    {
    public:
        using connection_callback_t = std::function<void(std::shared_ptr<session::quic_session>)>;
        using disconnection_callback_t = std::function<void(std::shared_ptr<session::quic_session>)>;
        using receive_callback_t = std::function<void(std::shared_ptr<session::quic_session>,
                                                       const std::vector<uint8_t>&)>;
        using stream_receive_callback_t = std::function<void(std::shared_ptr<session::quic_session>,
                                                              uint64_t,
                                                              const std::vector<uint8_t>&,
                                                              bool)>;
        using error_callback_t = std::function<void(std::error_code)>;
 
        explicit messaging_quic_server(std::string_view server_id);
 
        ~messaging_quic_server() noexcept override;
 
        // Non-copyable, non-movable
        messaging_quic_server(const messaging_quic_server&) = delete;
        messaging_quic_server& operator=(const messaging_quic_server&) = delete;
        messaging_quic_server(messaging_quic_server&&) = delete;
        messaging_quic_server& operator=(messaging_quic_server&&) = delete;
 
        // =====================================================================
        // Server Lifecycle
        // =====================================================================
 
        [[nodiscard]] auto start_server(unsigned short port) -> VoidResult;
 
        [[nodiscard]] auto start_server(unsigned short port,
                                        const quic_server_config& config)
            -> VoidResult;
 
        [[nodiscard]] auto stop_server() -> VoidResult;
 
        [[nodiscard]] auto server_id() const -> const std::string&;
 
        // =====================================================================
        // Session Management
        // =====================================================================
 
        [[nodiscard]] auto sessions() const
            -> std::vector<std::shared_ptr<session::quic_session>>;
 
        [[nodiscard]] auto get_session(const std::string& session_id)
            -> std::shared_ptr<session::quic_session>;
 
        [[nodiscard]] auto session_count() const -> size_t;
 
        [[nodiscard]] auto disconnect_session(const std::string& session_id,
                                              uint64_t error_code = 0)
            -> VoidResult;
 
        auto disconnect_all(uint64_t error_code = 0) -> void;
 
        // =====================================================================
        // Broadcasting
        // =====================================================================
 
        [[nodiscard]] auto broadcast(std::vector<uint8_t>&& data) -> VoidResult;
 
        [[nodiscard]] auto multicast(const std::vector<std::string>& session_ids,
                                     std::vector<uint8_t>&& data) -> VoidResult;
 
        // =====================================================================
        // i_network_component interface implementation
        // =====================================================================
 
        [[nodiscard]] auto is_running() const -> bool override;
 
        auto wait_for_stop() -> void override;
 
        // =====================================================================
        // i_quic_server interface implementation
        // =====================================================================
 
        [[nodiscard]] auto start(uint16_t port) -> VoidResult override;
 
        [[nodiscard]] auto stop() -> VoidResult override;
 
        [[nodiscard]] auto connection_count() const -> size_t override;
 
        auto set_connection_callback(interfaces::i_quic_server::connection_callback_t callback) -> void override;
 
        auto set_disconnection_callback(interfaces::i_quic_server::disconnection_callback_t callback) -> void override;
 
        auto set_receive_callback(interfaces::i_quic_server::receive_callback_t callback) -> void override;
 
        auto set_stream_callback(interfaces::i_quic_server::stream_callback_t callback) -> void override;
 
        auto set_error_callback(interfaces::i_quic_server::error_callback_t callback) -> void override;
 
        // =====================================================================
        // Legacy API (maintained for backward compatibility)
        // =====================================================================
 
        auto set_connection_callback(connection_callback_t callback) -> void;
 
        auto set_disconnection_callback(disconnection_callback_t callback) -> void;
 
        auto set_receive_callback(receive_callback_t callback) -> void;
 
        auto set_stream_receive_callback(stream_receive_callback_t callback) -> void;
 
        auto set_error_callback(error_callback_t callback) -> void;
 
#if KCENON_WITH_COMMON_SYSTEM
        auto set_monitor(kcenon::common::interfaces::IMonitor* monitor) -> void;
 
        auto get_monitor() const -> kcenon::common::interfaces::IMonitor*;
#endif // KCENON_WITH_COMMON_SYSTEM
 
    private:
#if defined(NETWORK_ENABLE_TEST_INJECTION)
        // Test-only: grants tests/support/quic_server_probe access to private
        // surfaces without leaking them through the public API.
        friend class kcenon::network::tests::support::quic_server_probe;
#endif
 
        // =====================================================================
        // Internal Implementation Methods
        // =====================================================================
 
        auto do_start_impl(unsigned short port) -> VoidResult;
 
        auto do_stop_impl() -> VoidResult;
 
        auto start_receive() -> void;
 
        auto handle_packet(std::span<const uint8_t> data,
                           const asio::ip::udp::endpoint& from) -> void;
 
        auto find_or_create_session(
            const protocols::quic::connection_id& dcid,
            const asio::ip::udp::endpoint& endpoint)
            -> std::shared_ptr<session::quic_session>;
 
        auto generate_session_id() -> std::string;
 
        auto on_session_close(const std::string& session_id) -> void;
 
        auto start_cleanup_timer() -> void;
 
        auto cleanup_dead_sessions() -> void;
 
        // =====================================================================
        // Internal Callback Helpers
        // =====================================================================
 
        auto invoke_connection_callback(std::shared_ptr<session::quic_session> session) -> void;
 
        auto invoke_disconnection_callback(std::shared_ptr<session::quic_session> session) -> void;
 
        auto invoke_receive_callback(std::shared_ptr<session::quic_session> session,
                                     const std::vector<uint8_t>& data) -> void;
 
        auto invoke_stream_receive_callback(std::shared_ptr<session::quic_session> session,
                                            uint64_t stream_id,
                                            const std::vector<uint8_t>& data,
                                            bool fin) -> void;
 
        auto invoke_error_callback(std::error_code ec) -> void;
 
        using callback_index = quic_server_callback;
 
        using callbacks_t = utils::callback_manager<
            connection_callback_t,
            disconnection_callback_t,
            receive_callback_t,
            stream_receive_callback_t,
            error_callback_t
        >;
 
        // =====================================================================
        // Member Variables
        // =====================================================================
 
        std::string server_id_;                          
        utils::lifecycle_manager lifecycle_;             
        callbacks_t callbacks_;                          
        std::unique_ptr<asio::io_context> io_context_;
        std::unique_ptr<asio::executor_work_guard<asio::io_context::executor_type>>
            work_guard_;
        std::unique_ptr<asio::ip::udp::socket> udp_socket_;
        std::shared_ptr<integration::thread_pool_interface> thread_pool_;
        std::future<void> io_context_future_;
 
        quic_server_config config_;
 
        // Session management
        mutable std::shared_mutex sessions_mutex_;
        std::map<std::string, std::shared_ptr<session::quic_session>> sessions_;
 
        // Receive buffer
        std::array<uint8_t, 65536> recv_buffer_;
        asio::ip::udp::endpoint recv_endpoint_;
 
        // Cleanup timer
        std::unique_ptr<asio::steady_timer> cleanup_timer_;
 
        // Session ID counter
        std::atomic<uint64_t> session_counter_{0};
 
        // Interface callback storage (separate from legacy callbacks)
        interfaces::i_quic_server::error_callback_t interface_error_cb_;
 
#if KCENON_WITH_COMMON_SYSTEM
        kcenon::common::interfaces::IMonitor* monitor_ = nullptr;
        std::atomic<uint64_t> messages_received_{0};
        std::atomic<uint64_t> messages_sent_{0};
        std::atomic<uint64_t> connection_errors_{0};
#endif // KCENON_WITH_COMMON_SYSTEM
    };
 
// =====================================================================
// Unified Pattern Type Aliases
// =====================================================================
// These aliases provide a consistent API pattern across all protocols,
// making QUIC servers accessible via the unified template naming.
// See: unified_messaging_server.h for TCP, unified_udp_messaging_server.h for UDP.
 
using quic_server = messaging_quic_server;
 
using secure_quic_server = messaging_quic_server;
 
} // namespace kcenon::network::core