The Server

In case you're wondering, the Firehose application server runs the Rack app Firehose::Rack::App.new inside of Thin or Rainbows! Firehose::Rack::App consists of a bunch of smaller apps and a middleware, which is useful for hacking.

Yeah, so?

You have a dirt simple HTTP pub-sub feed. You could setup an after_commit hook on ActiveRecord to push JSON to an end-point. On the other side, you could have a Backbone.js application that picks up the changes and updates the client-side UI.

Holy mackerel! Its a nice, clean, RESTful way to build real-time web applications.

The JavaScript Consumer

Firehose doesn't just stop at curl; it has a full-featured JavaScript client that lets you subscribe to channels for live updates.

Still have the server running? Copy and paste the code below into Firebug or the WebKit console.

There's also a Consumer that uses channel multiplexing.
The multiplexed consumer is useful for scenarios where you want to subscribe
to messages from many channels at once, without having to use one connection
per channel. You can specify a list of channels to subscribe to, including a
handler function per channel that gets called with all messages coming from that
channel.

How is it different from socket.io?

Also, socket.io attempts to abstract a low-latency full-duplex port. Firehose assumes that its impossible to simulate this in older web browsers that don't support WebSockets. As such, Firehose focuses on low-latency server-to-client connections and encourages the use of existing HTTP transports, like POST and PUT, for client-to-server communications.

The Ruby Publisher

While you can certainly make your own PUT requests when publishing messages, Firehose includes a Ruby client for easy publishing.

Configuration

Firehose can be configured via environmental variables. Take a look at the .env.sample file for more info.

Rack Configuration

There are two rack applications that are included with Firehose: Firehose::Rack::Producer which a client can PUT HTTP request with message payloads to publish information on Firehose and the Firehose::Rack::Consumer application which a client connects to via HTTP long polling or WebSockets to consume a message.

Consumer Configuration

# Kitchen-sink rack configuration file examplerequire'firehose'
consumer =Firehose::Rack::Consumer.newdo |app|
# Configure how long the server should wait before send the client a 204# with a request to reconnect. Typically browsers time-out the client connection# after 30 seconds, so we set the `Firehose.Consumer` JS client to 25, and the# server to 20 to make sure latency or timing doesn't cause any problems.
app.http_long_poll.timeout =20end
run consumer

Publisher Configuration

# Kitchen-sink rack configuration file examplerequire'firehose'# There's nothing to configure with the Publisher, but its possible that# you might include rack middleware authorization mechanisms here to control# who can publish to Firehose.
run Firehose::Rack::Publisher.new

Sprockets

Using Sprockets is the recommended method of including the included client-side assets in a web page.

Add the firehose gem in your app's Gemfile.

Append the firehose gem's assets to the sprockets path. In a Rails app, this is usually done in an initializer.

Not using sprockets?

If you don't intend to use the Firehose JavaScript client in a Ruby stack where Sprockets is available, you can grab the unminified source by running:

$ firehose javascript > firehose.js

Copy the firehose.js where needed in your project.

Web Server

Firehose currently supports Thin and Rainbows! (which is the default). Neither is listed as a dependency in the gemspec so that you don't need to install whichever one you aren't using. You can set which server to use via the .env file (recommended) or with the -s option to bin/firehose.

Exception Notification

If you'd like to be notified of exceptions, add something like this in your custom config.ru file.