WebSockets

WebSockets is a technology providing interactive communication between a server and client. It is an IETF standard defined by RFC 6455.

Normal HTTP connections follow a request/response paradigm and do not easily support asynchronous communications or unsolicited data pushed from the server to the client. WebSockets solves this by supporting bidirectional, full-duplex communications over persistent connections. A WebSocket connection is established over a standard HTTP connection and is then upgraded without impacting the original connection. This means it will work with existing networking infrastructure including firewalls and proxies.

WebSockets is currently supported in the current releases of all major browsers, including: Chrome, Firefox, IE, Opera and Safari.

Appweb Implementation

Appweb implements WebSockets as an optional pipeline filter called WebSockFilter. The filter implements the WebSockets protocol, handshaking and provides a C language API. The WebSock filter observes the WebSockets HTTP headers and manages the connection handshaking with the client. It also manages the framing and encoding/decoding of message data.

The WebSock filter is configured into the pipeline using the AddInputFilter directive.

WebSocket Handshake

A WebSocket connection begins life as a normal HTTP request and is upgraded to the WebSocket protocol. The WebSocketFilter is activated by a set of WebSocket HTTP headers from the client that describes a desired WebSocket connection. Here is a typical client HTTP request requiring a WebSocket upgrade:

GET /websock/proto/msg HTTP/1.1
Host: example.com
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Protocol: chat, better-chat
Sec-WebSocket-Key: 50cLrugr7h3yAbe5Kpc52Q==
Sec-WebSocket-Version: 13
Origin: http://example.com

The WebSocket filter constructs a handshake response that includes an accepted key and selected protocol. For example:

HTTP/1.1 101 Switching Protocols
Server: Embedthis-http
Date: Sat, 06 Oct 2014 05:10:15 GMT
Connection: Upgrade
Upgrade: WebSocket
Sec-WebSocket-Accept: 58ij/Yod1NTjzqcyjkZbZk6V6v0=
Sec-WebSocket-Protocol: chat
X-Inactivity-Timeout: 600
X-Request-Timeout: 600

After the handshake message has been sent, the server is free to send messages to the client. Once the client receives the handshake, it can send messages to the server. Either side can send at anytime thereafter. Communications are thus full-duplex.

Message Types

WebSockets supports several message types:

• Text in UTF-8
• Binary
• Close
• Ping/Pong

Text Messages

Text messages must be valid UTF-8 strings. The receiving peer will validate and reject non-conforming strings. However, Appweb can be configured to accept invalid UTF-8 strings via the IgnoreEncodingErrors Appweb directive.

Binary Messages

Binary message allow the transmission of any content. Messages can be an arbitrary length up to the maximum specified by the LimitWebSocketsMessage appweb.conf directive.

When messages are transmitted, they may be broken into frames of no more than the length specified by the LimitWebSocketsFrame directive. Incoming message frames are not subject to this limit. The WebSockets filter will aggregate message frames into complete messages before passing to the user callback. There are APIs provided to preserve frame boundaries if you wish to manage frame boundaries manually.

The LimitWebSocketsPacket directive defines what is the largest packet size that will be passed to the user callback receiving incoming WebSocket messages. If this is set to a value as large as the largest message, then complete messages will be passed to the user callback. If it is smaller than the message size, the message will be broken into packets and the last packet will have the HttpPacket.last field set to true. Note these packet boundaries do not correspond to frame boundaries.

Frame boundaries can be preserved by setting PreserveFrames directive or by calling the httpSetWebSocketPreserveFrames API. If enabled, each frame is passed as-is to the user callback without splitting or aggregating with other frames. Note that if enabled, some text messages may not have their UTF-8 fully validated if UTF code points span message frames.

Close Message

Ordinarily, WebSocket communications are terminated by sending a Close message. The close message includes a status code and an optional reason string to explain why the connection is being closed. The reason string must be less than 124 bytes in length so as to fit into a single WebSocket frame. When the server receives a close message, it responds with a close message to the peer. This happens internally in the WebSockFilter.

Ping/Pong Messages

To keep a communications channel alive, it is sometimes necessary to send regular messages to indicate the channel is still being used. Some servers, browsers or proxies may close an idle connection. The Ping/Pong WebSockets messages are designed to send non-application level traffic that will prevent the channel from being prematurely closed.

A ping message may be sent by either side and the peer will reply with pong message response. The pong message is generated internally by the WebSockets layer and is similarly consumed by the WebSockets layer at the peer. The application layer may initiate the peer message, but it will never see the pong response.

Appweb has a WebSocketsPing appweb.conf directive that can be used to automatically send ping messages at a specified interval. Note: use of this directive defeats the Appweb InactivityTimeout for an idle WebSockets connection.

Timeouts

The standard Appweb request and inactivity timeouts can be used for WebSocket communications. Typically, a route will be defined in the appweb.conf file for WebSockets and it will include appropriate request and inactivity timeout directives. The RequestTimeout gives the total time a WebSocket connection may remain open. The InactivityTimeout specifies the maximum time a WebSocket connection may be completely idle. Note that ping/pong messages will reset an inactivity timeout.

Configuration

It is typically necessary to create a dedicated Route for WebSockets communications. Such a route should define a unique URI prefix for WebSocket communications and configure the WebSocket filter. Any number of WebSocket routes can be defined. For example:

<Route ^/websock/{controller}$>
    WebSocketsProtocol  chat            # Use the chat application protocol
    AddFilter           webSocketFilter # Add the WebSockets filter
    AddHandler          espHandler      # Run an ESP controller
    Source              test.c          # Code is in test.c
    Target              run $1          # Use {controller}
    RequestTimeout      2hrs            # Maximum connection time
    InactivityTimeout   5mins           # Maximum idle time
</Route>

This creates a route for URIs beginning with "/websock" for WebSockets communications. It uses an ESP controller to respond to incoming messages. See below for sample ESP WebSocket code.

WebSockets Directives

The following directives are supported for controlling WebSocket communications within a route.

Directive	Purpose
IgnoreEncodingErrors	Ignore UTF-8 text message encoding errors.
InactivityTimeout	Maximum idle time before closing a connection.
RequestTimeout	Maximum duration before closing a connection.
LimitWebSockets	Maximum number of simultaneous WebSocket sessions.
LimitWebSocketsFrame	Maximum WebSockets message frame size for sent messages.
LimitWebSocketsMessage	Maximum WebSockets message size
LimitWebSocketsPacket	Maximum WebSockets message size passed to the callback in one transaction.
WebSocketsProtocol	Application level protocol supported by this route.
WebSocketsPing	Frequency to generate a ping message.

WebSockets APIs

Appweb provides a simple but powerful API for interaction with WebSockets.

Directive	Purpose
httpGetPacket	Get the next message
httpGetWebSocketCloseReason	Get the close reason supplied by the peer
httpGetWebSocketProtocol	Get the selected web socket protocol selected by the server
httpSend	Send a UTF-8 text message to the web socket peer
httpSendBlock	Send a message of a given type to the web socket peer
httpSendClose	Send a close message to the web socket peer
httpSetConnNotifier	Define a connection callback notifier function
httpSetWebSocketPreserveFrames	Preserve frame boundaries and do not split or aggregate frames.
httpSetWebSocketProtocols	Set the list of application-level protocols supported by the client. This is a client-only API.
httpWebSocketOrderlyClosed	Test if a close was orderly
espSetNotifier	Define a connection callback notifier function for ESP applications.

Using WebSockets API with ESP

ESP is an ideal web framework for use with WebSockets. ESP provides a very low latency connection between a client request and execution of C functions. A dedicated ESP controller can be created for the WebSocket that responds to the incoming WebSocket request. The controller then defines a callback that is notified when incoming WebSockets messages arrive. This callback will also be invoked for close or error events. For example:

#include "esp.h"
static void testCallback(HttpStream *stream, int event, int arg)
{
    if (event == HTTP_EVENT_READABLE) {
        HttpPacket *packet = httpGetPacket(stream->readq);
        printf("Message %s\n", mprGetBufStart(packet->content));
        /* Send a reply message */
        httpSend(stream, "Reply message at %s", mprGetDate(0));
        /* No need to free buffer, the garbage collector will free */
    } else if (event == HTTP_EVENT_APP_CLOSE) {
    } else if (event == HTTP_EVENT_ERROR) {
    }
}
/*
    Action run when the client connects
 */
static void test() {
    /* This keep the connection open */
    dontAutoFinalize();
    /* Define a callback for connection and I/O events */
    espSetNotifier(getStream(), testCallback);
}
/* One-time ESP loadable module initialization */
ESP_EXPORT int esp_controller_websock(HttpRoute *route, MprModule *module) {
    espDefineAction(route, "test", test);
    return 0;
}

Reading Messages

WebSocket messages are received by reading data from the packet read queue in response to an HTTP_EVENT_READABLE event. WebSocket messages are composed of one or more frames. Each packet typically contains one frame, provided the frame is smaller than the configured maximum packet size (LimitWebSocketsPacket).

The packet is retrieved via the httpGetPacket API. This removes the first packet from the given read queue.

HttpPacket *packet = httpGetPacket(stream->readq);

The packet contains information about the message and the message contents. Packet fields of interest are:

• packet->type — WebSocket message type
• packet->last — True if this packet corresponds to the last frame in a message
• packet->content — WebSocket message content. Instance of MprBuf.

The WebSocket frame types are:

• WS_MSG_CONT — Continuation frame
• WS_MSG_TEXT — UTF-8 text message
• WS_MSG_BINARY — Binary message
• WS_MSG_CLOSE — Close message
• WS_MSG_PING — Ping message
• WS_MSG_PONG — Pong message

The message contents is stored in the packet->content buffer. This is an instance of the MprBuf buffer object. A pointer to the start of the message can be retrieved via:

mprGetBufStart(packet->content)

The length of the message can be determined via:

mprGetBufLength(packet->content)

Note TEXT messages are null terminated and you can use the start reference as a c-string reference.

Sending Messages

Appweb provides two APIs for sending messages:

• httpSend — for simple formatted text messages
• httpSendBlock — a lower-level API for maximal control over message transmission

To send messages of type TEXT, Appweb provides a simple API: httpSend.

ssize httpSend (HttpStream *stream, cchar *fmt, ...)

This API sends UTF-8 messages to the client. Messages are fully buffered, i.e. the call will always accept the given data. The call returns the number of bytes accepted. For example:

httpSend(stream, "The temperature today is: %d", temp);

httpSendBlock

The WebSockFilter also provides a lower-level and more powerful API: httpSendBlock for sending messages.

ssize httpSendBlock(HttpStream *stream, int type, cchar *msg, ssize len, int flags)

This API can send messages and can control how messages are framed, buffered or whether the API should wait for completion.

Modes

The httpSendBlock API supports several modes for sending data that can be controlled via the httpSendBlock flags:

• Buffered — HTTP_BUFFER
• Blocking — HTTP_BLOCK
• Non-blocking — HTTP_NON_BLOCK

Buffered Mode

In buffered mode, the entire message provided to httpSendBlock is accepted and buffered in the Appweb pipeline. The call will never return having written less than requested. If the message is very large, this will consume memory sufficient to buffer the message. This mode is simple and fast, but may increase the memory footprint of Appweb. It is ideal for smaller messages.

char *msg;
msg = sfmt("The temperature today is: %d", temp);
httpSendBlock(stream, WS_MSG_BINARY, msg, slen(msg), HTTP_BUFFER);

Blocking Mode

In blocking mode, the message is not buffered, but rather the call blocks until the entire message has been sent down the Appweb pipeline. This call will consume a thread while the call blocks. This mode is simple, uses minimal memory, but will consume a thread. This mode is suitable for small messages, or occasional use for larger messages on lower-volume web sites. In this mode, the call may block for up to the inactivity timeout defined by the InactivityTimeout directive.

char buf[1000 * 1000];
memset(buf, 0x10, sizeof(buf));
httpSendBlock(stream, WS_MSG_BINARY, buf, sizeof(buf), HTTP_BLOCK);

Non-Blocking Mode

In non-blocking mode, the httpSendBlock call will only accept data that can be absorbed by the pipeline without exceeding the queue buffer limits. The call may return "short" having written less than requested. It is then the callers responsibility to resend the remaining portion of data at a later time. If this occurs the next call to httpSendBlock should set the message type to WS_MSG_CONT to indicate a continued message. This is the highest performance mode and consumes minimal memory. However it is more complex when the all returns having written less than requested. There is a sample that demonstrates this at:

https://github.com/embedthis/appweb-doc/tree/master/samples/websockets-output

Message Framing

The WebSockFilter may split the message into frames such that no frame is larger than the limits specified by the LimitWebSocketsFrame directive. However, if the HTTP_MORE flag is specified to indicate there is more data to complete the current message, the data provided will not be split into frames and will not be aggregated with previous or subsequent messages. i.e. frame boundaries will be preserved and sent as-is to the peer.

WebSocket Samples

See the Appweb samples for some specific WebSockets samples

https://github.com/embedthis/appweb-doc/tree/master/samples

WebSocket References

Topic	Description
RFC 6455	The WebSockets Protocol
WebSocket API	The Javascript WebSockets API
WebSockets Wikipedia	WebSockets Wikipedia
WebSockets 101	WebSockets 101
WebSocket.org	WebSockets background and demo
WebSocket Online Demo	The WebSockets online test site
Chrome WebSocket Tools	Chrome browser developer tools guide
WebSocket Protocol	The WebSocket Protocol - Past Travails are to be avoided
Real-time Data Exchange	Real-time data exchange in HTML5 and WebSockets
WebSockets Streams	WebSockets is a stream not a message based protocol....