-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
404 lines (348 loc) · 18.4 KB
/
index.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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
<!DOCTYPE html>
<html>
<head>
<title>The WebSocket Server API</title>
<meta charset='utf-8'>
<script src='http://darobin.github.com/respec/builds/respec-w3c-common.js' class='remove'></script>
<script class='remove'>
var respecConfig = {
// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
specStatus: "unofficial",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "websocket-server",
// if your specification has a subtitle that goes below the main
// formal title, define it here
// subtitle : "an excellent document",
// if you wish the publication date to be other than today, set this
// publishDate: "2009-08-06",
// if the specification's copyright date is a range of years, specify
// the start date here:
// copyrightStart: "2005"
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
// and its maturity status
// previousPublishDate: "1977-03-15",
// previousMaturity: "WD",
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "http://dev.w3.org/2009/dap/ReSpec.js/documentation.html",
// if this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2009-08-05",
// editors, add as many as you like
// only "name" is required
editors: [
{ name: "Alexandre Morgaut", url: "http://about.me/amorgaut",
company: "4D", companyURL: "http://4D.com/" },
],
// authors, add as many as you like.
// This is optional, uncomment if you have authors as well as editors.
// only "name" is required. Same format as editors.
//authors: [
// { name: "Your Name", url: "http://example.org/",
// company: "Your Company", companyURL: "http://example.com/" },
//],
// name of the WG
wg: "Client and Server JavaScript API Community Group",
// URI of the public WG page
wgURI: "http://w3c.org/community/jseverywhere",
// name (without the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-jseverywhere",
// URI of the patent status for this WG, for Rec-track documents
// !!!! IMPORTANT !!!!
// This is important for Rec-track documents, do not copy a patent URI from a random
// document unless you know what you're doing. If in doubt ask your friendly neighbourhood
// Team Contact.
wgPatentURI: "",
};
</script>
</head>
<body>
<!-- ---------------------------- Abstract ---------------------------------- -->
<section id='abstract'>
This specification defines an API that enables Packaged Web Applications and
Server-Side JavaScript platforms to manage connections through the WebSocket
protocol (defined by the IETF) for two-way communication with a remote client.
</section>
<!-- --------------------------- Introduction ------------------------------- -->
<section class="informative">
<h2>Introduction</h2>
<p>To enable Web applications to maintain bidirectional
communications with client-side processes, this specification
introduces the <code><a href="#websocketserver">WebSocketServer</a></code>
interface.</p>
</section>
<!-- -------------------------- Conformance --------------------------------- -->
<section id="conformance">
<p>Implementations of the APIs defined in this specification MUST implement
them in a manner consistent with the ECMAScript Bindings defined in the
Web IDL specification [[!WEBIDL]], as this specification uses that
specification and terminology.
</p>
<section id="dependencies">
<h3>Dependencies</h3>
<p>This specification relies on several other underlying specifications.</p>
<dl>
<dt>HTML</dt>
<dd><p>Many fundamental concepts from HTML5 are used by this
specification. [[!HTML5]]</p></dd>
<dt>WebIDL</dt>
<dd><p>The IDL blocks in this specification use the semantics of the
WebIDL specification. [[!WEBIDL]]</p></dd>
<dt>The Web Sockets API</dt>
<dd><p>The WebSocketServer interface is based on the client WebSocket one [[!WEBSOCKETS-API]]</p></dd>
<dt>HTML5 Web Messaging</dt>
<dd><p>The multiple incomming connection on the Web socket server are managed by the port
mechanism defined in the HTML5 Web Messaging specification [[!POSTMSG]]</p></dd>
</dl>
</section>
</section>
<!----------------------------- Terminology ---------------------------------->
<section>
<h2>Terminology</h2>
<p>The <dfn><a href="http://www.w3.org/TR/html5/webappapis.html#eventhandler">EventHandler</a></dfn> interface represents a callback used for event handlers
as defined in [[!HTML5]].
</p>
<p>The concepts <dfn><a href="http://www.w3.org/TR/html5/webappapis.html#queue-a-task">
queue a task</a></dfn> and <dfn><a href="http://www.w3.org/TR/html5/webappapis.html#fire-a-simple-event">
fire a simple event</a></dfn> are defined in [[!HTML5]].
</p>
<p>The terms <dfn><a href="http://www.w3.org/TR/html5/webappapis.html#event-handlers">
event handler</a></dfn> and <dfn><a href="http://www.w3.org/TR/html5/webappapis.html#event-handler-event-type">
event handler event types</a></dfn> are defined in [[!HTML5]].
</p>
<p>The <a href="http://www.w3.org/TR/html5/webappapis.html#task-source">task source</a>
for all <span title="concept-task">tasks</span>
<span title="queue a task">queued</span> in this specification is the
<a href="http://www.w3.org/TR/websockets/#websocket-task-source">WebSocket task source</a>
defined in [[!WEBSOCKETS-API]].
</p>
<p>The term DOM is used to refer to the API set made available to
scripts in Web applications, and does not necessarily imply the
existence of an actual <code>Document</code> object or of any other
<code>Node</code> objects as defined in the DOM Core
specifications. [[!DOM-LEVEL-3-CORE]]</p>
<p>An IDL attribute is said to be <em>getting</em> when its value is
being retrieved (e.g. by author script), and is said to be
<em>setting</em> when a new value is assigned to it.</p>
</section>
<!------------------------ Security and privacy ------------------------------>
<section>
<h2>Security and privacy considerations</h2>
<p>
This API must be only exposed to trusted content.
</p>
</section>
<!------------------------ Interface WebSocketServer ------------------------------>
<section>
<h2>Interface <a>WebSocketServer</a></h2>
<p>The <a>WebSocketServer</a> interface defines attributes and methods for
Web Socket Server communication</p>
<pre class="example highlight">
var webSocketServer = new WebSocketServer(urlToListen, serverID);
webSocketServer.onconnect = function handleClient(event) {
var port = event.port[0];
// security related informations
var origin = port.origin; // check same origin or CORS access
var cookies = port.cookies; // initial HTTP cookies
var authorization = port.authorization; // initial HTTP Authorization header
var remoteURI = port.remoteURI; // ex: "tcp:194.43.12.5:80"
// handle client messages
port.onmessage = function handleMessage(msgEvent) {
// send a message to a specific client
port.postMessage(message);
}
};
// send basic message to all connected clients
webSocketServer.send(message);
webSocketServer.onmessage = function (msgEvent) {
// global handling of client message
var origin = msgEvent.origin; // check same origin or CORS access
var cookies = msgEvent.cookies; // initial HTTP cookies
var authorization = msgEvent.authorization; // initial HTTP Authorization header
var remoteURI = msgEvent.remoteURI; // ex: "tcp:194.43.12.5:80"
};
</pre>
<dl title="[Constructor (DOMString url, optional DOMString socketServerID, optional DOMString protocol)] interface WebSocketServer : EventTarget" class="idl">
<dt>readonly attribute DOMString url</dt>
<dd><p class="issue">TBD: Coming from the <dfn><a href="http://www.w3.org/TR/websockets/#the-websocket-interface">WebSocket</a></dfn>
interface. Used on the Server Interface to specified the listened URI</p>
</dd></dd>
<dt>[ready state]const unsigned short CONNECTING = 0</dt>
<dd>The connection has not yet been established.</dd>
<dt>const unsigned short OPEN = 1</dt>
<dd>The WebSocket connection is established and communication is possible.</dd>
<dt>const unsigned short CLOSING = 2</dt>
<dd>The connection is going through the closing handshake, or the close() method has been
invoked.</dd>
<dt>const unsigned short CLOSED = 3</dt>
<dd>The connection has been closed or could not be opened.</dd>
<dt>readonly attribute unsigned short readyState</dt>
<dd>
<p>The <dfn><code>readyState</code></dfn> attribute represents the state of the connection. It can have the
constant defined values</p>
</dd>
<dt>readonly attribute unsigned long bufferedAmount</dt>
<dd>
<p>The <dfn><code>bufferedAmount</code></dfn> attribute must return the number of bytes of
application data (UTF-8 text and binary data) that have been queued using send() but
that, as of the last time the event loop started executing a task, had not yet been
transmitted to the network. (This thus includes any text sent during the execution of
the current task, regardless of whether the user agent is able to transmit text
asynchronously with script execution.) This does not include framing overhead incurred
by the protocol, or buffering done by the operating system or network hardware.
If the connection is closed, this attribute's value will only increase with each call
to the <dfn><code>send()</code></dfn> method (the number does not reset to zero once the
connection closes).</p>
</dd>
<dt>[networking]attribute EventHandler onopen</dt>
<dd>
<p>Event handler that corresponds to the <dfn><code>open</code></dfn> event, which is
fired when the socket is open and ready to receive connection attempts from clients. If
the creation of the server socket fails the error event will be fired instead.</p>
</dd>
// networking
<dt>attribute EventHandler onconnect</dt>
<dd>
<p>Event handler that corresponds to the <dfn><code>connect</code></dfn> event, which is
fired repeatedly and asynchronously after the <dfn><code>WebSocketServer</code></dfn>
object has been created, every time an incoming connection attempt on the specified URI
has been accepted.</p>
</dd>
<dt>attribute EventHandler onerror</dt>
<dd>
<p>Event handler that corresponds to the <dfn><code>error</code></dfn> event, which is
fired when there is an error on the server socket. The data attribute of the event passed
to the onerror handler will have a description of the kind of error.</p>
</dd>
<dt>attribute EventHandler onclose</dt>
<dd>
<p class="issue">TBD: Coming from the <dfn><a href="http://www.w3.org/TR/websockets/#the-websocket-interface">WebSocket</a></dfn>
interface. To be specified if required</p>
</dd>
<dt>readonly attribute DOMString extensions</dt>
<dd>
<p class="issue">TBD: Coming from the <dfn><a href="http://www.w3.org/TR/websockets/#the-websocket-interface">WebSocket</a></dfn>
interface. To be specified if required</p>
</dd>
<dt>readonly attribute DOMString protocol</dt>
<dd>
<p class="issue">TBD: Coming from the <dfn><a href="http://www.w3.org/TR/websockets/#the-websocket-interface">WebSocket</a></dfn>
interface. To be specified if required</p>
</dd>
<dt>void close()</dt>
<dd>
<p>Closes the Web socket. A closed Web socket can not be used any more.</p>
</dd>
<dt>[messaging]attribute EventHandler onmessage</dt>
<dd><p class="issue">TBD: Coming from the <dfn><a href="http://www.w3.org/TR/websockets/#the-websocket-interface">WebSocket</a></dfn>
interface. Expected to be used to handle messages from whatever connection. May be source of security issues.</p>
</dd>
<dt>attribute DOMString binaryType</dt>
<dd>
<p>When a WebSocket object is created, its binaryType IDL attribute must
be set to the string "blob". On getting, it must return the last value
it was set to. On setting, if the new value is either the string "blob"
or the string "arraybuffer", then set the IDL attribute to this new
value. Otherwise, throw a SyntaxError exception.</p>
<p class="issue">As <dfn><code>WebSocketServer</code></dfn> can be connected to multiple
client, this property should also be at the <dfn><code>port</code></dfn> level and
depend on each connection related <dfn><code>port.onmessage</code></dfn> event</p>
</dd>
<dt>void send(ArrayBufferView data)</dt>
<dd>
<p>Sends data on the given Web socket to all the connected clients.</p>
<dl class='parameters'>
<dt>(DOMString or Blob or ArrayBuffer or ArrayBufferView) data</dt>
<dd>
The data to write in one of the alternative representations as
stated below:
<ul>
<li> Represented as a sequence of Unicode characters. [[!UNICODE]].
<li> As raw data represented by the Blob object. [[!FILE-API]]
<li> Represented as an ArrayBuffer object. [[!TYPED-ARRAYS]]
<li> Represented by the section of the buffer described by the
ArrayBuffer object that the ArrayBufferView object references.
[[!TYPED-ARRAYS]].
</ul>
</dd>
</dl>
</dd>
</dl>
</section>
<!-- ----------------------- Ping and Pong frames ----------------------------- -->
<section id='ping-and-pong-frames'>
<h2>Ping and Pong frames</h2>
<p>The WebSocket protocol specification defines Ping and Pong frames that can be used for
keep-alive, heart-beats, network status probing, latency instrumentation, and so forth.
These are not currently exposed in the API.</p>
<p class="issue">TBD: Section coming from The Web Sockets API
[[!WEBSOCKETS-API]]. To be specified if required</p>
</section>
<!-- ----------------------- Parsing WebSocket URLs ----------------------------- -->
<section id='parsing-websocket-urls'>
<h2>Parsing WebSocket URLs</h2>
<p>The steps to <dfn id="parse-a-websocket-url-s-components">parse a WebSocket URL's components</dfn>
from a string <var title="">url</var> are as follows. These steps return either a
<var title="">host</var>, a <var title="">port</var>, a <var title="">resource name</var>,
and a <var title="">secure</var> flag, or they fail.</p>
<p class="issue">TBD: Section coming from The Web Sockets API
[[!WEBSOCKETS-API]]. To be specified if required</p>
</section>
<!-- -------------------------- Event definitions -------------------------------- -->
<section id='event-definitions'>
<h2>Event definitions</h2>
<p>TO BE DONE</p>
<section id='connect-event'>
<h2><dfn><code>connect</code></dfn> Event Interface</h2>
<dl class="idl" title="interface connect : MessageEvent {">
<dt>readonly attribute DOMString cookies</dt>
<dd>
<p>Cookies from the HTTP connection which initiated the Web Socket connection</p>
<p>May be used to bind the message to an existing session</p>
</dd>
<dt>readonly attribute DOMString authorization</dt>
<dd>
<p>Content of the Authorization header of the HTTP connection which initiated the Web
Socket connection</p>
<p>May be used to authenticate the user and provide related permissions</p>
</dd>
<dt>readonly attribute DOMString remoteURI</dt>
<dd></dd>
<dt>readonly attribute MessagePort ports</dt>
<dd>First port (index 0) is used to send and receive messages through a specific connection</dd>
};</dl>
</section>
<section id='message-event'>
<h2><dfn><code>message</code></dfn> Event Interface</h2>
<dl class="idl" title="interface message : MessageEvent {">
<dt>readonly attribute DOMString cookies</dt>
<dd>
<p>Cookies from the HTTP connection which initiated the Web Socket connection</p>
<p>May be used to detect from which connection the message come from and to bind the
message to an existing session</p>
</dd>
<dt>readonly attribute DOMString authorization</dt>
<dd>
<p>Content of the Authorization header of the HTTP connection which initiated the Web
Socket connection</p>
<p>May be used to authenticate the user and provide related permissions</p>
</dd>
<dt>readonly attribute DOMString remoteURI</dt>
<dd></dd>
<dd></dd>
};</dl>
</section>
</section>
<!-- -------------------------- Garbage collection -------------------------------- -->
<section id='garbage-collection'>
<h2>Garbage collection</h2>
<p class="issue">TBD: Section coming from The Web Sockets API
[[!WEBSOCKETS-API]]. To be specified if required</p>
</section>
<!-- ---------------------------- Appendix ---------------------------------- -->
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
Many thanks to Robin Berjon for making our lives so much easier with his cool tool.
</p>
</section>
</body>
</html>