I recently had the extreme pleasure to use node.js and socket.io on a project. Here are some insights.

Objective

So the objective of the project was to read data from the _changes feed of our CouchDB cluster (hosted by Cloudant) and publish the data to a widget which we can use to display a constant stream of "what are people doing right now".

The core of the problem we faced was not just taking this stream of data and feeding it on to a page, but since we'll deploy this widget to our homepage we needed to make sure that no matter how many clients see it, the impact on the database cluster is minimal; for example, it would be a single client (or down the road up to three for failover) who actually read data from the cluster.

After shopping around for a technology to use, it became obvious that we needed some sort of abstraction because of how the different technologies (e.g. comet, websockets, ajax longpolling, ...) are implemented in different browsers.
We decided to build this project on top of socket.io — pretty much for the same reasons most people go to jQuery, prototype or dojo these days.

Load /socket.io/socket.io.js asynchronously — don't ask why or how, but socket.io probably adds a route somewhere to serve this file. As for the code it loads, it seems to be vendor/socket.io/support/socket.io-client/socket.io.js.

Create a socket object — port designates the same port I had in server.js.

Whenever a message is received, push it on the list (aka id=container).

Note: The above code is example code only. It doesn't have any bells and whistles, e.g. a try/catch wouldn't hurt, etc..

Want more?

I'll spare you more of the official socket.io example code, as there is not only one outdated website and github repository, but already 30 other blogs out there discussing the same basic chat example. While the example is pretty basic, it lists the relevant events you might need in case there's more interaction between the code on the server and the client.

I may seem ungrateful for what socket.io does, but the horror or misery we face is that while socket.io provides a great value (all-around abstraction for client- and server-side communication), it really does not excel at documentation.

In its current state, the node.js community is probably mostly developers who get a kick out of writing cool apps. While general QA, testing and documentation have become a pretty standard thing in other programming communities, this has not happened in the node.js ecosystem yet.

As a developer myself, I don't feel embraced at all here. When I dive into the 20 files and 100s of lines of code, I'm hoping that beyond what I got now, we will actually never run into any larger problems which will require further debugging.

And if we do, we probably will have to switch to something else. (Which I think would be a slightly less cooler implementation using comet with an iframe, etc..)

Takeaways

In case you're looking into node.js for a customer, be aware that its APIs still change (fundamentally) and there are no guarantees for BC. And since the libraries for node.js tend to follow the patterns of the core, it's best to keep a local copy of node.js code and all libraries involved.

Working with CouchDB and the node.js http client can be a tedious task. E.g. Basic Authorization by hand along with the response and error handling etc.. For most cases I found Restler to be an excellent library (Thanks again, Stefano!). Restler may very well be the best HTTP client library for node.js out there.
The only thing Restler currently does not do well is work with _changes or streams in general because restler will always wait for a request to complete before it sends you data. Not suitable if the stream is never ending. :-)

All my messed up JavaScript code, now runs on the server. Booya!

Fin

That's all for now. I'm currently working on some chef-recipes for the application servers who'll run this code for us. I'll share more next time.