Puggernaut

Simple server push implementation using eventmachine and long polling.

Requirements

gem install puggernaut

How it works

Puggernaut consists of four pieces:

• TCP client to send push messages
• TCP server to receive push messages
• TCP server to deliver messages via WebSockets (em-websocket)
• HTTP server to deliver messages via long poll

Start it up

Run the puggernaut binary with optional port numbers:

puggernaut <http port> <tcp port> <tcp port (websocket)>

The default HTTP and TCP ports are 8100, 8101, and 8102, respectively.

Set up proxy pass

Set up a URL on your public facing web server that points to the Puggernaut HTTP server (long poll).

We all use Nginx, right?

nginx.conf

server {
    location /long_poll {
      proxy_pass http://localhost:8100/;
    }
}

Send push messages

require 'puggernaut'

client = Puggernaut::Client.new("localhost:8101", "localhost:9101")
client.push :channel => "message"
client.push :channel => [ "message 1", "message 2" ], :channel_2 => "message"

The Client.new initializer accepts any number of TCP server addresses.

Receive push messages

Include jQuery and puggernaut.js into to your HTML page.

Javascript client example:

Puggernaut.path = '/long_poll'; // (default long poll path)
Puggernaut.port = 8102;         // (default WebSocket port)

Puggernaut
  .watch('channel', function(e, message) {
    // do something with message
  })
  .watch('channel_2', function(e, message) {
    // do something with message
  });

Puggernaut.unwatch('channel');

Running specs

Specs are a work in progress, though we can vouch for some of the functionality :).

Set up Nginx to point to a cloned copy of this project:

nginx.conf

server {
    listen 80;
    server_name localhost;
    root /Users/me/puggernaut/public;
    passenger_enabled on;
    
    location /long_poll {
        proxy_pass http://localhost:8100/;
    }
}

You have now set up an instance of Puggernaut's spec server.

Start up an instance of Puggernaut by running bin/puggernaut.

When you visit http://localhost you will find a page that executes QUnit specs.