By default, WebSocket++ based servers accept any WebSocket connection. This behavior can be tailored to suit your application via a number of techniques. Most of this control comes by registering a validate handler. The validate handler is called after a connection handshake has been received and parsed, but before the response has been sent. The validate handler allows you to negotiate some aspects of the connection (such as which subprotocol or extensions to use) as well as rejecting or accepting the connection.
The signature of the validate handler is
bool validate_handler(connection_hdl hdl). It can be registered with an endpoint or connection via the
set_validate_handler(validate_handler h) method.
Accepting or Rejecting the Connection
The most basic function of the validate handler is to decide whether or not to accept the connection. This is done via the function's return value. Return true to accept the connection, false to reject it. If you are rejecting a connection, you can use
set_status(http::status_code::value code) to specify the HTTP error code to return.
set_body(string) also works here.
Accessing connection details
The validate handler may make its decisions about whether or not to accept connections by any means. Limits could be set based on global information, such as server resources in use, number of current connections, etc. Decisions can also be made using connection specific information. The validate handler is passed a connection_hdl as a parameter. Like with other handlers, this can be upgraded to a connection_ptr using
server::get_con_from_hdl(connection_hdl hdl). With the connection_ptr, you can retrieve various information about the connection itself:
|get_secure()||Whether or not the connection is secure.|
|get_host()||The host component of the connection URI (www.example.com).|
|get_resource()||The resource component of the connection URI (/foo).|
|get_port()||The port component of the connection URI.|
|get_request_header(key)||Value of header `key` from the handshake HTTP request.|
|get_origin()||Value of origin header set by browser clients to indicate the origin of the original requesting script.|
|get_requested_subprotocols()||A list of subprotocols the client is capable of speaking in order of preference.|
Browser clients will set an origin header indicating the origin of the original request. The
const std::string & get_origin() method can be used to retrieve this value. This header can be used to implement a policy whereby only scripts running on whitelisted domains may connect to the server. Please note, like the origin header used for this purpose in regular HTTP servers, nothing prevents non-browser clients from spoofing this value.
WebSocket clients may include a list of supported subprotocols with their request. This list can be retrieved using
std::vector<:string> & get_requested_subprotocols(). The list is ordered by client priority. As a server you may optionally choose one of these subprotocols to use. To select a subprotocol, use
void select_subprotocol(const std::string & value) during the validate handler. The handshake return will include this value to let the client know which one has been chosen. The WebSocket protocol does not define the meaning or interpretation of the subprotocol, this is left up to the individual endpoints.
On the client side, WebSocket++ based clients can build the outgoing subprotocol request list by calling
void add_subprotocol(string) before calling
connect() for each protocol they want to request, in order of preference. The server's response can be read via