Introducing Improved Web Socket Server September 10, 2020

The commercial edition of Gyroscope is shipped with a web socket server; it provides real-time communication capability among users of the Gyroscope application as well as other integrated endpoints. The web socket server, or WSS, is particularly useful for immediate control of user access and editing conflict notification. It is also often used for system-wide broadcast.

A previous version of WSS already has a few unique features:

Per-instance ID

In addition to logical identifiers such as a User ID, or a GS_ID in a multi-tenant setup, the Gyroscope WSS also issues a browser instance identifier that's based on the physical network connection. This allows the same user to coordinate messaging across multiple browsers on the same computer, or even multiple tabs on the same browser.

Asymmetrical Connection

Unlike many web socket servers that resemble a chat room, the communication between a client and the server is not two-way. Except for the initial registration during the application loading phase, the client almost never sends data to the socket server. Instead, the client sends a request to the web server, and the web server then, in turn, notifies the socket server, which eventually broadcasts to all the connected clients.

There are several advantages to this design. First, not all browsers support web socket. When the inbound notification is received via HTTP, the server captures all the user actions. Second, the socket server broadcasts messages from both the web server relay and other system-initiated messages. When the upstream is unified, the message flow becomes much easier to manage. Last, many network connections have asymmetric bandwidth. Uploading is often slower than downloading. A Gyroscope web socket client almost always downloads, maximizing network performance.

Auto Re-Connecting

Although most of the network traffic goes one direction, the connection between the client and server is nevertheless a two-way TCP connection; this connection can be severed by either the browser, in the form of a reload or network outage, or by the server, in the event of a reset. The Gyroscope WSS is typically configured to have a daily "shuffle", where all the socket clients are disconnected and then reconnected. The socket client detects network disruption and attempts to reconnect.

The new Gyroscope WSS has improvements in the following areas:

Managed Connections

The earlier version of the socket server treats each connection as an isolated instance. Requests are passed through. When a connection is authenticated, it is passively maintained. When the connection is dropped, the server would not care until a new connection is established. The new socket server actively maintains the life cycle of each connection. The physical socket IDs and the logical user credentials are associated at all times.

Container-based Authentication

Previously update notifications were sent to all socket clients along with a flag that identifies the messages' intended recipient. It was up to the client to filter out the irrelevant data. The web socket messaging structure in Gyroscope is defined in a way that only non-sensitive meta data can be possibly relayed. Nevertheless, in a multi-tenant application the action of one user should not translate to the chatter of other unrelated users.

The new socket server routes container-specific messages on the server side. If a message is for GS_123, the client that's on GS_456 will not be receiving anything at all. In addition, proper authentication is in place so that any form of impersonation is prevented.

Broadcasting Channel

There are times when we need to send messages to all containers. Instead of sending to each GS container, the new socket server can bypass container filter for a pre-defined list of commands. This channel is essential for running administrative commands.

Administrative Commands

The socket server responds to special commands and displays its internal states. For example, a request type of "gsidmap" in the actionlog table triggers a printout of all the pairing between physical sockets and the logical GS IDs. It's also possible, although not yet implemented, for the server to instruct a specific client to reconnect or adjust its retry settings.

Server-side Keep-alive

The automatic reconnecting feature in the previous socket server covers only a limited disconnecting scenarios. Often a connection is not actively disconnected. Rather it is either silently dropped by the routers in-between, or replaced with a new connection. The former is a mysterious case of a "zombie connection"; the latter is a waste of connection resource.

The solution to both issues is to send a heartbeat signal to keep the connection alive. The new socket server sends such signal at a customizable interval. Cloudflare's web socket proxy, for example, drops connections that are dormant for over 100 seconds. Some old or congested routers reset connections within 30 seconds. By default, the Gyroscope WSS heartbeat interval is 20 seconds.

Migration Notes

Starting 16.5, Gyroscope is already compatible with the new socket server, which internally versioned as 1.2. Previous deployments require patching the following spots:

• ws_js.php: WSS key should contain both salted and plain GSID
• wss.js: send gsid and auth (WSS key) in registration request
• wss.js: disconnect and retry counter adjustment
• icl/reauth.php: recompute WSS Key header with added GSID component

Existing Gyroscope users will receive hands-on instructions on the migration.