WebSocket (Socket function)

Convert Web thread to WebSocket thread (Socket class)

[Introduced in Model 204 7.8 βeta]

This page is under construction.

Syntax

%socket = [%(Socket):]WebSocket

Syntax terms

%Socket	Socket object
[%(Socket):]	The optional class name in parentheses denotes a virtual constructor. See "Usage notes", below, for more information about invoking a virtual constructor.

Usage notes

The HTTP protocol has been indispensible in creating the Internet as it exists today. It's still the core protocol for Web browsers and many other applications, whether on PCs, servers, laptops, or mobile devices. It has been extended over the years to accommodate demands for streaming video and sound, transfer of data files, and many other uses.

Yet HTTP still falls short in providing for efficient general purpose data transfer.

First, it is a half-duplex protocol, meaning that one side of the communication is always waiting for the other to reply. Second, the HTTP headers add considerable overhead to each interaction, wasting valuable bandwidth. Finally, each HTTP request requires its own TCP connection, which is generally closed after the server replies. This adds the overhead of connection establishment to every individual request. A typical web page requires several distinct http requests, each of which require separate TCP connections and its own set of http headers.

The Web Socket protocol was created to address these shortcomings. It is designed to allow full-duplex communication. Efficient framing of payload data uses minimal overhead. The protocol is end-user extensible. Most importantly, it can be deployed completely within an existing http/https framework. No firewall rule changes are required, and optional data masking avoids potential issues with caching proxies.

Web Sockets are supported in Janus Web Server as of Model 204 7.8.

The Janus Web implementation of Web Sockets requires some preparation before you can write your applications.

A Janus Web port is enabled for Web Socket communication with the WEBSOCKET parameter. Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the WEBSOCKET and NOWEBSOCKET parameters, respectively.

An http request for a Web Socket connection looks very similar to a normal http GET request. A special "upgrade" header in a request differentiates a Web Socket upgrade from all others. The upgrade request along with other unique headers advertise a request to negotiate a switch from HTTP to the Web Socket protocol.

When this negotiation completes successfully on a Janus Web Server thread, the connection immediately and irreversibly transitions to a Janus WebSocket connection.

The WebSocket method initiates acceptance of an upgrade of a Janus Web thread to a WebSocket thread. Once the WebSocket method returns, SendWebSocket, ReceiveWebSocket and Close are the only valid socket methods. No Janus Web $functions or methods are allowed and will result in request cancellation.

The Janus Web port must be enabled for Web Socket upgrades with the WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the JANUS WEB rule for the URL.

Any other usage will result in request cancellation.

Examples

The following example sends a text message to the WebSocket client.

... %sock = WebSocket if %sock is null then audittext Socket closed, status is {$STATUSD} stop end if %op = %sock:ReceiveWebSocket(%wsi) if %op eq 1 then setText %wso = Received your text message of {%wsi:length} bytes. %sock:SendWebSocket(%wso, %op, true) end if ...

See also

Socket class	List of Socket methods	Socket methods syntax
Notation conventions for methods