This is a BrowserChannel server.

• -It doesn't work yet-.
• It is missing tests

The server is implemented as connect middleware.

parse helps us decode URLs in requests

querystring will help decode the URL-encoded forward channel data

Client sessions are `EventEmitters

Client session Ids are generated using node-hat

randomInt(n) generates and returns a random int smaller than n (0 <= k < n)

randomArrayElement(array) Selects and returns a random element from array

The module is configurable

An optional array of host prefixes. Each browserchannel client will randomly pick from the list of host prefixes when it connects. This reduces the impact of per-host connection limits.

All host prefixes should point to the same server. Ie, if your server's hostname is example.com and your hostPrefixes contains ['a', 'b', 'c'], a.example.com, b.example.com and c.example.com should all point to the same host as example.com.

You can specify the base URL which browserchannel connects to. Change this if you want to scope browserchannel in part of your app, or if you want /channel to mean something else, or whatever.

We'll send keepalives every so often to make sure the http connection isn't closed by eagar clients. The standard timeout is 30 seconds, so we'll default to sending them every 20 seconds or so.

All server responses set some standard HTTP headers. To be honest, I don't know how many of these are necessary. I just copied them from google.

The nocache headers in particular seem unnecessary since each client request includes a randomized zx=junk query parameter.

Google's browserchannel server adds some junk after the first message data is sent. I assume this stops some whole-page buffering in IE. I assume the data used is noise so it doesn't compress.

I don't really know why google does this. I'm assuming there's a good reason to it though.

If the user is using IE, instead of using XHR backchannel loaded using a forever iframe. When data is sent, it is wrapped in tags which call functions in the browserchannel library.

This method wraps the normal .writeHead(), .write() and .end() methods by special versions which produce output based on the request's type.

This is not used for:

• The first channel test
• The first bind connection a client makes. The server sends arrays there, but the connection is a POST and it returns immediately. So that request happens using XHR/Trident like regular forward channel requests.

If the iframe is making the request using a secondary domain, I think we need to set the domain to the original domain so that we can call the response methods.

Make sure the domain doesn't contain anything by naughty by JSON.stringify()-ing it before passing it to the client. There are XSS vulnerabilities otherwise.

The data is passed to m(), which is bound to onTridentRpcMessage_ in the client.

Once the data has been received, the client needs to call d(), which is bound to onTridentDone_ with success=true.

This is a helper method for signalling an error in the request back to the client.

The HTML (iframe) handler has no way to discover that the embedded script tag didn't complete successfully. To signal errors, we return 200 OK and call an exposed rpcClose() method on the page.

For normal XHR requests, we send data normally.

Parsing client maps from the forward channel

The client sends data in a series of url-encoded maps. The data is encoded like this:

count=2&ofs=0&req0_x=3&req0_y=10&req1_abc=def

First, we need to buffer up the request response and query string decode it.

Next, we'll need to decode the querystring-encoded maps into an array of objects.

When this function is called, the data is in this form:

{ count: '2', ofs: '0', req0_x: '3', req0_y: '10', req1_abc: 'def' }

... and we will return an object in the form of [{x:'3', y:'10'}, {abc: 'def'}]

I really wish they'd just used JSON. I guess this lets you submit forward channel data using just a GET request if you really want to. I wonder if thats how early versions of browserchannel worked...

Scan through all the keys in the data. Every key of the form: req123_xxx will be used to populate its map.

The client uses mapX_type=_badmap to signify an error encoding a map.

The server module returns a function, which you can call with your configuration options. It returns your configured connect middleware, which is actually another function.

Strip off a trailing slash in base.

Host prefixes provide a way to skirt around connection limits. They're only really important for old browsers.

Create a new client session.

This method will start a new client session. It is called in two different ways:

• A new client is connecting for the first time
• A client is reconnecting a dropped connection. In this case, the client provides their previous sessionId and arrayId.

Session ids are generated by node-hat. They are guaranteed to be unique. This method is synchronous, because a database will never be involved in browserchannel session management. Browserchannel sessions only last as long as the user's browser is open. If there's any connection turbulence, the client will reconnect and get a new session id.

I'm not sure what should happen if there's an old sessionId that we still know about. Presumably, we rename the old session and pretend nothing happened... though I imagine its a bit more complicated than that. I'll have to read more of the code.

We create a new session id for the client and send any pending arrays

Resending arrays isn't implemented yet.

We probably need to reset the client's rid and all sorts of nonsense.

Otherwise we'll just create a new client like normal. I'm not sure if we ever tell the client that we have no idea about its old sessionId.

Create a new client. Clients extend node's EventEmitter so they have access to goodies like client.on(event, handler), client.emit('paarty'), etc.

The client's unique ID for this connection

The client is a big ol' state machine. It has the following states:

• init: The client has been created and its sessionId hasn't been sent yet. The client moves to the connected state almost immediately.

• connected: The client is sitting pretty and ready to send and receive data. The client should spend most of its time in this state.

• stopped: The client is invalid for some reason. The client stays in this state just long enough to tell the client to stop connecting and tell the application that the client is going to be destroyed. Then the client is becomes dead and its removed from the session list.

• dead: The client has been removed from the session list. It can no longer be used for any reason.

  It is invalid to send arrays to a client while it is stopped or dead. Unless you're Bruce Willis...

The state is modified through this method. It emits events when the state changes. (yay)

The server sends messages to the client via a hanging GET request. Of course, the client has to be the one to open that request.

This is a handle to that request.

If we haven't sent anything for 30 seconds, we'll send a little ['noop'] to the client to make sure we haven't forgotten it. (And to make sure the backchannel connection doesn't time out.)

Its possible that a little bit of noise on the network connection (but not at the application level) will make this setTimeout not fire sometimes. Its not a big deal anyway - the client will just reopen it.

Send any arrays we've buffered now that we have a backchannel

Sad.

The server sends data to the client by sending arrays. It seems a bit silly that client->server messages are maps and server->client messages are arrays, but there it is.

lastArrayId is the array ID of the last queued array

Every request from the client has an AID parameter which tells the server the ID of the last request the client has received. We won't remove arrays from the outgoingArrays list until the client has confirmed its received them.

In lastSentArrayId we store the ID of the last array which we actually sent.

The arrays get removed once they've been acknowledged

Queue an array to be sent

Figure out how many unacknowledged arrays are hanging around in the client.

The session has just been created. The first thing it needs to tell the client is its session id and host prefix and stuff.

Encoding server arrays for the back channel

The server sends data to the client in chunks. Each chunk is a JSON array prefixed by its length in bytes.

The array looks like this:

[ [100, ['message', 'one']], [101, ['message', 'two']], [102, ['message', 'three']] ]

Each individial message is prefixed by its array id, which is a counter starting at 0 when the session is first created and incremented with each array.

Away!

Queue the arrays to be sent on the next tick

The client's IP address when it first opened the session

The client's reported application version, or null. This is sent when the connection is first requested, so you can use it to make your application die / stay compatible with people who don't close their browsers.

Stop the client's connections and make it die. This will send the special 'stop' signal to the client, which will cause it to stop trying to reconnect.

This closes a client's connections and makes the server forget about it. The client will probably try and reconnect if you simply close its connections. It'll get a new client object when it does so.

... close all connections and stuff.

Send the client array data through the backchannel

Remind everybody that the client is still alive and ticking. If the client doesn't see any traffic for awhile, it'll get deleted and the browser will just have to reconnect.

This is the returned middleware. Connect middleware is a function which takes in an http request, an http response and a next method.

The middleware can do one of two things:

• Handle the request, sending data back to the server via the response
• Call next(), which allows the next middleware in the stack a chance to handle the request.

This server only supports browserchannel protocol version 8.

Connection testing

Before the browserchannel client connects, it tests the connection to make sure its working, and to look for buffering proxies.

The server-side code for connection testing is completely stateless.

Phase 1: Server info

The client is requests host prefixes. The server responds with an array of ['hostprefix' or null, 'blockedprefix' or null].

• hostprefix is subdomain prepended onto the hostname of each request. This gets around browser connection limits. Using this requires a bank of configured DNS entries and SSL certificates if you're using HTTPS.

• blockedprefix provides network admins a way to blacklist browserchannel requests. It is not supported by node-browserchannel.

This is a straight-up normal HTTP request like the forward channel requests. We don't use the funny iframe write methods.

Phase 2: Buffering proxy detection

The client is trying to determine if their connection is buffered or unbuffered. We reply with '11111', then 2 seconds later '2'.

The client should get the data in 2 chunks - but they won't if there's a misbehaving corporate proxy in the way or something.

BrowserChannel connection

Once a client has finished testing its connection, it connects.

BrowserChannel communicates through two connections:

• The forward channel is used for the client to send data to the server. It uses a POST request for each message.
• The back channel is used to get data back from the server. This uses a hanging GET request. If chunking is disallowed (ie, if the proxy buffers) then the back channel is closed after each server message.

All browserchannel connections have an associated client object. A client is created immediately if the connection is new.

This is a special error code for the client. It tells the client to abandon its connection request and reconnect.

Forward Channel

The client is new! Make them a new client object and let the application know.

On the initial request, we send any pending server arrays to the client. This is important because it tells the client what its session id is.

On normal forward channels, we reply to the request by telling the client if our backchannel is still live and telling it how many unconfirmed arrays we have.

Back Channel

console.log 'Back channel:', query

We'll 404 the user instead of letting another handler take care of it. Users shouldn't be using the specified URL prefix for anything else.