The bulk of the text of this specification is also
available in the WHATWG Web Applications 1.0 specification, under a license that permits
reuse of the specification text.

Abstract

This specification defines an API that enables Web pages to use
the WebSocket protocol (defined by the IETF) for two-way
communication with a remote host.

Status of This document

This section describes the status of this document at the
time of its publication. Other documents may supersede this
document. A list of current W3C publications and the
latest
revision of this technical report can be found in the W3C technical reports index at
http://www.w3.org/TR/.

If you wish to make comments regarding this document in a manner
that is tracked by the W3C, please submit them via using our
public bug database. If you do not have an account then you can
enter feedback using this form:

Feedback Comments

Please enter your feedback, carefully
indicating the title of the section for which you are submitting
feedback, quoting the text that's wrong today if appropriate. If
you're suggesting a new feature, it's really important to say
what the problem you're trying to solve is. That's more
important than the solution, in fact.

Please don't use section numbers as these tend to
change rapidly and make your feedback harder to understand.

(Note: Your IP address and user agent will be publicly recorded for spam prevention purposes.)

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This specification is being developed in conjunction with an
RFC for a wire protocol, the WebSocket Protocol,
available from the following location:

Candidate Recommendation Exit Criteria

To exit the Candidate Recommendation (CR) stage, the following criteria
must have been met:

There will be at least two interoperable implementations passing all
approved test cases in the
test suite
for this specification. An implementation is to be available (i.e. for
download), shipping (i.e. not private), and not experimental (i.e. intended
for a wide audience). The working group will decide when the test suite is
of sufficient quality to test interoperability and will produce an
implementation report (hosted together with the test suite).

A minimum of one month of the CR stage will have elapsed (i.e. not
until after 18 October 2012). This is to ensure that enough time is given
for any remaining major errors to be caught. The CR period will be extended
if implementations are slow to appear.

1 Introduction

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.

2 Conformance requirements

All diagrams, examples, and notes in this specification are
non-normative, as are all sections explicitly marked non-normative.
Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in the normative parts of this document are to be
interpreted as described in RFC2119. For readability, these words do
not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms
(such as "strip any leading space characters" or "return false and
abort these steps") are to be interpreted with the meaning of the
key word ("must", "should", "may", etc) used in introducing the
algorithm.

Some conformance requirements are phrased as requirements on
attributes, methods or objects. Such requirements are to be
interpreted as requirements on user agents.

Conformance requirements phrased as algorithms or specific steps
may be implemented in any manner, so long as the end result is
equivalent. (In particular, the algorithms defined in this
specification are intended to be easy to follow, and not intended to
be performant.)

The only conformance class defined by this specification is user
agents.

User agents may impose implementation-specific limits on
otherwise unconstrained inputs, e.g. to prevent denial of service
attacks, to guard against running out of memory, or to work around
platform-specific limitations.

When support for a feature is disabled (e.g. as an emergency
measure to mitigate a security problem, or to aid in development, or
for performance reasons), user agents must act as if they had no
support for the feature whatsoever, and as if the feature was not
mentioned in this specification. For example, if a particular
feature is accessed via an attribute in a Web IDL interface, the
attribute itself would be omitted from the objects that implement
that interface — leaving the attribute on the object but
making it return null or throw an exception is insufficient.

2.1 Dependencies

This specification relies on several other underlying
specifications.

HTML

Many fundamental concepts from HTML are used by this
specification. [HTML]

WebIDL

The IDL blocks in this specification use the semantics of the
WebIDL specification. [WEBIDL]

3 Terminology

The construction "a Foo object", where
Foo is actually an interface, is sometimes
used instead of the more accurate "an object implementing the
interface Foo".

The term DOM is used to refer to the API set made available to
scripts in Web applications, and does not necessarily imply the
existence of an actual Document object or of any other
Node objects as defined in the DOM Core
specifications. [DOMCORE]

An IDL attribute is said to be getting when its value is
being retrieved (e.g. by author script), and is said to be
setting when a new value is assigned to it.

The WebSocket(url, protocols)
constructor takes one or two arguments. The first argument, url, specifies the URL to which to
connect. The second, protocols, if present, is
either a string or an array of strings. If it is a string, it is
equivalent to an array consisting of just that string; if it is
omitted, it is equivalent to the empty array. Each string in the
array is a subprotocol name. The connection will only be established
if the server reports that it has selected one of these
subprotocols. The subprotocol names must all be strings that match
the requirements for elements that comprise the value of Sec-WebSocket-Protocol
header fields as defined by the WebSocket protocol specification. [WSP]

When the WebSocket() constructor is invoked, the UA
must run these steps:

If secure is false but the
origin of the entry script has a scheme
component that is itself a secure protocol, e.g. HTTPS, then throw
a SecurityError exception.

If port is a port to which the user agent
is configured to block access, then throw a
SecurityError exception. (User agents typically block
access to well-known ports like SMTP.)

Access to ports 80 and 443 should not be blocked, including the
unlikely cases when secure is false but port is 443 or secure is true
but port is 80.

If protocols is absent, let protocols be an empty array.

Otherwise, if protocols is present and a
string, let protocols instead be an array
consisting of just that string.

If any of the values in protocols occur
more than once or otherwise fail to match the requirements for
elements that comprise the value of Sec-WebSocket-Protocol
header fields as defined by the WebSocket protocol specification,
then throw a SyntaxError exception and abort these
steps. [WSP]

Return a new WebSocket object, and continue
these steps in the background (without blocking scripts).

Establish a WebSocket connection given the set (host, port, resource name, secure), along
with the protocols list, an empty list for the
extensions, and origin. The headers to send
appropriate cookies must be a Cookie header whose value is the
cookie-string computed from the user's cookie store and the
URL url; for these purposes this is
not a "non-HTTP" API. [WSP][COOKIES]

When the user agent validates the server's response during the
"establish a WebSocket connection" algorithm, if the status
code received from the server is not 101 (e.g. it is a redirect),
the user agent must fail the WebSocket connection.

Following HTTP procedures here could introduce
serious security problems in a Web browser context. For example,
consider a host with a WebSocket server at one path and an open
HTTP redirector at another. Suddenly, any script that can be given
a particular WebSocket URL can be tricked into communicating to
(and potentially sharing secrets with) any host on the Internet,
even if the script checks that the URL has the right hostname.

If the establish a WebSocket connection
algorithm fails, it triggers the fail the WebSocket
connection algorithm, which then invokes the close the
WebSocket connection algorithm, which then establishes that
the WebSocket connection is closed, which fires the close event as described below.

This constructor must be visible when the script's global
object is either a Window object or an object
implementing the WorkerUtils interface.

The url
attribute must return the result of resolving the URL that was passed to the
constructor. (It doesn't matter what it is resolved relative to,
since we already know it is an absolute URL.)

The readyState
attribute represents the state of the connection. It can have the
following values:

CONNECTING (numeric value 0)

The connection has not yet been established.

OPEN (numeric value 1)

The WebSocket connection is established and communication is possible.

CLOSING (numeric value 2)

The connection is going through the closing handshake, or the close() method has been invoked.

The extensions
attribute must initially return the empty string. After the
WebSocket connection is established, its value might change, as
defined below.

The extensions attribute returns
the extensions selected by the server, if any. (Currently this will
only ever be the empty string.)

The protocol attribute
must initially return the empty string. After the WebSocket
connection is established, its value might change, as defined
below.

The protocol attribute returns the
subprotocol selected by the server, if any. It can be used in
conjunction with the array form of the constructor's second argument
to perform subprotocol negotiation.

The close()
method must run the following steps:

If the method's first argument is present but is not an
integer equal to 1000 or in the range 3000 to 4999, throw an
InvalidAccessError exception and abort these
steps.

If the method's second argument is present, then run these
substeps:

Let raw reason be the method's second
argument.

Let Unicode reason be the result of
converting raw reason to a
sequence of Unicode characters.

Let reason be the result of encoding
Unicode reason as UTF-8.

If reason is longer than 123 bytes,
then throw a SyntaxError exception and abort these
steps. [RFC3629]

The fail the WebSocket connection
algorithm invokes the close the WebSocket
connection algorithm, which then establishes that
the WebSocket connection is closed, which fires the
close event as described below.

If the first argument is present, then the status
code to use in the WebSocket Close message must
be the integer given by the first argument. [WSP]

If the second argument is also present, then reason must be provided in the Close message
after the status code. [RFC3629][WSP]

The start the WebSocket closing handshake
algorithm eventually invokes the close the WebSocket
connection algorithm, which then establishes that the
WebSocket connection is closed, which fires the close event as described below.

The WebSocket closing handshake is
started, and will eventually invoke the close the
WebSocket connection algorithm, which will establish that
the WebSocket connection is closed, and thus the close event will fire, as described below.

The bufferedAmount
attribute must return the number of bytes of application data (UTF-8
text and binary data) that have been queued using send() but that, as of the last
time the event loop started executing a task, had not yet been transmitted to
the network. (This thus includes any text sent during the execution
of the current task, regardless of whether the user agent is able to
transmit text asynchronously with script execution.) This does not
include framing overhead incurred by the protocol, or buffering done
by the operating system or network hardware. If the connection is
closed, this attribute's value will only increase with each call to
the send() method (the
number does not reset to zero once the connection closes).

In this simple example, the bufferedAmount
attribute is used to ensure that updates are sent either at the
rate of one update every 50ms, if the network can handle that rate,
or at whatever rate the network can handle, if that is too
fast.

The bufferedAmount
attribute can also be used to saturate the network without sending
the data at a higher rate than the network can handle, though this
requires more careful monitoring of the value of the attribute over
time.

When a WebSocket object is created, its binaryType IDL
attribute must be set to the string "blob". On
getting, it must return the last value it was set to. On setting, if
the new value is either the string "blob" or
the string "arraybuffer", then set the IDL
attribute to this new value. Otherwise, throw a
SyntaxError exception.

This attribute allows authors to control how binary
data is exposed to scripts. By setting the attribute to "blob", binary data is returned in Blob
form; by setting it to "arraybuffer", it is
returned in ArrayBuffer form. User agents can use this
as a hint for how to handle incoming binary data: if the attribute
is set to "blob", it is safe to spool it to
disk, and if it is set to "arraybuffer", it is
likely more efficient to keep the data in memory. Naturally, user
agents are encouraged to use more subtle heuristics to decide
whether to keep incoming data in memory or not, e.g. based on how
big the data is or how common it is for a script to change the
attribute at the last minute. This latter aspect is important in
particular because it is quite possible for the attribute to be
changed after the user agent has received the data but before the
user agent has fired the event for it.

The send(data) method transmits data using the
connection. If the readyState attribute is
CONNECTING, it must
throw an InvalidStateError exception. Otherwise, the
user agent must run the appropriate set of steps from the following
list:

If the argument is a string

Let data be the result of converting the data argument to a
sequence of Unicode characters. If the WebSocket
connection is established and the WebSocket closing handshake has not yet
started, then the user agent must send a WebSocket
Message comprised of data using a text
frame opcode; if the data cannot be sent, e.g. because it would
need to be buffered but the buffer is full, the user agent must
close the WebSocket connectionwith prejudice. Any
invocation of this method with a string argument that does not
throw an exception must increase the bufferedAmount
attribute by the number of bytes needed to express the argument as
UTF-8. [UNICODE][RFC3629][WSP]

If the argument is a Blob object

If the WebSocket connection is established, and the WebSocket
closing handshake has not yet started, then the user agent
must send a WebSocket Message comprised of data using a binary frame opcode; if the data
cannot be sent, e.g. because it would need to be buffered but the
buffer is full, the user agent must close the WebSocket
connectionwith
prejudice. The data to be sent is the raw data represented
by the Blob object. Any
invocation of this method with a Blob argument that
does not throw an exception must increase the bufferedAmount
attribute by the size of the Blob object's raw data,
in bytes. [WSP][FILEAPI]

If the argument is an ArrayBuffer object

If the WebSocket connection is established, and the WebSocket
closing handshake has not yet started, then the user agent
must send a WebSocket Message comprised of data using a binary frame opcode; if the data
cannot be sent, e.g. because it would need to be buffered but the
buffer is full, the user agent must close the WebSocket
connectionwith
prejudice. The data to be sent is the data stored in the
buffer described by the ArrayBuffer object. Any invocation of
this method with an ArrayBuffer argument that does
not throw an exception must increase the bufferedAmount
attribute by the length of the ArrayBuffer in bytes.
[WSP][TYPEDARRAY]

If the argument is an ArrayBufferView object

If the WebSocket connection is established, and the WebSocket
closing handshake has not yet started, then the user agent
must send a WebSocket Message comprised of data using a binary frame opcode; if the data
cannot be sent, e.g. because it would need to be buffered but the
buffer is full, the user agent must close the WebSocket
connectionwith
prejudice. The data to be sent is the data stored in the
section of the buffer described by the ArrayBuffer
object that the ArrayBufferView object references.
Any invocation
of this method with an ArrayBufferView argument that
does not throw an exception must increase the bufferedAmount
attribute by the length of the ArrayBufferView in
bytes. [WSP][TYPEDARRAY]

5 Feedback from the protocol

Change the extensions attribute's
value to the extensions in use, if is not the null value. [WSP]

Change the protocol attribute's value to
the subprotocol in use, if is not the null value. [WSP]

Act as if the user agent had received a set-cookie-string consisting
of the cookies set during the server's opening handshake,
for the URL url given to the WebSocket() constructor. [COOKIES][RFC3629][WSP]

User agents are encouraged to check if they can
perform the above steps efficiently before they run the task,
picking tasks from other task queues
while they prepare the buffers if not. For example, if the binaryType attribute was set
to "blob" when the data arrived, and the user
agent spooled all the data to disk, but just before running the
above task for this particular
message the script switched binaryType to "arraybuffer", the user agent would want to page the
data back to RAM before running this task so as to avoid stalling the main
thread while it created the ArrayBuffer object.

Here is an example of how to define a handler for the message event in the case of text
frames:

If the user agent was required to fail the WebSocket
connection or the WebSocket connection is closedwith prejudice,
fire a simple event named error
at the WebSocket object. [WSP]

Create an event that uses the CloseEvent
interface, with the event type close, which does not bubble, is not
cancelable, has no default action, whose wasClean attribute is initialized to
true if the connection closed cleanly and false
otherwise, whose code
attribute is initialized to the WebSocket connection close code, and
whose reason attribute
is initialized to the WebSocket connection close reasondecoded as UTF-8, with error handling, and dispatch
the event at the WebSocket object. [WSP]

User agents must not convey any failure information to scripts
in a way that would allow a script to distinguish the following
situations:

A server whose host name could not be resolved.

A server to which packets could not successfully be routed.

A server that refused the connection on the specified port.

A server that failed to correctly perform a TLS handshake
(e.g., the server certificate can't be verified).

A server that did not complete the opening handshake (e.g.
because it was not a WebSocket server).

A WebSocket server that sent a correct opening handshake, but
that specified options that caused the client to drop the
connection (e.g. the server specified a subprotocol that the
client did not offer).

A WebSocket server that abruptly closed the connection after
successfully completing the opening handshake.

In all of these cases, the the WebSocket connection close
code would be 1006, as required by the WebSocket Protocol
specification. [WSP]

Allowing a script to distinguish these cases would allow a
script to probe the user's local network in preparation for an
attack.

In particular, this means the code 1015 is not used
by the user agent (unless the server erroneously uses it in its
close frame, of course).

The task source for all tasksqueued in this section is the WebSocket task
source.

6 Ping and Pong frames

The WebSocket protocol specification defines Ping and Pong frames
that can be used for keep-alive, heart-beats, network status
probing, latency instrumentation, and so forth. These are not
currently exposed in the API.

User agents may send ping and unsolicited pong frames as desired,
for example in an attempt to maintain local network NAT mappings, to
detect failed connections, or to display latency metrics to the
user. User agents must not use pings or unsolicited pongs to aid the
server; it is assumed that servers will solicit pongs whenever
appropriate for the server's needs.

7 Parsing WebSocket URLs

The steps to parse a WebSocket URL's components from
a string url are as follows. These steps return
either a host, a port, a
resource name, and a secure
flag, or they fail.

The wasClean
attribute must return the value it was initialized to. When the
object is created, this attribute must be initialized to false. It
represents whether the connection closed cleanly or not.

The code
attribute must return the value it was initialized to. When the
object is created, this attribute must be initialized to zero. It
represents the WebSocket connection close code provided by the
server.

The reason
attribute must return the value it was initialized to. When the
object is created, this attribute must be initialized to empty
string. It represents the WebSocket connection close reason provided
by the server.

9 Garbage collection

A WebSocket object whose readyState attribute's value
was set to CONNECTING
(0) as of the last time the event loop started
executing a task must not be
garbage collected if there are any event listeners registered for
open events, message events, error events, or close events.

A WebSocket object whose readyState attribute's value
was set to OPEN (1) as of
the last time the event loop started executing a task must not be garbage collected if
there are any event listeners registered for message events, error, or close events.

A WebSocket object whose readyState attribute's value
was set to CLOSING (2) as
of the last time the event loop started executing a
task must not be garbage collected
if there are any event listeners registered for error or close events.

A WebSocket object with an established connection that has
data queued to be transmitted to the network must not be garbage
collected. [WSP]

If a WebSocket object is garbage collected while its
connection is still open, the user agent must start the
WebSocket closing handshake, with no status code for the Close message. [WSP]

If a user agent is to make disappear a
WebSocket object (this happens when a
Document object goes away), the user agent must follow
the first appropriate set of steps from the following list: