WebRTC

Version 26 (Adrian Georgescu, 08/01/2015 06:15 am)

1 1 Saúl Ibarra Corretgé
h1. SylkServer WebRTC gateway application
2 1 Saúl Ibarra Corretgé
3 25 Adrian Georgescu
Starting with version 3.0.0 SylkServer features WebRTC gateway capacities. This application implements a WebSocket protocol which WebRTC endpoints can use in order to interact bidirectionally with the SIP world.
4 2 Saúl Ibarra Corretgé
5 24 Adrian Georgescu
h2. Deployment scenarios
6 24 Adrian Georgescu
7 25 Adrian Georgescu
 * Web page calling using a WebRTC enabled web browsers like Firefox and Google Chrome
8 26 Adrian Georgescu
 * Mobile iOS and Android application for multimedia calling
9 24 Adrian Georgescu
10 2 Saúl Ibarra Corretgé
h2. Architecture
11 1 Saúl Ibarra Corretgé
12 25 Adrian Georgescu
SylkServer WebRTC gateway application consists of several (internal and external) components, which together aim to provide the same communication experience as with "Blink":http://icanblink.com or any other feature-full SIP client.
13 21 Saúl Ibarra Corretgé
14 21 Saúl Ibarra Corretgé
TODO: diagram
15 1 Saúl Ibarra Corretgé
16 1 Saúl Ibarra Corretgé
All interaction with the gateway from the Web's side is performed through a WebSocket connection using the "sylkRTC protocol" described in this document.
17 1 Saúl Ibarra Corretgé
18 25 Adrian Georgescu
h5. Registration
19 25 Adrian Georgescu
20 25 Adrian Georgescu
This function is equivalent to SIP REGISTER method and allows an end-point to receive incoming calls.
21 25 Adrian Georgescu
22 1 Saúl Ibarra Corretgé
h5. Audio / video sessions
23 21 Saúl Ibarra Corretgé
24 25 Adrian Georgescu
This function is equivalent to SIP INVITE method and allows an end-point to establish audio and video sessions using RTP protocol.
25 25 Adrian Georgescu
26 1 Saúl Ibarra Corretgé
Audio and video sessions support is provided through an external component: "Janus.":https://github.com/meetecho/janus-gateway SylkServer communicates directly with Janus and offers a complete API together with the rest of the components described below.
27 21 Saúl Ibarra Corretgé
28 21 Saúl Ibarra Corretgé
h5. Chat sessions
29 1 Saúl Ibarra Corretgé
30 25 Adrian Georgescu
This function is equivalent to SIP INVITE method and allows an end-point to establish chat sessions using MSRP protocol.
31 1 Saúl Ibarra Corretgé
32 21 Saúl Ibarra Corretgé
Chat sessions are implemented as an internal component which translates JSON messages over WebSocket with MSRP chat messages. The payload will remain unchanged, so CPIM is mandatory and will be used end to end. A library such as "cpim.js":https://github.com/eface2face/cpim.js can be used to parse chat messages in a JavaScript application.
33 21 Saúl Ibarra Corretgé
34 25 Adrian Georgescu
h5. Contacts management
35 21 Saúl Ibarra Corretgé
36 25 Adrian Georgescu
This function corresponds to its equivalent XCAP protocol GET/PUT/DELETE methods. Contacts management is implemented as an internal component which fetches the user's XCAP documents and translates the contact list into JSON format, which is then sent over the WebSocket connection.
37 21 Saúl Ibarra Corretgé
38 25 Adrian Georgescu
h5. Presence
39 21 Saúl Ibarra Corretgé
40 21 Saúl Ibarra Corretgé
Presence information is gathered by sending SIP SUBSCRIBE requests on behalf of the user. The presence information is combined with the contact information and provided via JSON events to the application.
41 2 Saúl Ibarra Corretgé
42 2 Saúl Ibarra Corretgé
h2. WebSocket API
43 5 Saúl Ibarra Corretgé
44 1 Saúl Ibarra Corretgé
SylkServer offers the WebSocket API in order to interact with the WebRTC gateway in the @ws(s)://hostname:port/webrtcgateway/ws@ endpoint. Both WebSocket and Secure WebSocket are supported, depending on how SylkServer was configured, check the configuration section.
45 18 Saúl Ibarra Corretgé
46 5 Saúl Ibarra Corretgé
The API uses JSON messages and is modeled around 2 concepts: requests and events. We call this the sylkRTC protocol.
47 5 Saúl Ibarra Corretgé
48 1 Saúl Ibarra Corretgé
A request represents an action which SylkServer should perform, and it's identified with a transaction ID which the user must provide. SylkServer will reply with either an 'ack' or an 'error' response, with the associated transaction ID. An example transaction is that of adding an account.
49 5 Saúl Ibarra Corretgé
50 5 Saúl Ibarra Corretgé
Events are notifications sent by SylkServer to the client. They are the result of some change triggered by a user action, but they don't have a transaction ID associated with them. An example event would be the connection state changed event.
51 1 Saúl Ibarra Corretgé
52 7 Saúl Ibarra Corretgé
All messages are valid JSON and contain the "sylkrtc" key indicating the message type. A message without the "sylkrtc" key is an invalid message.
53 7 Saúl Ibarra Corretgé
54 5 Saúl Ibarra Corretgé
h3. Establishing the connection
55 1 Saúl Ibarra Corretgé
56 25 Adrian Georgescu
In order for a Web application to connect to SylkServer to begin to use the API a WebSocket connection must be established, using the @sylkRTC-1@ subprotocol. Example:
57 6 Saúl Ibarra Corretgé
58 6 Saúl Ibarra Corretgé
<pre>
59 6 Saúl Ibarra Corretgé
var conn = new WebSocket('wss://example.com/webrtcgateway/ws', 'sylkRTC-1');
60 6 Saúl Ibarra Corretgé
</pre>
61 6 Saúl Ibarra Corretgé
62 6 Saúl Ibarra Corretgé
After the connection is established, a 'ready' event will be sent to the client, indicating that the connection is ready to be used:
63 6 Saúl Ibarra Corretgé
64 6 Saúl Ibarra Corretgé
<pre>
65 18 Saúl Ibarra Corretgé
{"event": "ready", "sylkrtc": "event"}
66 6 Saúl Ibarra Corretgé
</pre>
67 1 Saúl Ibarra Corretgé
68 7 Saúl Ibarra Corretgé
Example:
69 7 Saúl Ibarra Corretgé
70 7 Saúl Ibarra Corretgé
<pre>
71 7 Saúl Ibarra Corretgé
var conn = new WebSocket('wss://example.com/webrtcgateway/ws', 'sylkRTC-1');
72 7 Saúl Ibarra Corretgé
conn.onmessage = function(event) {
73 7 Saúl Ibarra Corretgé
    var message = JSON.parse(event.data);
74 7 Saúl Ibarra Corretgé
    switch (message.sylkrtc) {
75 7 Saúl Ibarra Corretgé
        case 'event':
76 7 Saúl Ibarra Corretgé
            if (message.event === 'ready') {
77 7 Saúl Ibarra Corretgé
                console.log('Ready to rock!');
78 7 Saúl Ibarra Corretgé
            }
79 7 Saúl Ibarra Corretgé
            break;
80 1 Saúl Ibarra Corretgé
        default:
81 1 Saúl Ibarra Corretgé
            console.log('Received message type: ' + message.sylkrtc);
82 7 Saúl Ibarra Corretgé
            break;
83 7 Saúl Ibarra Corretgé
    }
84 7 Saúl Ibarra Corretgé
};
85 7 Saúl Ibarra Corretgé
</pre>
86 5 Saúl Ibarra Corretgé
87 18 Saúl Ibarra Corretgé
h3. Account management
88 8 Saúl Ibarra Corretgé
89 25 Adrian Georgescu
Multiple accounts can be managed from a single WebSocket connection. 2 types of requests are used to manage accounts: "account-add" and "account-remove". Once an account has been added it can be registered via SIP using the "account-register" command, and unregistered using the "account-unregister" command. Registration is required for receiving incoming calls. It's not necessary to register an account in order to make outgoing calls.
90 1 Saúl Ibarra Corretgé
91 18 Saúl Ibarra Corretgé
h5. account-add
92 13 Saúl Ibarra Corretgé
93 8 Saúl Ibarra Corretgé
Configures an account on the current connection.
94 8 Saúl Ibarra Corretgé
95 1 Saúl Ibarra Corretgé
<pre>
96 8 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
97 8 Saúl Ibarra Corretgé
 'password': '884edfee38ed471b8a15006700139485',
98 18 Saúl Ibarra Corretgé
 'sylkrtc': 'account-add',
99 8 Saúl Ibarra Corretgé
 'transaction': '04013f0f-25bb-4082-a02f-44399df492ff'}
100 1 Saúl Ibarra Corretgé
</pre>
101 8 Saúl Ibarra Corretgé
102 9 Saúl Ibarra Corretgé
The password MUST be in "HA1 format":https://en.wikipedia.org/wiki/Digest_access_authentication#Overview
103 18 Saúl Ibarra Corretgé
104 1 Saúl Ibarra Corretgé
h5. account-remove
105 9 Saúl Ibarra Corretgé
106 9 Saúl Ibarra Corretgé
Removes an account from the current connection.
107 9 Saúl Ibarra Corretgé
108 8 Saúl Ibarra Corretgé
<pre>
109 1 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
110 18 Saúl Ibarra Corretgé
 'sylkrtc': 'account-remove',
111 9 Saúl Ibarra Corretgé
 'transaction': 'bd3ee25d-5f16-4f76-b34e-8ac3fe0a4ac0'}
112 9 Saúl Ibarra Corretgé
</pre>
113 1 Saúl Ibarra Corretgé
114 13 Saúl Ibarra Corretgé
h5. register
115 1 Saúl Ibarra Corretgé
116 25 Adrian Georgescu
Triggers the account registration via SIP REGISTER method.
117 1 Saúl Ibarra Corretgé
118 9 Saúl Ibarra Corretgé
<pre>
119 9 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
120 18 Saúl Ibarra Corretgé
 'sylkrtc': 'account-register',
121 9 Saúl Ibarra Corretgé
 'transaction': 'bcb87b0f-0cc7-42a9-897e-81f035910670'}
122 9 Saúl Ibarra Corretgé
</pre>
123 9 Saúl Ibarra Corretgé
124 9 Saúl Ibarra Corretgé
The registration progress will be reported in form of events.
125 9 Saúl Ibarra Corretgé
126 9 Saúl Ibarra Corretgé
<pre>
127 9 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
128 9 Saúl Ibarra Corretgé
 'data': {'state': 'registering'},
129 9 Saúl Ibarra Corretgé
 'event': 'registration_state',
130 9 Saúl Ibarra Corretgé
 'sylkrtc': 'account_event'}
131 9 Saúl Ibarra Corretgé
132 9 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
133 9 Saúl Ibarra Corretgé
 'data': {'state': 'registered'},
134 9 Saúl Ibarra Corretgé
 'event': 'registration_state',
135 9 Saúl Ibarra Corretgé
 'sylkrtc': 'account_event'}
136 1 Saúl Ibarra Corretgé
</pre>
137 9 Saúl Ibarra Corretgé
138 9 Saúl Ibarra Corretgé
Example of failed registration:
139 9 Saúl Ibarra Corretgé
140 9 Saúl Ibarra Corretgé
<pre>
141 1 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
142 9 Saúl Ibarra Corretgé
 'data': {'reason': '904 Operation has no matching challenge ',
143 9 Saúl Ibarra Corretgé
          'state': 'failed'},
144 9 Saúl Ibarra Corretgé
 'event': 'registration_state',
145 9 Saúl Ibarra Corretgé
 'sylkrtc': 'account_event'}
146 1 Saúl Ibarra Corretgé
</pre>
147 9 Saúl Ibarra Corretgé
148 18 Saúl Ibarra Corretgé
h5. account-unregister
149 13 Saúl Ibarra Corretgé
150 1 Saúl Ibarra Corretgé
Unregister the account, via SIP.
151 10 Saúl Ibarra Corretgé
152 10 Saúl Ibarra Corretgé
<pre>
153 10 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
154 18 Saúl Ibarra Corretgé
 'sylkrtc': 'account-unregister',
155 1 Saúl Ibarra Corretgé
 'transaction': '1c81eea0-b247-4ced-b3b3-3ced1eba810e'}
156 10 Saúl Ibarra Corretgé
</pre>
157 9 Saúl Ibarra Corretgé
158 18 Saúl Ibarra Corretgé
h3. Sessions
159 1 Saúl Ibarra Corretgé
160 18 Saúl Ibarra Corretgé
h5. Incoming sessions
161 1 Saúl Ibarra Corretgé
162 18 Saúl Ibarra Corretgé
Incoming sessions are received via an *incoming_session* event:
163 14 Saúl Ibarra Corretgé
164 1 Saúl Ibarra Corretgé
<pre>
165 14 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
166 20 Saúl Ibarra Corretgé
 'data': {'originator': '31208005163@ag-projects.com', 'sdp': '...'},
167 18 Saúl Ibarra Corretgé
 'event': 'incoming_session',
168 1 Saúl Ibarra Corretgé
 'session': '509b256aa6a14540a2a37553e6bd33e1',
169 14 Saúl Ibarra Corretgé
 'sylkrtc': 'account_event'}
170 1 Saúl Ibarra Corretgé
171 14 Saúl Ibarra Corretgé
</pre>
172 1 Saúl Ibarra Corretgé
173 18 Saúl Ibarra Corretgé
The "session-answer" request can be used in order to answer an incoming session:
174 1 Saúl Ibarra Corretgé
175 1 Saúl Ibarra Corretgé
<pre>
176 15 Saúl Ibarra Corretgé
{'sdp': '...',
177 15 Saúl Ibarra Corretgé
 'session': '38dffdf81acb44b2b11b61f4488c4ca9',
178 18 Saúl Ibarra Corretgé
 'sylkrtc': 'session-answer',
179 15 Saúl Ibarra Corretgé
 'transaction': '179a855f-75a0-45a4-b5ef-0be8eb8389d1'}
180 1 Saúl Ibarra Corretgé
</pre>
181 15 Saúl Ibarra Corretgé
182 18 Saúl Ibarra Corretgé
h5. Outgoing sessions
183 14 Saúl Ibarra Corretgé
184 18 Saúl Ibarra Corretgé
In order to create an outgoing session the "session-create" request is used, by passing the SDP returned by the web browser. There is no need to wait for all ICE candidates since trickle ICE is used.
185 1 Saúl Ibarra Corretgé
186 14 Saúl Ibarra Corretgé
<pre>
187 14 Saúl Ibarra Corretgé
{'account': 'saghul@sip2sip.info',
188 14 Saúl Ibarra Corretgé
 'sdp': '...',
189 14 Saúl Ibarra Corretgé
 'session': '20c40185-1ef2-419e-b91a-70415778acb4',
190 18 Saúl Ibarra Corretgé
 'sylkrtc': 'session-create',
191 1 Saúl Ibarra Corretgé
 'transaction': '7afcb91a-8a64-4664-9448-8cb760492e1f',
192 1 Saúl Ibarra Corretgé
 'uri': '3333@sip2sip.info'}
193 14 Saúl Ibarra Corretgé
</pre>
194 14 Saúl Ibarra Corretgé
195 15 Saúl Ibarra Corretgé
h5. Trickle ICE
196 15 Saúl Ibarra Corretgé
197 18 Saúl Ibarra Corretgé
As new candidates are discovered they must be sent to the server using 'session-trickle' requests:
198 14 Saúl Ibarra Corretgé
199 14 Saúl Ibarra Corretgé
<pre>
200 14 Saúl Ibarra Corretgé
{'candidates': [{'candidate': 'candidate:0 1 UDP 2130379007 192.168.99.44 59051 typ host',
201 14 Saúl Ibarra Corretgé
                 'sdpMLineIndex': 0,
202 14 Saúl Ibarra Corretgé
                 'sdpMid': ''}],
203 1 Saúl Ibarra Corretgé
 'session': '20c40185-1ef2-419e-b91a-70415778acb4',
204 18 Saúl Ibarra Corretgé
 'sylkrtc': 'session-trickle',
205 1 Saúl Ibarra Corretgé
 'transaction': 'ecf777d8-7d26-4f16-bace-18f6fae5d8f8'}
206 1 Saúl Ibarra Corretgé
</pre>
207 1 Saúl Ibarra Corretgé
208 19 Saúl Ibarra Corretgé
Use an empty list of candidates to indicate that no more candidates will be sent.
209 19 Saúl Ibarra Corretgé
210 15 Saúl Ibarra Corretgé
This applies to both incoming and outgoing calls.
211 15 Saúl Ibarra Corretgé
212 15 Saúl Ibarra Corretgé
There is no need to wait for the acknowledgement for the "session-create" or "session-answer" request before sending "session-trickle" requests.
213 1 Saúl Ibarra Corretgé
214 19 Saúl Ibarra Corretgé
h5. Terminating sessions
215 15 Saúl Ibarra Corretgé
216 19 Saúl Ibarra Corretgé
A session can be terminated at any time by sending the "session-terminate" request:
217 1 Saúl Ibarra Corretgé
218 15 Saúl Ibarra Corretgé
<pre>
219 15 Saúl Ibarra Corretgé
{'session': '38dffdf81acb44b2b11b61f4488c4ca9',
220 19 Saúl Ibarra Corretgé
 'sylkrtc': 'session-terminate',
221 15 Saúl Ibarra Corretgé
 'transaction': '4d169de8-fe55-41f8-9a5c-c5f66c0a23c7'}
222 1 Saúl Ibarra Corretgé
</pre>
223 15 Saúl Ibarra Corretgé
224 15 Saúl Ibarra Corretgé
h5. Events
225 15 Saúl Ibarra Corretgé
226 19 Saúl Ibarra Corretgé
Session state related events are reported via the "session_event" event:
227 16 Saúl Ibarra Corretgé
228 16 Saúl Ibarra Corretgé
<pre>
229 16 Saúl Ibarra Corretgé
'data': {'state': 'established'},
230 16 Saúl Ibarra Corretgé
 'event': 'state',
231 16 Saúl Ibarra Corretgé
 'session': '38dffdf81acb44b2b11b61f4488c4ca9',
232 16 Saúl Ibarra Corretgé
 'sylkrtc': 'session_event'}
233 16 Saúl Ibarra Corretgé
</pre>
234 16 Saúl Ibarra Corretgé
235 16 Saúl Ibarra Corretgé
<pre>
236 16 Saúl Ibarra Corretgé
{'data': {'sdp': '...', 'state': 'accepted'},
237 16 Saúl Ibarra Corretgé
 'event': 'state',
238 16 Saúl Ibarra Corretgé
 'session': '20c40185-1ef2-419e-b91a-70415778acb4',
239 16 Saúl Ibarra Corretgé
 'sylkrtc': 'session_event'}
240 16 Saúl Ibarra Corretgé
</pre>
241 16 Saúl Ibarra Corretgé
242 1 Saúl Ibarra Corretgé
<pre>
243 1 Saúl Ibarra Corretgé
{'data': {'reason': '200 to BYE', 'state': 'terminated'},
244 1 Saúl Ibarra Corretgé
 'event': 'state',
245 1 Saúl Ibarra Corretgé
 'session': '20c40185-1ef2-419e-b91a-70415778acb4',
246 16 Saúl Ibarra Corretgé
 'sylkrtc': 'session_event'}
247 16 Saúl Ibarra Corretgé
</pre>
248 1 Saúl Ibarra Corretgé
249 19 Saúl Ibarra Corretgé
Valid session states:
250 17 Saúl Ibarra Corretgé
251 19 Saúl Ibarra Corretgé
* incoming: initial state for incoming sessions, no state event is sent for this state.
252 19 Saúl Ibarra Corretgé
* progress: on outgoing sessions, when in progress.
253 19 Saúl Ibarra Corretgé
* accepted: both for incoming and outgoing, when the session has been accepted by the remote party. For incoming, an "sdp" attribute will be present in the "data" section, as shown in the example above. 
254 19 Saúl Ibarra Corretgé
* established: the session has been established media-wise.
255 19 Saúl Ibarra Corretgé
* terminated: session was terminated, the "reason" attribute indicates the termination reason.
256 4 Saúl Ibarra Corretgé
257 25 Adrian Georgescu
h2. Zero-configuration
258 4 Saúl Ibarra Corretgé
259 25 Adrian Georgescu
The server is designed to work without any special configuration, its defaults settings will provide a working environment immediately after starting the software. It is however desirable to replace the bundled test TLS certificate with a valid TLS certificate signed by an authority recognised by the web application.
260 2 Saúl Ibarra Corretgé
261 23 Saúl Ibarra Corretgé
h2. JavaScript client library
262 1 Saúl Ibarra Corretgé
263 25 Adrian Georgescu
In order to interact with SylkServer's WebRTC gateway, "sylkrtc.js":http://projects.ag-projects.com/projects/sylkrtc JavaScript library is provided. This library implements the API described in this document in an easy to use manner. Check the README file in the project for the JavaScript API documentation.