-
Notifications
You must be signed in to change notification settings - Fork 9
/
signalling-protocol.html
144 lines (139 loc) · 8.17 KB
/
signalling-protocol.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="format-detection" content="telephone=no">
<meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width">
<title>rtc.io</title>
<link rel="stylesheet" type="text/css" href="css/reset.css">
<link rel="stylesheet" type="text/css" href="css/main.css">
<!-- responsive -->
<link rel="stylesheet" media="screen and (max-width: 960px)" href="css/tablet.css">
<link rel="stylesheet" media="screen and (max-width: 710px)" href="css/phone.css">
<link rel="stylesheet" type="text/css" href="fonts/source-sans/stylesheet.css">
<link rel="stylesheet" type="text/css" href="css/code.css">
</head>
<body>
<a class="scroll-point pt-top" name="top"></a>
<header>
<a href="https://github.com/rtc-io"><img class="fork" src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub"></a>
<a class="scroll-point pt-top" name="top"></a>
<div class="site">
<div class="mascot">
<img src="images/artsio.png">
</div>
<div class="logo" data-subtext="OpenSource WebRTC">
<a href="index.html">rtc.io</a>
</div>
<nav>
<ul>
<li><a href="index.html">About</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="modules.html">Modules</a></li>
</ul>
</nav>
</div>
<div class="shadow"></div>
</header>
<div class="main" role="content"><h1 id="rtc-signaller-protocol-overview">rtc-signaller Protocol Overview</h1>
<p>The signalling used by <code>rtc-signaller</code> follows some very simple rules:</p>
<ul>
<li><p>All messages are text (utf-8 encoded at present)</p>
</li>
<li><p>Message parts are delimited by a pipe (<code>|</code>) character</p>
</li>
<li><p>Message commands must be contained in the initial message part and can be recognized simply as their first character is the forward slash (<code>/</code>) character.</p>
</li>
<li><p>All messages (apart from <code>/to</code> messages) are distributed to all active peers currently "announced" in a room.</p>
</li>
<li><p>All signaling clients identify themselves with a unique, <a href="https://github.com/rtc-io/rtc-signaller/issues/10">non-reusable</a> id.</p>
</li>
</ul>
<hr>
<h2 id="transport-agnostic">Transport Agnostic</h2>
<p>While the <code>rtc-signaller</code> module provides some default behaviour to connect
via <a href="http://www.websocket.org/">websockets</a>, it is in fact a transport
"agnostic" protocol.</p>
<p>Basically, if you can send text over <em>x</em> then you could use <em>x</em> to send
<code>rtc-signaller</code> messages.</p>
<hr>
<h2 id="sender-metadata">Sender Metadata</h2>
<p>Sender metadata is injected into a message directly after the command (or initial message part) for all messages. The only exception is a <code>/to</code> message which has no sender metadata attached as this should be contained within the wrapped message.</p>
<p>At this stage only the sender id is included in the sender metadata (JSON), but this may be extended in the future to include additional information.</p>
<hr>
<h2 id="core-commands">Core Commands</h2>
<p>There are only a few core commands which make up the rtc-signaller signalling. These core commands should receive "special" treatment from a signalling server, whereas other commands are simply "passed through" to connected clients.</p>
<hr>
<h2 id="-announce">/announce</h2>
<p>The announce command is used to tell a signalling server (and connected peers) that a new client is joining a virtual room. The payload of the command is JSON and requires <strong>at least</strong> an <code>id</code> and a <code>room</code> attribute to be specified.</p>
<p>For example, this is what an announce message would typically look like (line breaks added for clarity):</p>
<pre><code>/announce
|{"id":"dc6ac0ae-6e15-409b-b211-228a8f4a43b9"}
|{"browser":"node","browserVersion":"?","id":"dc6ac0ae-6e15-409b-b211-228a8f4a43b9","agent":"signaller@0.18.3","room":"test-room"}</code></pre>
<hr>
<h2 id="-leave">/leave</h2>
<p>Unsurprisingly, a <code>/leave</code> message is the counterpart to an <code>/announce</code> message and is sent when a peer is disconnecting from the room.</p>
<p><strong>NOTE:</strong> As most client leave actions are "hard closes", i.e. a browser window / tab has been closed, a signalling server should monitor disconnections and issue an appropriate <code>/leave</code> message if the client has not issued one already.</p>
<hr>
<h2 id="-to">/to</h2>
<p>The <code>/to</code> command allows you to direct a message to a particular peer rather than broadcasting it to all peers connected to the same room as you.</p>
<p>An example <code>/to</code> command might look something like (again line breaks for clarity):</p>
<pre><code>/to
|51469ae5-5d9f-4294-84dd-83ce3b37b7dd
|/hello
|{"id":"98e17678-a89e-4f91-aee0-5b0d93ad546d"}</code></pre>
<p>For security reasons a signaling server is encouraged to direct <code>/to</code> messages only the connected peer; however, a client implementing this protocol should drop all '/to' messages that do not match it's own id.</p>
<hr>
<h2 id="that-s-pretty-much-it">That's Pretty Much It</h2>
<p>From a "protocol" perspective that's really all there is to it.</p>
<hr>
<h2 id="writing-a-client">Writing a Client</h2>
<p>The responsibilities of a client are fairly simple:</p>
<ul>
<li>For <code>/to</code> messages ensure the target matches, otherwise throw the message away.</li>
<li>For all other messages:<ul>
<li>divide messages on the <code>|</code> character</li>
<li>JSON parse any JSON parts into objects</li>
<li>extract the 2nd part as sender metadata</li>
</ul>
</li>
</ul>
<hr>
<h2 id="writing-a-server">Writing a Server</h2>
<p>The responsibilities of a server are also simple:</p>
<ul>
<li>Only send <code>/to</code> messages to the appropriate peer.</li>
<li>When an <code>/announce</code> message is received place the peer in a logical room with other peers announcing in the same room.</li>
<li>Handle client disconnection and <code>/leave</code> messages appropriately, i.e. remove a peer from the logical room.</li>
<li>Distribute "non <code>/to</code>" messages to all peers in the same room as the peer that the message originated from.</li>
</ul>
<hr>
<h2 id="what-about-authentication-">What About Authentication?</h2>
<p>While this hasn't been implemented in any applications to date, encrypted credentials or a session token could be supplied as part of the announce metadata.</p>
<p>Additionally for per message authentication a session token could be included as part of the sender metadata that is included in each message. This could be validated by the signaling server and stripped from the message before passing onto connected peers.</p>
<hr>
<h2 id="what-about-scaling-">What About Scaling?</h2>
<p>My intention was to minimally but adequately map out the interation required between peers, ensuring that both broadcast and direct messages were catered for. The likelihood is that implementing server -> server message passing and routing will require some additional work but this isn't something the end clients should have to care about.</p>
</div>
<footer>
<p>
<a href="http://nicta.com.au">
<img src="images/nicta-logo.gif" alt="NICTA logo">
</a>© NICTA 2013 - 2014
</p>
<p class="license">Project source code is licensed under the <a href="https://github.com/rtc-io/rtc/blob/master/LICENSE">Apache 2.0</a>.</p>
<a class="closing" href="#top"></a>
</footer>
</body>
<script src="js/app.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-26567546-2', 'rtc.io');
ga('send', 'pageview');
</script>
</html>