W3C

The Web Sockets API

W3C Working Draft 29 October 2009

This Version:
http://www.w3.org/TR/2009/WD-websockets-20091029/
Latest Published Version:
http://www.w3.org/TR/websockets/
Latest Editor's Draft:
http://dev.w3.org/html5/websockets/
Previous Versions:
http://www.w3.org/TR/2009/WD-websockets-20090423/
Editors:
Ian Hickson, Google, Inc.

Abstract

This specification defines an API that enables Web pages to use the Web Sockets protocol 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 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.

Table of contents

  1. 1 Introduction
  2. 2 Conformance requirements
    1. 2.1 Dependencies
  3. 3 Terminology
  4. 4 The WebSocket interface
  5. 5 Feedback from the protocol
    1. 5.1 Garbage collection
  6. References

1 Introduction

This 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.

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.

2.1 Dependencies

This specification relies on several other underlying specifications.

HTML5

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

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.

4 The 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:

  1. 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.

  2. 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.)

  3. Let origin be the ASCII serialization of the origin of the script that invoked the WebSocket() constructor, converted to ASCII lowercase.

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

  5. 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)
The connection has not yet been established.
OPEN (numeric value 1)
The Web Socket connection is established and communication is possible.
CLOSED (numeric value 2)
The connection has been closed or could not be opened.

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

5 Feedback from the protocol

When the Web Socket connection is established, the user agent must run the following steps:

  1. Change the readyState attribute's value to OPEN (1).

  2. 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.

5.1 Garbage collection

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.

References

All references are normative unless marked "Non-normative".

[DOMCORE]
Document Object Model (DOM) Level 3 Core Specification, A. Le Hors, P. Le Hegaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrnes. W3C, April 2004.
[HTML5]
HTML5, I. Hickson. WHATWG, August 2009.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF, March 1997.
[WEBIDL]
Web IDL, C. McCormack. W3C, July 2009.