Yet Another Web Socket Server Upgrade February 16, 2021

Starting 17.8, Gyroscope can connect to both the legacy web socket server (WSS) or a new, web socket streaming server (WSSS).

Although the transition requires minimal code change, WSSS handles the notification flow quite differently. To best explain the structural difference, let's look at the general setup of a web application with web socket notification capability:

When a browser connects to a web server, it is also instructed to establish a TCP connection with a web socket server. From this point on, the web socket server can push live messages directly to the browsers. In a conventional setup, a browser, or "client", talks to the web socket server directly. The client's activities are then broadcast to all the other connected clients:

There are two main issues with this design. One is that if the initiating client does not support web socket, its notification will be lost. The other clients will only receive notifications from some browsers. Even though most of today's browsers support web socket, there is no guarantee that a compatible browser will receive all the notifications.

Another issue is authentication. When a user signs in to a Gyroscope application, a security context is established through a set of authenticated cookies. This context is not shared with web socket requests.

The previous version of the web socket server (WSS) for Gyroscope uses an asymmetric flow. The only time when a client sends a message to the web socket server is during its initial handshake. The client asks for a unique connection ID. This ID is later used to ignore the client's own messages. After the handshake, the client never speaks to the web socket server again. It only passively receives notifications.

WSS implements an asymmetrical flow with the help of a database. When a user updates a record, the change is registered in the activity log (actionlog). In the same database write, the meta data for the web socket notification is recorded. Specifically, the wssdone column is used to identify which messages are yet to be announced:

The new web socket streaming server (WSSS) removes the reliance on the database. The application server directly relays the event to the web socket server. The activity log is updated separately. The web socket server no longer has to poll the database at an interval. This means that actions from the initiating client is instantly propagated to the other connected users.

Starting Gyroscope 17.8, the default web socket server is WSSS. For the sake of backward compatibility, the WSS_INTERNAL_KEY global can be set to empty in lb.php. Previous versions of Gyroscope can patch forminput.php by adding the streamaction function and modifying the logaction function.

It's important to pass in only the authenticated values to the all powerful streamaction function. The burden of verifying the legitimacy of a web socket notification is bore by the application server. For the most part, streamaction is transparently called by logaction.

Calling streamaction directly is rare but can be useful for testing. The wsstest.php contains a few test cases. The file is disabled by default and should stay deactivated on production. In addition to the "gsidmap" call that was supported in WSS, WSSS also supports the "wsclientmap" dump request.

It's worth noting that WSSS uses more TCP connection resource than WSS. Each time an action is relayed, a new connection is opened and briefly closed. With scheduled resets, it is unlikely that WSSS will run out of connection descriptors.