faye 0.1.0

data/History.txt

@@ -0,0 +1 @@
+

data/Jakefile

@@ -0,0 +1,2 @@
+require File.join('lib', 'faye')
+

data/Manifest.txt

@@ -0,0 +1,33 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+jake.yml
+Jakefile
+client/util/class.js
+client/util/event.js
+client/util/json.js
+client/util/uri.js
+client/util/xhr.js
+client/faye.js
+client/transport.js
+client/client.js
+client/channel.js
+lib/faye-min.js
+lib/faye.rb
+lib/faye/channel.rb
+lib/faye/connection.rb
+lib/faye/error.rb
+lib/faye/grammar.rb
+lib/faye/rack_adapter.rb
+lib/faye/server.rb
+examples/soapbox/README
+examples/soapbox/app.rb
+examples/soapbox/config.ru
+examples/soapbox/public/jquery.js
+examples/soapbox/public/soapbox.js
+examples/soapbox/public/style.css
+examples/soapbox/views/index.erb
+test/test_channel.rb
+test/test_grammar.rb
+test/test_server.rb

data/README.txt

@@ -0,0 +1,111 @@
+= Faye
+
+* http://github.com/jcoglan/faye
+
+Faye is an implementation of the Bayeux protocol in Ruby. It includes a
+server backend and an adapter for Rack, and a self-contained JavaScript
+client. Bayeux is a protocol designed to facilitate Comet, also known as
+'server push' or 'Ajax push', a technique for pushing messages from the
+server to the client to minimize latency.
+
+NOTE this is not currently intended for large-scale use. It is being
+developed mostly as a tool for scripting multiple browsers and automating
+JavaScript testing. However, use of a well-known protocol should allow
+it to be repurposed fairly easily.
+
+
+== Usage
+
+Faye can be installed as middleware in front of any Rack application. For
+example, here's a <tt>config.ru</tt> for running it with Sinatra:
+
+  require 'rubygems'
+  require 'faye'
+  require 'sinatra'
+  require 'path/to/sinatra/app'
+  
+  use Faye::RackAdapter, :mount   => '/comet',
+                         :timeout => 30
+  
+  run Sinatra::Application
+
+This starts a Comet endpoint at <tt>http://localhost:9292/comet</tt> with
+the client script at <tt>http://localhost:9292/comet.js</tt>. The +timeout+
+option sets how long (in seconds) a long-polling request will wait before
+timing out; this must be less than the timeout set on your frontend web server
+so that the Comet server can send a response before Apache (for example)
+closes the connection.
+
+In your front-end code, set up the client as follows:
+
+  <script type="text/javascript" src="/comet.js"></script>
+  
+  <script type="text/javascript">
+      CometClient = new Faye.Client('/comet');
+      CometClient.connect();
+  </script>
+
+This client object can then be used to publish and subscribe to named
+channels as follows:
+
+  CometClient.subscribe('/path/to/channel', function(message) {
+      // process received message
+  });
+  
+  CometClient.publish('/some/other/channel', {foo: 'bar'});
+
+You can publish arbitrary JavaScript objects to a channel, and the object will
+be transmitted as the +message+ parameter to any subscribers to that channel.
+Channel names must be formatted as absolute path names as shown. Channels
+beginning with <tt>/meta/</tt> are reserved for use by the messaging protocol
+and may not be subscribed to.
+
+
+== Examples
+
+See demo apps in +examples+. If you've checked this out from the repo rather than
+installing the gem you will need to build the JavaScript client from source, this
+is done as follows:
+
+  sudo gem install jake
+  jake -f
+
+
+== To-do
+
+* Provide support for user-defined <tt>/service/*</tt> channels
+* Support Thin's async response
+* Allow server to scale to multiple nodes
+* Provide a server-side client
+* Console for scripting browsers from the command line
+
+
+== Installation
+
+  sudo gem install hoe faye
+
+
+== License
+
+(The MIT License)
+
+Copyright (c) 2009 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 the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,13 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/faye.rb'
+
+Hoe.spec('faye') do |p|
+  # p.rubyforge_name = 'fayex' # if different than lowercase project name
+  p.developer('James Coglan', 'jcoglan@googlemail.com')
+  p.extra_deps = %w[eventmachine rack json]
+end
+
+# vim: syntax=Ruby

data/client/channel.js

@@ -0,0 +1,135 @@
+Faye.Channel = {
+  HANDSHAKE:    '<%= Faye::Channel::HANDSHAKE %>',
+  CONNECT:      '<%= Faye::Channel::CONNECT %>',
+  SUBSCRIBE:    '<%= Faye::Channel::SUBSCRIBE %>',
+  UNSUBSCRIBE:  '<%= Faye::Channel::UNSUBSCRIBE %>',
+  DISCONNECT:   '<%= Faye::Channel::DISCONNECT %>',
+  
+  META:         '<%= Faye::Channel::META %>',
+  SERVICE:      '<%= Faye::Channel::SERVICE %>',
+  
+  isValid: function(name) {
+    return Faye.Grammar.CHANNEL_NAME.test(name) ||
+           Faye.Grammar.CHANNEL_PATTERN.test(name);
+  },
+  
+  parse: function(name) {
+    if (!this.isValid(name)) return null;
+    return name.split('/').slice(1);
+  },
+  
+  isMeta: function(name) {
+    var segments = this.parse(name);
+    return segments ? (segments[0] === this.META) : null;
+  },
+  
+  isService: function(name) {
+    var segments = this.parse(name);
+    return segments ? (segments[0] === this.SERVICE) : null;
+  },
+  
+  isSubscribable: function(name) {
+    if (!this.isValid(name)) return null;
+    return !this.isMeta(name) && !this.isService(name);
+  },
+  
+  Tree: Faye.Class({
+    initialize: function(value) {
+      this._value = value;
+      this._children = {};
+    },
+    
+    eachChild: function(block, context) {
+      Faye.each(this._children, function(key, subtree) {
+        block.call(context, key, subtree);
+      });
+    },
+    
+    each: function(prefix, block, context) {
+      this.eachChild(function(path, subtree) {
+        path = prefix.concat(path);
+        subtree.each(path, block, context);
+      });
+      if (this._value !== undefined) block.call(context, prefix, this._value);
+    },
+    
+    map: function(block, context) {
+      var result = [];
+      this.each([], function(path, value) {
+        result.push(block.call(context, path, value));
+      });
+      return result;
+    },
+    
+    get: function(name) {
+      var tree = this.traverse(name);
+      return tree ? tree._value : null;
+    },
+    
+    set: function(name, value) {
+      var subtree = this.traverse(name, true);
+      if (subtree) subtree._value = value;
+    },
+    
+    traverse: function(path, createIfAbsent) {
+      if (typeof path === 'string') path = Faye.Channel.parse(path);
+      
+      if (path === null) return null;
+      if (path.length === 0) return this;
+      
+      var subtree = this._children[path[0]];
+      if (!subtree && !createIfAbsent) return null;
+      if (!subtree) subtree = this._children[path[0]] = new Faye.Channel.Tree();
+      
+      return subtree.traverse(path.slice(1), createIfAbsent);
+    },
+    
+    glob: function(path) {
+      if (typeof path === 'string') path = Faye.Channel.parse(path);
+      
+      if (path === null) return [];
+      if (path.length === 0) return (this._value === undefined) ? [] : [this._value];
+      
+      var list = [];
+      
+      if (Faye.enumEqual(path, ['*'])) {
+        Faye.each(this._children, function(key, subtree) {
+          if (subtree._value !== undefined) list.push(subtree._value);
+        });
+        return list;
+      }
+      
+      if (Faye.enumEqual(path, ['**'])) {
+        list = this.map(function(key, value) { return value });
+        list.pop();
+        return list;
+      }
+      
+      Faye.each(this._children, function(key, subtree) {
+        if (key !== path[0] && key !== '*') return;
+        var sublist = subtree.glob(path.slice(1));
+        Faye.each(sublist, function(channel) { list.push(channel) });
+      });
+      
+      if (this._children['**']) list.push(this._children['**']._value);
+      return list;
+    }
+    
+    /**
+      Tests
+      
+      glob = new Faye.Channel.Tree();
+      list = '/foo/bar /foo/boo /foo /foobar /foo/bar/boo /foobar/boo /foo/* /foo/**'.split(' ');
+
+      Faye.each(list, function(c, i) {
+          glob.set(c, i + 1);
+      });
+
+      console.log(glob.glob('/foo/*').sort());        // 1,2,7,8
+      console.log(glob.glob('/foo/bar').sort());      // 1,7,8
+      console.log(glob.glob('/foo/**').sort());       // 1,2,5,7,8
+      console.log(glob.glob('/foo/bar/boo').sort());  // 5,8
+    **/
+  })
+};
+

data/client/client.js

@@ -0,0 +1,265 @@
+Faye.Client = Faye.Class({
+  _UNCONNECTED:   {},
+  _CONNECTING:    {},
+  _CONNECTED:     {},
+  _DISCONNECTED:  {},
+  
+  _HANDSHAKE:     'handshake',
+  _RETRY:         'retry',
+  _NONE:          'none',
+  
+  DEFAULT_ENDPOINT:   '<%= Faye::RackAdapter::DEFAULT_ENDPOINT %>',
+  MAX_DELAY:          <%= Faye::Connection::MAX_DELAY %>,
+  INTERVAL:           <%= Faye::Connection::INTERVAL * 1000 %>,
+  
+  initialize: function(endpoint) {
+    this._endpoint  = endpoint || this.DEFAULT_ENDPOINT;
+    this._transport = Faye.Transport.get(this);
+    this._state     = this._UNCONNECTED;
+    this._outbox    = [];
+    this._channels  = new Faye.Channel.Tree();
+    
+    this._advice = {reconnect: this._RETRY, interval: this.INTERVAL};
+    
+    Faye.Event.on(Faye.ENV, 'beforeunload', this.disconnect, this);
+  },
+  
+  // Request
+  // MUST include:  * channel
+  //                * version
+  //                * supportedConnectionTypes
+  // MAY include:   * minimumVersion
+  //                * ext
+  //                * id
+  // 
+  // Success Response                             Failed Response
+  // MUST include:  * channel                     MUST include:  * channel
+  //                * version                                    * successful
+  //                * supportedConnectionTypes                   * error
+  //                * clientId                    MAY include:   * supportedConnectionTypes
+  //                * successful                                 * advice
+  // MAY include:   * minimumVersion                             * version
+  //                * advice                                     * minimumVersion
+  //                * ext                                        * ext
+  //                * id                                         * id
+  //                * authSuccessful
+  handshake: function(callback, scope) {
+    if (this._advice.reconnect === this._NONE) return;
+    if (this._state !== this._UNCONNECTED) return;
+    
+    this._state = this._CONNECTING;
+    var self = this, id = this.generateId();
+    
+    this._transport.send({
+      channel:      Faye.Channel.HANDSHAKE,
+      version:      Faye.BAYEUX_VERSION,
+      supportedConnectionTypes: Faye.Transport.supportedConnectionTypes(),
+      id:           id
+      
+    }, function(response) {
+      if (response.id !== id) return;
+      
+      if (!response.successful) {
+        setTimeout(function() { self.handshake(callback, scope) }, this._advice.interval);
+        return this._state = this._UNCONNECTED;
+      }
+      
+      this._state     = this._CONNECTED;
+      this._clientId  = response.clientId;
+      this._transport = Faye.Transport.get(this, response.supportedConnectionTypes);
+      
+      if (callback) callback.call(scope);
+    }, this);
+  },
+  
+  // Request                              Response
+  // MUST include:  * channel             MUST include:  * channel
+  //                * clientId                           * successful
+  //                * connectionType                     * clientId
+  // MAY include:   * ext                 MAY include:   * error
+  //                * id                                 * advice
+  //                                                     * ext
+  //                                                     * id
+  //                                                     * timestamp
+  connect: function(callback, scope) {
+    if (this._advice.reconnect === this._NONE) return;
+    
+    if (this._advice.reconnect === this._HANDSHAKE || this._state === this._UNCONNECTED)
+      return this.handshake(function() { this.connect(callback, scope) }, this);
+    
+    if (this._state !== this._CONNECTED) return;
+    
+    if (this._connectionId) return;
+    this._connectionId = this.generateId();
+    var self = this;
+    
+    this._transport.send({
+      channel:        Faye.Channel.CONNECT,
+      clientId:       this._clientId,
+      connectionType: this._transport.connectionType,
+      id:             this._connectionId
+      
+    }, function(response) {
+      if (response.id !== this._connectionId) return;
+      delete this._connectionId;
+      
+      if (response.successful)
+        this.connect();
+      else
+        setTimeout(function() { self.connect() }, this._advice.interval);
+    }, this);
+    
+    if (callback) callback.call(scope);
+  },
+  
+  // Request                              Response
+  // MUST include:  * channel             MUST include:  * channel
+  //                * clientId                           * successful
+  // MAY include:   * ext                                * clientId
+  //                * id                  MAY include:   * error
+  //                                                     * ext
+  //                                                     * id
+  disconnect: function() {
+    if (this._state !== this._CONNECTED) return;
+    this._state = this._DISCONNECTED;
+    
+    this._transport.send({
+      channel:      Faye.Channel.DISCONNECT,
+      clientId:     this._clientId
+    });
+    
+    this._channels = new Faye.Channel.Tree();
+  },
+  
+  // Request                              Response
+  // MUST include:  * channel             MUST include:  * channel
+  //                * clientId                           * successful
+  //                * subscription                       * clientId
+  // MAY include:   * ext                                * subscription
+  //                * id                  MAY include:   * error
+  //                                                     * advice
+  //                                                     * ext
+  //                                                     * id
+  //                                                     * timestamp
+  subscribe: function(channels, callback, scope) {
+    if (this._state !== this._CONNECTED) return;
+    
+    channels = [].concat(channels);
+    this._validateChannels(channels);
+    
+    var id = this.generateId();
+    
+    this._transport.send({
+      channel:      Faye.Channel.SUBSCRIBE,
+      clientId:     this._clientId,
+      subscription: channels,
+      id:           id
+      
+    }, function(response) {
+      if (response.id !== id) return;
+      if (!response.successful) return;
+      
+      channels = [].concat(response.subscription);
+      Faye.each(channels, function(channel) {
+        this._channels.set(channel, [callback, scope]);
+      }, this);
+    }, this);
+  },
+  
+  // Request                              Response
+  // MUST include:  * channel             MUST include:  * channel
+  //                * clientId                           * successful
+  //                * subscription                       * clientId
+  // MAY include:   * ext                                * subscription
+  //                * id                  MAY include:   * error
+  //                                                     * advice
+  //                                                     * ext
+  //                                                     * id
+  //                                                     * timestamp
+  unsubscribe: function(channels, callback, scope) {
+    if (this._state !== this._CONNECTED) return;
+    
+    channels = [].concat(channels);
+    this._validateChannels(channels);
+    
+    var id = this.generateId();
+    
+    this._transport.send({
+      channel:      Faye.Channel.UNSUBSCRIBE,
+      clientId:     this._clientId,
+      subscription: channels,
+      id:           id
+      
+    }, function(response) {
+      if (response.id !== id) return;
+      if (!response.successful) return;
+      
+      channels = [].concat(response.subscription);
+      Faye.each(channels, function(channel) {
+        this._channels.set(channel, null);
+      }, this);
+    }, this);
+  },
+  
+  // Request                              Response
+  // MUST include:  * channel             MUST include:  * channel
+  //                * data                               * successful
+  // MAY include:   * clientId            MAY include:   * id
+  //                * id                                 * error
+  //                * ext                                * ext
+  publish: function(channel, data) {
+    if (this._state !== this._CONNECTED) return;
+    this._validateChannels([channel]);
+    
+    this.enqueue({
+      channel:      channel,
+      data:         data,
+      clientId:     this._clientId
+    });
+    
+    if (this._timeout) return;
+    var self = this;
+    
+    this._timeout = setTimeout(function() {
+      delete self._timeout;
+      self.flush();
+    }, this.MAX_DELAY * 1000);
+  },
+  
+  generateId: function(bitdepth) {
+    bitdepth = bitdepth || 32;
+    return Math.floor(Math.pow(2,bitdepth) * Math.random()).toString(16);
+  },
+  
+  enqueue: function(message) {
+    this._outbox.push(message);
+  },
+  
+  flush: function() {
+    this._transport.send(this._outbox);
+    this._outbox = [];
+  },
+  
+  _validateChannels: function(channels) {
+    Faye.each(channels, function(channel) {
+      if (!Faye.Channel.isValid(channel))
+        throw '"' + channel + '" is not a valid channel name';
+      if (!Faye.Channel.isSubscribable(channel))
+        throw 'Clients may not subscribe to channel "' + channel + '"';
+    });
+  },
+  
+  _handleAdvice: function(advice) {
+    Faye.extend(this._advice, advice);
+    if (this._advice.reconnect === this._HANDSHAKE) this._clientId = null;
+  },
+  
+  _sendToSubscribers: function(message) {
+    var channels = this._channels.glob(message.channel);
+    Faye.each(channels, function(callback) {
+      if (!callback) return;
+      callback[0].call(callback[1], message.data);
+    });
+  }
+});
+