Websockets communication

Websockets are used within OpenTera to send messages and events from the server to the client.

While a websocket can be used as a bidirectional communication channel, the websocket is only used in a unidirectional channel from the server to the client in OpenTera.

All websocket communication is encrypted using SSL certificates.

Websockets management

Internally, websockets are managed by the Twisted engine and a protocol has been defined for user, participant and device websockets. This allows to manage differently the connections depending on the base object type.

An automatic ping mechanism ensures that data is transmitted over the websocket at each 10 seconds to detect inactive clients or badly closed connection. If no reply is received by this mechanism, the websocket channel will be automatically closed.

Establishing a websocket connection

The websocket url to connect to will depend on the object type. To get that url, a login query must be made to the correct REST API with the with_websocket parameter. See Login and authentication for more information on the login process.

The returned url will be valid for 60 seconds. If no connection is established within that time frame, the url will have to be requested again.

Communication over the websocket

All data sent from the server to the client will be formatted in a protocol buffers (protobuf) serialized data format. The dictionary of messages and events is documented here.

Internally, each websocket connection will subscribe to specific events using the internal services communication module. The list of those events is defined according to the type of websocket. As with all communication within OpenTera, information will be filtered to only transmit the data that the associated object to that websocket has access.

  • User websocket: User manager module events, session events, device events, participant events, user events, direct events. Filtering occurs in the UserEventManager class.

  • Participant websocket: Device events, participants event (self only), session events, direct events. Filtering occurs in the ParticipantEventManager class.

  • Device websocket: Device events (self only), participants event, session events, direct events. Filtering occurs in the DeviceEventManager class.

Direct events are always enabled by default on each of the websocket type, allowing to directly send an event or a message to a connected client, if that client type and uuid is known. See here for more information on how to use the publish system to communicate with a connected client directly.