Introduction to the WebSocketClient Module

The WebSocketClient module provides client support for RFC-6455 based WebSocket protocol implementations in Qore.

To use this module, use "%requires WebSocketClient" in your code.

This module automatically uses the WebSocketUtil module for encoding and decoding web socket messages.

All the public symbols in the module are defined in the WebSocketClient namespace.

Currently the module provides the following classes:

WebSocketClient::WebSocketClient "WebSocketClient": the web socket client class
WebSocketClient::WebSocketConnectionObject "WebSocketConnectionObject": the web socket connection class (based on the ConnectionProvider module)

Example

//!/usr/bin/env qore
 
%new-style
%enable-all-warnings
 
%requires WebSocketClient
 
*string url = shift ARGV;
if (!url) {
    stderr.printf("usage: %s <URL>\n", get_script_name());
    exit(1);
}
 
code callback = sub (*data d) {
    if (d.typeCode() == NT_BINARY) {
        printf("binary msg received: %y\n", d);
    } else if (d) {
        printf("%s\n", d);
    }
};
WebSocketClient ws(callback, {"url": url});
ws.connect();
# wait forever (or until ctrl-c)
Counter c(1);
c.waitForZero();

Debug Info Collection

WebSocket data providers support debug info collection for capturing technical details about WebSocket connections and message operations.

Example: Capturing WebSocket Debug Info: %requires WebSocketClient

# Create a WebSocket data provider

WebSocketClientDataProvider provider({"url": "wss://api.example.com/ws"});

# Enable debug collection

BufferedDebugInfoCollector collector();

provider.setDebugCollector(collector);

# Connect and send messages

provider.connect();

provider.sendMessage(MESSAGE_WS_DATA, {"message": "Hello"});

# Analyze debug info

list<hash<DataProviderDebugInfo>> info = collector.getAll();

foreach hash<DataProviderDebugInfo> debug in (info) {

printf("%s: %s\n", debug.operation, debug.ws_message_type);

printf(" Duration: %dms\n", debug.duration_ms);

printf(" Size: %d bytes\n", debug.request_size ?? debug.response_size);

if (debug.http2) {

printf(" Protocol: HTTP/2 WebSocket\n");

}

}

See Debugging Data Providers in the DataProvider module for more information.

WebSocketClient Module Release History

v2.6

added support for WebSocket over HTTP/2 (RFC 8441)
- automatic detection and use of HTTP/2 extended CONNECT when connecting to HTTP/2 servers
- added WebSocketClient::WebSocketClient::isHttp2() "WebSocketClient::isHttp2()" method to check if HTTP/2 WebSocket is being used
- added http2 key to WebSocketClient::WebSocketClient::getConnectionInfo() "WebSocketClient::getConnectionInfo()"
- data provider's ws-connected-event now includes http2 field indicating HTTP/2 usage
added debug info collection support via AbstractDataProvider::setDebugCollector() for the WebSocket data provider
debug info includes WebSocket message type, size, timing, connection protocol, and error info

v2.5

added WebSocket extension support with permessage-deflate compression (issue 5065)
- added extensions constructor option for providing extension instances
- added extension negotiation during WebSocket handshake
- added automatic compression/decompression for messages when extensions are active
- added WebSocketClient::WebSocketClient::hasPerMessageDeflate() "WebSocketClient::hasPerMessageDeflate()" method
- added WebSocketClient::WebSocketClient::getActiveExtensions() "WebSocketClient::getActiveExtensions()" method

v2.4

added optional AsyncAPI validation support via WebSocketClient::WebSocketClient::setAsyncApiValidator() "WebSocketClient::setAsyncApiValidator()" for validating WebSocket messages against AsyncAPI schemas (issue 5014)

v2.3

added the WebSocketClient::WebSocketClientWithSerialization "WebSocketClientWithSerialization" class, added support in the WebSocketClient::WebSocketClient "WebSocketClient" class for tokens and a logger instead of log closures / callbacks
added support for the data provider action catalog API (issue 4808)
added support for protocol version 13

v2.2

fixed creating example WebSocket client data providers from factories with templated option values (issue 4716)
added a "wait for message" API data provider to the WebSocket client data providers (issue 4716)

v2.1.1

the data provider factory uses the delayed observable class instead (issue 4701)

v2.1

fixed a deadlock deleting the client object when it goes out of scope in the event thread (issue 4697)
added the headers option to allow auth headers to be set in WebSocket client connections and data providers (issue 4694)

v2.0

added support for events and messages from the DataProvider API (issue 4557)

v1.9.1

added support for continuation frames (issue 4073)

v1.9

implemented support for a data provider scheme cache and rich option information for connections (issue 4025)

v1.8

removed the WebSocketConnectionObject::getConstructorInfo() and WebSocketConnectionObject::getConstructorInfoImpl() methods (issue 3696)
added support for socket events (issue 3425)

v1.7

all connection clases have unified constructor
added the WebSocketConnectionObject::getConstructorInfo() method to allow connections to be created dynamically, potentially in another process from a network call (removed in WebSocketClient 1.8) (issue 2628)
add WebSocketClient handling of WSCC_GoingAway event

v1.6.3

added missing exception handling in the connection close callback (issue 3225)

v1.6.2

allowed the handling of PING messages to be customized (issue 2887)

v1.6.1

added WebSocketClient::WebSocketClient::pong() "WebSocketClient::pong()" to allow an unsolicited PONG message to be sent as a unidirectional keep-alive message from the client to the server (issue 2566)

v1.6

added the WebSocketClient::WebSocketConnectionObject "WebSocketConnectionObject" class to support the ConnectionProvider module
updated for complex types
fixed a bug where the event loop thread would immediately terminate after a reconnection (issue 2061)
improved client logging
fixed a bug where the WebSocketClient::WebSocketClient class did not validate the Sec-WebSocket-Accept response header according to RFC6455 (issue 2062)
added support for the yield option in the constructor

v1.5

added timeout values to Socket and HTTPClient calls (issue 1725)

v1.4

fixed a bug parsing and generating the websocket close status code (issue 1216)

v1.3

ignore SOCKET-NOT-OPEN errors when closing (server already closed the connection)

v1.2

prepend "WebSocketClient: " to log messages

v1.1

added socket instrumention support from Qore 0.8.9

v1.0

the initial version of the WebSocketClient module

Table of Contents