BrowserSocket API
This document defines three interfaces. Namely BrowserSocket, ConnectionHandler, and Handshake. The BrowserSocket constructor is provided by the browser. ConnectionHandler constructors are provided by the application developer, but the ConnectionHandler objects are extended with some special functions by the browser.
Given a connectionHandlerFactory, the BrowserSocket constructor is able to provide the application with a BrowserSocket that may be used to receive incoming WebSocket connections.
The browser creates Handshake objects that correspond to handshake requests and handshake responses. The application developer is given the chance to intercept and modify handshake responses by defining a related function in the ConnectionHandler.
BrowserSocket Interface
[Constructor(in Function connectionHandlerFactory)]
interface BrowserSocket {
readonly attribute unsigned short port;
readonly attribute DOMString resourcePrefix;
attribute Function onerror;
void stop();
};
BrowserSocket(connectionHandlerFactory) is a constructor which takes a ConnectionHandler factory as its only parameter. BrowserSocket uses the factory to create ConnectionHandler instances for incoming connections.
The browser guarantees that each connectionHandler instance has methods send, and close available whenever onopen or onmessage are called.
Attribute port contains the TCP port that the browser is using to listen for incoming WebSocket connections.
Attribute resourcePrefix contains the prefix for resource names that have been mapped to the created BrowserSocket instance. The BrowserSocket receives connections to all resource that start with resourcePrefix. The first character of resourcePrefix should always be '/', and the last character of resourcePrefix should always be '/'.
Method onerror does not have a default implementation so it is safe to override.
Function stop can be called at any time to close the BrowserSocket.
ConnectionHandler Interface
interface ConnectionHandler {
Handshake handshakeResponseLoop(in Handshake interceptedResponse);
attribute Function onopen;
attribute Function onmessage;
attribute Function onerror;
attribute Function onclose;
void send(in DOMString data);
void close();
};
ConnectionHandler(handshakeRequest) is a constructor which takes a handshake request as its only parameter.
Methods onopen, onmessage, onerror, and onclose do not have a default implementation so it is safe to override them.
Custom handshakes can be implemented by defining a handshakeResponseLoop method. The connection can be cancelled from handshakeResponseLoop method by returning null.
Handshake Interface
The http-like headers for handshake requests and responses are presented as Handshake objects.
interface Handshake {
attribute DOMString firstLine;
attribute object headers;
attribute octet[] body;
};
The request/response line of the handshake request/response is stored under key firstLine.
The key/value pairs of the headers are stored in another dict under key headers.
Finally, the body of the request is provided as a list of integers representing bytes under key body.