Spec

REWRITE ME TO INSTEAD DESCRIBE BROWSERCHANNEL

Normally, node-browserchannel uses hanging GETs to move data from the server to the client and a sequence of POSTs to move data from the client to the server.

Before connecting, the client tests the network connection for buffering proxies. If buffering proxies are found, the client uses a series of short-lived GETs instead of a single long-lived one.

The client will automatically keep trying to reconnect once its been disconnected, doing a gmail-style exponential backoff. This process will stop if the client calls .disconnect() or if the client encounters a fatal error.

If a client is unexpectedly disconnected or times out, the server will wait a configurable amount of time for the client to reconnect. If the client does not reconnect during this time, the server socket will emit a fatal disconnected message. If the client manages to reconnect after this time, it will go through the handshaking process again and be assigned a new ID. If this happens, the client will fire a reconnected event. This also allows a server to be restarted without requiring the page to be reloaded, or really any special app code.

Requests

All node-browserchannel requests use XHR.

All node-browserchannel responses include no-cache directives, and the URLs have randomized query parameters (?r=XYZ) just to make doubly sure.

All node-browserchannel URLs start with <BASE>/<VERSION>/. a configurable base URL (default: /ss/) and VERSION is the protocol version, which at the moment is 0.

Connecting to a server

A new client starts in the ready state. When .connect() is called, the client transitions to the connecting state.

Phase 1: Connection Testing

Should the server do authentication here or when the client actually tries to connect?

Before connecting, the client runs a test to see if there is a buffering proxy between the browser and the server. It does this by doing a XHR GET to ss/0/test. This returns the string: 11111, then 2 seconds later 2. If these messages are delivered separately, the connection will use a long-lived connection for the back channel, with chunked encoding. If they're delivered together, it'll use a new GET request for every hunk of data in the backchannel.

According to the browserchannel code, in IE a buffering proxy can still result in XHR sending the information in two consecutive XHR callbacks. Check that the callbacks are called >500ms apart.

If the connection times out, the connection attempt is abandoned and the client moves to the awaiting reconnection state. If any other error happens, a connection failed event fires and the connection attempt is abandoned.

Phase 2: Connection

The client uses two streams to communicate with the server:

• forward: Used by the client to send data to the server. This POSTs data to ss/0/f each time the client issues a send() command.
• back: Used by the server to send data to the client. This uses a hanging GET request. Each time there is data ready for the client, it is sent over this connection. The URL is ss/0/b with the following query parameters:
• C: Should the connection be chunked? 1 or 0.
• OSID: (optional) The previous session ID.