Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines an API that enables Web pages to use the Web Sockets protocol for two-way communication with a remote host.
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 most recently formally published 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, please send them to public-webapps@w3.org (subscribe, archives), whatwg@whatwg.org (subscribe, archives), or hybi@ietf.org (subscribe, archives). All feedback is welcome.
Implementors should be aware that this specification is not stable. Implementors who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.
The latest stable version of the editor's draft of this specification is always available on the W3C CVS server. Change tracking for this document is available at the following location:
This specification is automatically generated from the corresponding section in the HTML5 specification's source document, as hosted in the WHATWG Subversion repository. Detailed change history for all of HTML5, including the parts that form this specification, can be found at the following locations:
The W3C Web Apps Working Group is the W3C working group responsible for this specification's progress along the W3C Recommendation track. This specification is the 29 October 2009 Working Draft.
This specification is being developed in conjunction with an Internet Draft for a wire protocol, the Web Socket Protocol, available from the IETF at the following location:
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
WebSocket interfaceThis section is non-normative.
To enable Web applications to maintain bidirectional
communications with server-side processes, this specification
introduces the WebSocket interface.
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.
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.
This specification relies on several other underlying specifications.
Many fundamental concepts from HTML5 are used by this specification. [HTML5]
The IDL blocks in this specification use the semantics of the WebIDL specification. [WEBIDL]
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.
WebSocket interface[Constructor(in DOMString url, in optional DOMString protocol)]
interface WebSocket {
readonly attribute DOMString URL;
// ready state
const unsigned short CONNECTING = 0;
const unsigned short OPEN = 1;
const unsigned short CLOSED = 2;
readonly attribute unsigned short readyState;
readonly attribute unsigned long bufferedAmount;
// networking
attribute Function onopen;
attribute Function onmessage;
attribute Function onclose;
boolean send(in DOMString data);
void close();
};
WebSocket implements EventTarget;The WebSocket(url, protocol)
constructor takes one or two arguments. The first argument, url, specifies the URL to which to
connect. The second, protocol, if present,
specifies a sub-protocol that the server must support for the
connection to be successful. When the WebSocket()
constructor is invoked, the UA must run these steps:
Parse a Web Socket URL's components from the
url argument, to obtain host, port, resource name, and secure. If
this fails, throw a SYNTAX_ERR exception and abort
these steps.
If port is a port to which the user
agent is configured to block access, then throw a
SECURITY_ERR exception. (User agents typically block
access to well-known ports like SMTP.)
Let origin be the ASCII serialization of the
origin of the script that invoked the WebSocket() constructor,
converted to ASCII lowercase.
Return a new WebSocket object, and continue
these steps in the background (without blocking scripts).
Establish a Web Socket connection to a host host, on port port (if one was specified), from origin, with the flag secure, with resource name as the resource name, and with protocol as the protocol (if it is present).
If the "establish a Web Socket
connection" algorithm fails, it triggers the "fail
the Web Socket connection" algorithm, which then invokes
the "close the Web Socket connection" algorithm,
which then establishes that the "Web Socket 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 value that was passed to the
constructor.
The readyState
attribute represents the state of the connection. It can have the
following values:
CONNECTING (numeric value 0)OPEN (numeric value 1)CLOSED (numeric value 2)When the object is created its readyState must be set to
CONNECTING (0).
The send(data) method transmits data using the
connection. If the connection has not yet been established (readyState is CONNECTING), it must raise
an INVALID_STATE_ERR exception. (No exception is raised
if the connection was once established but has subsequently been
closed, however.) If the data argument has any
unpaired surrogates, then it must raise SYNTAX_ERR. If
the connection is established, and the string has no
unpaired surrogates, then the user agent must send data using the Web Socket. 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 Web Socket
connection. The method must then return true if the
connection is still established (and the data was queued or sent
successfully), or false if the connection is closed (e.g. because
the user agent just had a buffer overflow and failed to send the
data).
The close()
method must close the Web Socket connection or
connection attempt, if any. If the connection is already closed, it
must do nothing.
Closing the connection eventually causes a close event to be fired and the readyState attribute's value
to change, as described below.
The bufferedAmount
attribute must return the number of bytes that have been queued but
not yet sent. 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).
The following are the event handlers that must be
supported, as IDL attributes, by all objects implementing the
WebSocket interface:
| Event handler | Event handler event type |
|---|---|
onopen | open
|
onmessage | message
|
onclose | close
|
When the Web Socket connection is established, the user agent must run the following steps:
Change the readyState attribute's value
to OPEN (1).
Queue a task to fire a simple event
named open at the
WebSocket object.
When a Web Socket message has been received with text data, the user agent must create an event that uses
the MessageEvent interface, with the event name message, which does not bubble, is not
cancelable, has no default action, and whose data attribute is set to data, and queue a task to dispatch it at
the WebSocket object.
When the Web Socket connection is
closed, the readyState attribute's value
must be changed to CLOSED
(2), and the user agent must queue a task to fire
a simple event named close at the
WebSocket object.
The task source for all tasks queued in this section is the Web Socket task source.
A WebSocket object with an open connection must not
be garbage collected if there are any event listeners registered for
message events.
If a WebSocket object is garbage collected while its
connection is still open, the user agent must close the Web
Socket connection.
All references are normative unless marked "Non-normative".