Functional Description

The call service allows users to discover and communicate with each other. It acts as an introductory service based on identities as opposed to IP addresses and can broker direct peer-to-peer connections between devices.

Caller Id

The advantage of IP addresses / ports are that they uniquely identify a device, however with identities, it isn’t clear which device should receive the call. This is because a user may be signed into a multiple devices at the same time. In addition, not every device is capable of real-time video chat.  This leads to three options:

1. Signal every device the user is signed into (Google Hangouts approach)
2. The layout context restricts the video chat DMApp component to a single capable device
3. The user nominates a device within the layout context to be used for real-time comms

A final possibility is that the user nominates one device for video/audio comms and allows the video to be rendered on other devices. The option chosen will depend on the quality of the resulting user experience and the capabilities of the devices in the home and is subject to user testing. The call-server must therefore maintain a flexible approach by mapping between a single call identifier and many devices.

Example

Taking option 3 as an example, the user has signed into a number of client devices and must nominate one of them to be advertised via the call service. This could be achieved when the client device creates a secure web socket connection with the call service, passing a session access token via a cookie. The token would be used to identify the caller via a request to the session service. Connection attempts from other devices or applications will result in an error response indicating that only one device per user may be registered with the call service.

Signalling

The call service implements signalling for WebRTC applications via web sockets and XHR. Signalling allows initiation of peer-to-peer communication sessions by exchanging control messages that initialise or close communication and report errors. Clients can use the call service’s signalling mechanism to exchange ICE candidates obtained separately from STUN/TURN servers. ICE candidates are the public IP addresses and ports that clients should use to communicate with each other and are the result of establishing NAT punch-through or relay. Signalling is also used to negotiate codecs, video resolutions and communication protocols via Session Description Protocol (SDP). Transport type can also be negotiated as reliable (TCP-like) or unreliable (UDP-like).

Once signalling is complete, users can chat directly with one another using real-time video, audio and text messages, courtesy of WebRTC. Clients can also exchange arbitrary binary payloads using application-defined protocols.

Responsibilities

• Broker connections between clients
• Permit clients to create, answer and hangup media calls (audio & video).
• Permit clients to send and receive arbitrary datagrams peer-to-peer
• Notify clients of disconnections
• Utilise 2Immerse user identities and authorize or disallow calls based on successful session access tokens

Collaborators

• STUN/TURN service
• Session service
• Logging service

API

PeerJS and peer-server are the nominated client and server technologies for implementing a WebRTC-based call service. The source code is available here: https://github.com/peers/peerjs

PeerJS is the client library and is documented here: http://peerjs.com/docs/#api

PeerServer is a call server that brokers connections between PeerJS clients. No peer-to-peer data goes through the server; it only acts as a connection broker. The source code is available here: https://github.com/peers/peerjs-server

Both PeerServer and PeerJS are distributed under the MIT license.

Changes required for 2Immerse

PeerJS uses randomly assigned user identifiers and tokens generated by the client when connecting a user to PeerServer. 2Immerse has its own userIds and session access tokens that must be used instead.

PeerServer must be modified to perform a request to the session service to validate the authenticity of the token and to lookup the corresponding userId. This userId must replace the randomly generated userId assigned by the PeerJS client.

PeerJS needs to be modified so that it doesn’t randomly generate access tokens or userIds, but instead sends the user’s session access token in a secure cookie.

Configuration

PeerJS/PeerServer must be configured to use secure web sockets and to enable its use behind a reverse proxy. This requires 2Immerse certificates to be generated for TLS/SSL.

Verbs

In addition to connection/disconnection, the PeerJS server routes the messages, and their payloads between peers. It supports the following message types:

Expire – message request to peer expired due to inactivity
Leave – used to notify ‘hang-up’ of the connection
Candidate – used to exchange ICE candidates (i.e. public facing IP addresses obtained from the STUN/TURN server)
Offer – used to create a connection with an SDP (Session Description Protocol) payload
Answer – response to an offer containing an SDP payload

The server will issue a Leave message on behalf of a disconnected peer and will queue outstanding messages destined for peers that it’s waiting for to reconnect.

Offer
Params:

ssoToken: session access token
peerId: peer to contact
sdp: SDP (Session Description Protocol)

Description:

When a peer starts a call to another peer, it creates an offer. This description includes all the information about the caller’s proposed configuration for the call (the SDP payload). The recipient then responds with an answer, which is a description of their end of the call. In this way, both devices share with one another the information needed in order to exchange media data.

Answer

Params:

ssoToken: session access token
peerId: peer to contact
sdp: SDP (Session Description Protocol)

Description:

Message sent in response to an offer. This includes all the information about the responder’s configuration for the call (the SDP payload).

Leave

Params:

ssoToken: session access token
peerId: peer to contact

Description:

Message sent to tell the recipient that the peer is leaving the call. This message can also be issued by the call server if a peer has disconnected unexpectedly.

Expire

Params:

ssoToken: session access token
peerId: peer to contact

Description:

Message sent by the call server to tell peers that their message has expired due to the recipient being un-contactable or unresponsive.

Candidate

Params:

ssoToken: session access token
peerId: peer to contact
iceCandidates: List of ICE candidates

Description:

Message sent between peers to announce their ICE candidates for the purpose of establishing direct peer-to-peer or relayed connections.