I’m pleased to finally announce the release of Faye 0.8 after a few months of reorganising the 0.7 codebase to make it more modular, and splitting parts of it out into separate projects. Before I get to what’s changed, I’m going to get the API changes out of the way: this is the stuff you need to know if you’re upgrading.

I hate introducing API changes but I’m afraid these really couldn’t be avoided. They’re really configuration changes so you shouldn’t need to change a lot of code. Please get on the mailing list if you have problems.

First, if you’re running the Ruby server you need to tell it which web server you’re using. Faye now supports the Thin, Rainbows and Goliath web servers, and you need to tell the WebSocket layer which set of adapters to load. For a ‘hello world’ app this looks like this:

# config.ru
require 'faye'
Faye::WebSocket.load_adapter('thin')

app = Faye::RackAdapter.new(:mount => '/faye', :timeout => 25)

run app

Depending on whether you run your application with rackup or thin, the load_adapter call might not be strictly necessary, but better to have it in there just in case. See the Faye Ruby docs and the faye-websocket documentation on how to run your app with different Ruby servers.

Second, if you use the Redis backend, you need to install a new library and change the engine.type setting in your server. Instead of specifying the name of the engine, this field now takes a reference to the engine object. In Ruby that looks like this:

# config.ru
# First run: gem install faye-redis

require 'faye'
require 'faye/redis'

bayeux = Faye::RackAdapter.new(
  :mount   => '/',
  :timeout => 25,
  :engine  => {
    :type  => Faye::Redis,
    :host  => 'redis.example.com',
    # more options
  }
)

And on Node:

// First run: npm install faye-redis

var faye  = require('faye'),
    redis = require('faye-redis');

var bayeux = new faye.NodeAdapter({
  mount:    '/',
  timeout:  25,
  engine: {
    type:   redis,
    host:   'redis.example.com',
    // more options
  }
});

Apart from this, Faye 0.8 should be backward-compatible with previous releases.

Having got the administrivia out of the way, what’s new? Well, the main focus of the 0.8 release is modularity. Two major components of Faye – the WebSocket support and the Redis engine – have been split off into their own packages. I’ve been blogging here already about faye-websocket (rubygem, npm package), and the major work over the last few months has gone into making this a really solid WebSocket and EventSource implementation. Because of its new-found freedom outside the main Faye project, it’s been adopted by other projects, notably SockJS, Cramp and Poltergeist. This adoption, particularly from SockJS, has meant more feedback, bug fixes and performance improvements and resulted in a really solid WebSocket library that improves Faye’s performance.

This new library has had a beneficial impact on Faye’s transport layer. faye-websocket is much faster than Faye’s 0.7 WebSocket code, supports EventSource and new WebSocket features, and runs on more Ruby servers: Faye 0.7 was confined to Thin whereas it now also runs on Rainbows and Goliath. On top of this, Faye 0.8 adds a new EventSource-based transport to support Opera 11 and browsers where proxies block WebSocket, and improves how it uses WebSocket. Previously, Faye’s WebSocket transport used the same polling-based /meta/connect cycle as other transports. It was faster than HTTP, but not optimal. Faye 0.8 now breaks out of this request/response pattern and pushes messages to WebSocket and EventSource connections as soon as they arrive at the server, without returning the /meta/connect poll. This results in lower latency, particular when delivering messages at high volume.

The second major change is that the Redis engine is now a separate library, faye-redis (rubygem, npm package). This has two important benefits. First, the main Faye package no longer depends on Redis clients, and in particular the Node version no longer depends on packages with C extensions, so no compiler is needed to install it. Second, it means Faye’s backend is now totally pluggable and third parties can implement their own engines: the API is thoroughly documented for Ruby and Node. The engine is a small piece of code (for example here’s the Ruby in-memory engine) but it really defines Faye’s behaviour. This layer is not concerned with transport negotiation (HTTP, WebSocket, etc) or even the Bayeux protocol format, it just implements the messaging business logic and stores the state of the system. You can easily implement your own engine to run on top of another messaging/storage stack, or change the messaging semantics if you like. Faye has a complete set of tests you can run to check your engine – see the Ruby and Node projects for examples.

Finally, there have been a couple of changes to the client. We’ve switched from exponential-backoff to fixed-interval for trying to reconnect after the client loses its connection to the server, and this interval is configurable using the retry setting:

// Attempts to reconnect every 5 seconds
var client = new Faye.Client('http://example.com/bayeux', {
  retry: 5
});

You can also set headers for long-polling requests on the client; this is useful for talking to OAuth-protected servers, for example:

client.setHeader('Authorization', 'OAuth ' + accessToken);

And finally, there’s a new server-side setting, ping, that controls how often the server sends keep-alive data over WebSocket and EventSource connections. This data is ignored by the client, but helps keep the connection open through proxies that like to kill idle connections.

// Sends pings every 10 seconds

var bayeux = new faye.NodeAdapter({
  mount: '/bayeux',
  ping:  10
});

And that just about wraps things up for this release. Since 0.7.1, the main Faye codebase has shed over 2,000 lines of code into other projects that we can easily ship incremental updates to without affecting Faye itself. It’s more performant, leaner and more modular and I know there are already projects doing cool things with it. If you’re using Faye for interesting projects, I’d love to hear from you on the mailing list.

The latest iteration of faye-websocket has just been released for Ruby and Node, probably the last release before I get back to making progress on Faye itself. It contains two major new features: EventSource support, and support for the Rainbows and Goliath web servers for the Ruby version.

EventSource is a server-push protocol that’s supported by many modern browsers. On the client side, you open a connection and listen for messages:

var es = new EventSource('http://example.com/events');
es.onmessage = function(event) {
  // process event.data
};

This sends a GET request with Content-Type: text/event-stream to the server and holds the connection open, and the server can then send messages to the client via a streaming HTTP response. It’s a one-way connection so the client cannot send messages to the server over this connection; it must use separate HTTP requests. However, EventSource uses a much simpler protocol than WebSocket, and looks more like ‘normal’ HTTP so it has less trouble getting through proxies.

On the server side, supporting this requires a lot of the same code as WebSocket, and I might use it in Faye later on, so I decided to add support for it in faye-websocket. In your Rack app, you can now easily handle EventSource connections using an API similar to WebSocket:

require 'faye/websocket'

App = lambda do |env|
  if Faye::EventSource.eventsource?(env)
    es = Faye::EventSource.new(env)

    # Periodically send messages
    loop = EM.add_periodic_timer(1) { es.send('Hello') }
    
    es.onclose = lambda do |event|
      EM.cancel_timer(loop)
      es = nil
    end

    # Async Rack response
    es.rack_response
  
  else
    # Normal HTTP
    [200, {'Content-Type' => 'text/plain'}, ['Hello']]
  end
end

Just like WebSocket, EventSource is designed as a convenient wrapper around the Rack environment and underlying TCP connection that deals with the wire protocol and connection details for you. It tries not to make any assumptions or force constraints on your application design. There are a lot of WebSocket libraries around whose interfaces look more like Rails controllers; black-box Rack components or full-stack servers that hide the socket object and force you respond to WebSockets on one endpoint, and normal HTTP on another. Faye needs to be able to speak many different transport protocols over a single endpoint, which is why this library is designed to be usable inside any Rack adapter while leaving routing decisions up to you.

The benefit of interacting with the sockets as first-class objects is that you can pass them to other parts of your application, which can deal with them as a simple abstraction. For example, if your application just needs to push data to the client, as many WebSocket apps do, you can maintain a socket pool full of objects that respond to send(). When the application wants to push data, it selects the right connection and calls send() on it, without worrying whether it’s a WebSocket or EventSource connection. This gives you some flexibility around which transport your client uses.

The Node API to this is very similar and both are fully documented on GitHub: Ruby docs, Node docs.

The final big change is that the Ruby version now works under a broader range of web servers; it now supports Rack apps running under Thin, Rainbows and Goliath. Hopefully, providing a portable socket implementation that’s easy to drop into any Rack app will open up possibilities for more portable async app frameworks, decoupling the application from the network transport just as Rack did for HTTP. faye-websocket extracted its initial Thin and Rainbows adapters from the Cramp project, and there’s a chance Cramp can now remove its WebSocket code and rely on a simple abstraction for binding the app framework to the web.

As usual, download from Rubygems and npm, and get on the Faye mailing list if you have problems.

I’ve just released the 0.2 version of faye-websocket for Ruby and Node. This release benefits from the fact that the SockJS project is now using faye-websocket to handle WebSocket connections; my thanks to them for finding the performance bugs and missing features that went into making this release.

The biggest difference in this release is performance. In 0.1, the Node version had a rather interesting performance profile and was pretty slow. We’ve now made a bunch of optimisations that give it a more predictable performance profile across message sizes, and increases performance across the range by orders of magnitude.

The following benchmarks were produced using the ws client to send 1000 messages of various sizes to an echo server:

Benchmarks for Node 0.6.6

On Ruby, the change is not so dramatic but for most message sizes performance is improved by at least a factor of 2. This is in part achieved by writing part of the parser in C; this being my first Ruby C extension there may be problems with it so please get on the mailing list if you find any.

Benchmarks for Ruby 1.9.3

There is one new feature in the form of Sec-WebSocket-Protocol support. With the latest WebSocket protocol, the one currently shipping in Chrome and Firefox, you can specify which application protocol(s) you want to use over the socket, for example:

// client-side
var ws = new WebSocket('ws://example.com/', ['irc', 'xmpp']);

On the server side, you can specify which protocols the server supports and the first of these that matches a protocol supported by the client will be selected and sent back to the client as part of the handshake.

// server-side
var ws = new WebSocket(request, socket, head, ['bayeux', 'irc']);
ws.protocol // -> 'irc'

I’m really pleased with the progress on this project since decoupling it from Faye, and stoked that SockJS has adopted it. They’ve helped me improve things a great deal just in the last few days and it’s great to know these changes will go into making Faye faster.

While announcing last week’s release of Faye 0.7, I mentioned a couple of things: first, Faye now exposes its WebSocket APIs for everyone to use, and second that I planned to extract some components in order to slim Faye down for the 0.8 release.

Well the first step in that process is now done, and faye-websocket packages are now available for Node and Ruby, installable using npm install faye-websocket and gem install faye-websocket respectively. This process has already shrunk the Faye codebase by over 2,300 LOC but I suppose you’re still wondering why we need another WebSocket library.

It was never my intention to turn Faye into a plain-WebSocket project. I just implemented enough of the protocol to get Faye working, and left it at that. But recently I’ve taken a look around at the other packages for both Node and Ruby, and it turns out pretty much all of them suffer from at least one of the following problems:

• They do not implement the WebSocket protocol either completely or correctly.
• Their WebSocket components are too tightly coupled to other concerns.
• They do not implement the WebSocket API.

The first is a simple matter of maintenance; I could contribute patches to projects to make them work. And it turns out you can’t take a piecemeal approach to implementing wire protocols, you need to deal with whatever might come your way. This is the Internet, after all. I found several libraries where sending them totally valid WebSocket data causes them to crash, simply because they are incomplete.

The second is somewhat trickier, depending on the nature of the project. Some projects are simple WebSocket implementations. Some are transport abstractions aiming to provide a socket-like interface on top of other protocols. And some are full-blown messaging systems with semantics over and above those provided by WebSockets. Faye falls into the latter camp, although its WebSocket code has always been decoupled from the rest of the codebase.

The third is harder to fix, though. If you change the API for a project, you affect all its users. Its author probably has reasons for the API they picked, reasons you weren’t privy to when examining potential use cases. Patches that change the user-facing API of a library are much less likely to be accepted.

But the problem posed by non-standard APIs is, to me, quite serious. The Web Standards movement came about because web developers wanted to write portable code, and have a reasonable expectation of that code working when delivered to users. The WebSocket API is part of that same effort, to provide Web authors with standard interfaces to code against in order to produce portable software. As I have ranted about at length before, ignorance of code portability constitutes a missed opportunity for anyone developing Node programs.

Every time somebody invents a new API for a standard piece of Web infrastructure, they make everyone else’s code less portable. The aim with faye-websocket is to keep the standard WebSocket API so that code developed for the browser can be reused on the server. For example, the Faye pub/sub messaging client uses a ‘transport’ object to send messages to the server; there’s a transport based on XMLHttpRequest, one based on JSON-P, one based on Node’s HTTP library, and one based on WebSockets. If using an HTTP transport, one must pick whether to use XMLHttpRequest or Node HTTP, based on the environment. With WebSockets, we can reuse the same transport class on the server and in the browser, because Faye’s WebSockets have the same API you get in the browser. This means less code to write, and more code you can automatically test from the command line.

And this doesn’t just apply to WebSocket clients. After the handshake, the WebSocket protocol is symmetric: both peers can send and receive messages with the same protocol operating in both directions. It seems to me that any code based on WebSockets ought to be equally happy handling a server-side connection or a client-side one, since both ends of the connection have exactly the same capabilities. For this reason, faye-websocket wraps server-side connections with the standard API:

var WebSocket = require('faye-websocket'),
    http      = require('http'),
    server    = http.createServer();

server.addListener('upgrade', function(request, socket, head) {
  var ws = new WebSocket(request, socket, head);
  
  ws.onmessage = function(event) {
    ws.send(event.data);
  };
  
  ws.onclose = function(event) {
    console.log('close', event.code, event.reason);
    ws = null;
  };
});

server.listen(8000);

Server-side connections transparently select between draft-75, draft-76 or hybi-07-compatible protocols and handle text, binary, ping/pong, close and fragmented messages. The client is hybi-08, but has been tested up to version 17.

Of course, nothing is ever perfect on the first release but faye-websocket does have one of the most complete protocol implementations around, and I’d like to see more implementations adopt the standard API. The standard interfaces might not be to your taste, but they benefit the ecosystem by giving everyone a predictable playing field. If you maintain a WebSocket project, please test it using the Autobahn test suite (here are Faye’s server and client results) and consider exposing the standard API to your users.

I’m very excited to announce the release of Faye 0.7, available now through gem and npm. This release focuses on two main areas: new event APIs for hooking into the framework, and a polished stand-alone WebSocket implementation.

Let’s deal with the new APIs first. The main one is an API for listening to what’s going on inside the engine. People have historically used extensions for various sorts of monitoring but there are certain events extensions can’t catch. For example, when a client session ends due to inactivity rather than because the client sent a /meta/disconnect message, there’s no way to detect that. Well now you can:

var bayeux = new Faye.NodeAdapter({mount: '/faye', timeout: 45});

bayeux.bind('disconnect', function(clientId) {
  // event listener logic
});

There’s a complete API for listening to all the major events in Faye’s pub/sub model, and I encourage you to use it over extensions if all you want is a little monitoring.

The second new event API is on the client side. Faye will always attempt to reconnect for you if the network connection is dropped, but often it’s useful to signal the connection loss to the user. You can now do this using these events on the client:

client.bind('transport:down', function() {
  // Fires when the connection is lost
});
client.bind('transport:up', function() {
  // Fires when the connection is established
});

You don’t need to reconnect the client yourself, these events are just there to notify you of what’s going on. And to give you even more feedback, publish() now supports the same Deferrable API as subscribe().

Now onto the WebSocket changes. The first of which is that Faye now includes a WebSocket client, and will use this instead of HTTP for server-side clients. The server-side HTTP transports now support cookies, and all transports support SSL. The WebSocket stack has received a lot of bug fixes based on the Autobahn test suite, and is now one of the most complete WebSocket implementations available for Node or Ruby. (Want proof? Here’s the server and client test report.)

Faye’s WebSocket stack also has the advantage of having been reasonably decoupled from the rest of the codebase since it was first introduced in version 0.5, and now I’ve taken the decision to open it up for everyone to use. It makes adding WebSocket support to existing Node and Rack apps very easy indeed; you can drop sockets right into your existing application and they expose the same API you use in the browser:

var http = require('http'),
    faye = require('faye');

var server = http.createServer();

server.addListener('upgrade', function(request, socket, head) {
  var ws = new faye.WebSocket(request, socket, head);

  ws.onmessage = function(event) {
    ws.send(event.data);
  };

  ws.onclose = function(event) {
    console.log('close', event.code, event.reason);
    ws = null;
  };
});

server.listen(8000);

The sockets implement the standard WebSocket API on both the server- and client-side. They handle text and binary data, and transparently handle ping/pong, close, and fragmented messages for you. The server supports a wide range of protocol versions and the client should be able to talk to any modern WebSocket server.

If, however, you don’t want to use WebSockets for your Faye client, you can easily switch them off:

client.disable('websocket');

I think the WebSocket tools are important because while there are plenty of messaging frameworks and transport abstractions around (e.g. libraries that present the WebSocket API on top of other wire transports), the state of pure WebSocket implementations seems to be somewhat lacking at the moment. Hopefully this can improve the situation as we move towards broader socket support across the web.

So that’s about it for the 0.7 release. Work is already underway on the 0.8 release, and the current plan is to focus on refactoring. The Faye distribution contains several components, such as the WebSocket code and the Redis backend, that can be broken off into separate projects. Indeed, work is already underway on extracting the WebSocket code for Ruby. As usual, this release should be backward compatible but if you have problems don’t hesitate to post on the mailing list.