Kurlyk
Loading...
Searching...
No Matches
kurlyk::WebSocketClient Class Reference

Public facade for managing WebSocket connections, events, and message sending. More...

#include <WebSocketClient.hpp>

Public Member Functions

 WebSocketClient ()
 Initializes the WebSocket client facade and its backend-specific implementation.
 WebSocketClient (std::unique_ptr< WebSocketConfig > config, std::function< void(bool)> callback=nullptr)
 Initializes the facade with a WebSocket configuration object.
 WebSocketClient (const std::string &url, const Headers &headers=Headers(), const std::string &proxy_server=std::string(), const std::string &proxy_auth=std::string(), ProxyType proxy_type=ProxyType::PROXY_HTTP, long request_timeout=20, bool reconnect=true, bool verify_cert=true, const std::string &ca_file=std::string(), int rpm=200)
 Initializes the facade with URL-based configuration values.
 WebSocketClient (const WebSocketClient &)=delete
WebSocketClientoperator= (const WebSocketClient &)=delete
virtual ~WebSocketClient ()
 Schedules backend shutdown through NetworkWorker before the facade is destroyed.
void on_event (std::function< void(std::unique_ptr< WebSocketEventData >)> callback)
 Sets a callback for WebSocket events.
std::function< void(std::unique_ptr< WebSocketEventData >)> & event_handler ()
 Accessor for the event handler function.
std::future< bool > set_config (std::unique_ptr< WebSocketConfig > config)
 Asynchronously sets the WebSocket configuration.
void set_config (std::unique_ptr< WebSocketConfig > config, std::function< void(bool)> callback)
 Sets the WebSocket configuration and executes a callback upon completion.
std::future< bool > connect ()
 Asynchronously connects to the WebSocket server.
void connect (std::function< void(bool)> callback)
 Connects to the WebSocket server and executes a callback upon completion.
bool connect_and_wait ()
 Connects to the WebSocket server, blocking until the connection completes.
std::future< bool > disconnect ()
 Asynchronously disconnects from the WebSocket server.
bool disconnect_and_wait ()
 Disconnects from the WebSocket server, blocking until the disconnection completes.
void disconnect (std::function< void(bool success)> callback)
 Disconnects from the WebSocket server and invokes a callback upon completion.
const bool is_connected () const
 Checks if the WebSocket is connected.
SubmitResult submit_message (const std::string &message, long rate_limit_id=0, std::function< void(const std::error_code &)> callback=nullptr)
 Attempts to submit a message through the WebSocket.
bool send_message (const std::string &message, long rate_limit_id=0, std::function< void(const std::error_code &)> callback=nullptr)
 Sends a message through the WebSocket.
SubmitResult submit_close (const int status=1000, const std::string &reason=std::string(), std::function< void(const std::error_code &)> callback=nullptr)
 Attempts to submit a close request to the WebSocket server.
bool send_close (const int status=1000, const std::string &reason=std::string(), std::function< void(const std::error_code &)> callback=nullptr)
 Sends a close request to the WebSocket server.
std::list< std::unique_ptr< WebSocketEventData > > receive_events ()
 Retrieves all pending WebSocket events in a batch.
std::unique_ptr< WebSocketEventDatareceive_event ()
 Retrieves a single WebSocket event, if available.
std::string get_http_version () const
 Retrieves the HTTP version used in the WebSocket connection.
Headers get_headers () const
 Retrieves the headers associated with the WebSocket connection.
std::string get_remote_endpoint () const
 Retrieves the remote endpoint information.
void set_url (const std::string &host, const std::string &path, const std::string &query="")
 Sets the WebSocket server URL with optional query parameters.
void set_url (const std::string &url, const QueryParams &query)
 Sets the WebSocket server URL with specified query parameters.
void set_accept_encoding (bool identity=false, bool deflate=false, bool gzip=false, bool brotli=false)
 Sets the Accept-Encoding header with specified encodings.
void set_proxy (const std::string &ip, int port, ProxyType type=ProxyType::PROXY_HTTP)
 Sets the proxy server address.
void set_proxy (const std::string &ip, int port, const std::string &username, const std::string &password, ProxyType type=ProxyType::PROXY_HTTP)
 Sets the proxy server address with authentication.
void set_proxy_server (const std::string &server)
 Sets the proxy server address.
void set_proxy_auth (const std::string &auth)
 Sets the proxy authentication credentials.
void set_proxy_type (ProxyType type)
 Sets the proxy type.
void set_proxy_auth (const std::string &username, const std::string &password)
 Configures proxy authentication credentials.
void set_reconnect (bool reconnect, long reconnect_attempts=0, long reconnect_delay=0)
 Configures reconnection behavior.
void set_user_agent (const std::string &user_agent)
 Sets the User-Agent header.
void set_accept_language (const std::string &accept_language)
 Sets the Accept-Language header.
void set_cookie (const std::string &cookie)
 Sets the cookie data.
void set_idle_timeout (long idle_timeout)
 Configures the idle timeout for the WebSocket connection.
void set_request_timeout (long request_timeout)
 Sets the timeout for WebSocket requests.
void set_max_send_queue_size (std::size_t max_send_queue_size)
 Sets the maximum number of outbound send operations queued for this client.
void set_ca_file (const std::string &ca_file)
 Sets the path to the CA certificate file.
void set_ca_file (bool verify_cert, const std::string &ca_file)
 Sets certificate verification and sets the CA certificate file.
void set_verify_cert (bool verify_cert)
 Sets whether to verify the server’s certificate.
long add_rate_limit (long requests_per_period, long period_ms)
 Adds a rate limit configuration to control the frequency of WebSocket messages.
long add_rate_limit_rpm (long requests_per_minute)
 Adds a rate limit based on Requests Per Minute (RPM).
long add_rate_limit_rps (long requests_per_second)
 Adds a rate limit based on Requests Per Second (RPS).

Private Member Functions

void init_config ()
 Initializes the WebSocket configuration if it is not already set.

Static Private Member Functions

static void ensure_initialized ()
 Ensures the WebSocket and network components are initialized.

Private Attributes

selected_backend_client_ptr m_client
 Backend-specific WebSocket client selected by compile-time platform macros.
std::unique_ptr< WebSocketConfigm_config
 Deferred WebSocket configuration copied into the backend before connect().

Detailed Description

Public facade for managing WebSocket connections, events, and message sending.

Internally owns a backend-specific WebSocket client selected at compile time for the active platform.

Definition at line 15 of file WebSocketClient.hpp.

Constructor & Destructor Documentation

◆ WebSocketClient() [1/4]

kurlyk::WebSocketClient::WebSocketClient ( )
inline

Initializes the WebSocket client facade and its backend-specific implementation.

Definition at line 19 of file WebSocketClient.hpp.

◆ WebSocketClient() [2/4]

kurlyk::WebSocketClient::WebSocketClient ( std::unique_ptr< WebSocketConfig > config,
std::function< void(bool)> callback = nullptr )
inline

Initializes the facade with a WebSocket configuration object.

Parameters
configA unique pointer to a WebSocketConfig object.
callbackCallback invoked when configuration is completed.

Definition at line 30 of file WebSocketClient.hpp.

◆ WebSocketClient() [3/4]

kurlyk::WebSocketClient::WebSocketClient ( const std::string & url,
const Headers & headers = Headers(),
const std::string & proxy_server = std::string(),
const std::string & proxy_auth = std::string(),
ProxyType proxy_type = ProxyType::PROXY_HTTP,
long request_timeout = 20,
bool reconnect = true,
bool verify_cert = true,
const std::string & ca_file = std::string(),
int rpm = 200 )
inline

Initializes the facade with URL-based configuration values.

Parameters
urlThe WebSocket server URL.
headersHTTP headers included in the WebSocket connection request.
proxy_serverProxy address in <ip:port> format.
proxy_authProxy authentication in <username:password> format.
proxy_typeProxy type (e.g., HTTP, SOCKS5).
request_timeoutTimeout for WebSocket requests in seconds (0 means no timeout).
reconnectEnables automatic reconnection if true.
verify_certIf true, verifies the server’s certificate and hostname according to RFC 2818.
ca_filePath to the Root CA certificate file.
rpmRequests per minute (RPM).

Definition at line 50 of file WebSocketClient.hpp.

◆ WebSocketClient() [4/4]

kurlyk::WebSocketClient::WebSocketClient ( const WebSocketClient & )
delete

◆ ~WebSocketClient()

virtual kurlyk::WebSocketClient::~WebSocketClient ( )
inlinevirtual

Schedules backend shutdown through NetworkWorker before the facade is destroyed.

Definition at line 84 of file WebSocketClient.hpp.

Member Function Documentation

◆ add_rate_limit()

long kurlyk::WebSocketClient::add_rate_limit ( long requests_per_period,
long period_ms )
inline

Adds a rate limit configuration to control the frequency of WebSocket messages.

The first rate limit added will serve as the primary rate limit, applying to all WebSocket requests by default. Additional rate limits can be added for specific types of requests or contexts as needed.

Parameters
requests_per_periodThe maximum number of messages allowed within the specified period.
period_msThe time period in milliseconds during which the request limit applies.
Returns
The index of the added rate limit configuration.

Definition at line 442 of file WebSocketClient.hpp.

◆ add_rate_limit_rpm()

long kurlyk::WebSocketClient::add_rate_limit_rpm ( long requests_per_minute)
inline

Adds a rate limit based on Requests Per Minute (RPM).

Parameters
requests_per_minuteMaximum number of requests allowed per minute.
Returns
The index of the added rate limit configuration.

Definition at line 450 of file WebSocketClient.hpp.

◆ add_rate_limit_rps()

long kurlyk::WebSocketClient::add_rate_limit_rps ( long requests_per_second)
inline

Adds a rate limit based on Requests Per Second (RPS).

Parameters
requests_per_secondMaximum number of requests allowed per second.
Returns
The index of the added rate limit configuration.

Definition at line 458 of file WebSocketClient.hpp.

◆ connect() [1/2]

std::future< bool > kurlyk::WebSocketClient::connect ( )
inline

Asynchronously connects to the WebSocket server.

Returns
A future containing the success status of the connection.

Definition at line 126 of file WebSocketClient.hpp.

◆ connect() [2/2]

void kurlyk::WebSocketClient::connect ( std::function< void(bool)> callback)
inline

Connects to the WebSocket server and executes a callback upon completion.

Parameters
callbackThe callback function to execute after connection, receiving a success status.

Definition at line 146 of file WebSocketClient.hpp.

◆ connect_and_wait()

bool kurlyk::WebSocketClient::connect_and_wait ( )
inline

Connects to the WebSocket server, blocking until the connection completes.

Returns
True if the connection was successful, or false if it failed.

Definition at line 161 of file WebSocketClient.hpp.

◆ disconnect() [1/2]

std::future< bool > kurlyk::WebSocketClient::disconnect ( )
inline

Asynchronously disconnects from the WebSocket server.

Returns
A future containing the success status of the disconnection.

Definition at line 168 of file WebSocketClient.hpp.

◆ disconnect() [2/2]

void kurlyk::WebSocketClient::disconnect ( std::function< void(bool success)> callback)
inline

Disconnects from the WebSocket server and invokes a callback upon completion.

Parameters
callbackThe callback function to execute after disconnection, receiving a success status.

Definition at line 187 of file WebSocketClient.hpp.

◆ disconnect_and_wait()

bool kurlyk::WebSocketClient::disconnect_and_wait ( )
inline

Disconnects from the WebSocket server, blocking until the disconnection completes.

Returns
True if the disconnection was successful, or false if it failed.

Definition at line 180 of file WebSocketClient.hpp.

◆ ensure_initialized()

void kurlyk::WebSocketClient::ensure_initialized ( )
inlinestaticprivate

Ensures the WebSocket and network components are initialized.

This method is called only once per application run.

Definition at line 480 of file WebSocketClient.hpp.

◆ event_handler()

std::function< void(std::unique_ptr< WebSocketEventData >)> & kurlyk::WebSocketClient::event_handler ( )
inline

Accessor for the event handler function.

Returns
A reference to the event handler callback function for WebSocket events.

Definition at line 99 of file WebSocketClient.hpp.

◆ get_headers()

Headers kurlyk::WebSocketClient::get_headers ( ) const
inline

Retrieves the headers associated with the WebSocket connection.

Returns
A Headers object containing the HTTP headers.

Definition at line 266 of file WebSocketClient.hpp.

◆ get_http_version()

std::string kurlyk::WebSocketClient::get_http_version ( ) const
inline

Retrieves the HTTP version used in the WebSocket connection.

Returns
The HTTP version string.

Definition at line 260 of file WebSocketClient.hpp.

◆ get_remote_endpoint()

std::string kurlyk::WebSocketClient::get_remote_endpoint ( ) const
inline

Retrieves the remote endpoint information.

Returns
The remote endpoint as a string in the format "IP:Port".

Definition at line 272 of file WebSocketClient.hpp.

◆ init_config()

void kurlyk::WebSocketClient::init_config ( )
inlineprivate

Initializes the WebSocket configuration if it is not already set.

Definition at line 468 of file WebSocketClient.hpp.

◆ is_connected()

const bool kurlyk::WebSocketClient::is_connected ( ) const
inline

Checks if the WebSocket is connected.

Returns
True if the WebSocket is connected, false otherwise.

Definition at line 194 of file WebSocketClient.hpp.

◆ on_event()

void kurlyk::WebSocketClient::on_event ( std::function< void(std::unique_ptr< WebSocketEventData >)> callback)
inline

Sets a callback for WebSocket events.

Parameters
callbackThe function to be executed on each WebSocket event.

Definition at line 93 of file WebSocketClient.hpp.

◆ operator=()

WebSocketClient & kurlyk::WebSocketClient::operator= ( const WebSocketClient & )
delete

◆ receive_event()

std::unique_ptr< WebSocketEventData > kurlyk::WebSocketClient::receive_event ( )
inline

Retrieves a single WebSocket event, if available.

Returns
A unique pointer to a WebSocketEventData object representing a single event, or nullptr if no events are available.

Definition at line 254 of file WebSocketClient.hpp.

◆ receive_events()

std::list< std::unique_ptr< WebSocketEventData > > kurlyk::WebSocketClient::receive_events ( )
inline

Retrieves all pending WebSocket events in a batch.

Returns
A list of unique pointers to WebSocketEventData objects representing events.

Definition at line 248 of file WebSocketClient.hpp.

◆ send_close()

bool kurlyk::WebSocketClient::send_close ( const int status = 1000,
const std::string & reason = std::string(),
std::function< void(const std::error_code &)> callback = nullptr )
inline

Sends a close request to the WebSocket server.

Parameters
statusThe status code for the close request (default: 1000).
reasonOptional reason for closing the connection.
callbackOptional callback to execute after sending the close request.
Returns
True if the close request was successfully queued, false otherwise.

Definition at line 239 of file WebSocketClient.hpp.

◆ send_message()

bool kurlyk::WebSocketClient::send_message ( const std::string & message,
long rate_limit_id = 0,
std::function< void(const std::error_code &)> callback = nullptr )
inline

Sends a message through the WebSocket.

Parameters
messageThe content of the message to be sent.
rate_limit_idThe ID of the rate limit to apply to this message. A value of 0 indicates the default or no rate limit.
callbackAn optional callback to execute after sending the message.
Returns
True if the message was successfully queued, false otherwise.

Definition at line 215 of file WebSocketClient.hpp.

◆ set_accept_encoding()

void kurlyk::WebSocketClient::set_accept_encoding ( bool identity = false,
bool deflate = false,
bool gzip = false,
bool brotli = false )
inline

Sets the Accept-Encoding header with specified encodings.

Parameters
identityEnables identity encoding.
deflateEnables deflate encoding.
gzipEnables gzip encoding.
brotliEnables brotli encoding.

Definition at line 298 of file WebSocketClient.hpp.

◆ set_accept_language()

void kurlyk::WebSocketClient::set_accept_language ( const std::string & accept_language)
inline

Sets the Accept-Language header.

Parameters
accept_languageAccept-Language string.

Definition at line 378 of file WebSocketClient.hpp.

◆ set_ca_file() [1/2]

void kurlyk::WebSocketClient::set_ca_file ( bool verify_cert,
const std::string & ca_file )
inline

Sets certificate verification and sets the CA certificate file.

Parameters
verify_certIf true, enables server certificate verification.
ca_filePath to the CA certificate file.

Definition at line 421 of file WebSocketClient.hpp.

◆ set_ca_file() [2/2]

void kurlyk::WebSocketClient::set_ca_file ( const std::string & ca_file)
inline

Sets the path to the CA certificate file.

Parameters
ca_filePath to the CA certificate file.

Definition at line 413 of file WebSocketClient.hpp.

◆ set_config() [1/2]

std::future< bool > kurlyk::WebSocketClient::set_config ( std::unique_ptr< WebSocketConfig > config)
inline

Asynchronously sets the WebSocket configuration.

Parameters
configA unique pointer to the WebSocket configuration object.
Returns
A future containing the success status of the configuration setup.

Definition at line 106 of file WebSocketClient.hpp.

◆ set_config() [2/2]

void kurlyk::WebSocketClient::set_config ( std::unique_ptr< WebSocketConfig > config,
std::function< void(bool)> callback )
inline

Sets the WebSocket configuration and executes a callback upon completion.

Parameters
configA unique pointer to the WebSocket configuration object.
callbackThe callback function to execute after setting the configuration, receiving a success status.

Definition at line 119 of file WebSocketClient.hpp.

◆ set_cookie()

void kurlyk::WebSocketClient::set_cookie ( const std::string & cookie)
inline

Sets the cookie data.

Parameters
cookieCookie data string.

Definition at line 385 of file WebSocketClient.hpp.

◆ set_idle_timeout()

void kurlyk::WebSocketClient::set_idle_timeout ( long idle_timeout)
inline

Configures the idle timeout for the WebSocket connection.

Parameters
idle_timeoutIdle timeout in seconds (0 means no timeout).

Definition at line 392 of file WebSocketClient.hpp.

◆ set_max_send_queue_size()

void kurlyk::WebSocketClient::set_max_send_queue_size ( std::size_t max_send_queue_size)
inline

Sets the maximum number of outbound send operations queued for this client.

Parameters
max_send_queue_sizeQueue limit, or 0 to keep the send queue unbounded.

Definition at line 406 of file WebSocketClient.hpp.

◆ set_proxy() [1/2]

void kurlyk::WebSocketClient::set_proxy ( const std::string & ip,
int port,
const std::string & username,
const std::string & password,
ProxyType type = ProxyType::PROXY_HTTP )
inline

Sets the proxy server address with authentication.

Parameters
ipProxy server IP address.
portProxy server port.
usernameProxy username.
passwordProxy password.
typeType of proxy (default is HTTP).

Definition at line 321 of file WebSocketClient.hpp.

◆ set_proxy() [2/2]

void kurlyk::WebSocketClient::set_proxy ( const std::string & ip,
int port,
ProxyType type = ProxyType::PROXY_HTTP )
inline

Sets the proxy server address.

Parameters
ipProxy server IP address.
portProxy server port.
typeType of proxy (default is HTTP).

Definition at line 307 of file WebSocketClient.hpp.

◆ set_proxy_auth() [1/2]

void kurlyk::WebSocketClient::set_proxy_auth ( const std::string & auth)
inline

Sets the proxy authentication credentials.

Parameters
authProxy authentication in <username:password> format.

Definition at line 340 of file WebSocketClient.hpp.

◆ set_proxy_auth() [2/2]

void kurlyk::WebSocketClient::set_proxy_auth ( const std::string & username,
const std::string & password )
inline

Configures proxy authentication credentials.

Parameters
usernameProxy username.
passwordProxy password.

Definition at line 355 of file WebSocketClient.hpp.

◆ set_proxy_server()

void kurlyk::WebSocketClient::set_proxy_server ( const std::string & server)
inline

Sets the proxy server address.

Parameters
serverProxy address in <ip:port> format.

Definition at line 333 of file WebSocketClient.hpp.

◆ set_proxy_type()

void kurlyk::WebSocketClient::set_proxy_type ( ProxyType type)
inline

Sets the proxy type.

Parameters
typeType of proxy.

Definition at line 347 of file WebSocketClient.hpp.

◆ set_reconnect()

void kurlyk::WebSocketClient::set_reconnect ( bool reconnect,
long reconnect_attempts = 0,
long reconnect_delay = 0 )
inline

Configures reconnection behavior.

Parameters
reconnectEnables automatic reconnection.
reconnect_attemptsNumber of reconnection attempts (0 means infinite attempts).
reconnect_delayDelay in seconds between reconnection attempts.

Definition at line 364 of file WebSocketClient.hpp.

◆ set_request_timeout()

void kurlyk::WebSocketClient::set_request_timeout ( long request_timeout)
inline

Sets the timeout for WebSocket requests.

Parameters
request_timeoutRequest timeout in seconds (0 means no timeout).

Definition at line 399 of file WebSocketClient.hpp.

◆ set_url() [1/2]

void kurlyk::WebSocketClient::set_url ( const std::string & host,
const std::string & path,
const std::string & query = "" )
inline

Sets the WebSocket server URL with optional query parameters.

Parameters
hostHostname or IP address.
pathPath for the request.
queryOptional query parameters.

Definition at line 280 of file WebSocketClient.hpp.

◆ set_url() [2/2]

void kurlyk::WebSocketClient::set_url ( const std::string & url,
const QueryParams & query )
inline

Sets the WebSocket server URL with specified query parameters.

Parameters
urlFull URL of the server.
queryQuery parameters as a dictionary.

Definition at line 288 of file WebSocketClient.hpp.

◆ set_user_agent()

void kurlyk::WebSocketClient::set_user_agent ( const std::string & user_agent)
inline

Sets the User-Agent header.

Parameters
user_agentUser-Agent string.

Definition at line 371 of file WebSocketClient.hpp.

◆ set_verify_cert()

void kurlyk::WebSocketClient::set_verify_cert ( bool verify_cert)
inline

Sets whether to verify the server’s certificate.

Parameters
verify_certIf true, enables server certificate verification.

Definition at line 428 of file WebSocketClient.hpp.

◆ submit_close()

SubmitResult kurlyk::WebSocketClient::submit_close ( const int status = 1000,
const std::string & reason = std::string(),
std::function< void(const std::error_code &)> callback = nullptr )
inline

Attempts to submit a close request to the WebSocket server.

Parameters
statusThe status code for the close request (default: 1000).
reasonOptional reason for closing the connection.
callbackOptional callback to execute after sending the close request.
Returns
SubmitResult describing whether the close request was successfully queued.

Definition at line 227 of file WebSocketClient.hpp.

◆ submit_message()

SubmitResult kurlyk::WebSocketClient::submit_message ( const std::string & message,
long rate_limit_id = 0,
std::function< void(const std::error_code &)> callback = nullptr )
inline

Attempts to submit a message through the WebSocket.

Parameters
messageThe content of the message to be sent.
rate_limit_idThe ID of the rate limit to apply to this message. A value of 0 indicates the default or no rate limit.
callbackAn optional callback to execute after sending the message.
Returns
SubmitResult describing whether the message was successfully queued.

Definition at line 203 of file WebSocketClient.hpp.

Member Data Documentation

◆ m_client

selected_backend_client_ptr kurlyk::WebSocketClient::m_client
private

Backend-specific WebSocket client selected by compile-time platform macros.

Definition at line 464 of file WebSocketClient.hpp.

◆ m_config

std::unique_ptr<WebSocketConfig> kurlyk::WebSocketClient::m_config
private

Deferred WebSocket configuration copied into the backend before connect().

Definition at line 465 of file WebSocketClient.hpp.


The documentation for this class was generated from the following file: