faye-websocket 0.2.0 → 0.3.0

data/CHANGELOG.txt

@@ -1,3 +1,9 @@
+=== 0.3.0 / 2012-01-13
+
+* Add support for EventSource connections
+* Support the Thin, Rainbows and Goliath web servers
+
+
 === 0.2.0 / 2011-12-21
 
 * Add support for Sec-WebSocket-Protocol negotiation

data/README.rdoc

@@ -4,9 +4,21 @@ This is a robust, general-purpose WebSocket implementation extracted from the
 {Faye}[http://faye.jcoglan.com] project. It provides classes for easily building
 WebSocket servers and clients in Ruby. It does not provide a server itself, but
 rather makes it easy to handle WebSocket connections within an existing
-{Rack}[http://rack.rubyforge.org/] application running under
-{Thin}[http://code.macournoyer.com/thin/]. It does not provide any abstraction
-other than the standard {WebSocket API}[http://dev.w3.org/html5/websockets/].
+{Rack}[http://rack.rubyforge.org/] application. It does not provide any
+abstraction other than the standard
+{WebSocket API}[http://dev.w3.org/html5/websockets/].
+
+It also provides an abstraction for handling {EventSource}[http://dev.w3.org/html5/eventsource/]
+connections, which are one-way connections that allow the server to push data to
+the client. They are based on streaming HTTP responses and can be easier to
+access via proxies than WebSockets.
+
+Currently, the following web servers are supported, and can be accessed directly
+or via HAProxy:
+
+* {Thin}[http://code.macournoyer.com/thin/]
+* {Rainbows}[http://rainbows.rubyforge.org/] using EventMachine
+* {Goliath}[http://postrank-labs.github.com/goliath/]
 
 The server-side socket can process {draft-75}[http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-75],
 {draft-76}[http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76],
@@ -16,19 +28,18 @@ supports both +text+ and +binary+ messages, and transparently handles +ping+,
 +pong+, +close+ and fragmented messages.
 
 
-== Accepting WebSocket connections in Rack
+== Handling WebSocket connections in Rack
 
-You can handle WebSockets on the server side by listening for HTTP Upgrade
-requests, and creating a new socket for the request. This socket object exposes
-the usual WebSocket methods for receiving and sending messages. For example this
-is how you'd implement an echo server:
+You can handle WebSockets on the server side by listening for requests using the
+<tt>Faye::WebSocket.websocket?</tt> method, and creating a new socket for the
+request. This socket object exposes the usual WebSocket methods for receiving
+and sending messages. For example this is how you'd implement an echo server:
 
+    # app.rb
     require 'faye/websocket'
-    require 'rack'
-    require 'eventmachine'
     
-    app = lambda do |env|
-      if env['HTTP_UPGRADE']
+    App = lambda do |env|
+      if Faye::WebSocket.websocket?(env)
         ws = Faye::WebSocket.new(env)
         
         ws.onmessage = lambda do |event|
@@ -40,27 +51,33 @@ is how you'd implement an echo server:
           ws = nil
         end
         
-        # Thin async response
-        [-1, {}, []]
+        # Return async Rack response
+        ws.rack_response
         
       else
         # Normal HTTP request
         [200, {'Content-Type' => 'text/plain'}, ['Hello']]
       end
     end
-    
-    EM.run {
-      thin = Rack::Handler.get('thin')
-      thin.run(app, :Port => 9292)
-    }
+
+This is a standard Rack app, so it can be run using a <tt>config.ru</tt> file.
+However, so that incoming requests can be properly prepared to process WebSocket
+connections, you need to tell <tt>Faye::WebSocket</tt> which adapter to load;
+this can be either +thin+, +rainbows+ or +goliath+. If one of these servers is
+already loaded before <tt>faye/websocket</tt> is loaded, it will load
+appropriate adapters automatically.
+
+    # config.ru
+    require './app'
+    Faye::WebSocket.load_adapter('thin')
+    run App
 
 
 == Using the WebSocket client
 
 The client supports both the plain-text +ws+ protocol and the encrypted +wss+
 protocol, and has exactly the same interface as a socket you would use in a web
-browser. On the wire it identifies itself as hybi-13, though it's compatible
-with servers speaking later versions of the protocol.
+browser. On the wire it identifies itself as hybi-13.
 
     require 'faye/websocket'
     require 'eventmachine'
@@ -125,15 +142,183 @@ messages.
   the other peer.
 * <b><tt>close(code, reason)</tt></b> closes the connection, sending the given
   status code and reason text, both of which are optional.
-* <b><tt>protocol</tt></b> is a string or +nil+ identifying the subprotocol th
-  socket is using.
+* <b><tt>protocol</tt></b> is a string (which may be empty) identifying the
+  subprotocol the socket is using.
+
+
+== Handling EventSource connections in Rack
+
+EventSource connections provide a very similar interface, although because they
+only allow the server to send data to the client, there is no +onmessage+ API.
+EventSource allows the server to push text messages to the client, where each
+message has an optional event-type and ID.
+
+    # app.rb
+    require 'faye/websocket'
+    
+    App = lambda do |env|
+      if Faye::EventSource.eventsource?(env)
+        es = Faye::EventSource.new(env)
+        p [:open, es.url, es.last_event_id]
+        
+        # Periodically send messages
+        loop = EM.add_periodic_timer(1) { es.send('Hello') }
+        
+        es.onclose = lambda do |event|
+          EM.cancel_timer(loop)
+          es = nil
+        end
+        
+        # Return async Rack response
+        es.rack_response
+        
+      else
+        # Normal HTTP request
+        [200, {'Content-Type' => 'text/plain'}, ['Hello']]
+      end
+    end
+
+The +send+ method takes two optional parameters, <tt>:event</tt> and
+<tt>:id</tt>. The default event-type is <tt>'message'</tt> with no ID. For
+example, to send a +notification+ event with ID +99+:
+
+    es.send('Breaking News!', :event => 'notification', :id => '99')
+
+The +EventSource+ object exposes the following properties:
+
+* <b><tt>url</tt></b> is a string containing the URL the client used to create
+  the EventSource.
+* <b><tt>last_event_id</tt></b> is a string containing the last event ID
+  received by the client. You can use this when the client reconnects after a
+  dropped connection to determine which messages need resending.
+
+When you initialize an EventSource with <tt>Faye::EventSource.new</tt>, you can
+pass configuration options after the +env+ parameter. Available options are:
+
+* <b><tt>:retry</tt></b> is a number that tells the client how long (in seconds)
+  it should wait after a dropped connection before attempting to reconnect.
+* <b><tt>:ping</tt></b> is a number that tells the server how often (in seconds)
+  to send 'ping' packets to the client to keep the connection open, to defeat
+  timeouts set by proxies. The client will ignore these messages.
+
+For example, this creates a connection that pings every 15 seconds and is
+retryable every 10 seconds if the connection is broken:
+
+    es = Faye::EventSource.new(es, :ping => 15, :retry => 10)
+
+
+== Running your socket application
+
+To use this library you must be using an EventMachine-based server; currently
+Thin, Rainbows and Goliath are supported.
+
+
+=== Running the app with Thin
+
+Thin can be started via the command line if you've set up a <tt>config.ru</tt>
+file for your application:
+
+    thin start -R config.ru -p 9292
+
+Or, you can use +rackup+. In development mode, this adds middlewares that don't
+work with async apps, so you must start it in production mode:
+
+    rackup config.ru -s thin -E production -p 9292
+
+It can also be started using the <tt>Rack::Handler</tt> interface common to many
+Ruby servers. It must be run using EventMachine, and you can configure Thin
+further in a block passed to +run+:
+
+    require 'eventmachine'
+    require 'rack'
+    require 'thin'
+    require './app'
+    
+    EM.run {
+      thin = Rack::Handler.get('thin')
+      
+      thin.run(App, :Port => 9292) do |server|
+        # You can set options on the server here, for example to set up SSL:
+        server.ssl_options = {
+          :private_key_file => 'path/to/ssl.key',
+          :cert_chain_file  => 'path/to/ssl.crt'
+        }
+        server.ssl = true
+      end
+    }
+
+
+=== Running the app with Rainbows
+
+<tt>Faye::WebSocket</tt> can only be run using EventMachine. To begin with,
+you'll need a Rainbows config file that tells it to use EventMachine, along with
+whatever Rainbows/Unicorn configuration you require.
+
+    # rainbows.conf
+    Rainbows! do
+      use :EventMachine
+    end
+
+You can then run your <tt>config.ru</tt> file from the command line. Again,
+<tt>Rack::Lint</tt> will complain unless you put the application in production
+mode.
+
+    rainbows config.ru -c path/to/rainbows.conf -E production -p 9292
+
+Rainbows also has a Ruby API for starting a server:
+
+    require 'rainbows'
+    require './app'
+    
+    rackup = Unicorn::Configurator::RACKUP
+    rackup[:port] = 9292
+    rackup[:set_listener] = true
+    options = rackup[:options]
+    options[:config_file] = 'path/to/rainbows.conf'
+    
+    server = Rainbows::HttpServer.new(App, options)
+    
+    # This is non-blocking; use server.start.join to block
+    server.start
+
+
+=== Running the app with Goliath
+
+Goliath can be made to run arbitrary Rack apps by delegating to them from a
+<tt>Goliath::API</tt> instance. A simple server looks like this:
+
+    require 'goliath'
+    require './app'
+    
+    class EchoServer < Goliath::API
+      def response(env)
+        App.call(env)
+      end
+    end
+
+<tt>Faye::WebSocket</tt> can also be used inline within a Goliath app:
+
+    require 'goliath'
+    require 'faye/websocket'
+    
+    class EchoServer < Goliath::API
+      def response(env)
+        ws = Faye::WebSocket.new(env)
+        
+        ws.onmessage = lambda do |event|
+          ws.send(event.data)
+        end
+        
+        ws.rack_response
+      end
+    end
 
 
 == License
 
 (The MIT License)
 
-Copyright (c) 2009-2011 James Coglan
+Copyright (c) 2009-2012 James Coglan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the 'Software'), to deal in

data/examples/app.rb

@@ -0,0 +1,50 @@
+require File.expand_path('../../lib/faye/websocket', __FILE__)
+require 'rack'
+
+static = Rack::File.new(File.dirname(__FILE__))
+
+App = lambda do |env|
+  if Faye::WebSocket.websocket?(env)
+    ws = Faye::WebSocket.new(env, ['irc', 'xmpp'])
+    p [:open, ws.url, ws.version, ws.protocol]
+    
+    ws.onmessage = lambda do |event|
+      ws.send(event.data)
+    end
+    
+    ws.onclose = lambda do |event|
+      p [:close, event.code, event.reason]
+      ws = nil
+    end
+    
+    ws.rack_response
+  
+  elsif Faye::EventSource.eventsource?(env)
+    es   = Faye::EventSource.new(env)
+    time = es.last_event_id.to_i
+    
+    p [:open, es.url, es.last_event_id]
+    
+    loop = EM.add_periodic_timer(2) do
+      time += 1
+      es.send("Time: #{time}")
+      EM.add_timer(1) do
+        es.send('Update!!', :event => 'update', :id => time) if es
+      end
+    end
+    
+    es.send("Welcome!\n\nThis is an EventSource server.")
+    
+    es.onclose = lambda do |event|
+      EM.cancel_timer(loop)
+      p [:close, es.url]
+      es = nil
+    end
+    
+    es.rack_response
+  
+  else
+    static.call(env)
+  end
+end
+

data/examples/config.ru

@@ -0,0 +1,17 @@
+# Run using your favourite async server:
+# 
+#     thin start -R examples/config.ru -p 7000
+#     rainbows -c spec/rainbows.conf -E production examples/config.ru -p 7000
+# 
+# If you run using one of these commands, the webserver is loaded before this
+# file, so Faye::WebSocket can figure out which adapter to load. If instead you
+# run using `rackup`, you need the `load_adapter` line below.
+# 
+#     rackup -E production -s thin examples/config.ru -p 7000
+
+require 'rubygems'
+require File.expand_path('../app', __FILE__)
+# Faye::WebSocket.load_adapter('thin')
+
+run App
+

data/examples/server.rb

@@ -1,43 +1,44 @@
 require 'rubygems'
-require File.expand_path('../../lib/faye/websocket', __FILE__)
-require 'rack'
-require 'eventmachine'
+require 'rack/content_length'
+require 'rack/chunked'
 
 port   = ARGV[0] || 7000
 secure = ARGV[1] == 'ssl'
+engine = ARGV[2] || 'thin'
+spec   = File.expand_path('../../spec', __FILE__)
 
-static = Rack::File.new(File.dirname(__FILE__))
+require File.expand_path('../app', __FILE__)
+Faye::WebSocket.load_adapter(engine)
 
-app = lambda do |env|
-  if env['HTTP_UPGRADE']
-    socket = Faye::WebSocket.new(env, ['irc', 'xmpp'])
-    p [:open, socket.url, socket.version, socket.protocol]
-    
-    socket.onmessage = lambda do |event|
-      socket.send(event.data)
-    end
-    
-    socket.onclose = lambda do |event|
-      p [:close, event.code, event.reason]
-      socket = nil
+case engine
+
+when 'goliath'
+  class WebSocketServer < Goliath::API
+    def response(env)
+      App.call(env)
     end
-    
-    [-1, {}, []]
-  else
-    static.call(env)
   end
-end
 
-EM.run {
-  thin = Rack::Handler.get('thin')
-  thin.run(app, :Port => port) do |server|
-    if secure
-      server.ssl = true
-      server.ssl_options = {
-        :private_key_file => File.expand_path('../../spec/server.key', __FILE__),
-        :cert_chain_file  => File.expand_path('../../spec/server.crt', __FILE__)
-      }
+when 'rainbows'
+  rackup = Unicorn::Configurator::RACKUP
+  rackup[:port] = port
+  rackup[:set_listener] = true
+  options = rackup[:options]
+  options[:config_file] = spec + '/rainbows.conf'
+  Rainbows::HttpServer.new(App, options).start.join
+
+when 'thin'
+  EM.run {
+    thin = Rack::Handler.get('thin')
+    thin.run(App, :Port => port) do |server|
+      if secure
+        server.ssl_options = {
+          :private_key_file => spec + '/server.key',
+          :cert_chain_file  => spec + '/server.crt'
+        }
+        server.ssl = true
+      end
     end
-  end
-}
+  }
+end
 

data/examples/sse.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html>
+  <head>
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
+    <title>EventSource test</title>
+  </head>
+  <body>
+    
+    <h1>EventSource test</h1>
+    <ul></ul>
+    
+    <script type="text/javascript">
+      var logger = document.getElementsByTagName('ul')[0],
+          socket = new EventSource('/');
+      
+      var log = function(text) {
+        logger.innerHTML += '<li>' + text + '</li>';
+      };
+      
+      socket.onopen = function() {
+        log('OPEN');
+      };
+      
+      socket.onmessage = function(event) {
+        log('MESSAGE: ' + event.data);
+      };
+      
+      socket.addEventListener('update', function(event) {
+        log('UPDATE(' + event.lastEventId + '): ' + event.data);
+      });
+      
+      socket.onerror = function(event) {
+        log('ERROR: ' + event.message);
+      };
+    </script>
+    
+  </body>
+</html>
+