Call Service

 In

Revision for “Call Service” created on 5 July 2016 @ 17:33:00

Title
Call Service
Content
<h1>Functional Description</h1>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.<h2>Caller Id</h2>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<span style="line-height: 1.5;"> 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:</span><ol> <li><span style="line-height: 1.5;">Signal every device the user is signed into (Google Hangouts approach)</span></li> <li>The layout context restricts the video chat DMApp component to a single capable device</li> <li>The user nominates a device within the layout context to be used for real-time comms</li> </ol>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.<h3>Example</h3>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.<h2>Signalling</h2>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.<h2>Responsibilities</h2><ul> <li>Broker connections between clients</li> <li>Permit clients to create, answer and hangup media calls (audio &amp; video).</li> <li>Permit clients to send and receive arbitrary datagrams peer-to-peer</li> <li>Notify clients of disconnections</li> <li>Utilise 2Immerse user identities and authorize or disallow calls based on successful session access tokens</li> </ul><h2>Collaborators</h2><ul> <li>STUN/TURN service</li> <li>Session service</li> <li>Logging service</li> </ul><h2>API</h2>PeerJS and peer-server are the nominated client and server technologies for implementing a WebRTC-based call service. The source code is available here: <a href="https://github.com/peers/peerjs">https://github.com/peers/peerjs</a>PeerJS is the client library and is documented here: <a href="http://peerjs.com/docs/%23api">http://peerjs.com/docs/#api</a>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: <a href="https://github.com/peers/peerjs-server">https://github.com/peers/peerjs-server</a>Both PeerServer and PeerJS are distributed under the MIT license.<h2>Changes required for 2Immerse</h2>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.<h2>Configuration</h2>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.<h2>Verbs</h2>In addition to connection/disconnection, the PeerJS server routes the messages, and their payloads between peers. It supports the following message types:<strong>Expire</strong> - message request to peer expired due to inactivity <strong>Leave</strong> - used to notify 'hang-up' of the connection <strong>Candidate</strong> - used to exchange ICE candidates (i.e. public facing IP addresses obtained from the STUN/TURN server) <strong>Offer</strong> - used to create a connection with an SDP (Session Description Protocol) payload <strong>Answer</strong> - response to an offer containing an SDP payloadThe 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.[wsd theme="napkin"] title Call Service: WebRTC signalling plane participant PeerA participant STUN participant TURN participant Call Server participant PeerBPeerA-&gt;STUN: Who am I? STUN-&gt;PeerA: Symmetric NAT PeerA-&gt;TURN: Request channel PeerA-&gt;Call Server: Offer (SDP A) Call Server-&gt;PeerB: Offer (SDP A) PeerB-&gt;Call Server: Answer (SDP B) Call Server-&gt;PeerA: Answer (SDP B) PeerA-&gt;Call Server: ICE Candidate (A) Call Server-&gt;PeerB: ICE Candidate (A) PeerB-&gt;STUN: Who am I? STUN-&gt;PeerB: IP address / port PeerB-&gt;Call Server: ICE Candidate (B) Call Server-&gt;PeerA: ICE Candidate (B) [/wsd]<img class="alignnone size-full wp-image-782" src="https://2immerse.eu/wp-content/uploads/2016/04/CallServiceSignallingPlane.png" alt="CallServiceSignallingPlane" width="547" height="540" /><strong>Offer</strong> <em>Params</em>:ssoToken: session access token peerId: peer to contact sdp: SDP (Session Description Protocol)<em>Description</em>: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.<strong>Answer</strong><em>Params</em>:ssoToken: session access token peerId: peer to contact sdp: SDP (Session Description Protocol)<em>Description</em>:Message sent in response to an offer. This includes all the information about the responder's configuration for the call (the SDP payload).<strong>Leave</strong><em>Params</em>:ssoToken: session access token peerId: peer to contact<em>Description</em>: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.<strong>Expire</strong><em>Params</em>:ssoToken: session access token peerId: peer to contact<em>Description</em>:Message sent by the call server to tell peers that their message has expired due to the recipient being un-contactable or unresponsive.<strong>Candidate</strong><em>Params</em>:ssoToken: session access token peerId: peer to contact iceCandidates: List of ICE candidates<em>Description</em>:Message sent between peers to announce their ICE candidates for the purpose of establishing direct peer-to-peer or relayed connections.
Excerpt
Markdown content
<h1>Functional Description</h1> 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. <h2>Caller Id</h2> 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<span style="line-height: 1.5;"> 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:</span> <ol> <li><span style="line-height: 1.5;">Signal every device the user is signed into (Google Hangouts approach)</span></li> <li>The layout context restricts the video chat DMApp component to a single capable device</li> <li>The user nominates a device within the layout context to be used for real-time comms</li> </ol> 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. <h3>Example</h3> 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. <h2>Signalling</h2> 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. <h2>Responsibilities</h2> <ul> <li>Broker connections between clients</li> <li>Permit clients to create, answer and hangup media calls (audio &amp; video).</li> <li>Permit clients to send and receive arbitrary datagrams peer-to-peer</li> <li>Notify clients of disconnections</li> <li>Utilise 2Immerse user identities and authorize or disallow calls based on successful session access tokens</li> </ul> <h2>Collaborators</h2> <ul> <li>STUN/TURN service</li> <li>Session service</li> <li>Logging service</li> </ul> <h2>API</h2> PeerJS and peer-server are the nominated client and server technologies for implementing a WebRTC-based call service. The source code is available here: <a href="https://github.com/peers/peerjs">https://github.com/peers/peerjs</a>PeerJS is the client library and is documented here: <a href="http://peerjs.com/docs/%23api">http://peerjs.com/docs/#api</a>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: <a href="https://github.com/peers/peerjs-server">https://github.com/peers/peerjs-server</a>Both PeerServer and PeerJS are distributed under the MIT license. <h2>Changes required for 2Immerse</h2> 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. <h2>Configuration</h2> 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. <h2>Verbs</h2> In addition to connection/disconnection, the PeerJS server routes the messages, and their payloads between peers. It supports the following message types:<strong>Expire</strong> - message request to peer expired due to inactivity <strong>Leave</strong> - used to notify 'hang-up' of the connection <strong>Candidate</strong> - used to exchange ICE candidates (i.e. public facing IP addresses obtained from the STUN/TURN server) <strong>Offer</strong> - used to create a connection with an SDP (Session Description Protocol) payload <strong>Answer</strong> - response to an offer containing an SDP payloadThe 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.[wsd theme="napkin"] title Call Service: WebRTC signalling plane participant PeerA participant STUN participant TURN participant Call Server participant PeerBPeerA-&gt;STUN: Who am I? STUN-&gt;PeerA: Symmetric NAT PeerA-&gt;TURN: Request channel PeerA-&gt;Call Server: Offer (SDP A) Call Server-&gt;PeerB: Offer (SDP A) PeerB-&gt;Call Server: Answer (SDP B) Call Server-&gt;PeerA: Answer (SDP B) PeerA-&gt;Call Server: ICE Candidate (A) Call Server-&gt;PeerB: ICE Candidate (A) PeerB-&gt;STUN: Who am I? STUN-&gt;PeerB: IP address / port PeerB-&gt;Call Server: ICE Candidate (B) Call Server-&gt;PeerA: ICE Candidate (B) [/wsd]<img class="alignnone size-full wp-image-782" src="https://2immerse.eu/wp-content/uploads/2016/04/CallServiceSignallingPlane.png" alt="CallServiceSignallingPlane" width="547" height="540" /><strong>Offer</strong> <em>Params</em>:ssoToken: session access token peerId: peer to contact sdp: SDP (Session Description Protocol)<em>Description</em>: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.<strong>Answer</strong><em>Params</em>:ssoToken: session access token peerId: peer to contact sdp: SDP (Session Description Protocol)<em>Description</em>:Message sent in response to an offer. This includes all the information about the responder's configuration for the call (the SDP payload).<strong>Leave</strong><em>Params</em>:ssoToken: session access token peerId: peer to contact<em>Description</em>: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.<strong>Expire</strong><em>Params</em>:ssoToken: session access token peerId: peer to contact<em>Description</em>:Message sent by the call server to tell peers that their message has expired due to the recipient being un-contactable or unresponsive.<strong>Candidate</strong><em>Params</em>:ssoToken: session access token peerId: peer to contact iceCandidates: List of ICE candidates<em>Description</em>:Message sent between peers to announce their ICE candidates for the purpose of establishing direct peer-to-peer or relayed connections.


OldNewDate CreatedAuthorActions
5 July 2016 @ 17:33:00Mark Lomas
5 July 2016 @ 17:32:26 [Autosave]Mark Lomas
5 July 2016 @ 16:51:49Mark Lomas
5 July 2016 @ 16:51:18Mark Lomas
5 July 2016 @ 16:41:57Mark Lomas
5 July 2016 @ 16:41:15Mark Lomas
5 July 2016 @ 16:39:00Mark Lomas
5 July 2016 @ 16:37:33Mark Lomas
5 July 2016 @ 16:27:05Mark Lomas
5 July 2016 @ 16:26:44Mark Lomas
12 May 2016 @ 15:09:14Mark Lomas
12 May 2016 @ 15:02:05Mark Lomas
18 April 2016 @ 00:40:48Ian Kegel
Recent Posts
Contact Us

We're not around right now. But you can send us an email and we'll get back to you, asap.

Not readable? Change text. captcha txt

Start typing and press Enter to search