Client events released

What are client events?

For a while now we have been running a beta of a feature we call ‘client events’. This allows a connected client to utilise the bi-directional nature of WebSockets to send lightweight events to all other subscribers on a channel. This is really fast, and bypasses your server.

What can they be used for?

Because client events never reach your server, they are best for scenarios where you are making other clients aware of user activity. An example might be notifying other users when someone is typing in a chat room, or for showing transitory data in a collaboration application before an action is persisted.

You can however send whatever data you like (within reason). It is perfectly feasible to build a chat room entirely using client events where messages are only available while a user is connected.

And of course, client events can be really useful when building HTML5 Multiplayer Games – but please keep security in mind.

Security

We’re committed to security, and it is important that you realise the implications of client events before you enable them. Without your server validating content, it is possible for mischievous clients to send data that you wouldn’t expect to other connected clients.

We have tackled this in a number of ways:

• All client events must be prefixed with ‘client-‘. Therefore it is not possible to spoof events which are sent by your application via the REST API.
• Client events are only allowed on private or presence channels. This means that senders of client events will have been authorised by your application, and you can therefore clock mischievous users.
• Client events must be enabled for your apps manually, and are not turned on by default.

It is your responsibility to ensure that client events are dealt with carefully. For example you should sanitise any data received from other clients, and avoid simple XSS vulnerabilities such as inserting raw data as HTML or (as if you would ;) ) evaling content.

Rate limiting

Part of the reason we ran beta testing on this feature was to examine usage patterns. In some scenarios we have seen applications whose clients send client event extremely rapidly. In a busy channel this can cause issues for other connected clients that can’t process all the events that they are receiving.

To avoid this issue, we are rate limiting the client events sent by each client to 10 messages per second. Going beyond this threshold will result in an error being returned to the client, and events being discarded.

Move your mouse over me

Don’t trigger events like this!

javascript
1<script type="mce-text/javascript">
2var el = document.getElementById('myElement'); el.addEventListener('mousemove', function(evt){   var data = { x: evt.clientX, y: evt.clientY };   el.innerText = JSON.stringify(data); }, false);
3</script>
Copy

Avoid triggering client events based on DOM event handlers that can be spammy e.g.

javascript
1document.getElementById('myElement')
2.addEventListener('mousemove', function(evt){
3  var data =  { x: evt.clientX, y: evt.clientY };
4  myChannel.trigger('client-move', data);
5}, false);
Copy

How do I enable them?

Easy. Just go to the Settings** tab for the application you want to enable client events for, check the Client events checkbox and click the Update* button. You’re now ready to use Client events.

Check out the client event docs for additional information and suggested best practices, have fun, and get in touch if you have any questions or comments.