Internal messages structure

Communication between the various modules and service and between the server and the clients is based on standardized messages and events. All of the messages and events are serialized and defined with the protocol buffers (probuf) mechanism.

Since clients could be implemented in any language and will need to reuse the messages structure, an external repository, opentera-messages, is used for that purpose.

Message wrappers

Wrappers are used to encapsulate message in a standard way, providing common fields and header for each message.

General message wrapper (TeraMessage)

All messages that are going out through the websocket channels to the clients are wrapped in the TeraMessage structure.

The wrapper is quite simple and only contains an Any field. Since protobuf’s Any allows for type detection, this allows the client to identify the type of the content of the message without explicitly having to try to cast to any known type and see if it makes senses.

TeraMessage wrapper is currently not used for internal message communications, only for communications with clients over websockets.

Event wrapper (TeraEvent)

All events going in and out of the OpenTera server are wrapped in a TeraEvent structure.

The Header part of the event is self-explanatory. The topic field is used as a way to identify the internal communication system topic being used to send that event.

A single TeraEvent wrapper can contains multiple events, if needed.

Same as with TeraMessage, the Any field in that structure allows for easier type detection in the receiver.

Module message wrapper (TeraModuleMessage)

Message that are addressed to one of the module are wrapped in a TeraModuleMessage.

The Header part of the message is self-explanatory. seq is a unique sequence number, while source contains who is sending the message to the module, while the dest contains the specific module topic.

A single TeraModuleMessage can contain multiple messages, if needed.

Same as with TeraMessage, the Any field in that structure allows for easier type detection in the receiver.

Specific events messages

Users, participants and devices

Those events indicate a status change in users, participants or devices. The specific status are defined and described in each of the messages proto below.

DeviceEvent 

Device event, describing a device state (online / offline, busy / not busy) or status change (such as battery level).

ParticipantEvent 

Participant event, describing a state change (online / offline, busy / not busy).

UserEvent 

User event, describing a state change (online / offline, busy / not busy).

Sessions

Those events are generated with session management services.

JoinSessionEvent 

Event to invite a specific user, participant and/or device to join a session.

JoinSessionReplyEvent 

Event indicating that a specific user, participant or device replied to a JoinSessionEvent

LeaveSessionEvent 

Event indicating that a specific user, participant or device left the session. Also use to indicate to a user, participant or device that it needs to leave the session now.

StopSessionEvent 

Event indicating that a specific session was terminated.

OpenTera modules & system services

Those events are generated or used to communicate with some of the modules and systems service in the OpenTera platform.