kcenon::network::protocol::quic Namespace Reference

Classes
struct	quic_config
	Configuration options for QUIC connections. More...

Functions
auto	create_connection (const quic_config &config={}, std::string_view id="") -> std::unique_ptr< unified::i_connection >
	Creates a QUIC connection (not yet connected)
auto	connect (const unified::endpoint_info &endpoint, const quic_config &config={}, std::string_view id="") -> std::unique_ptr< unified::i_connection >
	Creates and connects a QUIC connection in one call.
auto	connect (std::string_view url, const quic_config &config={}, std::string_view id="") -> std::unique_ptr< unified::i_connection >
	Creates and connects a QUIC connection using URL format.
auto	create_listener (const quic_config &config, std::string_view id="") -> std::unique_ptr< unified::i_listener >
	Creates a QUIC listener (not yet listening)
auto	listen (const unified::endpoint_info &bind_address, const quic_config &config, std::string_view id="") -> std::unique_ptr< unified::i_listener >
	Creates and starts a QUIC listener in one call.
auto	listen (uint16_t port, const quic_config &config, std::string_view id="") -> std::unique_ptr< unified::i_listener >
	Creates and starts a QUIC listener on a specific port.

Function Documentation

connect() [1/2]

auto kcenon::network::protocol::quic::connect ( const unified::endpoint_info & endpoint, const quic_config & config = {}, std::string_view id = "" ) -> std::unique_ptr<unified::i_connection>

nodiscard

Creates and connects a QUIC connection in one call.

Parameters

endpoint	The remote endpoint to connect to
config	QUIC configuration options
id	Optional unique identifier for the connection

Returns

Unique pointer to an i_connection instance (connecting)

This is a convenience function that creates a connection and immediately initiates the QUIC handshake to the specified endpoint.

Usage Example

quic_config cfg;
cfg.server_name = "example.com";
 
auto conn = protocol::quic::connect({"example.com", 443}, cfg);
conn->set_callbacks({
    .on_connected = []() { std::cout << "Connected!\n"; }
});
// QUIC handshake is already in progress

Definition at line 85 of file quic.cpp.

{
    // Ensure server_name is set for TLS
    quic_config cfg = config;
    if (cfg.server_name.empty()) {
        cfg.server_name = endpoint.host;
    }
 
    auto conn = create_connection(cfg, id);
    // Initiate connection (async, will complete in background)
    (void)conn->connect(endpoint);
    return conn;
}

References config, create_connection(), and kcenon::network::protocol::quic::quic_config::server_name.

Here is the call graph for this function:

connect() [2/2]

auto kcenon::network::protocol::quic::connect ( std::string_view url, const quic_config & config = {}, std::string_view id = "" ) -> std::unique_ptr<unified::i_connection>

nodiscard

Creates and connects a QUIC connection using URL format.

Parameters

url	The URL to connect to (format: "quic://host:port" or "host:port")
config	QUIC configuration options
id	Optional unique identifier for the connection

Returns

Unique pointer to an i_connection instance (connecting)

If server_name is not set in config, it will be extracted from the URL.

Definition at line 101 of file quic.cpp.

{
    auto [host, port] = parse_url(url);
    if (host.empty() || port == 0) {
        // Return a connection that will fail on connect
        return create_connection(config, id);
    }
 
    // Ensure server_name is set for TLS
    quic_config cfg = config;
    if (cfg.server_name.empty()) {
        cfg.server_name = host;
    }
 
    auto conn = create_connection(cfg, id);
    (void)conn->connect(unified::endpoint_info{host, port});
    return conn;
}

References config, create_connection(), and kcenon::network::protocol::quic::quic_config::server_name.

Here is the call graph for this function:

create_connection()

auto kcenon::network::protocol::quic::create_connection ( const quic_config & config = {}, std::string_view id = "" ) -> std::unique_ptr<unified::i_connection>

nodiscard

Creates a QUIC connection (not yet connected)

Parameters

config	QUIC configuration options
id	Optional unique identifier for the connection

Returns

Unique pointer to an i_connection instance

The returned connection is not connected. Call connect() to establish the connection to a remote endpoint.

QUIC Semantics

QUIC connections have built-in TLS 1.3 encryption, multiplexed streams, and support for connection migration.

• connect() initiates the QUIC handshake
• is_connected() returns true after handshake completion
• send() sends data on the default stream

Usage Example

quic_config cfg;
cfg.server_name = "example.com";
cfg.alpn_protocols = {"h3"};
 
auto conn = protocol::quic::create_connection(cfg, "my-quic-client");
conn->set_callbacks({
    .on_connected = []() { std::cout << "Connected!\n"; },
    .on_data = [](std::span<const std::byte> data) {
        // Handle received data
    }
});
conn->connect({"example.com", 443});

Definition at line 74 of file quic.cpp.

{
    std::string connection_id = id.empty()
        ? generate_unique_id("quic-conn")
        : std::string(id);
 
    return std::make_unique<unified::adapters::quic_connection_adapter>(
        config, connection_id);
}

References config.

Referenced by connect(), and connect().

Here is the caller graph for this function:

create_listener()

auto kcenon::network::protocol::quic::create_listener ( const quic_config & config, std::string_view id = "" ) -> std::unique_ptr<unified::i_listener>

nodiscard

Creates a QUIC listener (not yet listening)

Parameters

config	QUIC configuration options (cert_file and key_file required)
id	Optional unique identifier for the listener

Returns

Unique pointer to an i_listener instance

The returned listener is not listening. Call start() to begin accepting connections.

QUIC Server Requirements

QUIC servers require TLS certificates. The cert_file and key_file must be set in the configuration.

Usage Example

quic_config cfg;
cfg.cert_file = "/path/to/cert.pem";
cfg.key_file = "/path/to/key.pem";
cfg.alpn_protocols = {"h3"};
 
auto listener = protocol::quic::create_listener(cfg, "my-quic-server");
listener->set_callbacks({
    .on_accept = [](std::string_view conn_id) {
        std::cout << "New connection: " << conn_id << "\n";
    },
    .on_data = [](std::string_view conn_id, std::span<const std::byte> data) {
        // Handle received data from conn_id
    }
});
listener->start(443);

Definition at line 122 of file quic.cpp.

{
    std::string listener_id = id.empty()
        ? generate_unique_id("quic-listener")
        : std::string(id);
 
    return std::make_unique<unified::adapters::quic_listener_adapter>(
        config, listener_id);
}

References config.

Referenced by listen().

Here is the caller graph for this function:

listen() [1/2]

auto kcenon::network::protocol::quic::listen ( const unified::endpoint_info & bind_address, const quic_config & config, std::string_view id = "" ) -> std::unique_ptr<unified::i_listener>

nodiscard

Creates and starts a QUIC listener in one call.

Parameters

bind_address	The local address to bind to
config	QUIC configuration options (cert_file and key_file required)
id	Optional unique identifier for the listener

Returns

Unique pointer to an i_listener instance (listening)

This is a convenience function that creates a listener and immediately starts listening on the specified address.

Usage Example

quic_config cfg;
cfg.cert_file = "/path/to/cert.pem";
cfg.key_file = "/path/to/key.pem";
 
auto listener = protocol::quic::listen({"0.0.0.0", 443}, cfg);
listener->set_callbacks({
    .on_accept = [](std::string_view conn_id) { }
});
// Listener is already accepting connections

Definition at line 133 of file quic.cpp.

{
    auto listener = create_listener(config, id);
    (void)listener->start(bind_address);
    return listener;
}

References config, and create_listener().

Referenced by listen().

Here is the call graph for this function:

Here is the caller graph for this function:

listen() [2/2]

auto kcenon::network::protocol::quic::listen ( uint16_t port, const quic_config & config, std::string_view id = "" ) -> std::unique_ptr<unified::i_listener>

nodiscard

Creates and starts a QUIC listener on a specific port.

Parameters

port	The port number to listen on
config	QUIC configuration options (cert_file and key_file required)
id	Optional unique identifier for the listener

Returns

Unique pointer to an i_listener instance (listening)

Convenience overload that binds to all interfaces (0.0.0.0).

Definition at line 142 of file quic.cpp.

{
    return listen(unified::endpoint_info{"0.0.0.0", port}, config, id);
}

References config, and listen().

Here is the call graph for this function: