Broadcast Alerts

Wednesday, March 1, 2017

By Alex Lein

The WebSocket now notifies all connected clients of impending upgrades and maintenance windows, and the messages can be interpreted by your code and react appropriately.

Broadcast Message Types

There are two kinds of broadcast messages, maintenance messages, and upgrade messages. For all types, the JSON message will be named broadcast, and there will always be a kind key to help with parsing. Another key, serverTime, is also sent to help with clock synchronization.

Maintenance Window Notification

Any time there is a planned system maintenance window, the WebSocket will announce the schedule before it begins. During a maintenance window, the service may go down and come back online repeatedly until the window ends.

You can use the keys starting and ending to keep track of the maintenance window, and change your system's behaviour if a disconnection event occurs, or if commands timeout.

An example would be: broadcast { "kind": "maintenance", "serverTime": "2017-03-03T23:00:00Z", "starting": "2017-03-04T23:59:00Z", "ending": "2017-03-04T23:59:00", "message": "The service is going down for maintenance at 03/04/2017 11:59pm. It will be under maintenance until 04/04/2017 4:00am.", }

The documentation for the BroadcastMaintenance format can be found in the API reference.

System Upgrade Message

This broadcast describes to a client that the service will be upgrading to a new release, and a re-connection will have to take place. The downtime of a service upgrade is only a few seconds, and is not considered part of a maintenance window. All upgrades are mandatory, but always contain bugfixes and/or new features.

When the key reload is true, it is advised that you re-load all previously cached resources as their format or content may have changed to coincide with a new feature or a bugfix.

The key eta lets you know when the upgrade is due to complete so you can reconnect.

An example would be: broadcast { "kind": "upgrade", "serverTime": "2017-03-04T12:50:00Z", "eta": "2017-03-04T13:00:00Z", "reload": true, "message": "A service upgrade will be available at 03/04/2017 12:00pm. Upon reconnection, please reload all resources.", }

The documentation for the BroadcastUpgrade format can be found in the API reference.