[html5] r1840 - [] (0) Web Socket specification - replaces TCPConnection and related interfaces. [...]
whatwg at whatwg.org
whatwg at whatwg.org
Thu Jul 3 01:36:38 PDT 2008
Author: ianh
Date: 2008-07-03 01:36:37 -0700 (Thu, 03 Jul 2008)
New Revision: 1840
Modified:
index
source
Log:
[] (0) Web Socket specification - replaces TCPConnection and related interfaces. Also split 'serialisation of an origin' into two algorithms, one for unicode and one for ascii. And some minor editorial things.
Modified: index
===================================================================
--- index 2008-07-01 23:09:39 UTC (rev 1839)
+++ index 2008-07-03 08:36:37 UTC (rev 1840)
@@ -25,7 +25,7 @@
<h1 id=html-5>HTML 5</h1>
- <h2 class="no-num no-toc" id=draft>Draft Recommendation — 1 July
+ <h2 class="no-num no-toc" id=draft>Draft Recommendation — 3 July
2008</h2>
<p>You can take part in this work. <a
@@ -1104,9 +1104,6 @@
<ul class=toc>
<li><a href="#relaxing"><span class=secno>5.3.1 </span>Relaxing the
same-origin restriction</a>
-
- <li><a href="#the-string"><span class=secno>5.3.2 </span>The string
- representing the script's domain in IDNA format</a>
</ul>
<li><a href="#scripting"><span class=secno>5.4 </span>Scripting</a>
@@ -1567,65 +1564,46 @@
<li><a href="#notes"><span class=secno>7.2.5 </span>Notes</a>
</ul>
- <li><a href="#network"><span class=secno>7.3 </span>Network
- connections</a>
+ <li><a href="#network"><span class=secno>7.3 </span>Web sockets</a>
<ul class=toc>
<li><a href="#network-intro"><span class=secno>7.3.1
</span>Introduction</a>
- <li><a href="#the-connection"><span class=secno>7.3.2 </span>The
- <code>Connection</code> interface</a>
+ <li><a href="#the-websocket"><span class=secno>7.3.2 </span>The
+ <code>WebSocket</code> interface</a>
- <li><a href="#connection"><span class=secno>7.3.3 </span>Connection
+ <li><a href="#websocket"><span class=secno>7.3.3 </span>WebSocket
Events</a>
- <li><a href="#tcp-connections"><span class=secno>7.3.4 </span>TCP
- connections</a>
-
- <li><a href="#broadcast"><span class=secno>7.3.5 </span>Broadcast
- connections</a>
+ <li><a href="#the-web"><span class=secno>7.3.4 </span>The Web Socket
+ protocol</a>
<ul class=toc>
- <li><a href="#broadcasting"><span class=secno>7.3.5.1.
- </span>Broadcasting over TCP/IP</a>
+ <li><a href="#client-side"><span class=secno>7.3.4.1.
+ </span>Client-side requirements</a>
+ <ul class=toc>
+ <li><a href="#handshake"><span class=secno>7.3.4.1.1.
+ </span>Handshake</a>
- <li><a href="#bluetooth-broadcast"><span class=secno>7.3.5.2.
- </span>Broadcasting over Bluetooth</a>
+ <li><a href="#data-framing"><span class=secno>7.3.4.1.2.
+ </span>Data framing</a>
+ </ul>
- <li><a href="#irda-broadcast"><span class=secno>7.3.5.3.
- </span>Broadcasting over IrDA</a>
- </ul>
+ <li><a href="#server-side"><span class=secno>7.3.4.2.
+ </span>Server-side requirements</a>
+ <ul class=toc>
+ <li><a href="#minimal"><span class=secno>7.3.4.2.1. </span>Minimal
+ handshake</a>
- <li><a href="#peer-to-peer"><span class=secno>7.3.6
- </span>Peer-to-peer connections</a>
- <ul class=toc>
- <li><a href="#peer-to-peer0"><span class=secno>7.3.6.1.
- </span>Peer-to-peer connections over TCP/IP</a>
+ <li><a href="#handshake0"><span class=secno>7.3.4.2.2.
+ </span>Handshake details</a>
- <li><a href="#bluetooth-peer"><span class=secno>7.3.6.2.
- </span>Peer-to-peer connections over Bluetooth</a>
+ <li><a href="#ws-sd-framing"><span class=secno>7.3.4.2.3.
+ </span>Data framing</a>
+ </ul>
- <li><a href="#irda-peer"><span class=secno>7.3.6.3.
- </span>Peer-to-peer connections over IrDA</a>
+ <li><a href="#closing"><span class=secno>7.3.4.3. </span>Closing the
+ connection</a>
</ul>
-
- <li><a href="#the-common"><span class=secno>7.3.7 </span>The common
- protocol for TCP-based connections</a>
- <ul class=toc>
- <li><a href="#clients"><span class=secno>7.3.7.1. </span>Clients
- connecting over TCP</a>
-
- <li><a href="#servers"><span class=secno>7.3.7.2. </span>Servers
- accepting connections over TCP</a>
-
- <li><a href="#sending"><span class=secno>7.3.7.3. </span>Sending and
- receiving data over TCP</a>
- </ul>
-
- <li><a href="#network-security"><span class=secno>7.3.8
- </span>Security</a>
-
- <li><a href="#network-other-specs"><span class=secno>7.3.9
- </span>Relationship to other standards</a>
</ul>
<li><a href="#crossDocumentMessages"><span class=secno>7.4
@@ -1736,7 +1714,7 @@
<li><a href="#creating"><span class=secno>9.2.5.1. </span>Creating
and inserting elements</a>
- <li><a href="#closing"><span class=secno>9.2.5.2. </span>Closing
+ <li><a href="#closing0"><span class=secno>9.2.5.2. </span>Closing
elements that have implied end tags</a>
<li><a href="#foster"><span class=secno>9.2.5.3. </span>Foster
@@ -1955,7 +1933,7 @@
<p><em>This section is non-normative.</em>
<p>This specification is intended to replace XHTML 1.0 as the normative
- definition of the XML serialisation of the HTML vocabulary. <a
+ definition of the XML serialization of the HTML vocabulary. <a
href="#refsXHTML10">[XHTML10]</a>
<p>While this specification updates the semantics and requirements of the
@@ -2151,7 +2129,8 @@
requirements and implementation conformance requirements. User agents are
not free to handle non-conformant documents as they please; the processing
model described in this specification applies to implementations
- regardless of the conformity of the input documents.
+ regardless of the conformity of the input documents.</p>
+ <!-- put this list into its own section -->
<p>User agents fall into several (overlapping) categories with different
conformance requirements.
@@ -2586,9 +2565,9 @@
stating that it does not apply to the other format, as in "for HTML, ...
(this does not apply to XHTML)".
- <p>This specification uses the term <em>document</em> to refer to any use
- of HTML, ranging from short static documents to long essays or reports
- with rich multimedia, as well as to fully-fledged interactive
+ <p>This specification uses the term <em title="">document</em> to refer to
+ any use of HTML, ranging from short static documents to long essays or
+ reports with rich multimedia, as well as to fully-fledged interactive
applications.
<p>The term <dfn id=root-element>root element</dfn>, when not explicitly
@@ -15971,8 +15950,8 @@
document</a> has the <a href="#same-origin">same origin</a> as the
<code><a href="#iframe">iframe</a></code> element's document, or the <a
href="#browsing1">browsing context</a>'s <a href="#active">active
- document</a>'s <em><a href="#address"><span title="the document's
- address">address</span><!-- XXX xref --></a></em> has the <a
+ document</a>'s <em title=""><span title="the document's
+ address">address</span><!-- XXX xref --></em> has the <a
href="#same-origin">same origin</a> as the <code><a
href="#iframe">iframe</a></code> element's document, the following
requirements apply:
@@ -30755,34 +30734,81 @@
change it.</p>
</dl>
- <p>The <dfn id=serialization0>serialization of an origin</dfn> is the
+ <p>The <dfn id=unicode>Unicode serialization of an origin</dfn> is the
string obtained by applying the following algorithm to the given <a
href="#origin0">origin</a>:
<ol>
- <li>If the <a href="#origin0">origin</a> in question is not a
- scheme/host/port tuple, then return the empty string.
+ <li>
+ <p>If the <a href="#origin0">origin</a> in question is not a
+ scheme/host/port tuple, then return the empty string and abort these
+ steps.
- <li>Otherwise, let <var title="">result</var> be the scheme part of the <a
- href="#origin0">origin</a> tuple.
+ <li>
+ <p>Otherwise, let <var title="">result</var> be the scheme part of the <a
+ href="#origin0">origin</a> tuple.
- <li>Append the string "<code title="">://</code>" to <var
- title="">result</var>.
+ <li>
+ <p>Append the string "<code title="">://</code>" to <var
+ title="">result</var>.
- <li>Apply the IDNA ToUnicode algorithm to each component of the host part
- of the <a href="#origin0">origin</a> tuple, and append the results
- — each component, in the same order, separated by U+002E FULL STOP
- characters (".") — to <var title="">result</var>.
+ <li>
+ <p>Apply the IDNA ToUnicode algorithm to each component of the host part
+ of the <a href="#origin0">origin</a> tuple, and append the results
+ — each component, in the same order, separated by U+002E FULL STOP
+ characters (".") — to <var title="">result</var>.
- <li>If the port part of the <a href="#origin0">origin</a> tuple gives a
- port that is different from the default port for the protocol given by
- the scheme part of the <a href="#origin0">origin</a> tuple, then append a
- U+003A COLON character (":") and the given port, in base ten, to <var
- title="">result</var>.
+ <li>
+ <p>If the port part of the <a href="#origin0">origin</a> tuple gives a
+ port that is different from the default port for the protocol given by
+ the scheme part of the <a href="#origin0">origin</a> tuple, then append
+ a U+003A COLON character (":") and the given port, in base ten, to <var
+ title="">result</var>.
- <li>Return <var title="">result</var>.
+ <li>
+ <p>Return <var title="">result</var>.
</ol>
+ <p>The <dfn id=ascii>ASCII serialization of an origin</dfn> is the string
+ obtained by applying the following algorithm to the given <a
+ href="#origin0">origin</a>:
+
+ <ol>
+ <li>
+ <p>If the <a href="#origin0">origin</a> in question is not a
+ scheme/host/port tuple, then return the empty string and abort these
+ steps.
+
+ <li>
+ <p>Otherwise, let <var title="">result</var> be the scheme part of the <a
+ href="#origin0">origin</a> tuple.
+
+ <li>
+ <p>Append the string "<code title="">://</code>" to <var
+ title="">result</var>.
+
+ <li>
+ <p>Apply the IDNA ToASCII algorithm the host part of the <a
+ href="#origin0">origin</a> tuple, with both the AllowUnassigned and
+ UseSTD3ASCIIRules flags set, and append the results <var
+ title="">result</var>.</p>
+
+ <p>If ToASCII fails to convert one of the components of the string, e.g.
+ because it is too long or because it contains invalid characters, then
+ return the empty string and abort these steps. <a
+ href="#refsRFC3490">[RFC3490]</a></p>
+
+ <li>
+ <p>If the port part of the <a href="#origin0">origin</a> tuple gives a
+ port that is different from the default port for the protocol given by
+ the scheme part of the <a href="#origin0">origin</a> tuple, then append
+ a U+003A COLON character (":") and the given port, in base ten, to <var
+ title="">result</var>.
+
+ <li>
+ <p>Return <var title="">result</var>.
+ </ol>
+
<p>Two <a href="#origin0" title=origin>origins</a> are said to be the <dfn
id=same-origin>same origin</dfn> if the following algorithm returns true:
@@ -30888,24 +30914,6 @@
href="#domain">domain</a></code> attribute is used to enable pages on
different hosts of a domain to access each others' DOMs.
- <h4 id=the-string><span class=secno>5.3.2 </span>The string representing
- the script's domain in IDNA format</h4>
- <!-- XXX this is only used by the TCPConnection stuff and will be
- removed when that part is next updated -->
-
- <p><dfn id=the-string0>The string representing the script's domain in IDNA
- format</dfn> is obtained as follows: take the host part of the script's <a
- href="#origin0">origin</a> tuple and apply the IDNA ToASCII algorithm and
- then the IDNA ToUnicode algorithm to each component of the domain name
- (with both the AllowUnassigned and UseSTD3ASCIIRules flags set both
- times). <a href="#refsRFC3490">[RFC3490]</a>
-
- <p>If ToASCII fails to convert one of the components of the string, e.g.
- because it is too long or because it contains invalid characters, or if
- the <a href="#origin0">origin</a> of the script is not a scheme/host/port
- tuple, then the string representing the script's domain in IDNA format
- cannot be obtained. (ToUnicode is defined to never fail.)
-
<h3 id=scripting><span class=secno>5.4 </span>Scripting</h3>
<p>Various mechanisms can cause author-provided executable code to run in
@@ -35134,8 +35142,8 @@
<p><em>This section is non-normative.</em>
<p>This specification introduces two related mechanisms, similar to HTTP
- session cookies <a href="#refsRFC2965">[RFC2965]</a>, for storing
- structured data on the client side.
+ session cookies, for storing structured data on the client side. <a
+ href="#refsRFC2965">[RFC2965]</a> <a href="#refsRFC2109">[RFC2109]</a>
<p>The first is designed for scenarios where the user is carrying out a
single transaction, but could be carrying out multiple transactions in
@@ -36184,7 +36192,7 @@
<p>Treating persistent storage as cookies: user agents should present the
persistent storage and database features to the user in a way that does
not distinguish them from HTTP session cookies. <a
- href="#refsRFC2965">[RFC2965]</a></p>
+ href="#refsRFC2965">[RFC2965]</a> <a href="#refsRFC2109">[RFC2109]</a></p>
<p>This might encourage users to view persistent storage with healthy
suspicion.</p>
@@ -36517,7 +36525,7 @@
<p>User agents must ignore any entity bodies returned in the responses, but
must, unless otherwise specified by the user, honor the HTTP headers
(including, in particular, redirects and HTTP cookie headers). <a
- href="#refsRFC2965">[RFC2965]</a>
+ href="#refsRFC2965">[RFC2965]</a> <a href="#refsRFC2109">[RFC2109]</a>
<p>When the <code title=attr-hyperlink-ping><a href="#ping">ping</a></code>
attribute is present, user agents should clearly indicate to the user that
@@ -41240,28 +41248,12 @@
href="#event-source">event-source</a></code> functionality on a per-page
basis.
- <h3 id=network><span class=secno>7.3 </span>Network connections</h3>
+ <h3 id=network><span class=secno>7.3 </span>Web sockets</h3>
- <p>To enable Web applications to communicate with each other in local area
- networks, and to maintain bidirectional communications with their
- originating server, this specification introduces the <code><a
- href="#connection0">Connection</a></code> interface.
+ <p>To enable Web applications to maintain bidirectional communications with
+ their originating server, this specification introduces the <code><a
+ href="#websocket0">WebSocket</a></code> interface.
- <p>The <code><a href="#window">Window</a></code> interface provides three
- constructors for creating <code><a
- href="#connection0">Connection</a></code> objects: <code
- title=dom-TCPConnection><a
- href="#tcpconnection">TCPConnection()</a></code>, for creating a direct
- (possibly encrypted) link to another node on the Internet using TCP/IP;
- <code title=dom-LocalBroadcastConnection><a
- href="#localbroadcastconnection">LocalBroadcastConnection()</a></code>,
- for creating a connection to any listening peer on a local network (which
- could be a local TCP/IP subnet using UDP, a Bluetooth PAN, or another kind
- of network infrastructure); and <code title=dom-PeerToPeerConnection><a
- href="#peertopeerconnection">PeerToPeerConnection()</a></code>, for a
- direct peer-to-peer connection (which could again be over TCP/IP,
- Bluetooth, IrDA, or some other type of network).
-
<p class=note>This interface does not allow for raw access to the
underlying network. For example, this interface could not be used to
implement an IRC client without proxying messages through a custom server.
@@ -41273,813 +41265,856 @@
<p class=big-issue>An introduction to the client-side and server-side of
using the direct connection APIs.
- <p class=big-issue>An example of a party-line implementation of a broadcast
- service, and direct peer-to-peer chat for direct local connections.</p>
- <!--
- <div class="example">
- <p>The following script creates a connection to a local party
- line:</p>
- <pre>var a = new LocalBroadcastConnection();
- a.onread = function(e) { alert(e.source + ' wrote ' + e.data); }
- a.send('hello');</pre>
- </div>
--->
- <!--XXX
- Explain why we don't use HTTP instead of our own protocol: wouldn't
- work for peer-to-peer, too much work to implement server if you
- have to implement a compliant HTTP server as well, etc
- -->
+ <h4 id=the-websocket><span class=secno>7.3.2 </span>The <code><a
+ href="#websocket0">WebSocket</a></code> interface</h4>
- <h4 id=the-connection><span class=secno>7.3.2 </span>The <code><a
- href="#connection0">Connection</a></code> interface</h4>
+ <pre class=idl>interface <dfn id=websocket0>WebSocket</dfn> {
+ // constructor
+ [Constructor] <a href="#websocket0">WebSocket</a>(in DOMString url);
+ readonly attribute DOMString <a href="#url2" title=dom-WebSocket-URL>URL</a>;
- <pre class=idl>interface <dfn id=connection0>Connection</dfn> {
- readonly attribute DOMString <a href="#network1" title=dom-Connection-network>network</a>;
- readonly attribute DOMString <a href="#peer" title=dom-Connection-peer>peer</a>;
- readonly attribute int <a href="#readystate1" title=dom-Connection-readyState>readyState</a>;
- attribute EventListener <a href="#onopen" title=dom-Connection-onopen>onopen</a>;
- attribute EventListener <a href="#onread" title=dom-Connection-onread>onread</a>;
- attribute EventListener <a href="#onclose" title=dom-Connection-onclose>onclose</a>;
- void <a href="#send" title=dom-Connection-send>send</a>(in DOMString data);
- void <a href="#disconnect" title=dom-Connection-disconnect>disconnect</a>();
+ // ready state
+ const unsigned short <a href="#connecting0" title=dom-WebSocket-CONNECTING>CONNECTING</a> = 0;
+ const unsigned short <a href="#open3" title=dom-WebSocket-OPEN>OPEN</a> = 1;
+ const unsigned short <a href="#closed" title=dom-WebSocket-CLOSED>CLOSED</a> = 2;
+ readonly attribute int <a href="#readystate1" title=dom-WebSocket-readyState>readyState</a>;
+
+ // networking
+ attribute EventListener <a href="#onopen" title=handler-WebSocket-onopen>onopen</a>;
+ attribute EventListener <a href="#onread" title=handler-WebSocket-onread>onread</a>;
+ attribute EventListener <a href="#onclosed" title=handler-WebSocket-onclosed>onclosed</a>;
+ void <a href="#senddata" title=dom-WebSocket-send>send</a>(in DOMString data);
+ void <a href="#disconnect" title=dom-WebSocket-disconnect>disconnect</a>();
};</pre>
- <p><code><a href="#connection0">Connection</a></code> objects must also
+ <p><code><a href="#websocket0">WebSocket</a></code> objects must also
implement the <code>EventTarget</code> interface. <a
href="#refsDOM3EVENTS">[DOM3EVENTS]</a>
- <p>When a <code><a href="#connection0">Connection</a></code> object is
- created, the UA must try to establish a connection, as described in the
- sections below describing each connection type.
+ <p>The <dfn id=websocket1 title=dom-WebSocket><code>WebSocket</code></dfn>
+ constructor takes one argument, <var title="">url</var>, which specifies
+ the <a href="#url">URL</a> to which to connect. When a <code><a
+ href="#websocket0">WebSocket</a></code> object is created, the UA must <a
+ href="#parse0" title="parse a url">parse</a> this argument and verify that
+ the URL parses without failure and has a <a href="#ltschemegt"
+ title=url-scheme><scheme></a> component whose value is either "<code
+ title="">ws</code>" or "<code title="">wss</code>", when compared
+ case-insensitively<!-- XXX ASCII -->. If it does, it has, and it is, then
+ the user agent must asynchronously <a href="#establish">establish a Web
+ Socket connection</a> to <var title="">url</var>. Otherwise, the
+ constructor must raise a <code>SYNTAX_ERR</code> exception.
- <p>The <dfn id=network1
- title=dom-Connection-network><code>network</code></dfn> attribute
- represents the name of the network connection (the value depends on the
- kind of connection being established). The <dfn id=peer
- title=dom-Connection-peer><code>peer</code></dfn> attribute identifies the
- remote host for direct (non-broadcast) connections.
+ <p>The <dfn id=url2 title=dom-WebSocket-URL><code>URL</code></dfn>
+ attribute must return the value that was passed to the constructor.
- <p>The <code title=dom-Connection-network><a
- href="#network1">network</a></code> attribute must be set as soon as the
- <code><a href="#connection0">Connection</a></code> object is created, and
- keeps the same value for the lifetime of the object. The <code
- title=dom-Connection-peer><a href="#peer">peer</a></code> attribute must
- initially be set to the empty string and must be updated once, when the
- connection is established, after which point it must keep the same value
- for the lifetime of the object.
-
<p>The <dfn id=readystate1
- title=dom-Connection-readyState><code>readyState</code></dfn> attribute
- represents the state of the connection. When the object is created it must
- be set to 0. It can have the following values:
+ title=dom-WebSocket-readyState><code>readyState</code></dfn> attribute
+ represents the state of the connection. It can have the following values:
<dl>
- <dt>0 Connecting
+ <dt><dfn id=connecting0
+ title=dom-WebSocket-CONNECTING><code>CONNECTING</code></dfn> (numeric
+ value 0)
<dd>The connection has not yet been established.
- <dt>1 Connected
+ <dt><dfn id=open3 title=dom-WebSocket-OPEN><code>OPEN</code></dfn>
+ (numeric value 1)
- <dd>The connection is established and communication is possible.
+ <dd>The <a href="#web-socket">Web Socket connection is established</a> and
+ communication is possible.
- <dt>2 Closed
+ <dt><dfn id=closed title=dom-WebSocket-CLOSED><code>CLOSED</code></dfn>
+ (numeric value 2)
- <dd>The connection has been closed.
+ <dd>The connection has been closed or could not be opened.
</dl>
- <p id=openConnection>Once a connection is established, the <code
- title=dom-Connection-readyState><a
- href="#readystate1">readyState</a></code> attribute's value must be
- changed to 1, and the <code title=event-connection-open><a
- href="#open3">open</a></code> event must be fired on the <code><a
- href="#connection0">Connection</a></code> object.
+ <p>When the object is created its <code title=dom-WebSocket-readyState><a
+ href="#readystate1">readyState</a></code> must be set to <code
+ title=dom-WebSocket-CONNECTING><a
+ href="#connecting0">CONNECTING</a></code> (0).
- <p>When data is received, the <code title=event-connection-read><a
- href="#read">read</a></code> event will be fired on the <code><a
- href="#connection0">Connection</a></code> object.</p>
- <!-- conf crit for this
- statement is in the various protocol-specific sections below. -->
+ <p>The <dfn id=senddata title=dom-WebSocket-send><code>send(<var
+ title="">data</var>)</code></dfn> method transmits data using the
+ connection. If the connection is not established (<code
+ title=dom-WebSocket-readyState><a
+ href="#readystate1">readyState</a></code> is not <code
+ title=dom-WebSocket-OPEN><a href="#open3">OPEN</a></code>), it must raise
+ an <code>INVALID_STATE_ERR</code> exception. If the connection <em
+ title="">is</em> established, then the user agent must <a
+ href="#send-">send <var title="">data</var> using the Web Socket</a>.
- <p id=closeConnection>When the connection is closed, the <code
- title=dom-Connection-readyState><a
- href="#readystate1">readyState</a></code> attribute's value must be
- changed to 2, and the <code title=event-connection-close><a
- href="#close0">close</a></code> event must be fired on the <code><a
- href="#connection0">Connection</a></code> object.
-
- <p>The <dfn id=onopen
- title=dom-Connection-onopen><code>onopen</code></dfn>, <dfn id=onread
- title=dom-Connection-onread><code>onread</code></dfn>, and <dfn id=onclose
- title=dom-Connection-onclose><code>onclose</code></dfn> attributes must,
- when set, register their new value as an event listener for their
- respective events (namely <code title=event-connection-open><a
- href="#open3">open</a></code>, <code title=event-connection-read><a
- href="#read">read</a></code>, and <code title=event-connection-close><a
- href="#close0">close</a></code>), and unregister their previous value if
- any.
-
- <p>The <dfn id=send title=dom-Connection-send><code>send()</code></dfn>
- method transmits data using the connection. If the connection is not yet
- established, it must raise an <code>INVALID_STATE_ERR</code> exception. If
- the connection <em>is</em> established, then the behavior depends on the
- connection type, as described below.
-
<p>The <dfn id=disconnect
- title=dom-Connection-disconnect><code>disconnect()</code></dfn> method
- must close the connection, if it is open. If the connection is already
- closed, it must do nothing. Closing the connection causes a <code
- title=event-connection-close><a href="#close0">close</a></code> event to
- be fired and the <code title=dom-Connection-readyState><a
+ title=dom-WebSocket-disconnect><code>disconnect()</code></dfn> method must
+ <a href="#close1">close the Web Socket connection</a> or connection
+ attempt, if any. If the connection is already closed, it must do nothing.
+ Closing the connection causes a <code
+ title=event-connection-close>close</code> event to be fired and the <code
+ title=dom-WebSocket-readyState><a
href="#readystate1">readyState</a></code> attribute's value to change, as
- <a href="#closeConnection">described above</a>.
+ <a href="#closeWebSocket">described below</a>.
- <h4 id=connection><span class=secno>7.3.3 </span>Connection Events</h4>
+ <h4 id=websocket><span class=secno>7.3.3 </span>WebSocket Events</h4>
- <p>All the events described in this section are events in no namespace,
- which do not bubble, are not cancelable, and have no default action.
+ <p>The <dfn id=open4 title=event-WebSocket-open><code>open</code></dfn>
+ event is fired when the <a href="#web-socket">Web Socket connection is
+ established</a>.
- <p>The <dfn id=open3 title=event-connection-open><code>open</code></dfn>
- event is fired when the connection is established. UAs must use the normal
- <code>Event</code> interface when firing this event.
-
- <p>The <dfn id=close0 title=event-connection-close><code>close</code></dfn>
+ <p>The <dfn id=close0 title=event-WebSocket-close><code>close</code></dfn>
event is fired when the connection is closed (whether by the author,
- calling the <code title=dom-Connection-disconnect><a
+ calling the <code title=dom-WebSocket-disconnect><a
href="#disconnect">disconnect()</a></code> method, or by the server, or by
- a network error). UAs must use the normal <code>Event</code> interface
- when firing this event as well.
+ a network error).
<p class=note>No information regarding why the connection was closed is
passed to the application in this version of this specification.
- <p>The <dfn id=read title=event-connection-read><code>read</code></dfn>
- event is fired when when data is received for a connection. UAs must use
- the <code><a href="#connectionreadevent">ConnectionReadEvent</a></code>
- interface for this event.
+ <p>The <dfn id=read title=event-WebSocket-read><code>read</code></dfn>
+ event is fired when when data is received for a connection. It uses the
+ <code><a href="#websocketreadevent">WebSocketReadEvent</a></code>
+ interface:
<pre
- class=idl>interface <dfn id=connectionreadevent>ConnectionReadEvent</dfn> : Event {
- readonly attribute DOMString <a href="#data5" title=dom-ConnectionReadEvent-data>data</a>;
- readonly attribute DOMString <a href="#source4" title=dom-ConnectionReadEvent-source>source</a>;
- void <a href="#initconnectionreadevent" title=dom-ConnectionReadEvent-initConnectionReadEvent>initConnectionReadEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg);
- void <a href="#initconnectionreadeventns" title=dom-ConnectionReadEvent-initConnectionReadEventNS>initConnectionReadEventNS</a>(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg);
+ class=idl>interface <dfn id=websocketreadevent>WebSocketReadEvent</dfn> : Event {
+ readonly attribute DOMString <a href="#data5" title=dom-WebSocketReadEvent-data>data</a>;
+ void <a href="#initwebsocketreadevent" title=dom-WebSocketReadEvent-initWebSocketReadEvent>initWebSocketReadEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg);
+ void <a href="#initwebsocketreadeventns" title=dom-WebSocketReadEvent-initWebSocketReadEventNS>initWebSocketReadEventNS</a>(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg);
};
</pre>
- <p>The <dfn id=initconnectionreadevent
- title=dom-ConnectionReadEvent-initConnectionReadEvent><code>initConnectionReadEvent()</code></dfn>
- and <dfn id=initconnectionreadeventns
- title=dom-ConnectionReadEvent-initConnectionReadEventNS><code>initConnectionReadEventNS()</code></dfn>
+ <p>The <dfn id=initwebsocketreadevent
+ title=dom-WebSocketReadEvent-initWebSocketReadEvent><code>initWebSocketReadEvent()</code></dfn>
+ and <dfn id=initwebsocketreadeventns
+ title=dom-WebSocketReadEvent-initWebSocketReadEventNS><code>initWebSocketReadEventNS()</code></dfn>
methods must initialise the event in a manner analogous to the
similarly-named methods in the DOM3 Events interfaces. <a
href="#refsDOM3EVENTS">[DOM3EVENTS]</a>
<p>The <dfn id=data5
- title=dom-ConnectionReadEvent-data><code>data</code></dfn> attribute
- represents the data that was transmitted from the peer.
+ title=dom-WebSocketReadEvent-data><code>data</code></dfn> attribute
+ represents the data that was received.
- <p>The <dfn id=source4
- title=dom-ConnectionReadEvent-source><code>source</code></dfn> attribute
- represents the name of the peer. This is primarily useful on broadcast
- connections; on direct connections it is equal to the <code
- title=dom-Connection-peer><a href="#peer">peer</a></code> attribute on the
- <code><a href="#connection0">Connection</a></code> object.</p>
- <!-- XXX check that the following three sections define "the data
- that was transmitted" and "the name of the peer" in terms that mean
- they fit into the above definitions ("for the purposes of the
- ConnectionReadEvent"), and check they say that they MUST be set
- correctly. -->
- <!-- XXX should we have a Connection attribute on the event? -->
+ <p>When the user agent is to <dfn id=fire-a title="fire a read event">fire
+ a <code title=event-WebSocket-read>read</code> event</dfn> with data <var
+ title="">data</var>, the user agent must dispatch an event whose name is
+ <code title=event-WebSocket-read><a href="#read">read</a></code>, with no
+ namespace, which does not bubble but is cancelable, which uses the
+ <code><a href="#websocketreadevent">WebSocketReadEvent</a></code>
+ interface, and whose <code title=dom-WebSocketReadEvent-data><a
+ href="#data5">data</a></code> attribute is set to <var
+ title="">data</var>, at the given object.
<p>Events that would be fired during script execution (e.g. between the
- connection object being created — and thus the connection being
- established — and the current script completing; or, during the
- execution of a <code title=event-connection-read><a
- href="#read">read</a></code> event handler) must be buffered, and those
- events queued up and each one individually fired after the script has
- completed.</p>
- <!-- XXX make this more generic -->
+ <code><a href="#websocket0">WebSocket</a></code> object being created
+ — and thus the connection being established — and the current
+ script completing; or, during the execution of a <code
+ title=event-connection-read>read</code> event handler) must be buffered,
+ and those events queued up and each one individually fired after the
+ script has completed.</p>
+ <!-- XXX make this more generic
+ -->
- <h4 id=tcp-connections><span class=secno>7.3.4 </span>TCP connections</h4>
+ <hr>
- <p>The <dfn id=tcpconnection
- title=dom-TCPConnection><code>TCPConnection(<var title="">subdomain</var>,
- <var title="">port</var>, <var title="">secure</var>)</code></dfn>
- constructor on the <code><a href="#window">Window</a></code> interface
- returns a new object implementing the <code><a
- href="#connection0">Connection</a></code> interface, set up for a direct
- connection to a specified host on the page's domain.
+ <p>The following are the <a href="#event4">event handler DOM attributes</a>
+ that must be supported by objects implementing the <code><a
+ href="#websocket0">WebSocket</a></code> interface:
- <p>When this constructor is invoked, the following steps must be followed.
+ <dl>
+ <dt><dfn id=onopen
+ title=handler-WebSocket-onopen><code>onopen</code></dfn>
- <p>First, if the host part of the script's <a href="#origin0">origin</a> is
- not a host name (e.g. it is an IP address) then the UA must raise a <a
- href="#security9">security exception</a>. <span class=issue>We currently
- don't allow connections to be set up back to an originating IP address,
- but we could, if the subdomain is the empty string.</span>
+ <dd>
+ <p>Must be invoked whenever an <code title=event-WebSocket-open><a
+ href="#open4">open</a></code> event is targeted at or bubbles through
+ the <code><a href="#websocket0">WebSocket</a></code> object.
- <p>Then, if the <var title="">subdomain</var> argument is null or the empty
- string, the target host is the host part of the script's <a
- href="#origin0">origin</a>. Otherwise, the <var title="">subdomain</var>
- argument is prepended to the host part of the script's <a
- href="#origin0">origin</a> with a dot separating the two strings, and that
- is the target host.
+ <dt><dfn id=onread
+ title=handler-WebSocket-onread><code>onread</code></dfn>
- <p>If either:
+ <dd>
+ <p>Must be invoked whenever an <code title=event-WebSocket-read><a
+ href="#read">read</a></code> event is targeted at or bubbles through the
+ <code><a href="#websocket0">WebSocket</a></code> object.
- <ul>
- <li>the target host is not a valid host name, or
+ <dt><dfn id=onclosed
+ title=handler-WebSocket-onclosed><code>onclosed</code></dfn>
- <li>the <var title="">port</var> argument is neither equal to 80, nor
- equal to 443, nor greater than or equal to 1024 and less than or equal to
- 65535,
- </ul>
+ <dd>
+ <p>Must be invoked whenever an <code title=event-WebSocket-close><a
+ href="#close0">close</a></code> event is targeted at or bubbles through
+ the <code><a href="#websocket0">WebSocket</a></code> object.
+ </dl>
- <p>...then the UA must raise a <a href="#security9">security exception</a>.</p>
- <!-- XXX we should have our own port for this too, e.g. 980 -->
+ <h4 id=the-web><span class=secno>7.3.4 </span>The Web Socket protocol</h4>
- <p>Otherwise, the user agent must verify that the <a
- href="#the-string0">the string representing the script's domain in IDNA
- format</a> can be obtained without errors. If it cannot, then the user
- agent must raise a <a href="#security9">security exception</a>.
+ <h5 id=client-side><span class=secno>7.3.4.1. </span>Client-side
+ requirements</h5>
- <p>The user agent may also raise a <a href="#security9">security
- exception</a> at this time if, for some reason, permission to create a
- direct TCP connection to the relevant host is denied. Reasons could
- include the UA being instructed by the user to not allow direct
- connections, or the UA establishing (for instance using UPnP) that the
- network topology will cause connections on the specified port to be
- directed at the wrong host.
+ <p><em>This section only applies to user agents.</em>
- <p>If no exceptions are raised by the previous steps, then a new <code><a
- href="#connection0">Connection</a></code> object must be created, its
- <code title=dom-Connection-peer><a href="#peer">peer</a></code> attribute
- must be set to a string consisting of the name of the target host, a colon
- (U+003A COLON), and the port number as decimal digits, and its <code
- title=dom-Connection-network><a href="#network1">network</a></code>
- attribute must be set to the same value as the <code
- title=dom-Connection-peer><a href="#peer">peer</a></code> attribute.
+ <h6 id=handshake><span class=secno>7.3.4.1.1. </span>Handshake</h6>
- <p>This object must then be returned.
+ <p>When the user agent is to <dfn id=establish>establish a Web Socket
+ connection</dfn> to <var title="">url</var>, it must run the following
+ steps, in the background (without blocking scripts or anything like that):
- <p>The user agent must then begin trying to establish a connection with the
- target host and specified port. (This typically would begin in the
- background, while the script continues to execute.)
+ <ol>
+ <li id=ws-ua-1>
+ <p><a href="#resolve" title="resolve a url">Resolve</a> the <a
+ href="#url">URL</a> <var title="">url</var>.
+ </li>
+ <!-- warning for
+ editors: this is referred to as "the first step" by later steps -->
- <p>If the <var title="">secure</var> boolean argument is set to true, then
- the user agent must establish a secure connection with the target host and
- specified port using TLS or another protocol, negotiated with the server.
- <a href="#refsRFC2246">[RFC2246]</a> If this fails the user agent must act
- as if it had <a href="#closeConnection">closed the connection</a>.
+ <li>
+ <p>If the <a href="#ltschemegt" title=url-scheme><scheme></a>
+ component of the resulting <a href="#absolute">absolute URL</a> is
+ "<code title="">ws</code>", set <var title="">secure</var> to false;
+ otherwise, the <a href="#ltschemegt" title=url-scheme><scheme></a>
+ component is "<code title="">wss</code>", set <var title="">secure</var>
+ to true.
- <p>Once a secure connection is established, or if the <var
- title="">secure</var> boolean argument is not set to true, then the user
- agent must continue to connect to the server using the protocol described
- in the section entitled <a href="#clients0">clients connecting over
- TCP</a>. All data on connections made using TLS must be sent as
- "application data".
+ <li>
+ <p>Let <var title="">host</var> be the value of the <a href="#lthostgt"
+ title=url-host><host></a> component in the resulting <a
+ href="#absolute">absolute URL</a>.
- <p>Once the connection is established, the UA must act as described in the
- section entitled <a href="#sending0">sending and receiving data over
- TCP</a>.
+ <li>
+ <p>If the resulting <a href="#absolute">absolute URL</a> has a <a
+ href="#ltportgt" title=url-port><port></a> component, then let
+ <var title="">port</var> be that component's value; otherwise, if <var
+ title="">secure</var> is false, let <var title="">port</var> be 81,
+ otherwise let <var title="">port</var> be 815.
- <p>User agents should allow multiple TCP connections to be established per
- host. In particular, user agents should not apply per-host HTTP connection
- limits to connections established with the <code
- title=dom-TCPConnection><a href="#tcpconnection">TCPConnection</a></code>
- constructor.
+ <li>
+ <p>Let <var title="">resource name</var> be the value of the <a
+ href="#ltpathgt" title=url-path><path></a> component (which might
+ be empty) in the resulting <a href="#absolute">absolute URL</a>.
- <h4 id=broadcast><span class=secno>7.3.5 </span>Broadcast connections</h4>
+ <li>
+ <p>If <var title="">resource name</var> is the empty string, set it to a
+ single character U+002F SOLIDUS (/).
- <p>The <dfn id=localbroadcastconnection
- title=dom-LocalBroadcastConnection><code>LocalBroadcastConnection()</code></dfn>
- constructor on the <code><a href="#window">Window</a></code> interface
- returns a new object implementing the <code><a
- href="#connection0">Connection</a></code> interface, set up to broadcast
- on the local network.
+ <li>
+ <p>If the resulting <a href="#absolute">absolute URL</a> has a <a
+ href="#ltquerygt" title=url-query><query></a> component, then
+ append a single 003F QUESTION MARK (?) character to <var
+ title="">resource name</var>, followed by the value of the <a
+ href="#ltquerygt" title=url-query><query></a> component.
- <p>When this constructor is invoked, a new <code><a
- href="#connection0">Connection</a></code> object must be created.
+ <li>
+ <p>If the user agent is configured to use a proxy to connect to port <var
+ title="">port</var>, then connect to that proxy and ask it to open a
+ TCP/IP connection to the host given by <var title="">host</var> to the
+ port given by <var title="">port</var>.</p>
- <p>The <code title=dom-Connection-network><a
- href="#network1">network</a></code> attribute of the object must be set to
- <a href="#the-string0">the string representing the script's domain in IDNA
- format</a>. If this string cannot be obtained, then the user agent must
- raise a <a href="#security9">security exception</a> exception when the
- constructor is called.
+ <div class=example>
+ <p>For example, if the user agent uses an HTTP proxy, then if it was to
+ try to connect to port 80 on server example.com, it might send the
+ following lines to the proxy server:</p>
- <p>The <code title=dom-Connection-peer><a href="#peer">peer</a></code>
- attribute must be set to the empty string.
+ <pre>CONNECT example.com HTTP/1.1</pre>
- <p>The object must then be returned, unless, for some reason, permission to
- broadcast on the local network is to be denied. In the latter case, a <a
- href="#security9">security exception</a> must be raised instead. User
- agents may deny such permission for any reason, for example a user
- preference.
+ <p>If there was a password, the connection might look like:</p>
- <p>If the object is returned (i.e. if no exception is raised), the user
- agent must the begin broadcasting and listening on the local network, in
- the background, as described below. The user agent may define "the local
- network" in any way it considers appropriate and safe; for instance the
- user agent may ask the user which network (e.g. Bluetooth, IrDA, Ethernet,
- etc) the user would like to broadcast on before beginning broadcasting.
+ <pre>CONNECT example.com HTTP/1.1
+Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE=</pre>
+ </div>
- <p>UAs may broadcast and listen on multiple networks at once. For example,
- the UA could broadcast on both Bluetooth and Wifi at the same time.</p>
- <!-- XXX bridging? how do we handle one UA not seeing
- the same hosts as another UA? -->
+ <p>Otherwise, if the user agent is not configured to use a proxy, then
+ open a TCP/IP connection to the host given by <var title="">host</var>
+ to the port given by <var title="">port</var>.</p>
- <p>As soon as the object is returned, the connection <a
- href="#openConnection">has been established</a>, which implies that the
- <code title=event-connection-open><a href="#open3">open</a></code> event
- must be fired. Broadcast connections are never closed.
+ <li>
+ <p>If the connection could not be opened, then <a href="#fail-the">fail
+ the Web Socket connection</a> and abort these steps.
- <h5 id=broadcasting><span class=secno>7.3.5.1. </span>Broadcasting over
- TCP/IP</h5>
+ <li>
+ <p>If <var title="">secure</var> is true, perform a TLS handshake over
+ the connection. All further communication on this channel must run
+ through the encrypted tunnel. <a href="#refsRFC2246">[RFC2246]</a>
- <p class=big-issue>Should we drop this altogether? Letting people fill the
- local network with garbage seems unwise.
+ <li>
+ <p>Send the following bytes to the remote side (the server):</p>
- <p class=big-issue>We need to register a UDP port for this. For now this
- spec refers to port 18080/udp.
+ <pre>47 45 54 20</pre>
- <p class=note>Since this feature requires that the user agent listen to a
- particular port, some platforms might prevent more than one user agent per
- IP address from using this feature at any one time.
+ <p>Send the <var title="">resource name</var> value, encoded as US-ASCII.</p>
- <p>On TCP/IP networks, broadcast connections transmit data using UDP over
- port 18080.
+ <p>Send the following bytes:</p>
- <p>When the <code title=dom-Connection-send><a href="#send">send(<var
- title="">data</var>)</a></code> method is invoked on a <code><a
- href="#connection0">Connection</a></code> object that was created by the
- <code title=dom-LocalBroadcastConnection><a
- href="#localbroadcastconnection">LocalBroadcastConnection()</a></code>
- constructor, the user agent must follow these steps:
+ <pre>20 48 54 54 50 2f 31 2e 31 0d 0a 55 70 67 72 61
+64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 43
+6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 61
+64 65 0d 0a</pre>
- <ol>
- <li>Create a string consisting of the value of the <code
- title=dom-Connection-network><a href="#network1">network</a></code>
- attribute of the <code><a href="#connection0">Connection</a></code>
- object, a U+0020 SPACE character, a U+0002 START OF TEXT character, and
- the <var title="">data</var> argument.
+ <p class=note>The string "GET ", the path, " HTTP/1.1", CRLF,
+ the string "Upgrade: WebSocket", CRLF, and the string
+ "Connection: Upgrade", CRLF.</p>
- <li>Encode the string as UTF-8.
+ <li>
+ <p>Send the following bytes:</p>
- <li>If the resulting byte stream is longer than 65487 bytes, raise an
- <code>INDEX_SIZE_ERR</code> DOM exception and stop.
+ <pre>48 6f 73 74 3a 20</pre>
- <li>Create a UDP packet whose data is the byte stream, with the source and
- destination ports being 18080, and with appropriate length and checksum
- fields. Transmit this packet to IPv4 address 255.255.255.255 or IPv6
- address ff02::1, as appropriate. <span class=note>IPv6 applications will
- also have to enable reception from this address.</span>
- </ol>
+ <p>Send the <var title="">host</var> value, encoded as US-ASCII, if it
+ represents a host name (and not an IP address).</p>
- <p>When a broadcast connection is opened on a TCP/IP network, the user
- agent should listen for UDP packets on port 18080.
+ <p>Send the following bytes:</p>
- <p>When the user agent receives a packet on port 18080, the user agent must
- attempt to decode that packet's data as UTF-8. If the data is not fully
- correct UTF-8 (i.e. if there are decoding errors) then the packet must be
- ignored. Otherwise, the user agent must check to see if the decoded string
- contains a U+0020 SPACE character. If it does not, then the packet must
- again be ignored (it might be a peer discovery packet from a <code
- title=dom-PeerToPeerConnection><a
- href="#peertopeerconnection">PeerToPeerConnection()</a></code>
- constructor). If it does then the user agent must split the string at the
- first space character. All the characters before the space are then known
- as <var title="">d</var>, and all the characters after the space are known
- as <var title="">s</var>. If <var title="">s</var> is not at least one
- character long, or if the first character of <var title="">s</var> is not
- a U+0002 START OF TEXT character, then the packet must be ignored. (This
- allows for future extension of this protocol.)
+ <pre>0d 0a</pre>
- <p>Otherwise, for each <code><a href="#connection0">Connection</a></code>
- object that was created by the <code title=dom-LocalBroadcastConnection><a
- href="#localbroadcastconnection">LocalBroadcastConnection()</a></code>
- constructor and whose <code title=dom-Connection-network><a
- href="#network1">network</a></code> attribute exactly matches <var
- title="">d</var>, a <code title=event-connection-read><a
- href="#read">read</a></code> event must be fired on the <code><a
- href="#connection0">Connection</a></code> object. The string <var
- title="">s</var>, with the first character removed, must be used as the
- <code title=dom-ConnectionReadEvent-data><a href="#data5">data</a></code>,
- and the source IP address of the packet as the <code
- title=dom-ConnectionReadEvent-source><a href="#source4">source</a></code>.
+ <p class=note>The string "Host: ", the host, and CRLF.</p>
- <p class=big-issue>Making the source IP available means that if two or more
- machines in a private network can be made to go to a hostile page
- simultaneously, the hostile page can determine the IP addresses used
- locally (i.e. on the other side of any NAT router). Is there some way we
- can keep link-local IP addresses secret while still allowing for
- applications to distinguish between multiple participants?
+ <li>
+ <p>Send the following bytes:</p>
- <h5 id=bluetooth-broadcast><span class=secno>7.3.5.2. </span>Broadcasting
- over Bluetooth</h5>
+ <pre>4f 72 69 67 69 6e 3a 20</pre>
- <p class=big-issue>Does anyone know enough about Bluetooth to write this
- section?
+ <p>Send the <a href="#ascii" title="ASCII serialization of an
+ origin">ASCII serialization</a> of the <a href="#origin0">origin</a> of
+ the script that invoked the <code><a
+ href="#websocket0">WebSocket</a></code> constructor.</p>
- <h5 id=irda-broadcast><span class=secno>7.3.5.3. </span>Broadcasting over
- IrDA</h5>
+ <p>Send the following bytes:</p>
- <p class=big-issue>Does anyone know enough about IrDA to write this
- section?
+ <pre>0d 0a</pre>
- <h4 id=peer-to-peer><span class=secno>7.3.6 </span>Peer-to-peer connections</h4>
+ <p class=note>The string "Origin: ", the origin, and CRLF.</p>
- <p>The <dfn id=peertopeerconnection
- title=dom-PeerToPeerConnection><code>PeerToPeerConnection()</code></dfn>
- constructor on the <code><a href="#window">Window</a></code> interface
- returns a new object implementing the <code><a
- href="#connection0">Connection</a></code> interface, set up for a direct
- connection to a user-specified host.
+ <li>
+ <p>If the client has any authentication information or cookies that would
+ be relevant to a resource with a <a href="#url">URL</a> that has a
+ scheme of <code title="">http</code> if <var title="">secure</var> is
+ false and <code title="">https</code> if <var title="">secure</var> is
+ true and is otherwise identical to <var title="">url</var>, then HTTP
+ headers that would be appropriate for that information should be sent at
+ this point. <a href="#refsRFC2616">[RFC2616]</a> <a
+ href="#refsRFC2965">[RFC2965]</a> <a href="#refsRFC2109">[RFC2109]</a></p>
- <p>When this constructor is invoked, a new <code><a
- href="#connection0">Connection</a></code> object must be created.
+ <p>Each header must be on a line of its own (each ending with a CR LF
+ sequence). For the purposes of this step, each header must not be split
+ into multiple lines (despite HTTP otherwise allowing this with
+ continuation lines).</p>
- <p>The <code title=dom-Connection-network><a
- href="#network1">network</a></code> attribute of the object must be set to
- <a href="#the-string0">the string representing the script's domain in IDNA
- format</a>. If this string cannot be obtained, then the user agent must
- raise a <a href="#security9">security exception</a> exception when the
- constructor is called.
+ <div class=example>
+ <p>For example, if the server had a username and password that applied
+ to that URL, it could send:</p>
- <p>The <code title=dom-Connection-peer><a href="#peer">peer</a></code>
- attribute must be set to the empty string.
+ <pre>Authorization: Basic d2FsbGU6ZXZl</pre>
+ </div>
- <p>The object must then be returned, unless, for some reason, permission to
- establish peer-to-peer connections is generally disallowed, for example
- due to administrator settings. In the latter case, a <a
- href="#security9">security exception</a> must be raised instead.
+ <li>
+ <p>Send the following bytes:</p>
- <p>The user agent must then, typically while the script resumes execution,
- find a remote host to establish a connection to. To do this it must start
- broadcasting and listening for peer discovery messages and listening for
- incoming connection requests on all the supported networks. How this is
- performed depends on the type of network and is described below.
+ <pre>0d 0a</pre>
- <p>The UA should inform the user of the clients that are detected, and
- allow the user to select one to connect to. UAs may also allow users to
- explicit specify hosts that were not detected, e.g. by having the user
- enter an IP address.
+ <p class=note>Just a CRLF (a blank line).</p>
- <p>If an incoming connection is detected before the user specifies a target
- host, the user agent should ask the user to confirm that this is the host
- they wish to connect to. If it is, the connection should be accepted and
- the UA will act as the <em>server</em> in this connection. (Which UA acts
- as the server and which acts as the client is not discernible at the DOM
- API level.)
+ <li>
+ <p>Read the first 75 bytes from the server. If the connection closes
+ before 75 bytes are received, or if the first 75 bytes aren't exactly
+ equal to the following bytes, then <a href="#fail-the">fail the Web
+ Socket connection</a> and abort these steps.</p>
- <p>If no incoming connection is detected and if the user specifies a
- particular target host, a connection should be established to that host,
- with the UA acting as the <em>client</em> in the connection.
+ <pre>48 54 54 50 2f 31 2e 31 20 31 30 31 20 53 77 69
+74 63 68 69 6e 67 20 50 72 6f 74 6f 63 6f 6c 73
+0d 0a 55 70 67 72 61 64 65 3a 20 57 65 62 53 6f
+63 6b 65 74 0d 0a 43 6f 6e 6e 65 63 74 69 6f 6e
+3a 20 55 70 67 72 61 64 65 0d 0a</pre>
- <p>No more than one connection must be established per <code><a
- href="#connection0">Connection</a></code> object, so once a connection has
- been established, the user agent must stop listening for further
- connections (unless, or until such time as, another <code><a
- href="#connection0">Connection</a></code> object is being created).
+ <p class=note>The string
+ "HTTP/1.1 101 Switching Protocols", CRLF, the string
+ "Upgrade: WebSocket", CRLF, the string "Connection: Upgrade",
+ CRLF.</p>
- <p>If at any point the user cancels the connection process or the remote
- host refuses the connection, then the user agent must act as if it had <a
- href="#closeConnection">closed the connection</a>, and stop trying to
- connect.
+ <p class=big-issue>What if the response is a 401 asking for credentials?</p>
- <h5 id=peer-to-peer0><span class=secno>7.3.6.1. </span>Peer-to-peer
- connections over TCP/IP</h5>
+ <li>
+ <p>Let <var title="">headers</var> be a list of name-value pairs,
+ initially empty.
- <p class=big-issue>Should we replace this section with something that uses
- Rendez-vous/zeroconf or equivalent?
+ <li id=ws-ua-header-loop>
+ <p><em title="">Header</em>: Let <var title="">name</var> and <var
+ title="">value</var> be empty byte arrays.
- <p class=big-issue>We need to register ports for this. For now this spec
- refers to port 18080/udp and 18080/tcp.
+ <li>
+ <p>Read a byte from the server.</p>
- <p class=note>Since this feature requires that the user agent listen to a
- particular port, some platforms might prevent more than one user agent per
- IP address from using this feature at any one time.
+ <p>If the connection closes before this byte is received, then <a
+ href="#fail-the">fail the Web Socket connection</a> and abort these
+ steps.</p>
- <p>When using TCP/IP, broadcasting peer discovery messages must be done by
- creating UDP packets every few seconds containing as their data the value
- of the connection's <code title=dom-Connection-network><a
- href="#network1">network</a></code> attribute, encoded as UTF-8, with the
- source and destination ports being set to 18080 and appropriate length and
- checksum fields, and sending these packets to address (in IPv4)
- 255.255.255.255 or (in IPv6) ff02::1, as appropriate.
+ <p>Otherwise, handle the byte as described in the appropriate entry
+ below:</p>
- <p>Listening for peer discovery messages must be done by examining incoming
- UDP packets on port 18080. <span class=note>IPv6 applications will also
- have to enable reception from the ff02::1 address.</span> If their payload
- is exactly byte-for-byte equal to a UTF-8 encoded version of the value of
- the connection's <code title=dom-Connection-network><a
- href="#network1">network</a></code> attribute, then the source address of
- that packet represents the address of a host that is ready to accept a
- peer-to-peer connection, and it should therefore be offered to the user.
+ <dl class=switch>
+ <dt>If the byte is 0x0d (ASCII CR)
- <p>Incoming connection requests must be listened for on TCP port 18080. If
- an incoming connection is received, the UA must act as a <em>server</em>,
- as described in the section entitled <a href="#servers0">servers accepting
- connections over TCP</a>.
+ <dd>If the <var title="">name</var> byte array is empty, then jump to
+ the <a href="#ws-ua-headers-processing">headers processing</a> step.
+ Otherwise, <a href="#fail-the">fail the Web Socket connection</a> and
+ abort these steps.
- <p>If no incoming connection requests are accepted and the user instead
- specifies a target host to connect to, the UA acts as a <em>client</em>:
- the user agent must attempt to connect to the user-specified host on port
- 18080, as described in the section entitled <a href="#clients0">clients
- connecting over TCP</a>.
+ <dt>If the byte is 0x0a (ASCII LF)
- <p>Once the connection is established, the UA must act as described in the
- section entitled <a href="#sending0">sending and receiving data over
- TCP</a>.
+ <dd><a href="#fail-the">Fail the Web Socket connection</a> and abort
+ these steps.
- <p class=note>This specification does not include a way to establish
- <em>secure</em> (encrypted) peer-to-peer connections at this time. <span
- class=big-issue>If you can see a good way to do this, let me know.</span>
+ <dt>If the byte is 0x3a (ASCII ":")
- <h5 id=bluetooth-peer><span class=secno>7.3.6.2. </span>Peer-to-peer
- connections over Bluetooth</h5>
+ <dd>Move on to the next step.
- <p class=big-issue>Does anyone know enough about Bluetooth to write this
- section?
+ <dt>If the byte is in the range 0x41 .. 0x5a (ASCII "A" .. "Z")
- <h5 id=irda-peer><span class=secno>7.3.6.3. </span>Peer-to-peer connections
- over IrDA</h5>
+ <dd>Append a byte whose value is the byte's value plus 0x20 to the <var
+ title="">name</var> byte array and redo this step for the next byte.
- <p class=big-issue>Does anyone know enough about IrDA to write this
- section?</p>
- <!--XXX
- <p>Prompts the user to select a connection to make, which could
- look like this:</p>
+ <dt>Otherwise
-<pre>|:: New Connection :::::::::::::::::::::::::::::::::::::::::|
-| |
-| Select the peer to connect to: |
-| |
-| JohnSmith_Series60 via Bluetooth (( Connect )) |
-| Patrick's Phone via Bluetooth ( Connect ) |
-| John Smith via UDP ( Connect ) |
-| |
-| ( Cancel ) |
-|___________________________________________________________|
-</pre>
+ <dd>Append the byte to the <var title="">name</var> byte array and redo
+ this step for the next byte.
+ </dl>
- <p>While the prompt is displayed, the UA should broadcast on all
- supported networks, as described <span title="announcing peer
- connections">below</span>.</p>
+ <p class=note>This reads a header name, terminated by a colon, converting
+ upper-case ASCII letters to lowercase, and aborting if a stray CR or LF
+ is found.</p>
- <p>Returns null if the prompt was canceled. Otherwise, returns a
- <code>Connection</code> object with its <code>network</code>
- attribute set to <var title="">topic</var> and its <code>peer</code>
- attribute set to a string uniquely identifying the selected peer,
- and opens a connection to that peer. (See: <span>peer connection
- formats</span>.)</p>
+ <li>
+ <p>Read a byte from the server.</p>
+ <p>If the connection closes before this byte is received, then <a
+ href="#fail-the">fail the Web Socket connection</a> and abort these
+ steps.</p>
- |:: New Connection :::::::::::::::::::::::::::::::::::::::::|
- | |
- | Would you like to open a connection called "Chess" for |
- | this Web site?: |
- | |
- | example.org |
- | |
- | Select connection to use: [ Bluetooth | v ] |
- | |
- | (( Open connection )) ( Cancel ) |
- |___________________________________________________________|
+ <p>Otherwise, handle the byte as described in the appropriate entry
+ below:</p>
- c = new LocalBroadcastConnection("Chess");
- c.onread = function(s, f) { alert("got message " + s + " from " + f); }
- c.send("hello, anybody there?");
+ <dl class=switch>
+ <dt>If the byte is 0x20 (ASCII space)
+ <dd>Ignore the byte and move on to the next step.
- |:: New Connection :::::::::::::::::::::::::::::::::::::::::|
- | |
- | Select the peer to connect to: |
- | |
- | JohnSmith_Series60 via Bluetooth (( Connect )) |
- | Patrick's Phone via Bluetooth ( Connect ) |
- | John Smith via UDP ( Connect ) |
- | |
- | ( Cancel ) |
- |___________________________________________________________|
+ <dt>Otherwise
- c = new LocalPeerConnection("Chess");
- // c.peer contains peer's name
- c.onread = function(s) { alert("got message " + s); } // second argument is c.peer
- c.send("hello");
+ <dd>Treat the byte as described by the list in the next step, then move
+ on to that next step for real.
+ </dl>
- c = new TCPConnection("chess.example.com", 8089, false);
- // c.peer contains 'chess.example.com:8089'
- c.onread = function(s) { alert("got message " + s); } // second argument is c.peer
- c.send("hello");
+ <p class=note>This skips past a space character after the colon, if
+ necessary.</p>
-> > Again, what else should we support? Should this have an HTML Element
-> > backing it for more declarative authoring? What error handling do we need?
-> > Should it automatically use bluetooth, TCP/IP broadcast, infrared, or
-> > should it be under the control of the author or user?
--->
+ <li>
+ <p>Read a byte from the server.</p>
- <h4 id=the-common><span class=secno>7.3.7 </span>The common protocol for
- TCP-based connections</h4>
+ <p>If the connection closes before this byte is received, then <a
+ href="#fail-the">fail the Web Socket connection</a> and abort these
+ steps.</p>
- <p>The same protocol is used for <code title=dom-TCPConnection><a
- href="#tcpconnection">TCPConnection</a></code> and <code
- title=dom-PeerToPeerConnection><a
- href="#peertopeerconnection">PeerToPeerConnection</a></code> connection
- types. This section describes how such connections are established from
- the client and server sides, and then describes how data is sent and
- received over such connections (which is the same for both clients and
- servers).
+ <p>Otherwise, handle the byte as described in the appropriate entry
+ below:</p>
- <h5 id=clients><span class=secno>7.3.7.1. </span><dfn id=clients0>Clients
- connecting over TCP</dfn></h5>
+ <dl class=switch>
+ <dt>If the byte is 0x0d (ASCII CR)
- <p>This section defines the client-side requirements of the protocol used
- by the <code title=dom-TCPConnection><a
- href="#tcpconnection">TCPConnection</a></code> and <code
- title=dom-PeerToPeerConnection><a
- href="#peertopeerconnection">PeerToPeerConnection</a></code> connection
- types.
+ <dd>Move on to the next step.
- <p>If a TCP connection to the specified target host and port cannot be
- established, for example because the target host is a domain name that
- cannot be resolved to an IP address, or because packets cannot be routed
- to the host, the user agent should retry creating the connection. If the
- user agent gives up trying to connect, the user agent must act as if it
- had <a href="#closeConnection">closed the connection</a>.
+ <dt>If the byte is 0x0a (ASCII LF)
- <p class=note>No information regarding the state of the connection is
- passed to the application while the connection is being established in
- this version of this specification.
+ <dd><a href="#fail-the">Fail the Web Socket connection</a> and abort
+ these steps.
- <p>Once a TCP/IP connection to the remote host is established, the user
- agent must transmit the following sequence of bytes, represented here in
- hexadecimal form:
+ <dt>Otherwise
- <pre>0x48 0x65 0x6C 0x6C 0x6F 0x0A</pre>
+ <dd>Append the byte to the <var title="">name</var> byte array and redo
+ this step for the next byte.
+ </dl>
- <p class=note>This represents the string "Hello" followed by a newline,
- encoded in UTF-8.
+ <p class=note>This reads a header value, terminated by a CRLF.</p>
- <p>The user agent must then read all the bytes sent from the remote host,
- up to the first 0x0A byte (inclusive). That string of bytes is then
- compared byte-for-byte to the following string of bytes:
+ <li>
+ <p>Read a byte from the server.</p>
- <pre>0x57 0x65 0x6C 0x63 0x6F 0x6E 0x65 0x0A</pre>
+ <p>If the connection closes before this byte is received, or if the byte
+ is not a 0x0a byte (ASCII LF), then <a href="#fail-the">fail the Web
+ Socket connection</a> and abort these steps.</p>
- <p class=note>This says "Welcome".
+ <p class=note>This skips past the LF byte of the CRLF after the header.</p>
- <p>If the server sent back a string in any way different to this, then the
- user agent must <a href="#closeConnection">close the connection</a> and
- give up trying to connect.
+ <li>
+ <p>Append an entry to the <var title="">headers</var> list that has the
+ name given by the string obtained by interpreting the <var
+ title="">name</var> byte array as a UTF-8 byte stream and the value
+ given by the string obtained by interpreting the <var
+ title="">value</var> byte array as a UTF-8 byte stream.</p>
- <p>Otherwise, the user agent must then take <a href="#the-string0">the
- string representing the script's domain in IDNA format</a>, encode it as
- UTF-8, and send that to the remote host, followed by a 0x0A byte (a U+000A
- LINE FEED in UTF-8).
+ <li>
+ <p>Return to the <a href="#ws-ua-header-loop">header</a> step above.</p>
- <p>The user agent must then read all the bytes sent from the remote host,
- up to the first 0x0A byte (inclusive). That string of bytes must then be
- compared byte-for-byte to the string that was just sent to the server (the
- one with the IDNA domain name and ending with a newline character). If the
- server sent back a string in any way different to this, then the user
- agent must <a href="#closeConnection">close the connection</a> and give up
- trying to connect.
+ <li id=ws-ua-headers-processing>
+ <p><em title="">Headers processing</em>: If there is not exactly one
+ entry in the <var title="">headers</var> list whose name is "<code
+ title="">websocket-origin</code>", or if there is not exactly one entry
+ in the <var title="">headers</var> list whose name is "<code
+ title="">websocket-location</code>", or if there are any entries in the
+ <var title="">headers</var> list whose names are the empty string, then
+ <a href="#fail-the">fail the Web Socket connection</a> and abort these
+ steps.</p>
- <p>Otherwise, the connection <a href="#openConnection">has been
- established</a> (and events and so forth get fired, as described above).
+ <li>
+ <p>Handle each entry in the <var title="">headers</var> list as follows:</p>
- <p>If at any point during this process the connection is closed
- prematurely, then the user agent must <a href="#closeConnection">close the
- connection</a> and give up trying to connect.</p>
- <!-- XXX we should support automatic reconnect -->
+ <dl class=switch>
+ <dt>If the entry's name is "<code title="">websocket-origin</code>"
- <h5 id=servers><span class=secno>7.3.7.2. </span><dfn id=servers0>Servers
- accepting connections over TCP</dfn></h5>
+ <dd>Assume the value is a <a href="#url">URL</a>. If the value does not
+ have the <a href="#same-origin">same origin</a> as the script that
+ invoked the <code><a href="#websocket0">WebSocket</a></code>
+ constructor, then <a href="#fail-the">fail the Web Socket
+ connection</a> and abort these steps.
- <p>This section defines the server side of the protocol described in the
- previous section. For authors, it should be used as a guide for how to
- implement servers that can communicate with Web pages over TCP. For UAs
- these are the requirements for the server part of <code
- title=dom-PeerToPeerConnection><a
- href="#peertopeerconnection">PeerToPeerConnection</a></code>s.
+ <dt>If the entry's name is "<code title="">websocket-location</code>"
- <p>Once a TCP/IP connection from a remote host is established, the user
- agent must transmit the following sequence of bytes, represented here in
- hexadecimal form:
+ <dd>If the value is not exactly equal to the <a
+ href="#absolute">absolute URL</a> that resulted from the <a
+ href="#ws-ua-1">first step</a> of ths algorithm, then <a
+ href="#fail-the">fail the Web Socket connection</a> and abort these
+ steps.
- <pre>0x57 0x65 0x6C 0x63 0x6F 0x6E 0x65 0x0A</pre>
+ <dt>If the entry's name is "<code title="">set-cookie</code>" or "<code
+ title="">set-cookie2</code>" or another cookie-related header name
- <p class=note>This says "Welcome" and a newline in UTF-8.
+ <dd>Handle the cookie as defined by the appropriate spec, except pretend
+ that the resource's <a href="#url">URL</a> actually has a scheme of
+ <code title="">http</code> if <var title="">secure</var> is false and
+ <code title="">https</code> if <var title="">secure</var> is true and
+ is otherwise identical to <var title="">url</var>. <a
+ href="#refsRFC2965">[RFC2965]</a> <a href="#refsRFC2109">[RFC2109]</a>
- <p>The user agent must then read all the bytes sent from the remote host,
- up to the first 0x0A byte (inclusive). That string of bytes is then
- compared byte-for-byte to the following string of bytes:
+ <dt>Any other name
- <pre>0x48 0x65 0x6C 0x6C 0x6F 0x0A</pre>
+ <dd>Ignore it.
+ </dl>
- <p class=note>"Hello" and a newline.
+ <li>
+ <p>Change the <code title=dom-WebSocket-readyState><a
+ href="#readystate1">readyState</a></code> attribute's value to <code
+ title=dom-WebSocket-OPEN><a href="#open3">OPEN</a></code> (1).</p>
- <p>If the remote host sent back a string in any way different to this, then
- the user agent must <a href="#closeConnection">close the connection</a>
- and give up trying to connect.
+ <li>
+ <p><a href="#firing2">Fire a simple event</a> named <code
+ title=event-WebSocket-open><a href="#open4">open</a></code> at the
+ <code><a href="#websocket0">WebSocket</a></code> object.</p>
- <p>Otherwise, the user agent must then take <a href="#the-string0">the
- string representing the script's domain in IDNA format</a>, encode it as
- UTF-8, and send that to the remote host, followed by a 0x0A byte (a U+000A
- LINE FEED in UTF-8).
+ <li>
+ <p>The <dfn id=web-socket>Web Socket connection is established</dfn>. Now
+ the user agent must send and receive to and from the connection as
+ described in the next section.</p>
+ </ol>
- <p>The user agent must then read all the bytes sent from the remote host,
- up to the first 0x0A byte (inclusive). That string of bytes must then be
- compared byte-for-byte to the string that was just sent to that host (the
- one with the IDNA domain name and ending with a newline character). If the
- remote host sent back a string in any way different to this, then the user
- agent must <a href="#closeConnection">close the connection</a> and give up
- trying to connect.
+ <p>To <dfn id=fail-the>fail the Web Socket connection</dfn>, the user agent
+ must <a href="#close1">close the Web Socket connection</a>, and may report
+ the problem to the user (which would be especially useful for developers).
+ However, user agents must not convey the failure information to the script
+ in a way distinguishable from the Web Socket being closed normally.
- <p>Otherwise, the connection <a href="#openConnection">has been
- established</a> (and events and so forth get fired, as described above).
+ <h6 id=data-framing><span class=secno>7.3.4.1.2. </span>Data framing</h6>
- <p class=note>For author-written servers (as opposed to the server side of
- a peer-to-peer connection), the script's domain would be replaced by the
- hostname of the server. Alternatively, such servers might instead wait for
- the client to send its domain string, and then simply echo it back. This
- would allow connections from pages on any domain, instead of just pages
- originating from the same host. The client compares the two strings to
- ensure they are the same before allowing the connection to be used by
- author script.
+ <p>Once a <a href="#web-socket">Web Socket connection is established</a>,
+ the user agent must run through the following state machine for the bytes
+ sent by the server.
- <p>If at any point during this process the connection is closed
- prematurely, then the user agent must <a href="#closeConnection">close the
- connection</a> and give up trying to connect.</p>
- <!-- XXX we should support automatic reconnect -->
+ <ol>
+ <li>
+ <p>Try to read a byte from the server. Let <var title="">frame type</var>
+ be that byte.</p>
- <h5 id=sending><span class=secno>7.3.7.3. </span><dfn id=sending0>Sending
- and receiving data over TCP</dfn></h5>
+ <p>If no byte could be read because the <a href="#web-socket0">Web Socket
+ connection is closed</a>, then abort.</p>
- <p>When the <code title=dom-Connection-send><a href="#send">send(<var
- title="">data</var>)</a></code> method is invoked on the connection's
- corresponding <code><a href="#connection0">Connection</a></code> object,
- the user agent must take the <var title="">data</var> argument, replace
- any U+0000 NULL and U+0017 END OF TRANSMISSION BLOCK characters in it with
- U+FFFD REPLACEMENT CHARACTER characters, then transmit a U+0002 START OF
- TEXT character, this new <var title="">data</var> string and a single
- U+0017 END OF TRANSMISSION BLOCK character (in that order) to the remote
- host, all encoded as UTF-8.
+ <li>
+ <p>Handle the <var title="">frame type</var> byte as follows:</p>
- <p>When the user agent receives bytes on the connection, the user agent
- must buffer received bytes until it receives a 0x17 byte (a U+0017 END OF
- TRANSMISSION BLOCK character). If the first buffered byte is not a 0x02
- byte (a U+0002 START OF TEXT character encoded as UTF-8) then all the data
- up to the 0x17 byte, inclusive, must be dropped. (This allows for future
- extension of this protocol.) Otherwise, all the data from (but not
- including) the 0x02 byte and up to (but not including) the 0x17 byte must
- be taken, interpreted as a UTF-8 string, and a <code
- title=event-connection-read><a href="#read">read</a></code> event must be
- fired on the <code><a href="#connection0">Connection</a></code> object
- with that string as the <code title=dom-ConnectionReadEvent-data><a
- href="#data5">data</a></code>. If that string cannot be decoded as UTF-8
- without errors, the packet should be ignored.
+ <dl>
+ <dt>If the high-order bit of the <var title="">frame type</var> byte is
+ set (i.e. if <var title="">frame type</var> <i title="">and</i>ed with
+ 0x80 returns 0x80)
- <p class=note>This protocol does not yet allow binary data (e.g. an image
- or <a href="#media9">media data</a>) to be efficiently transmitted. A
- future version of this protocol might allow this by using the prefix
- character U+001F INFORMATION SEPARATOR ONE, followed by binary data which
- uses a particular byte (e.g. 0xFF) to encode byte 0x17 somehow (since
- otherwise 0x17 would be treated as transmission end by down-level UAs).</p>
- <!--
- Specifically, replace all occurrences of 0xFF with 0xFF 0xFF and
- all occurrences of 0x17 with 0xFF 0x00, or similar.
- -->
+ <dd>
+ <p>Run these steps. If at any point during these steps a read is
+ attempted but fails because the <a href="#web-socket0">Web Socket
+ connection is closed</a>, then abort.</p>
- <h4 id=network-security><span class=secno>7.3.8 </span>Security</h4>
+ <ol>
+ <li>
+ <p>Let <var title="">length</var> be zero.
- <p class=big-issue>Need to write this section.
+ <li>
+ <p>Let <var title="">multiple</var> be 1.
- <p class=big-issue>If you have an unencrypted page that is (through a
- man-in-the-middle attack) changed, it can access a secure service that is
- using IP authentication and then send that data back to the attacker. Ergo
- we should probably stop unencrypted pages from accessing encrypted
- services, on the principle that the actual level of security is zero. Then
- again, if we do that, we prevent insecure sites from using SSL as a
- tunneling mechanism.
+ <li id=ws-cd-length>
+ <p><em>Length</em>: Read a byte, let <var title="">b</var> be that
+ byte.
- <p class=big-issue>Should consider dropping the subdomain-only restriction.
- It doesn't seem to add anything, and prevents cross-domain chatter.
+ <li>
+ <p>Let <var title="">b<sub title="">v</sub></var> be integer
+ corresponding to the low 7 bits of <var title="">b</var> (the value
+ you would get by <i>and</i>ing <var title="">b</var> with 0x7f).
- <h4 id=network-other-specs><span class=secno>7.3.9 </span>Relationship to
- other standards</h4>
+ <li>
+ <p>Add <var title="">b<sub title="">v</sub></var> multiplied by <var
+ title="">multiple</var> to <var title="">length</var>.
- <p class=big-issue>Should have a section talking about the fact that we
- blithely ignoring IANA's port assignments here.
+ <li>
+ <p>Multiply <var title="">multiple</var> by 127, and store that new
+ value in <var title="">multiple</var>.
- <p class=big-issue>Should explain why we are not reusing HTTP for this.
- (HTTP is too heavy-weight for such a simple need; requiring authors to
- implement an HTTP server just to have a party line is too much of a
- barrier to entry; cannot rely on prebuilt components; having a simple
- protocol makes it much easier to do RAD; HTTP doesn't fit the needs and
- doesn't have the security model needed; etc)
+ <li>
+ <p>If the high-order bit of <var title="">b</var> is set (i.e. if
+ <var title="">b</var> <i title="">and</i>ed with 0x80 returns 0x80),
+ then return to the step above labeled <a
+ href="#ws-cd-length">length</a>.
+ <li>
+ <p>Read <var title="">length</var> bytes.
+
+ <li>
+ <p>Discard the read bytes.
+ </ol>
+
+ <dt>If the high-order bit of the <var title="">frame type</var> byte is
+ <em title="">not</em> set (i.e. if <var title="">frame type</var> <i
+ title="">and</i>ed with 0x80 returns 0x00)
+
+ <dd>
+ <p>Run these steps. If at any point during these steps a read is
+ attempted but fails because the <a href="#web-socket0">Web Socket
+ connection is closed</a>, then abort.</p>
+
+ <ol>
+ <li>
+ <p>Let <var title="">raw data</var> be an empty byte array.
+
+ <li id=ws-cd-data>
+ <p><em>Data</em>: Read a byte, let <var title="">b</var> be that
+ byte.
+
+ <li>
+ <p>If <var title="">b</var> is not 0xff, then append <var
+ title="">b</var> to <var title="">raw data</var> and return to the
+ previous step (labeled <a href="#ws-cd-data">data</a>).
+
+ <li>
+ <p>Interpret <var title="">raw data</var> as a UTF-8 string, and
+ store that string in <var title="">data</var>.</p>
+
+ <li>
+ <p>If <var title="">frame type</var> is 0x00, <a href="#fire-a">fire
+ a <code title=event-WebSocket-read>read</code> event</a> at the
+ <code><a href="#websocket0">WebSocket</a></code> object with data
+ <var title="">data</var>. Otherwise, discard the data.
+ </ol>
+ </dl>
+
+ <li>
+ <p>Return to the first step to read the next byte.
+ </ol>
+
+ <hr>
+
+ <p>Once a <a href="#web-socket">Web Socket connection is established</a>,
+ the user agent must use the following steps to <dfn id=send->send <var
+ title="">data</var> using the Web Socket</dfn>:
+
+ <ol>
+ <li>
+ <p>Send a 0x00 byte to the server.
+
+ <li>
+ <p>Encode <var title="">data</var> using UTF-8 and send the resulting
+ byte stream to the server.
+
+ <li>
+ <p>Send a 0xff byte to the server.
+ </ol>
+
+ <h5 id=server-side><span class=secno>7.3.4.2. </span>Server-side
+ requirements</h5>
+
+ <p><em>This section only applies to servers.</em></p>
+ <!-- XXX that's not a defined conformance class -->
+
+ <h6 id=minimal><span class=secno>7.3.4.2.1. </span>Minimal handshake</h6>
+
+ <p class=note>This section describes the minimal requirements for a
+ server-side implementation of Web Sockets.
+
+ <p>Listen on a port for TCP/IP. Upon receiving a connection request, open a
+ connection and send the following bytes back to the client:
+
+ <pre>48 54 54 50 2f 31 2e 31 20 31 30 31 20 53 77 69
+74 63 68 69 6e 67 20 50 72 6f 74 6f 63 6f 6c 73
+0d 0a 55 70 67 72 61 64 65 3a 20 57 65 62 53 6f
+63 6b 65 74 0d 0a 43 6f 6e 6e 65 63 74 69 6f 6e
+3a 20 55 70 67 72 61 64 65 0d 0a</pre>
+
+ <p>Send the string "<code title="">WebSocket-Origin</code>" followed by a
+ U+003A COLON (":") followed by the <a href="#ascii" title="ASCII
+ serialization of an origin">ASCII serialization</a> of the origin from
+ which the server is willing to accept connections, followed by a CRLF pair
+ (0x0d 0x0a).
+
+ <div class=example>
+ <p>For instance:</p>
+
+ <pre>WebSocket-Origin: http://example.com</pre>
+ </div>
+
+ <p>Send the string "<code title="">WebSocket-Location</code>" followed by a
+ U+003A COLON (":") followed by the <a href="#url">URL</a> of the Web
+ Socket script, followed by a CRLF pair (0x0d 0x0a).
+
+ <div class=example>
+ <p>For instance:</p>
+
+ <pre>WebSocket-Location: ws://example.com:80/demo</pre>
+ </div>
+
+ <p>Send another CRLF pair (0x0d 0x0a).
+
+ <p>Read (and discard) data from the client until four bytes 0x0d 0x0a 0x0d
+ 0x0a are read.
+
+ <p>If the connection isn't dropped at this point, go to the <a
+ href="#ws-sd-framing">data framing</a> section.
+
+ <h6 id=handshake0><span class=secno>7.3.4.2.2. </span>Handshake details</h6>
+
+ <p>The previous section ignores the data that is transmitted by the client
+ during the handshake.
+
+ <p>The data sent by the client consists of a number of fields separated by
+ CR LF pairs (bytes 0x0d 0x0a).
+
+ <p>The first field consists of three tokens separated by space characters
+ (byte 0x20). The middle token is the path being opened. If the server
+ supports multiple paths, then the server should echo the value of this
+ field in the initial handshake, on the <code
+ title="">WebSocket-Location</code> line.
+
+ <p>The remaining fields consist of name-value pairs, with the name part
+ separated from the value part by a colon and a space (bytes 0x3a 0x20). Of
+ these, several are interesting:
+
+ <dl>
+ <dt>Host (bytes 48 6f 73 74)
+
+ <dd>
+ <p>The value gives the hostname that the client intended to use when
+ opening the Web Socket. It would be of interest in particular to virtual
+ hosting environments, where one server might serve multiple hosts, and
+ might therefore want to return different data.</p>
+
+ <dt>Origin (bytes 4f 72 69 67 69 6e)
+
+ <dd>
+ <p>The value gives the scheme, hostname, and port (if it's not the
+ default port for the given scheme) of the page that asked the client to
+ open the Web Socket. It would be interesting if the server's operator
+ had deals with operators of other sites, since the server could then
+ decide how to respond (or indeed, <em>whether</em> to respond) based on
+ which site was requesting a connection.</p>
+
+ <p>If the server supports connections from more than one origin, then the
+ server should echo the value of this field in the initial handshake, on
+ the <code title="">WebSocket-Origin</code> line.</p>
+
+ <dt>Other fields
+
+ <dd>
+ <p>Other fields can be used, such as "<code title="">Cookie</code>" or
+ "<code>Authorization</code>", for authentication purposes.</p>
+ </dl>
+
+ <h6 id=ws-sd-framing><span class=secno>7.3.4.2.3. </span>Data framing</h6>
+
+ <p class=note>This section only describes how to handle content that this
+ specification allows user agents to send (text). It doesn't handle any
+ arbitrary content in the same way that the requirements on user agents
+ defined earlier handle any content including possible future extensions to
+ the protocols.
+
+ <p>The server should run through the following steps to process the bytes
+ sent by the client:
+
+ <ol>
+ <li>
+ <p>Read a byte from the client. Assuming everything is going according to
+ plan, it will be a 0x00 byte. Behaviour for the server is undefined if
+ the byte is not 0x00.
+
+ <li>
+ <p>Let <var title="">raw data</var> be an empty byte array.
+
+ <li id=ws-sd-data>
+ <p><em>Data</em>: Read a byte, let <var title="">b</var> be that byte.
+
+ <li>
+ <p>If <var title="">b</var> is not 0xff, then append <var
+ title="">b</var> to <var title="">raw data</var> and return to the
+ previous step (labeled <a href="#ws-sd-data">data</a>).
+
+ <li>
+ <p>Interpret <var title="">raw data</var> as a UTF-8 string, and apply
+ whatever server-specific processing should occur for the resulting
+ string.</p>
+
+ <li>
+ <p>Return to the first step to read the next byte.
+ </ol>
+
+ <hr>
+
+ <p>The server should run through the followin steps to send strings to the
+ client:
+
+ <ol>
+ <li>
+ <p>Send a 0x00 byte to the client to indicate the start of a string.
+
+ <li>
+ <p>Encode <var title="">data</var> using UTF-8 and send the resulting
+ byte stream to the client.
+
+ <li>
+ <p>Send a 0xff byte to the client to indicate the end of the message.
+ </ol>
+
+ <h5 id=closing><span class=secno>7.3.4.3. </span>Closing the connection</h5>
+
+ <p>To <dfn id=close1>close the Web Socket connection</dfn>, either the user
+ agent or the server closes the TCP/IP connection. There is no closing
+ handshake. Whether the user agent or the server closes the connection, it
+ is said that the <dfn id=web-socket0>Web Socket connection is
+ closed</dfn>.
+
+ <p>Servers may <a href="#close1">close the Web Socket connection</a>
+ whenever desired.
+
+ <p>User agents should not <a href="#close1">close the Web Socket
+ connection</a> arbitrarily.
+
+ <p id=closeWebSocket>When the <a href="#web-socket0">Web Socket connection
+ is closed</a>, the <code title=dom-WebSocket-readyState><a
+ href="#readystate1">readyState</a></code> attribute's value must be
+ changed to <code title=dom-WebSocket-CLOSED><a
+ href="#closed">CLOSED</a></code> (2), and the user agent must <a
+ href="#firing2">fire a simple event</a> named <code
+ title=event-WebSocket-close><a href="#close0">close</a></code> at the
+ <code><a href="#websocket0">WebSocket</a></code> object.
+
<h3 id=crossDocumentMessages><span class=secno>7.4 </span><dfn
id=cross-document>Cross-document messaging</dfn></h3>
@@ -42139,8 +42174,8 @@
title=dom-window-postMessage><a
href="#postmessage">postMessage()</a></code> method, the <code
title=dom-MessageEvent-origin><a href="#origin1">origin</a></code>
- attribute must be set to the <a href="#serialization0"
- title="serialization of an origin">serialization</a> of the <a
+ attribute must be set to the <a href="#unicode" title="Unicode
+ serialization of an origin">Unicode serialization</a> of the <a
href="#origin0">origin</a> of the script that invoked the method, the
<code title=dom-MessageEvent-lastEventId><a
href="#lasteventid">lastEventId</a></code> attribute must be set to the
@@ -44484,7 +44519,7 @@
<dd>
<p>Consume the <a href="#next-input">next input character</a>. If it is
- a U+002F SOLIDUS (/) character, switch to the <a href="#close1">close
+ a U+002F SOLIDUS (/) character, switch to the <a href="#close2">close
tag open state</a>. Otherwise, emit a U+003C LESS-THAN SIGN character
token and reconsume the current input character in the <a
href="#data-state">data state</a>.</p>
@@ -44502,7 +44537,7 @@
<dt>U+002F SOLIDUS (/)
- <dd>Switch to the <a href="#close1">close tag open state</a>.
+ <dd>Switch to the <a href="#close2">close tag open state</a>.
<dt>U+0041 LATIN CAPITAL LETTER A through to U+005A LATIN CAPITAL
LETTER Z
@@ -44539,7 +44574,7 @@
</dl>
</dl>
- <dt><dfn id=close1>Close tag open state</dfn>
+ <dt><dfn id=close2>Close tag open state</dfn>
<dd>
<p>If the <a href="#content3">content model flag</a> is set to the RCDATA
@@ -46474,8 +46509,8 @@
this is a <a href="#parse2">parse error</a>.
</ol>
- <h5 id=closing><span class=secno>9.2.5.2. </span>Closing elements that have
- implied end tags</h5>
+ <h5 id=closing0><span class=secno>9.2.5.2. </span>Closing elements that
+ have implied end tags</h5>
<p>When the steps below require the UA to <dfn id=generate>generate implied
end tags</dfn>, then, while the <a href="#current5">current node</a> is a
@@ -49089,7 +49124,7 @@
is a <a href="#parse2">parse error</a>; ignore the token. (<a
href="#fragment">fragment case</a>)</p>
- <p>Otherwise, <a href="#close2">close the cell</a> (see below) and
+ <p>Otherwise, <a href="#close3">close the cell</a> (see below) and
reprocess the current token.</p>
<dt>An end tag whose tag name is one of: "body", "caption", "col",
@@ -49109,7 +49144,7 @@
href="#fragment">fragment case</a>), then this is a <a
href="#parse2">parse error</a> and the token must be ignored.</p>
- <p>Otherwise, <a href="#close2">close the cell</a> (see below) and
+ <p>Otherwise, <a href="#close3">close the cell</a> (see below) and
reprocess the current token.</p>
<dt>Anything else
@@ -49120,7 +49155,7 @@
<span>insertion mode</span>.</p>
</dl>
- <p>Where the steps above say to <dfn id=close2>close the cell</dfn>, they
+ <p>Where the steps above say to <dfn id=close3>close the cell</dfn>, they
mean to run the following algorithm:
<ol>
@@ -53726,11 +53761,7 @@
raising an exception when the wrong number of arguments is passed -
is that a language-specific thing, or what?
-why |new XMLHttpRequest()| returns an object that .toStrings to
-[object XMLHttpRequest], same with new TCPConnection(); what if a
-constructor is called without using "new" in JS?
-
reload: fire an event when "reload" is pressed so that the page can
reload its data instead of the whole page. cancel the event cancels
the HTTP reload. Abuse prevention required, though.
@@ -54461,5 +54492,11 @@
0x12 (ASCII 'foo')
0x12 ("foo")
0x12 ('foo')
+ 0x12 (ASCII "<code title="">foo</code>")
+ 0x12 (ASCII '<code title="">foo</code>')
+ 0x12 ("<code title="">foo</code>")
+ 0x12 ('<code title="">foo</code>')
+Also check case of hex characters in the ASCII cases.
+
-->
Modified: source
===================================================================
--- source 2008-07-01 23:09:39 UTC (rev 1839)
+++ source 2008-07-03 08:36:37 UTC (rev 1840)
@@ -112,7 +112,7 @@
<p><em>This section is non-normative.</em></p>
<p>This specification is intended to replace XHTML 1.0 as the
- normative definition of the XML serialisation of the HTML
+ normative definition of the XML serialization of the HTML
vocabulary. <a href="#refsXHTML10">[XHTML10]</a></p>
<p>While this specification updates the semantics and requirements
@@ -339,6 +339,10 @@
specification applies to implementations regardless of the
conformity of the input documents.</p>
+
+
+ <!-- put this list into its own section -->
+
<p>User agents fall into several (overlapping) categories with
different conformance requirements.</p>
@@ -821,10 +825,10 @@
out by explicitly stating that it does not apply to the other
format, as in "for HTML, ... (this does not apply to XHTML)".</p>
- <p>This specification uses the term <em>document</em> to refer to
- any use of HTML, ranging from short static documents to long essays
- or reports with rich multimedia, as well as to fully-fledged
- interactive applications.</p>
+ <p>This specification uses the term <em title="">document</em> to
+ refer to any use of HTML, ranging from short static documents to
+ long essays or reports with rich multimedia, as well as to
+ fully-fledged interactive applications.</p>
<p>The term <dfn>root element</dfn>, when not explicitly qualified
as referring to the document's root element, means the furthest
@@ -13777,10 +13781,10 @@
while the <span>browsing context</span>'s <span>active
document</span> has the <span>same origin</span> as the
<code>iframe</code> element's document, or the <span>browsing
- context</span>'s <span>active document</span>'s <em><span title="the
- document's address">address</span><!-- XXX xref --></em> has the
- <span>same origin</span> as the <code>iframe</code> element's
- document, the following requirements apply:</p>
+ context</span>'s <span>active document</span>'s <em title=""><span
+ title="the document's address">address</span><!-- XXX xref --></em>
+ has the <span>same origin</span> as the <code>iframe</code>
+ element's document, the following requirements apply:</p>
<ul>
@@ -28277,36 +28281,77 @@
</dl>
- <p>The <dfn>serialization of an origin</dfn> is the string obtained
- by applying the following algorithm to the given
+ <p>The <dfn>Unicode serialization of an origin</dfn> is the string
+ obtained by applying the following algorithm to the given
<span>origin</span>:</p>
<ol>
- <li>If the <span>origin</span> in question is not a
- scheme/host/port tuple, then return the empty string.</li>
+ <li><p>If the <span>origin</span> in question is not a
+ scheme/host/port tuple, then return the empty string and abort
+ these steps.</p></li>
- <li>Otherwise, let <var title="">result</var> be the scheme part of
- the <span>origin</span> tuple.</li>
+ <li><p>Otherwise, let <var title="">result</var> be the scheme part
+ of the <span>origin</span> tuple.</p></li>
- <li>Append the string "<code title="">://</code>" to <var
- title="">result</var>.</li>
+ <li><p>Append the string "<code title="">://</code>" to <var
+ title="">result</var>.</p></li>
- <li>Apply the IDNA ToUnicode algorithm to each component of the
+ <li><p>Apply the IDNA ToUnicode algorithm to each component of the
host part of the <span>origin</span> tuple, and append the results
— each component, in the same order, separated by U+002E FULL
- STOP characters (".") — to <var title="">result</var>.</li>
+ STOP characters (".") — to <var title="">result</var>.</p></li>
- <li>If the port part of the <span>origin</span> tuple gives a port
+ <li><p>If the port part of the <span>origin</span> tuple gives a port
that is different from the default port for the protocol given by
the scheme part of the <span>origin</span> tuple, then append a
U+003A COLON character (":") and the given port, in base ten, to
- <var title="">result</var>.</li>
+ <var title="">result</var>.</p></li>
- <li>Return <var title="">result</var>.</li>
+ <li><p>Return <var title="">result</var>.</p></li>
</ol>
+ <p>The <dfn>ASCII serialization of an origin</dfn> is the string
+ obtained by applying the following algorithm to the given
+ <span>origin</span>:</p>
+
+ <ol>
+
+ <li><p>If the <span>origin</span> in question is not a
+ scheme/host/port tuple, then return the empty string and abort
+ these steps.</p></li>
+
+ <li><p>Otherwise, let <var title="">result</var> be the scheme part
+ of the <span>origin</span> tuple.</p></li>
+
+ <li><p>Append the string "<code title="">://</code>" to <var
+ title="">result</var>.</p></li>
+
+ <li>
+
+ <p>Apply the IDNA ToASCII algorithm the host part of the
+ <span>origin</span> tuple, with both the AllowUnassigned and
+ UseSTD3ASCIIRules flags set, and append the results <var
+ title="">result</var>.</p>
+
+ <p>If ToASCII fails to convert one of the components of the
+ string, e.g. because it is too long or because it contains invalid
+ characters, then return the empty string and abort these steps. <a
+ href="#refsRFC3490">[RFC3490]</a></p>
+
+ </li>
+
+ <li><p>If the port part of the <span>origin</span> tuple gives a port
+ that is different from the default port for the protocol given by
+ the scheme part of the <span>origin</span> tuple, then append a
+ U+003A COLON character (":") and the given port, in base ten, to
+ <var title="">result</var>.</p></li>
+
+ <li><p>Return <var title="">result</var>.</p></li>
+
+ </ol>
+
<p>Two <span title="origin">origins</span> are said to be the
<dfn>same origin</dfn> if the following algorithm returns true:</p>
@@ -28443,27 +28488,6 @@
- <h4>The string representing the script's domain in IDNA format</h4>
-
- <!-- XXX this is only used by the TCPConnection stuff and will be
- removed when that part is next updated -->
-
- <p><dfn>The string representing the script's domain in IDNA
- format</dfn> is obtained as follows: take the host part of the
- script's <span>origin</span> tuple and apply the IDNA ToASCII
- algorithm and then the IDNA ToUnicode algorithm to each component of
- the domain name (with both the AllowUnassigned and UseSTD3ASCIIRules
- flags set both times). <a href="#refsRFC3490">[RFC3490]</a></p>
-
- <p>If ToASCII fails to convert one of the components of the string,
- e.g. because it is too long or because it contains invalid
- characters, or if the <span>origin</span> of the script is not a
- scheme/host/port tuple, then the string representing the script's
- domain in IDNA format cannot be obtained. (ToUnicode is defined to
- never fail.)</p>
-
-
-
<h3 id="scripting">Scripting</h3>
<p>Various mechanisms can cause author-provided executable code to
@@ -32803,8 +32827,9 @@
<p><em>This section is non-normative.</em></p>
<p>This specification introduces two related mechanisms, similar to
- HTTP session cookies <a href="#refsRFC2965">[RFC2965]</a>, for
- storing structured data on the client side.</p>
+ HTTP session cookies, for storing structured data on the client
+ side. <a href="#refsRFC2965">[RFC2965]</a> <a
+ href="#refsRFC2109">[RFC2109]</a></p>
<p>The first is designed for scenarios where the user is carrying
out a single transaction, but could be carrying out multiple
@@ -33854,7 +33879,8 @@
<p>Treating persistent storage as cookies: user agents should
present the persistent storage and database features to the user
in a way that does not distinguish them from HTTP session
- cookies. <a href="#refsRFC2965">[RFC2965]</a></p>
+ cookies. <a href="#refsRFC2965">[RFC2965]</a> <a
+ href="#refsRFC2109">[RFC2109]</a></p>
<p>This might encourage users to view persistent storage with
healthy suspicion.</p>
@@ -34220,7 +34246,8 @@
<p>User agents must ignore any entity bodies returned in the
responses, but must, unless otherwise specified by the user, honor
the HTTP headers (including, in particular, redirects and HTTP
- cookie headers). <a href="#refsRFC2965">[RFC2965]</a></p>
+ cookie headers). <a href="#refsRFC2965">[RFC2965]</a> <a
+ href="#refsRFC2109">[RFC2109]</a></p>
<p>When the <code title="attr-hyperlink-ping">ping</code> attribute is
present, user agents should clearly indicate to the user that
@@ -38788,26 +38815,12 @@
- <h3 id="network">Network connections</h3>
+ <h3 id="network">Web sockets</h3>
- <p>To enable Web applications to communicate with each other in
- local area networks, and to maintain bidirectional communications
- with their originating server, this specification introduces the
- <code>Connection</code> interface.</p>
+ <p>To enable Web applications to maintain bidirectional
+ communications with their originating server, this specification
+ introduces the <code>WebSocket</code> interface.</p>
- <p>The <code>Window</code> interface provides three constructors
- for creating <code>Connection</code> objects: <code
- title="dom-TCPConnection">TCPConnection()</code>, for creating a
- direct (possibly encrypted) link to another node on the Internet
- using TCP/IP; <code
- title="dom-LocalBroadcastConnection">LocalBroadcastConnection()</code>,
- for creating a connection to any listening peer on a local network
- (which could be a local TCP/IP subnet using UDP, a Bluetooth PAN, or
- another kind of network infrastructure); and <code
- title="dom-PeerToPeerConnection">PeerToPeerConnection()</code>, for
- a direct peer-to-peer connection (which could again be over TCP/IP,
- Bluetooth, IrDA, or some other type of network).</p>
-
<p class="note">This interface does not allow for raw access to the
underlying network. For example, this interface could not be used to
implement an IRC client without proxying messages through a custom
@@ -38821,834 +38834,958 @@
<p class="big-issue">An introduction to the client-side and
server-side of using the direct connection APIs.</p>
- <p class="big-issue">An example of a party-line implementation of a
- broadcast service, and direct peer-to-peer chat for direct local
- connections.</p>
-<!--
- <div class="example">
- <p>The following script creates a connection to a local party
- line:</p>
- <pre>var a = new LocalBroadcastConnection();
- a.onread = function(e) { alert(e.source + ' wrote ' + e.data); }
- a.send('hello');</pre>
- </div>
--->
+ <h4>The <code>WebSocket</code> interface</h4>
+
+ <pre class="idl">interface <dfn>WebSocket</dfn> {
+ // constructor
+ [Constructor] <span>WebSocket</span>(in DOMString url);
+ readonly attribute DOMString <span title="dom-WebSocket-URL">URL</span>;
- <!--XXX
- Explain why we don't use HTTP instead of our own protocol: wouldn't
- work for peer-to-peer, too much work to implement server if you
- have to implement a compliant HTTP server as well, etc
- -->
+ // ready state
+ const unsigned short <span title="dom-WebSocket-CONNECTING">CONNECTING</span> = 0;
+ const unsigned short <span title="dom-WebSocket-OPEN">OPEN</span> = 1;
+ const unsigned short <span title="dom-WebSocket-CLOSED">CLOSED</span> = 2;
+ readonly attribute int <span title="dom-WebSocket-readyState">readyState</span>;
-
- <h4>The <code>Connection</code> interface</h4>
-
- <pre class="idl">interface <dfn>Connection</dfn> {
- readonly attribute DOMString <span title="dom-Connection-network">network</span>;
- readonly attribute DOMString <span title="dom-Connection-peer">peer</span>;
- readonly attribute int <span title="dom-Connection-readyState">readyState</span>;
- attribute EventListener <span title="dom-Connection-onopen">onopen</span>;
- attribute EventListener <span title="dom-Connection-onread">onread</span>;
- attribute EventListener <span title="dom-Connection-onclose">onclose</span>;
- void <span title="dom-Connection-send">send</span>(in DOMString data);
- void <span title="dom-Connection-disconnect">disconnect</span>();
+ // networking
+ attribute EventListener <span title="handler-WebSocket-onopen">onopen</span>;
+ attribute EventListener <span title="handler-WebSocket-onread">onread</span>;
+ attribute EventListener <span title="handler-WebSocket-onclosed">onclosed</span>;
+ void <span title="dom-WebSocket-send">send</span>(in DOMString data);
+ void <span title="dom-WebSocket-disconnect">disconnect</span>();
};</pre>
- <p><code>Connection</code> objects must also implement the
+ <p><code>WebSocket</code> objects must also implement the
<code>EventTarget</code> interface. <a
href="#refsDOM3EVENTS">[DOM3EVENTS]</a>
- <p>When a <code>Connection</code> object is created, the UA must try
- to establish a connection, as described in the sections below
- describing each connection type.</p>
+ <p>The <dfn title="dom-WebSocket"><code>WebSocket</code></dfn>
+ constructor takes one argument, <var title="">url</var>, which
+ specifies the <span>URL</span> to which to connect. When a
+ <code>WebSocket</code> object is created, the UA must <span
+ title="parse a url">parse</span> this argument and verify that the
+ URL parses without failure and has a <span
+ title="url-scheme"><scheme></span> component whose value is
+ either "<code title="">ws</code>" or "<code title="">wss</code>",
+ when compared case-insensitively<!-- XXX ASCII -->. If it does, it
+ has, and it is, then the user agent must asynchronously
+ <span>establish a Web Socket connection</span> to <var
+ title="">url</var>. Otherwise, the constructor must raise a
+ <code>SYNTAX_ERR</code> exception.</p>
- <p>The <dfn
- title="dom-Connection-network"><code>network</code></dfn> attribute
- represents the name of the network connection (the value depends on
- the kind of connection being established). The <dfn
- title="dom-Connection-peer"><code>peer</code></dfn> attribute
- identifies the remote host for direct (non-broadcast)
- connections.</p>
+ <p>The <dfn title="dom-WebSocket-URL"><code>URL</code></dfn>
+ attribute must return the value that was passed to the
+ constructor.</p>
- <p>The <code title="dom-Connection-network">network</code> attribute
- must be set as soon as the <code>Connection</code> object is
- created, and keeps the same value for the lifetime of the object.
- The <code title="dom-Connection-peer">peer</code> attribute must
- initially be set to the empty string and must be updated once, when
- the connection is established, after which point it must keep the
- same value for the lifetime of the object.</p>
-
<p>The <dfn
- title="dom-Connection-readyState"><code>readyState</code></dfn>
- attribute represents the state of the connection. When the object is
- created it must be set to 0. It can have the following values:</p>
+ title="dom-WebSocket-readyState"><code>readyState</code></dfn>
+ attribute represents the state of the connection. It can have the
+ following values:</p>
<dl>
- <dt>0 Connecting</dt>
+ <dt><dfn title="dom-WebSocket-CONNECTING"><code>CONNECTING</code></dfn> (numeric value 0)</dt>
+
<dd>The connection has not yet been established.</dd>
- <dt>1 Connected</dt>
- <dd>The connection is established and communication is possible.</dd>
+ <dt><dfn title="dom-WebSocket-OPEN"><code>OPEN</code></dfn> (numeric value 1)</dt>
- <dt>2 Closed</dt>
- <dd>The connection has been closed.</dd>
+ <dd>The <span>Web Socket connection is established</span> and communication is possible.</dd>
- </dl>
+ <dt><dfn title="dom-WebSocket-CLOSED"><code>CLOSED</code></dfn> (numeric value 2)</dt>
- <p id="openConnection">Once a connection is established, the <code
- title="dom-Connection-readyState">readyState</code> attribute's
- value must be changed to 1, and the <code
- title="event-connection-open">open</code> event must be fired on the
- <code>Connection</code> object.</p>
+ <dd>The connection has been closed or could not be opened.</dd>
- <p>When data is received, the <code
- title="event-connection-read">read</code> event will be fired on the
- <code>Connection</code> object.</p> <!-- conf crit for this
- statement is in the various protocol-specific sections below. -->
+ </dl>
- <p id="closeConnection">When the connection is closed, the <code
- title="dom-Connection-readyState">readyState</code> attribute's
- value must be changed to 2, and the <code
- title="event-connection-close">close</code> event must be fired on
- the <code>Connection</code> object.</p>
+ <p>When the object is created its <code
+ title="dom-WebSocket-readyState">readyState</code> must be set to
+ <code title="dom-WebSocket-CONNECTING">CONNECTING</code> (0).</p>
- <p>The <dfn title="dom-Connection-onopen"><code>onopen</code></dfn>,
- <dfn title="dom-Connection-onread"><code>onread</code></dfn>, and
- <dfn title="dom-Connection-onclose"><code>onclose</code></dfn>
- attributes must, when set, register their new value as an event
- listener for their respective events (namely <code
- title="event-connection-open">open</code>, <code
- title="event-connection-read">read</code>, and <code
- title="event-connection-close">close</code>), and unregister their
- previous value if any.</p>
+ <p>The <dfn title="dom-WebSocket-send"><code>send(<var
+ title="">data</var>)</code></dfn> method transmits data using the
+ connection. If the connection is not established (<code
+ title="dom-WebSocket-readyState">readyState</code> is not <code
+ title="dom-WebSocket-OPEN">OPEN</code>), it must raise an
+ <code>INVALID_STATE_ERR</code> exception. If the connection <em
+ title="">is</em> established, then the user agent must <span>send
+ <var title="">data</var> using the Web Socket</span>.</p>
- <p>The <dfn title="dom-Connection-send"><code>send()</code></dfn>
- method transmits data using the connection. If the connection is not
- yet established, it must raise an <code>INVALID_STATE_ERR</code>
- exception. If the connection <em>is</em> established, then the
- behavior depends on the connection type, as described below.</p>
-
<p>The <dfn
- title="dom-Connection-disconnect"><code>disconnect()</code></dfn>
- method must close the connection, if it is open. If the connection
- is already closed, it must do nothing. Closing the connection causes
- a <code title="event-connection-close">close</code> event to be
- fired and the <code
- title="dom-Connection-readyState">readyState</code> attribute's
- value to change, as <a href="#closeConnection">described
- above</a>.</p>
+ title="dom-WebSocket-disconnect"><code>disconnect()</code></dfn>
+ method must <span>close the Web Socket connection</span> or
+ connection attempt, if any. If the connection is already closed, it
+ must do nothing. Closing the connection causes a <code
+ title="event-connection-close">close</code> event to be fired and
+ the <code title="dom-WebSocket-readyState">readyState</code>
+ attribute's value to change, as <a href="#closeWebSocket">described
+ below</a>.</p>
- <h4>Connection Events</h4>
+ <h4>WebSocket Events</h4>
- <p>All the events described in this section are events in no
- namespace, which do not bubble, are not cancelable, and have no
- default action.</p>
+ <p>The <dfn title="event-WebSocket-open"><code>open</code></dfn>
+ event is fired when the <span>Web Socket connection is
+ established</span>.</p>
- <p>The <dfn title="event-connection-open"><code>open</code></dfn>
- event is fired when the connection is established. UAs must use the
- normal <code>Event</code> interface when firing this event.</p>
-
- <p>The <dfn title="event-connection-close"><code>close</code></dfn>
+ <p>The <dfn title="event-WebSocket-close"><code>close</code></dfn>
event is fired when the connection is closed (whether by the author,
calling the <code
- title="dom-Connection-disconnect">disconnect()</code> method, or by
- the server, or by a network error). UAs must use the normal
- <code>Event</code> interface when firing this event as well.</p>
+ title="dom-WebSocket-disconnect">disconnect()</code> method, or by
+ the server, or by a network error).</p>
<p class="note">No information regarding why the connection was
closed is passed to the application in this version of this
specification.</p>
- <p>The <dfn title="event-connection-read"><code>read</code></dfn>
- event is fired when when data is received for a connection. UAs must
- use the <code>ConnectionReadEvent</code> interface for this
- event.</p>
+ <p>The <dfn title="event-WebSocket-read"><code>read</code></dfn>
+ event is fired when when data is received for a connection. It uses
+ the <code>WebSocketReadEvent</code> interface:</p>
- <pre class="idl">interface <dfn>ConnectionReadEvent</dfn> : Event {
- readonly attribute DOMString <span title="dom-ConnectionReadEvent-data">data</span>;
- readonly attribute DOMString <span title="dom-ConnectionReadEvent-source">source</span>;
- void <span title="dom-ConnectionReadEvent-initConnectionReadEvent">initConnectionReadEvent</span>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg);
- void <span title="dom-ConnectionReadEvent-initConnectionReadEventNS">initConnectionReadEventNS</span>(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg);
+ <pre class="idl">interface <dfn>WebSocketReadEvent</dfn> : Event {
+ readonly attribute DOMString <span title="dom-WebSocketReadEvent-data">data</span>;
+ void <span title="dom-WebSocketReadEvent-initWebSocketReadEvent">initWebSocketReadEvent</span>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg);
+ void <span title="dom-WebSocketReadEvent-initWebSocketReadEventNS">initWebSocketReadEventNS</span>(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg);
};
</pre>
<p>The <dfn
- title="dom-ConnectionReadEvent-initConnectionReadEvent"><code>initConnectionReadEvent()</code></dfn>
+ title="dom-WebSocketReadEvent-initWebSocketReadEvent"><code>initWebSocketReadEvent()</code></dfn>
and <dfn
- title="dom-ConnectionReadEvent-initConnectionReadEventNS"><code>initConnectionReadEventNS()</code></dfn>
+ title="dom-WebSocketReadEvent-initWebSocketReadEventNS"><code>initWebSocketReadEventNS()</code></dfn>
methods must initialise the event in a manner analogous to the
similarly-named methods in the DOM3 Events interfaces. <a
href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p>
<p>The <dfn
- title="dom-ConnectionReadEvent-data"><code>data</code></dfn>
- attribute represents the data that was transmitted from the
- peer.</p>
+ title="dom-WebSocketReadEvent-data"><code>data</code></dfn>
+ attribute represents the data that was received.</p>
- <p>The <dfn
- title="dom-ConnectionReadEvent-source"><code>source</code></dfn>
- attribute represents the name of the peer. This is primarily useful
- on broadcast connections; on direct connections it is equal to the
- <code title="dom-Connection-peer">peer</code> attribute on the
- <code>Connection</code> object.</p>
+ <p>When the user agent is to <dfn title="fire a read event">fire a
+ <code title="event-WebSocket-read">read</code> event</dfn> with data
+ <var title="">data</var>, the user agent must dispatch an event
+ whose name is <code title="event-WebSocket-read">read</code>, with
+ no namespace, which does not bubble but is cancelable, which uses
+ the <code>WebSocketReadEvent</code> interface, and whose <code
+ title="dom-WebSocketReadEvent-data">data</code> attribute is set to
+ <var title="">data</var>, at the given object.</p>
- <!-- XXX check that the following three sections define "the data
- that was transmitted" and "the name of the peer" in terms that mean
- they fit into the above definitions ("for the purposes of the
- ConnectionReadEvent"), and check they say that they MUST be set
- correctly. -->
-
- <!-- XXX should we have a Connection attribute on the event? -->
-
<p>Events that would be fired during script execution (e.g. between
- the connection object being created — and thus the connection
- being established — and the current script completing; or,
- during the execution of a <code
+ the <code>WebSocket</code> object being created — and thus the
+ connection being established — and the current script
+ completing; or, during the execution of a <code
title="event-connection-read">read</code> event handler) must be
buffered, and those events queued up and each one individually fired
- after the script has completed.</p> <!-- XXX make this more generic -->
+ after the script has completed.</p> <!-- XXX make this more generic
+ -->
- <h4>TCP connections</h4>
+ <hr>
- <p>The <dfn title="dom-TCPConnection"><code>TCPConnection(<var
- title="">subdomain</var>, <var title="">port</var>, <var
- title="">secure</var>)</code></dfn> constructor on the
- <code>Window</code> interface returns a new object implementing
- the <code>Connection</code> interface, set up for a direct
- connection to a specified host on the page's domain.</p>
+ <p>The following are the <span>event handler DOM attributes</span>
+ that must be supported by objects implementing the
+ <code>WebSocket</code> interface:</p>
- <p>When this constructor is invoked, the following steps must be
- followed.</p>
+ <dl>
- <p>First, if the host part of the script's <span>origin</span> is
- not a host name (e.g. it is an IP address) then the UA must raise a
- <span>security exception</span>. <span class="issue">We currently
- don't allow connections to be set up back to an originating IP
- address, but we could, if the subdomain is the empty
- string.</span></p>
+ <dt><dfn title="handler-WebSocket-onopen"><code>onopen</code></dfn></dt>
- <p>Then, if the <var title="">subdomain</var> argument is null or
- the empty string, the target host is the host part of the script's
- <span>origin</span>. Otherwise, the <var title="">subdomain</var>
- argument is prepended to the host part of the script's
- <span>origin</span> with a dot separating the two strings, and that
- is the target host.</p>
+ <dd><p>Must be invoked whenever an <code
+ title="event-WebSocket-open">open</code> event is targeted at or
+ bubbles through the <code>WebSocket</code> object.</p></dd>
- <p>If either:</p>
- <ul>
- <li>the target host is not a valid host name, or</li>
- <li>the <var title="">port</var> argument is neither equal to 80,
- nor equal to 443, nor greater than or equal to 1024 and less than
- or equal to 65535,</li>
- </ul>
- <p>...then the UA must raise a <span>security exception</span>.</p>
- <!-- XXX we should have our own port for this too, e.g. 980 -->
+ <dt><dfn title="handler-WebSocket-onread"><code>onread</code></dfn></dt>
- <p>Otherwise, the user agent must verify that the <span>the string
- representing the script's domain in IDNA format</span> can be
- obtained without errors. If it cannot, then the user agent must
- raise a <span>security exception</span>.</p>
+ <dd><p>Must be invoked whenever an <code
+ title="event-WebSocket-read">read</code> event is targeted at or
+ bubbles through the <code>WebSocket</code> object.</p></dd>
- <p>The user agent may also raise a <span>security exception</span>
- at this time if, for some reason, permission to create a direct TCP
- connection to the relevant host is denied. Reasons could include the
- UA being instructed by the user to not allow direct connections, or
- the UA establishing (for instance using UPnP) that the network
- topology will cause connections on the specified port to be directed
- at the wrong host.</p>
+ <dt><dfn title="handler-WebSocket-onclosed"><code>onclosed</code></dfn></dt>
- <p>If no exceptions are raised by the previous steps, then a new
- <code>Connection</code> object must be created, its <code
- title="dom-Connection-peer">peer</code> attribute must be set to a
- string consisting of the name of the target host, a colon (U+003A
- COLON), and the port number as decimal digits, and its <code
- title="dom-Connection-network">network</code> attribute must be set
- to the same value as the <code
- title="dom-Connection-peer">peer</code> attribute.</p>
+ <dd><p>Must be invoked whenever an <code
+ title="event-WebSocket-close">close</code> event is targeted at or
+ bubbles through the <code>WebSocket</code> object.</p></dd>
- <p>This object must then be returned.</p>
+ </dl>
- <p>The user agent must then begin trying to establish a connection
- with the target host and specified port. (This typically would begin
- in the background, while the script continues to execute.)</p>
- <p>If the <var title="">secure</var> boolean argument is set to
- true, then the user agent must establish a secure connection with
- the target host and specified port using TLS or another protocol,
- negotiated with the server. <a href="#refsRFC2246">[RFC2246]</a> If
- this fails the user agent must act as if it had <a
- href="#closeConnection">closed the connection</a>.</p>
+ <h4>The Web Socket protocol</h4>
- <p>Once a secure connection is established, or if the <var
- title="">secure</var> boolean argument is not set to true, then the
- user agent must continue to connect to the server using the protocol
- described in the section entitled <span>clients connecting over
- TCP</span>. All data on connections made using TLS must be sent as
- "application data".</p>
+ <h5>Client-side requirements</h5>
- <p>Once the connection is established, the UA must act as described
- in the section entitled <span>sending and receiving data over
- TCP</span>.</p>
+ <p><em>This section only applies to user agents.</em></p>
- <p>User agents should allow multiple TCP connections to be
- established per host. In particular, user agents should not apply
- per-host HTTP connection limits to connections established with the
- <code title="dom-TCPConnection">TCPConnection</code>
- constructor.</p>
+ <h6>Handshake</h6>
+ <p>When the user agent is to <dfn>establish a Web Socket
+ connection</dfn> to <var title="">url</var>, it must run the
+ following steps, in the background (without blocking scripts or
+ anything like that):</p>
- <h4>Broadcast connections</h4>
+ <ol>
- <p>The <dfn
- title="dom-LocalBroadcastConnection"><code>LocalBroadcastConnection()</code></dfn>
- constructor on the <code>Window</code> interface returns a new
- object implementing the <code>Connection</code> interface, set up to
- broadcast on the local network.</p>
+ <li id="ws-ua-1"><p><span title="resolve a url">Resolve</span> the
+ <span>URL</span> <var title="">url</var>.</p></li> <!-- warning for
+ editors: this is referred to as "the first step" by later steps -->
- <p>When this constructor is invoked, a new <code>Connection</code>
- object must be created.</p>
+ <li><p>If the <span title="url-scheme"><scheme></span>
+ component of the resulting <span>absolute URL</span> is "<code
+ title="">ws</code>", set <var title="">secure</var> to false;
+ otherwise, the <span title="url-scheme"><scheme></span>
+ component is "<code title="">wss</code>", set <var
+ title="">secure</var> to true.</p></li>
- <p>The <code title="dom-Connection-network">network</code> attribute
- of the object must be set to <span>the string representing the
- script's domain in IDNA format</span>. If this string cannot be
- obtained, then the user agent must raise a <span>security
- exception</span> exception when the constructor is called.</p>
+ <li><p>Let <var title="">host</var> be the value of the <span
+ title="url-host"><host></span> component in the resulting
+ <span>absolute URL</span>.</p></li>
- <p>The <code title="dom-Connection-peer">peer</code> attribute must
- be set to the empty string.</p>
+ <li><p>If the resulting <span>absolute URL</span> has a <span
+ title="url-port"><port></span> component, then let <var
+ title="">port</var> be that component's value; otherwise, if <var
+ title="">secure</var> is false, let <var title="">port</var> be 81,
+ otherwise let <var title="">port</var> be 815.</p></li>
- <p>The object must then be returned, unless, for some reason,
- permission to broadcast on the local network is to be denied. In the
- latter case, a <span>security exception</span> must be raised
- instead. User agents may deny such permission for any reason, for
- example a user preference.</p>
+ <li><p>Let <var title="">resource name</var> be the value of the
+ <span title="url-path"><path></span> component (which might
+ be empty) in the resulting <span>absolute URL</span>.</p></li>
- <p>If the object is returned (i.e. if no exception is raised), the
- user agent must the begin broadcasting and listening on the local
- network, in the background, as described below. The user agent may
- define "the local network" in any way it considers appropriate and
- safe; for instance the user agent may ask the user which network
- (e.g. Bluetooth, IrDA, Ethernet, etc) the user would like to
- broadcast on before beginning broadcasting.</p>
+ <li><p>If <var title="">resource name</var> is the empty string,
+ set it to a single character U+002F SOLIDUS (/).</p></li>
- <p>UAs may broadcast and listen on multiple networks at once. For
- example, the UA could broadcast on both Bluetooth and Wifi at the
- same time.</p> <!-- XXX bridging? how do we handle one UA not seeing
- the same hosts as another UA? -->
+ <li><p>If the resulting <span>absolute URL</span> has a <span
+ title="url-query"><query></span> component, then append a
+ single 003F QUESTION MARK (?) character to <var title="">resource
+ name</var>, followed by the value of the <span
+ title="url-query"><query></span> component.</p></li>
- <p>As soon as the object is returned, the connection <a
- href="#openConnection">has been established</a>, which implies that
- the <code title="event-connection-open">open</code> event must be
- fired. Broadcast connections are never closed.</p>
+ <li>
+ <p>If the user agent is configured to use a proxy to connect to
+ port <var title="">port</var>, then connect to that proxy and ask
+ it to open a TCP/IP connection to the host given by <var
+ title="">host</var> to the port given by <var
+ title="">port</var>.</p>
- <h5>Broadcasting over TCP/IP</h5>
+ <div class="example">
- <p class="big-issue">Should we drop this altogether? Letting people
- fill the local network with garbage seems unwise.</p>
+ <p>For example, if the user agent uses an HTTP proxy, then if it
+ was to try to connect to port 80 on server example.com, it might
+ send the following lines to the proxy server:</p>
- <p class="big-issue">We need to register a UDP port for this. For
- now this spec refers to port 18080/udp.</p>
+ <pre>CONNECT example.com HTTP/1.1</pre>
- <p class="note">Since this feature requires that the user agent
- listen to a particular port, some platforms might prevent more than
- one user agent per IP address from using this feature at any one
- time.</p>
+ <p>If there was a password, the connection might look like:</p>
- <p>On TCP/IP networks, broadcast connections transmit data using UDP
- over port 18080.</p>
+ <pre>CONNECT example.com HTTP/1.1
+Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE=</pre>
- <p>When the <code title="dom-Connection-send">send(<var
- title="">data</var>)</code> method is invoked on a
- <code>Connection</code> object that was created by the <code
- title="dom-LocalBroadcastConnection">LocalBroadcastConnection()</code>
- constructor, the user agent must follow these steps:</p>
+ </div>
- <ol>
+ <p>Otherwise, if the user agent is not configured to use a proxy,
+ then open a TCP/IP connection to the host given by <var
+ title="">host</var> to the port given by <var
+ title="">port</var>.</p>
- <li>Create a string consisting of the value of the <code
- title="dom-Connection-network">network</code> attribute of the
- <code>Connection</code> object, a U+0020 SPACE character, a U+0002
- START OF TEXT character, and the <var title="">data</var>
- argument.</li>
+ </li>
- <li>Encode the string as UTF-8.</li>
+ <li><p>If the connection could not be opened, then <span>fail the
+ Web Socket connection</span> and abort these steps.</p></li>
- <li>If the resulting byte stream is longer than 65487 bytes, raise
- an <code>INDEX_SIZE_ERR</code> DOM exception and stop.</li>
+ <li><p>If <var title="">secure</var> is true, perform a TLS
+ handshake over the connection. All further communication on this
+ channel must run through the encrypted tunnel. <a
+ href="#refsRFC2246">[RFC2246]</a></p></li>
- <li>Create a UDP packet whose data is the byte stream, with the
- source and destination ports being 18080, and with appropriate
- length and checksum fields. Transmit this packet to IPv4 address
- 255.255.255.255 or IPv6 address ff02::1, as appropriate. <span
- class="note">IPv6 applications will also have to enable reception
- from this address.</span></li>
+ <li>
+ <p>Send the following bytes to the remote side (the server):</p>
+
+ <pre>47 45 54 20</pre>
+
+ <p>Send the <var title="">resource name</var> value, encoded as
+ US-ASCII.</p>
+
+ <p>Send the following bytes:</p>
+
+ <pre>20 48 54 54 50 2f 31 2e 31 0d 0a 55 70 67 72 61
+64 65 3a 20 57 65 62 53 6f 63 6b 65 74 0d 0a 43
+6f 6e 6e 65 63 74 69 6f 6e 3a 20 55 70 67 72 61
+64 65 0d 0a</pre>
+
+ <p class="note">The string "GET ", the path,
+ " HTTP/1.1", CRLF, the string "Upgrade: WebSocket",
+ CRLF, and the string "Connection: Upgrade", CRLF.</p>
+
+ </li>
+
+ <li>
+
+ <p>Send the following bytes:</p>
+
+ <pre>48 6f 73 74 3a 20</pre>
+
+ <p>Send the <var title="">host</var> value, encoded as US-ASCII,
+ if it represents a host name (and not an IP address).</p>
+
+ <p>Send the following bytes:</p>
+
+ <pre>0d 0a</pre>
+
+ <p class="note">The string "Host: ", the host, and CRLF.</p>
+
+ </li>
+
+ <li>
+
+ <p>Send the following bytes:</p>
+
+ <pre>4f 72 69 67 69 6e 3a 20</pre>
+
+ <p>Send the <span title="ASCII serialization of an origin">ASCII
+ serialization</span> of the <span>origin</span> of the script that
+ invoked the <code>WebSocket</code> constructor.</p>
+
+ <p>Send the following bytes:</p>
+
+ <pre>0d 0a</pre>
+
+ <p class="note">The string "Origin: ", the origin, and CRLF.</p>
+
+ </li>
+
+ <li>
+
+ <p>If the client has any authentication information or cookies
+ that would be relevant to a resource with a <span>URL</span> that
+ has a scheme of <code title="">http</code> if <var
+ title="">secure</var> is false and <code title="">https</code> if
+ <var title="">secure</var> is true and is otherwise identical to
+ <var title="">url</var>, then HTTP headers that would be
+ appropriate for that information should be sent at this point. <a
+ href="#refsRFC2616">[RFC2616]</a> <a
+ href="#refsRFC2965">[RFC2965]</a> <a
+ href="#refsRFC2109">[RFC2109]</a></p>
+
+ <p>Each header must be on a line of its own (each ending with a CR
+ LF sequence). For the purposes of this step, each header must not
+ be split into multiple lines (despite HTTP otherwise allowing this
+ with continuation lines).</p>
+
+ <div class="example">
+
+ <p>For example, if the server had a username and password that
+ applied to that URL, it could send:</p>
+
+ <pre>Authorization: Basic d2FsbGU6ZXZl</pre>
+
+ </div>
+
+ </li>
+
+ <li>
+
+ <p>Send the following bytes:</p>
+
+ <pre>0d 0a</pre>
+
+ <p class="note">Just a CRLF (a blank line).</p>
+
+ </li>
+
+ <li>
+
+ <p>Read the first 75 bytes from the server. If the connection
+ closes before 75 bytes are received, or if the first 75 bytes
+ aren't exactly equal to the following bytes, then <span>fail the
+ Web Socket connection</span> and abort these steps.</p>
+
+ <pre>48 54 54 50 2f 31 2e 31 20 31 30 31 20 53 77 69
+74 63 68 69 6e 67 20 50 72 6f 74 6f 63 6f 6c 73
+0d 0a 55 70 67 72 61 64 65 3a 20 57 65 62 53 6f
+63 6b 65 74 0d 0a 43 6f 6e 6e 65 63 74 69 6f 6e
+3a 20 55 70 67 72 61 64 65 0d 0a</pre>
+
+ <p class="note">The string
+ "HTTP/1.1 101 Switching Protocols", CRLF, the
+ string "Upgrade: WebSocket", CRLF, the string
+ "Connection: Upgrade", CRLF.</p>
+
+ <p class="big-issue">What if the response is a 401 asking for
+ credentials?</p>
+
+ </li>
+
+ <li><p>Let <var title="">headers</var> be a list of name-value
+ pairs, initially empty.</p></li>
+
+ <li id="ws-ua-header-loop"><p><em title="">Header</em>: Let <var
+ title="">name</var> and <var title="">value</var> be empty byte
+ arrays.</p></li>
+
+ <li>
+
+ <p>Read a byte from the server.</p>
+
+ <p>If the connection closes before this byte is received, then
+ <span>fail the Web Socket connection</span> and abort these
+ steps.</p>
+
+ <p>Otherwise, handle the byte as described in the appropriate
+ entry below:</p>
+
+ <dl class="switch">
+
+ <dt>If the byte is 0x0d (ASCII CR)</dt>
+
+ <dd>If the <var title="">name</var> byte array is empty, then
+ jump to the <a href="#ws-ua-headers-processing">headers
+ processing</a> step. Otherwise, <span>fail the Web Socket
+ connection</span> and abort these steps.</dd>
+
+
+ <dt>If the byte is 0x0a (ASCII LF)</dt>
+
+ <dd><span>Fail the Web Socket connection</span> and abort these
+ steps.</dd>
+
+
+ <dt>If the byte is 0x3a (ASCII ":")</dt>
+
+ <dd>Move on to the next step.</dd>
+
+
+ <dt>If the byte is in the range 0x41 .. 0x5a (ASCII "A" .. "Z")</dt>
+
+ <dd>Append a byte whose value is the byte's value plus 0x20 to
+ the <var title="">name</var> byte array and redo this step for
+ the next byte.</dd>
+
+
+ <dt>Otherwise</dt>
+
+ <dd>Append the byte to the <var title="">name</var> byte
+ array and redo this step for the next byte.</dd>
+
+ </dl>
+
+ <p class="note">This reads a header name, terminated by a colon,
+ converting upper-case ASCII letters to lowercase, and aborting if
+ a stray CR or LF is found.</p>
+
+ </li>
+
+ <li>
+
+ <p>Read a byte from the server.</p>
+
+ <p>If the connection closes before this byte is received, then
+ <span>fail the Web Socket connection</span> and abort these
+ steps.</p>
+
+ <p>Otherwise, handle the byte as described in the appropriate
+ entry below:</p>
+
+ <dl class="switch">
+
+ <dt>If the byte is 0x20 (ASCII space)</dt>
+
+ <dd>Ignore the byte and move on to the next step.</dd>
+
+
+ <dt>Otherwise</dt>
+
+ <dd>Treat the byte as described by the list in the next step,
+ then move on to that next step for real.</dd>
+
+ </dl>
+
+ <p class="note">This skips past a space character after the colon,
+ if necessary.</p>
+
+ </li>
+
+ <li>
+
+ <p>Read a byte from the server.</p>
+
+ <p>If the connection closes before this byte is received, then
+ <span>fail the Web Socket connection</span> and abort these
+ steps.</p>
+
+ <p>Otherwise, handle the byte as described in the appropriate
+ entry below:</p>
+
+ <dl class="switch">
+
+ <dt>If the byte is 0x0d (ASCII CR)</dt>
+
+ <dd>Move on to the next step.</dd>
+
+
+ <dt>If the byte is 0x0a (ASCII LF)</dt>
+
+ <dd><span>Fail the Web Socket connection</span> and abort these
+ steps.</dd>
+
+
+ <dt>Otherwise</dt>
+
+ <dd>Append the byte to the <var title="">name</var> byte array
+ and redo this step for the next byte.</dd>
+
+ </dl>
+
+ <p class="note">This reads a header value, terminated by a
+ CRLF.</p>
+
+ </li>
+
+ <li>
+
+ <p>Read a byte from the server.</p>
+
+ <p>If the connection closes before this byte is received, or if
+ the byte is not a 0x0a byte (ASCII LF), then <span>fail the Web
+ Socket connection</span> and abort these steps.</p>
+
+ <p class="note">This skips past the LF byte of the CRLF after the
+ header.</p>
+
+ </li>
+
+ <li>
+
+ <p>Append an entry to the <var title="">headers</var> list that
+ has the name given by the string obtained by interpreting the <var
+ title="">name</var> byte array as a UTF-8 byte stream and the
+ value given by the string obtained by interpreting the <var
+ title="">value</var> byte array as a UTF-8 byte stream.</p>
+
+ </li>
+
+ <li>
+
+ <p>Return to the <a href="#ws-ua-header-loop">header</a> step
+ above.</p>
+
+ </li>
+
+ <li id="ws-ua-headers-processing">
+
+ <p><em title="">Headers processing</em>: If there is not exactly
+ one entry in the <var title="">headers</var> list whose name is
+ "<code title="">websocket-origin</code>", or if there is not
+ exactly one entry in the <var title="">headers</var> list whose
+ name is "<code title="">websocket-location</code>", or if there
+ are any entries in the <var title="">headers</var> list whose
+ names are the empty string, then <span>fail the Web Socket
+ connection</span> and abort these steps.</p>
+
+ </li>
+
+ <li>
+
+ <p>Handle each entry in the <var title="">headers</var> list as
+ follows:</p>
+
+ <dl class="switch">
+
+ <dt>If the entry's name is "<code
+ title="">websocket-origin</code>"</dt>
+
+ <dd>Assume the value is a <span>URL</span>. If the value does not
+ have the <span>same origin</span> as the script that invoked the
+ <code>WebSocket</code> constructor, then <span>fail the Web
+ Socket connection</span> and abort these steps.</dd>
+
+
+ <dt>If the entry's name is "<code
+ title="">websocket-location</code>"</dt>
+
+ <dd>If the value is not exactly equal to the <span>absolute
+ URL</span> that resulted from the <a href="#ws-ua-1">first
+ step</a> of ths algorithm, then <span>fail the Web Socket
+ connection</span> and abort these steps.</dd>
+
+
+ <dt>If the entry's name is "<code title="">set-cookie</code>" or
+ "<code title="">set-cookie2</code>" or another cookie-related
+ header name</dt>
+
+ <dd>Handle the cookie as defined by the appropriate spec, except
+ pretend that the resource's <span>URL</span> actually has a
+ scheme of <code title="">http</code> if <var
+ title="">secure</var> is false and <code title="">https</code> if
+ <var title="">secure</var> is true and is otherwise identical to
+ <var title="">url</var>. <a href="#refsRFC2965">[RFC2965]</a> <a
+ href="#refsRFC2109">[RFC2109]</a></dd>
+
+
+ <dt>Any other name</dt>
+
+ <dd>Ignore it.</dd>
+
+ </dl>
+
+ </li>
+
+ <li>
+
+ <p>Change the <code
+ title="dom-WebSocket-readyState">readyState</code> attribute's value
+ to <code title="dom-WebSocket-OPEN">OPEN</code> (1).</p>
+
+ </li>
+
+ <li>
+
+ <p><span>Fire a simple event</span> named <code
+ title="event-WebSocket-open">open</code> at the
+ <code>WebSocket</code> object.</p>
+
+ </li>
+
+ <li>
+
+ <p>The <dfn>Web Socket connection is established</dfn>. Now the
+ user agent must send and receive to and from the connection as
+ described in the next section.</p>
+
+ </li>
+
</ol>
- <p>When a broadcast connection is opened on a TCP/IP network, the
- user agent should listen for UDP packets on port 18080.</p>
+ <p>To <dfn>fail the Web Socket connection</dfn>, the user agent must
+ <span>close the Web Socket connection</span>, and may report the
+ problem to the user (which would be especially useful for
+ developers). However, user agents must not convey the failure
+ information to the script in a way distinguishable from the Web
+ Socket being closed normally.</p>
- <p>When the user agent receives a packet on port 18080, the user
- agent must attempt to decode that packet's data as UTF-8. If the
- data is not fully correct UTF-8 (i.e. if there are decoding errors)
- then the packet must be ignored. Otherwise, the user agent must
- check to see if the decoded string contains a U+0020 SPACE
- character. If it does not, then the packet must again be ignored (it
- might be a peer discovery packet from a <code
- title="dom-PeerToPeerConnection">PeerToPeerConnection()</code>
- constructor). If it does then the user agent must split the
- string at the first space character. All the characters before the
- space are then known as <var title="">d</var>, and all the
- characters after the space are known as <var title="">s</var>. If
- <var title="">s</var> is not at least one character long, or if the
- first character of <var title="">s</var> is not a U+0002 START OF
- TEXT character, then the packet must be ignored. (This allows for
- future extension of this protocol.)</p>
- <p>Otherwise, for each <code>Connection</code> object that was
- created by the <code
- title="dom-LocalBroadcastConnection">LocalBroadcastConnection()</code>
- constructor and whose <code
- title="dom-Connection-network">network</code> attribute exactly
- matches <var title="">d</var>, a <code
- title="event-connection-read">read</code> event must be fired on the
- <code>Connection</code> object. The string <var title="">s</var>,
- with the first character removed, must be used as the <code
- title="dom-ConnectionReadEvent-data">data</code>, and the source IP
- address of the packet as the <code
- title="dom-ConnectionReadEvent-source">source</code>.</p>
+ <h6>Data framing</h6>
- <p class="big-issue">Making the source IP available means that if
- two or more machines in a private network can be made to go to a
- hostile page simultaneously, the hostile page can determine the IP
- addresses used locally (i.e. on the other side of any NAT
- router). Is there some way we can keep link-local IP addresses
- secret while still allowing for applications to distinguish between
- multiple participants?</p>
+ <p>Once a <span>Web Socket connection is established</span>, the
+ user agent must run through the following state machine for the
+ bytes sent by the server.</p>
+ <ol>
- <h5 id="bluetooth-broadcast">Broadcasting over Bluetooth</h5>
+ <li>
- <p class="big-issue">Does anyone know enough about Bluetooth to
- write this section?</p>
+ <p>Try to read a byte from the server. Let <var title="">frame
+ type</var> be that byte.</p>
+ <p>If no byte could be read because the <span>Web Socket
+ connection is closed</span>, then abort.</p>
- <h5 id="irda-broadcast">Broadcasting over IrDA</h5>
+ </li>
- <p class="big-issue">Does anyone know enough about IrDA to write
- this section?</p>
+ <li>
+ <p>Handle the <var title="">frame type</var> byte as follows:</p>
- <h4>Peer-to-peer connections</h4>
+ <dl>
- <p>The <dfn
- title="dom-PeerToPeerConnection"><code>PeerToPeerConnection()</code></dfn>
- constructor on the <code>Window</code> interface returns a new
- object implementing the <code>Connection</code> interface, set up
- for a direct connection to a user-specified host.</p>
+ <dt>If the high-order bit of the <var title="">frame type</var>
+ byte is set (i.e. if <var title="">frame type</var> <i
+ title="">and</i>ed with 0x80 returns 0x80)</dt>
- <p>When this constructor is invoked, a new <code>Connection</code>
- object must be created.</p>
+ <dd>
- <p>The <code title="dom-Connection-network">network</code> attribute
- of the object must be set to <span>the string representing the
- script's domain in IDNA format</span>. If this string cannot be
- obtained, then the user agent must raise a <span>security
- exception</span> exception when the constructor is called.</p>
+ <p>Run these steps. If at any point during these steps a read is
+ attempted but fails because the <span>Web Socket connection is
+ closed</span>, then abort.</p>
- <p>The <code title="dom-Connection-peer">peer</code> attribute must
- be set to the empty string.</p>
+ <ol>
- <p>The object must then be returned, unless, for some reason,
- permission to establish peer-to-peer connections is generally
- disallowed, for example due to administrator settings. In the latter
- case, a <span>security exception</span> must be raised instead.</p>
+ <li><p>Let <var title="">length</var> be zero.</p></li>
- <p>The user agent must then, typically while the script resumes
- execution, find a remote host to establish a connection to. To do
- this it must start broadcasting and listening for peer discovery
- messages and listening for incoming connection requests on all the
- supported networks. How this is performed depends on the type of
- network and is described below.</p>
+ <li><p>Let <var title="">multiple</var> be 1.</p></li>
- <p>The UA should inform the user of the clients that are detected,
- and allow the user to select one to connect to. UAs may also allow
- users to explicit specify hosts that were not detected, e.g. by
- having the user enter an IP address.</p>
+ <li id="ws-cd-length"><p><em>Length</em>: Read a byte, let <var
+ title="">b</var> be that byte.</p></li>
- <p>If an incoming connection is detected before the user specifies a
- target host, the user agent should ask the user to confirm that this
- is the host they wish to connect to. If it is, the connection should
- be accepted and the UA will act as the <em>server</em> in this
- connection. (Which UA acts as the server and which acts as the
- client is not discernible at the DOM API level.)</p>
+ <li><p>Let <var title="">b<sub title="">v</sub></var> be
+ integer corresponding to the low 7 bits of <var title="">b</var>
+ (the value you would get by <i>and</i>ing <var title="">b</var>
+ with 0x7f).</p></li>
- <p>If no incoming connection is detected and if the user specifies a
- particular target host, a connection should be established to that
- host, with the UA acting as the <em>client</em> in the
- connection.</p>
+ <li><p>Add <var title="">b<sub title="">v</sub></var>
+ multiplied by <var title="">multiple</var> to <var
+ title="">length</var>.</p></li>
- <p>No more than one connection must be established per
- <code>Connection</code> object, so once a connection has been
- established, the user agent must stop listening for further
- connections (unless, or until such time as, another
- <code>Connection</code> object is being created).</p>
+ <li><p>Multiply <var title="">multiple</var> by 127, and store
+ that new value in <var title="">multiple</var>.</p></li>
- <p>If at any point the user cancels the connection process or the
- remote host refuses the connection, then the user agent must act as
- if it had <a href="#closeConnection">closed the connection</a>, and
- stop trying to connect.</p>
+ <li><p>If the high-order bit of <var title="">b</var> is set
+ (i.e. if <var title="">b</var> <i title="">and</i>ed with 0x80
+ returns 0x80), then return to the step above labeled <a
+ href="#ws-cd-length">length</a>.</p></li>
+ <li><p>Read <var title="">length</var> bytes.</p></li>
- <h5>Peer-to-peer connections over TCP/IP</h5>
+ <li><p>Discard the read bytes.</p></li>
- <p class="big-issue">Should we replace this section with something
- that uses Rendez-vous/zeroconf or equivalent?</p>
+ </ol>
- <p class="big-issue">We need to register ports for this. For now
- this spec refers to port 18080/udp and 18080/tcp.</p>
+ </dd>
- <p class="note">Since this feature requires that the user agent
- listen to a particular port, some platforms might prevent more than
- one user agent per IP address from using this feature at any one
- time.</p>
+ <dt>If the high-order bit of the <var title="">frame type</var>
+ byte is <em title="">not</em> set (i.e. if <var title="">frame
+ type</var> <i title="">and</i>ed with 0x80 returns 0x00)</dt>
- <p>When using TCP/IP, broadcasting peer discovery messages must be
- done by creating UDP packets every few seconds containing as their
- data the value of the connection's <code
- title="dom-Connection-network">network</code> attribute, encoded as
- UTF-8, with the source and destination ports being set to 18080 and
- appropriate length and checksum fields, and sending these packets to
- address (in IPv4) 255.255.255.255 or (in IPv6) ff02::1, as
- appropriate.</p>
+ <dd>
- <p>Listening for peer discovery messages must be done by examining
- incoming UDP packets on port 18080. <span class="note">IPv6
- applications will also have to enable reception from the ff02::1
- address.</span> If their payload is exactly byte-for-byte equal to a
- UTF-8 encoded version of the value of the connection's <code
- title="dom-Connection-network">network</code> attribute, then the
- source address of that packet represents the address of a host that
- is ready to accept a peer-to-peer connection, and it should
- therefore be offered to the user.</p>
+ <p>Run these steps. If at any point during these steps a read is
+ attempted but fails because the <span>Web Socket connection is
+ closed</span>, then abort.</p>
- <p>Incoming connection requests must be listened for on TCP port
- 18080. If an incoming connection is received, the UA must act as a
- <em>server</em>, as described in the section entitled <span>servers
- accepting connections over TCP</span>.</p>
+ <ol>
- <p>If no incoming connection requests are accepted and the user
- instead specifies a target host to connect to, the UA acts as a
- <em>client</em>: the user agent must attempt to connect to the
- user-specified host on port 18080, as described in the section
- entitled <span>clients connecting over TCP</span>.</p>
+ <li><p>Let <var title="">raw data</var> be an empty byte array.</p></li>
- <p>Once the connection is established, the UA must act as described
- in the section entitled <span>sending and receiving data over
- TCP</span>.</p>
+ <li id="ws-cd-data"><p><em>Data</em>: Read a byte, let <var
+ title="">b</var> be that byte.</p></li>
- <p class="note">This specification does not include a way to
- establish <em>secure</em> (encrypted) peer-to-peer connections at
- this time. <span class="big-issue">If you can see a good way to do
- this, let me know.</span></p>
+ <li><p>If <var title="">b</var> is not 0xff, then append <var
+ title="">b</var> to <var title="">raw data</var> and return to
+ the previous step (labeled <a
+ href="#ws-cd-data">data</a>).</p></li>
- <h5 id="bluetooth-peer">Peer-to-peer connections over Bluetooth</h5>
+ <li><p>Interpret <var title="">raw data</var> as a UTF-8
+ string, and store that string in <var title="">data</var>.</p>
- <p class="big-issue">Does anyone know enough about Bluetooth to
- write this section?</p>
+ <li><p>If <var title="">frame type</var> is 0x00, <span>fire a
+ <code title="event-WebSocket-read">read</code> event</span> at
+ the <code>WebSocket</code> object with data <var
+ title="">data</var>. Otherwise, discard the data.</p></li>
+ </ol>
- <h5 id="irda-peer">Peer-to-peer connections over IrDA</h5>
+ </dd>
- <p class="big-issue">Does anyone know enough about IrDA to write
- this section?</p>
+ </dl>
+ </li>
+ <li><p>Return to the first step to read the next byte.</p></li>
-<!--XXX
- <p>Prompts the user to select a connection to make, which could
- look like this:</p>
+ </ol>
-<pre>|:: New Connection :::::::::::::::::::::::::::::::::::::::::|
-| |
-| Select the peer to connect to: |
-| |
-| JohnSmith_Series60 via Bluetooth (( Connect )) |
-| Patrick's Phone via Bluetooth ( Connect ) |
-| John Smith via UDP ( Connect ) |
-| |
-| ( Cancel ) |
-|___________________________________________________________|
-</pre>
+ <hr>
- <p>While the prompt is displayed, the UA should broadcast on all
- supported networks, as described <span title="announcing peer
- connections">below</span>.</p>
+ <p>Once a <span>Web Socket connection is established</span>, the
+ user agent must use the following steps to <dfn>send <var
+ title="">data</var> using the Web Socket</dfn>:</p>
- <p>Returns null if the prompt was canceled. Otherwise, returns a
- <code>Connection</code> object with its <code>network</code>
- attribute set to <var title="">topic</var> and its <code>peer</code>
- attribute set to a string uniquely identifying the selected peer,
- and opens a connection to that peer. (See: <span>peer connection
- formats</span>.)</p>
+ <ol>
+ <li><p>Send a 0x00 byte to the server.</p></li>
- |:: New Connection :::::::::::::::::::::::::::::::::::::::::|
- | |
- | Would you like to open a connection called "Chess" for |
- | this Web site?: |
- | |
- | example.org |
- | |
- | Select connection to use: [ Bluetooth | v ] |
- | |
- | (( Open connection )) ( Cancel ) |
- |___________________________________________________________|
+ <li><p>Encode <var title="">data</var> using UTF-8 and send the
+ resulting byte stream to the server.</p></li>
- c = new LocalBroadcastConnection("Chess");
- c.onread = function(s, f) { alert("got message " + s + " from " + f); }
- c.send("hello, anybody there?");
+ <li><p>Send a 0xff byte to the server.</p></li>
+ </ol>
- |:: New Connection :::::::::::::::::::::::::::::::::::::::::|
- | |
- | Select the peer to connect to: |
- | |
- | JohnSmith_Series60 via Bluetooth (( Connect )) |
- | Patrick's Phone via Bluetooth ( Connect ) |
- | John Smith via UDP ( Connect ) |
- | |
- | ( Cancel ) |
- |___________________________________________________________|
- c = new LocalPeerConnection("Chess");
- // c.peer contains peer's name
- c.onread = function(s) { alert("got message " + s); } // second argument is c.peer
- c.send("hello");
+ <h5>Server-side requirements</h5>
- c = new TCPConnection("chess.example.com", 8089, false);
- // c.peer contains 'chess.example.com:8089'
- c.onread = function(s) { alert("got message " + s); } // second argument is c.peer
- c.send("hello");
+ <p><em>This section only applies to servers.</em></p> <!-- XXX that's not a defined conformance class -->
-> > Again, what else should we support? Should this have an HTML Element
-> > backing it for more declarative authoring? What error handling do we need?
-> > Should it automatically use bluetooth, TCP/IP broadcast, infrared, or
-> > should it be under the control of the author or user?
--->
+ <h6>Minimal handshake</h6>
+ <p class="note">This section describes the minimal requirements for
+ a server-side implementation of Web Sockets.</p>
- <h4>The common protocol for TCP-based connections</h4>
+ <p>Listen on a port for TCP/IP. Upon receiving a connection request,
+ open a connection and send the following bytes back to the
+ client:</p>
- <p>The same protocol is used for <code
- title="dom-TCPConnection">TCPConnection</code> and <code
- title="dom-PeerToPeerConnection">PeerToPeerConnection</code>
- connection types. This section describes how such connections are
- established from the client and server sides, and then describes how
- data is sent and received over such connections (which is the same
- for both clients and servers).</p>
+ <pre>48 54 54 50 2f 31 2e 31 20 31 30 31 20 53 77 69
+74 63 68 69 6e 67 20 50 72 6f 74 6f 63 6f 6c 73
+0d 0a 55 70 67 72 61 64 65 3a 20 57 65 62 53 6f
+63 6b 65 74 0d 0a 43 6f 6e 6e 65 63 74 69 6f 6e
+3a 20 55 70 67 72 61 64 65 0d 0a</pre>
+ <p>Send the string "<code title="">WebSocket-Origin</code>" followed
+ by a U+003A COLON (":") followed by the <span title="ASCII
+ serialization of an origin">ASCII serialization</span> of the origin
+ from which the server is willing to accept connections, followed by
+ a CRLF pair (0x0d 0x0a).</p>
- <h5><dfn>Clients connecting over TCP</dfn></h5>
+ <div class="example">
- <p>This section defines the client-side requirements of the protocol
- used by the <code title="dom-TCPConnection">TCPConnection</code> and
- <code title="dom-PeerToPeerConnection">PeerToPeerConnection</code>
- connection types.</p>
+ <p>For instance:</p>
- <p>If a TCP connection to the specified target host and port cannot
- be established, for example because the target host is a domain name
- that cannot be resolved to an IP address, or because packets cannot
- be routed to the host, the user agent should retry creating the
- connection. If the user agent gives up trying to connect, the user
- agent must act as if it had <a href="#closeConnection">closed the
- connection</a>.</p>
+ <pre>WebSocket-Origin: http://example.com</pre>
- <p class="note">No information regarding the state of the connection
- is passed to the application while the connection is being
- established in this version of this specification.</p>
+ </div>
- <p>Once a TCP/IP connection to the remote host is established, the
- user agent must transmit the following sequence of bytes,
- represented here in hexadecimal form:</p>
+ <p>Send the string "<code title="">WebSocket-Location</code>"
+ followed by a U+003A COLON (":") followed by the <span>URL</span> of
+ the Web Socket script, followed by a CRLF pair (0x0d 0x0a).</p>
- <pre>0x48 0x65 0x6C 0x6C 0x6F 0x0A</pre>
+ <div class="example">
- <p class="note">This represents the string "Hello" followed by a
- newline, encoded in UTF-8.</p>
+ <p>For instance:</p>
- <p>The user agent must then read all the bytes sent from the remote
- host, up to the first 0x0A byte (inclusive). That string of bytes is
- then compared byte-for-byte to the following string of bytes:</p>
+ <pre>WebSocket-Location: ws://example.com:80/demo</pre>
- <pre>0x57 0x65 0x6C 0x63 0x6F 0x6E 0x65 0x0A</pre>
+ </div>
- <p class="note">This says "Welcome".</p>
+ <p>Send another CRLF pair (0x0d 0x0a).</p>
- <p>If the server sent back a string in any way different to this,
- then the user agent must <a href="#closeConnection">close the
- connection</a> and give up trying to connect.</p>
+ <p>Read (and discard) data from the client until four bytes 0x0d
+ 0x0a 0x0d 0x0a are read.</p>
- <p>Otherwise, the user agent must then take <span>the string
- representing the script's domain in IDNA format</span>, encode it as
- UTF-8, and send that to the remote host, followed by a 0x0A byte (a
- U+000A LINE FEED in UTF-8).</p>
+ <p>If the connection isn't dropped at this point, go to the <a
+ href="#ws-sd-framing">data framing</a> section.</p>
- <p>The user agent must then read all the bytes sent from the remote
- host, up to the first 0x0A byte (inclusive). That string of bytes
- must then be compared byte-for-byte to the string that was just sent
- to the server (the one with the IDNA domain name and ending with a
- newline character). If the server sent back a string in any way
- different to this, then the user agent must <a
- href="#closeConnection">close the connection</a> and give up trying
- to connect.</p>
- <p>Otherwise, the connection <a href="#openConnection">has been
- established</a> (and events and so forth get fired, as described
- above).</p>
+ <h6>Handshake details</h6>
- <p>If at any point during this process the connection is closed
- prematurely, then the user agent must <a
- href="#closeConnection">close the connection</a> and give up trying
- to connect.</p> <!-- XXX we should support automatic reconnect -->
+ <p>The previous section ignores the data that is transmitted by the
+ client during the handshake.</p>
+ <p>The data sent by the client consists of a number of fields
+ separated by CR LF pairs (bytes 0x0d 0x0a).</p>
- <h5><dfn>Servers accepting connections over TCP</dfn></h5>
+ <p>The first field consists of three tokens separated by space
+ characters (byte 0x20). The middle token is the path being
+ opened. If the server supports multiple paths, then the server
+ should echo the value of this field in the initial handshake, on the
+ <code title="">WebSocket-Location</code> line.</p>
- <p>This section defines the server side of the protocol described in
- the previous section. For authors, it should be used as a guide for
- how to implement servers that can communicate with Web pages over
- TCP. For UAs these are the requirements for the server part of <code
- title="dom-PeerToPeerConnection">PeerToPeerConnection</code>s.</p>
+ <p>The remaining fields consist of name-value pairs, with the name
+ part separated from the value part by a colon and a space (bytes
+ 0x3a 0x20). Of these, several are interesting:</p>
- <p>Once a TCP/IP connection from a remote host is established, the
- user agent must transmit the following sequence of bytes,
- represented here in hexadecimal form:</p>
+ <dl>
- <pre>0x57 0x65 0x6C 0x63 0x6F 0x6E 0x65 0x0A</pre>
+ <dt>Host (bytes 48 6f 73 74)</dt>
- <p class="note">This says "Welcome" and a newline in UTF-8.</p>
+ <dd>
- <p>The user agent must then read all the bytes sent from the remote
- host, up to the first 0x0A byte (inclusive). That string of bytes is
- then compared byte-for-byte to the following string of bytes:</p>
+ <p>The value gives the hostname that the client intended to use
+ when opening the Web Socket. It would be of interest in particular
+ to virtual hosting environments, where one server might serve
+ multiple hosts, and might therefore want to return different
+ data.</p>
- <pre>0x48 0x65 0x6C 0x6C 0x6F 0x0A</pre>
+ </dd>
- <p class="note">"Hello" and a newline.</p>
+ <dt>Origin (bytes 4f 72 69 67 69 6e)</dt>
- <p>If the remote host sent back a string in any way different to
- this, then the user agent must <a href="#closeConnection">close the
- connection</a> and give up trying to connect.</p>
+ <dd>
- <p>Otherwise, the user agent must then take <span>the string
- representing the script's domain in IDNA format</span>, encode it as
- UTF-8, and send that to the remote host, followed by a 0x0A byte (a
- U+000A LINE FEED in UTF-8).</p>
+ <p>The value gives the scheme, hostname, and port (if it's not the
+ default port for the given scheme) of the page that asked the
+ client to open the Web Socket. It would be interesting if the
+ server's operator had deals with operators of other sites, since
+ the server could then decide how to respond (or indeed,
+ <em>whether</em> to respond) based on which site was requesting a
+ connection.</p>
- <p>The user agent must then read all the bytes sent from the remote
- host, up to the first 0x0A byte (inclusive). That string of bytes
- must then be compared byte-for-byte to the string that was just sent
- to that host (the one with the IDNA domain name and ending with a
- newline character). If the remote host sent back a string in any way
- different to this, then the user agent must <a
- href="#closeConnection">close the connection</a> and give up trying
- to connect.</p>
+ <p>If the server supports connections from more than one origin,
+ then the server should echo the value of this field in the initial
+ handshake, on the <code title="">WebSocket-Origin</code> line.</p>
- <p>Otherwise, the connection <a href="#openConnection">has been
- established</a> (and events and so forth get fired, as described
- above).</p>
+ </dd>
- <p class="note">For author-written servers (as opposed to the server
- side of a peer-to-peer connection), the script's domain would be
- replaced by the hostname of the server. Alternatively, such servers
- might instead wait for the client to send its domain string, and
- then simply echo it back. This would allow connections from pages on
- any domain, instead of just pages originating from the same
- host. The client compares the two strings to ensure they are the
- same before allowing the connection to be used by author script.</p>
+ <dt>Other fields</dt>
- <p>If at any point during this process the connection is closed
- prematurely, then the user agent must <a
- href="#closeConnection">close the connection</a> and give up trying
- to connect.</p> <!-- XXX we should support automatic reconnect -->
+ <dd>
+ <p>Other fields can be used, such as "<code
+ title="">Cookie</code>" or "<code>Authorization</code>", for
+ authentication purposes.</p>
- <h5><dfn>Sending and receiving data over TCP</dfn></h5>
+ </dd>
- <p>When the <code title="dom-Connection-send">send(<var
- title="">data</var>)</code> method is invoked on the connection's
- corresponding <code>Connection</code> object, the user agent must
- take the <var title="">data</var> argument, replace any U+0000 NULL
- and U+0017 END OF TRANSMISSION BLOCK characters in it with U+FFFD
- REPLACEMENT CHARACTER characters, then transmit a U+0002 START OF
- TEXT character, this new <var title="">data</var> string and a
- single U+0017 END OF TRANSMISSION BLOCK character (in that order) to
- the remote host, all encoded as UTF-8.</p>
+ </dl>
- <p>When the user agent receives bytes on the connection, the user
- agent must buffer received bytes until it receives a 0x17 byte (a
- U+0017 END OF TRANSMISSION BLOCK character). If the first buffered
- byte is not a 0x02 byte (a U+0002 START OF TEXT character encoded as
- UTF-8) then all the data up to the 0x17 byte, inclusive, must be
- dropped. (This allows for future extension of this protocol.)
- Otherwise, all the data from (but not including) the 0x02 byte and
- up to (but not including) the 0x17 byte must be taken, interpreted
- as a UTF-8 string, and a <code
- title="event-connection-read">read</code> event must be fired on the
- <code>Connection</code> object with that string as the <code
- title="dom-ConnectionReadEvent-data">data</code>. If that string
- cannot be decoded as UTF-8 without errors, the packet should be
- ignored.</p>
- <p class="note">This protocol does not yet allow binary data
- (e.g. an image or <span>media data</span>) to be efficiently transmitted. A
- future version of this protocol might allow this by using the prefix
- character U+001F INFORMATION SEPARATOR ONE, followed by binary data
- which uses a particular byte (e.g. 0xFF) to encode byte 0x17 somehow
- (since otherwise 0x17 would be treated as transmission end by
- down-level UAs).</p>
+ <h6 id="ws-sd-framing">Data framing</h6>
- <!--
- Specifically, replace all occurrences of 0xFF with 0xFF 0xFF and
- all occurrences of 0x17 with 0xFF 0x00, or similar.
- -->
+ <p class="note">This section only describes how to handle content
+ that this specification allows user agents to send (text). It
+ doesn't handle any arbitrary content in the same way that the
+ requirements on user agents defined earlier handle any content
+ including possible future extensions to the protocols.</p>
- <h4 id="network-security">Security</h4>
+ <p>The server should run through the following steps to process the
+ bytes sent by the client:</p>
- <p class="big-issue">Need to write this section.</p>
+ <ol>
- <p class="big-issue">If you have an unencrypted page that is
- (through a man-in-the-middle attack) changed, it can access a secure
- service that is using IP authentication and then send that data back
- to the attacker. Ergo we should probably stop unencrypted pages from
- accessing encrypted services, on the principle that the actual level
- of security is zero. Then again, if we do that, we prevent insecure
- sites from using SSL as a tunneling mechanism.</p>
+ <li><p>Read a byte from the client. Assuming everything is going
+ according to plan, it will be a 0x00 byte. Behaviour for the server
+ is undefined if the byte is not 0x00.</p></li>
- <p class="big-issue">Should consider dropping the subdomain-only
- restriction. It doesn't seem to add anything, and prevents
- cross-domain chatter.</p>
+ <li><p>Let <var title="">raw data</var> be an empty byte
+ array.</p></li>
- <h4 id="network-other-specs">Relationship to other standards</h4>
+ <li id="ws-sd-data"><p><em>Data</em>: Read a byte, let <var
+ title="">b</var> be that byte.</p></li>
- <p class="big-issue">Should have a section talking about the fact
- that we blithely ignoring IANA's port assignments here.</p>
+ <li><p>If <var title="">b</var> is not 0xff, then append <var
+ title="">b</var> to <var title="">raw data</var> and return to the
+ previous step (labeled <a href="#ws-sd-data">data</a>).</p></li>
- <p class="big-issue">Should explain why we are not reusing HTTP for
- this. (HTTP is too heavy-weight for such a simple need; requiring
- authors to implement an HTTP server just to have a party line is too
- much of a barrier to entry; cannot rely on prebuilt components;
- having a simple protocol makes it much easier to do RAD; HTTP
- doesn't fit the needs and doesn't have the security model
- needed; etc)</p>
+ <li><p>Interpret <var title="">raw data</var> as a UTF-8 string,
+ and apply whatever server-specific processing should occur for the
+ resulting string.</p>
+ <li><p>Return to the first step to read the next byte.</p></li>
+ </ol>
+ <hr>
+
+ <p>The server should run through the followin steps to send strings
+ to the client:</p>
+
+ <ol>
+
+ <li><p>Send a 0x00 byte to the client to indicate the start of a
+ string.</p></li>
+
+ <li><p>Encode <var title="">data</var> using UTF-8 and send the
+ resulting byte stream to the client.</p></li>
+
+ <li><p>Send a 0xff byte to the client to indicate the end of the
+ message.</p></li>
+
+ </ol>
+
+
+ <h5>Closing the connection</h5>
+
+ <p>To <dfn>close the Web Socket connection</dfn>, either the user
+ agent or the server closes the TCP/IP connection. There is no
+ closing handshake. Whether the user agent or the server closes the
+ connection, it is said that the <dfn>Web Socket connection is
+ closed</dfn>.</p>
+
+ <p>Servers may <span>close the Web Socket connection</span> whenever
+ desired.</p>
+
+ <p>User agents should not <span>close the Web Socket
+ connection</span> arbitrarily.</p>
+
+ <p id="closeWebSocket">When the <span>Web Socket connection is
+ closed</span>, the <code
+ title="dom-WebSocket-readyState">readyState</code> attribute's value
+ must be changed to <code title="dom-WebSocket-CLOSED">CLOSED</code>
+ (2), and the user agent must <span>fire a simple event</span> named
+ <code title="event-WebSocket-close">close</code> at the
+ <code>WebSocket</code> object.</p>
+
+
+
<h3 id="crossDocumentMessages"><dfn>Cross-document messaging</dfn></h3>
<p>Web browsers, for security and privacy reasons, prevent documents
@@ -39720,9 +39857,9 @@
the value passed as the <var title="">message</var> argument to
the <code title="dom-window-postMessage">postMessage()</code>
method, the <code title="dom-MessageEvent-origin">origin</code>
- attribute must be set to the <span title="serialization of an
- origin">serialization</span> of the <span>origin</span> of the
- script that invoked the method, the <code
+ attribute must be set to the <span title="Unicode serialization of
+ an origin">Unicode serialization</span> of the <span>origin</span>
+ of the script that invoked the method, the <code
title="dom-MessageEvent-lastEventId">lastEventId</code> attribute
must be set to the empty string, and the <code
title="dom-MessageEvent-source">source</code> attribute must be
@@ -48898,11 +49035,7 @@
raising an exception when the wrong number of arguments is passed -
is that a language-specific thing, or what?
-why |new XMLHttpRequest()| returns an object that .toStrings to
-[object XMLHttpRequest], same with new TCPConnection(); what if a
-constructor is called without using "new" in JS?
-
reload: fire an event when "reload" is pressed so that the page can
reload its data instead of the whole page. cancel the event cancels
the HTTP reload. Abuse prevention required, though.
@@ -49633,7 +49766,13 @@
0x12 (ASCII 'foo')
0x12 ("foo")
0x12 ('foo')
+ 0x12 (ASCII "<code title="">foo</code>")
+ 0x12 (ASCII '<code title="">foo</code>')
+ 0x12 ("<code title="">foo</code>")
+ 0x12 ('<code title="">foo</code>')
+Also check case of hex characters in the ASCII cases.
+
-->
</body>
More information about the Commit-Watchers
mailing list