faye-rails 1.0.0

data/README.md

@@ -0,0 +1,117 @@
+# faye-rails [![Build Status](https://secure.travis-ci.org/RLovelett/faye-rails.png)](http://travis-ci.org/RLovelett/faye-rails)
+
+faye-rails is a Ruby gem which handles embedding Faye's rack-based server into the rails stack and providing it with access to controllers and views based on bindings and observers.
+
+# Embedded server
+
+Due to the limitations of most Rack-based web servers available Faye can only be run on Thin, however if you are using thin, then you can add as many Faye servers as you want to the Rails router like so:
+
+    App::Application.routes.draw do
+      faye_server '/faye', :timeout => 25
+    end
+
+You can also pass a block to `faye_server` which will be executed in the context of the Faye server, thus you can call any methods on `Faye::RackAdapter` from within the block:
+
+    App::Application.routes.draw do
+      faye_server '/faye', :timeout => 25 do
+        class MockExtension
+          def incoming(message, callback)
+            callback.call(message)
+          end
+        end
+        add_extension(MockExtension.new)
+      end
+    end
+
+If you really want to, you can ask Faye to start it's own listening Thin server on an arbitrary port:
+
+    App::Application.routes.draw do
+      faye_server '/faye', :timeout => 25 do
+        listen(9292)
+      end
+    end
+
+You can also do some rudimentary routing using the map method:
+
+    App::Application.routes.draw do
+      faye_server '/faye', :timeout => 25 do
+        map '/widgets/**' => WidgetsController
+        map :default => :block
+      end
+    end
+
+You can find more details on the #map method in the [rdoc](http://rubydoc.info/github/jamesotron/faye-rails/master/FayeRails/RackAdapter)
+
+# Controller
+
+faye-rails includes a controller for handling the binding between model events and channels with it's own DSL for managing channel-based events.
+
+    class WidgetController < FayeRails::Controller
+    end
+
+## Model observers
+
+You can subscribe to changes in models using the controller's observer DSL:
+
+    class WidgetController < FayeRails::Controller
+      observe Widget, :after_create do |new_widget|
+        WidgetController.publish('/widgets', new_widget.attributes)
+      end
+    end
+
+The available callbacks are derived from the ActiveRecord callback stack. See [ActiveRecord::Callbacks](http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html) for more information regarding the callback queue.
+
+See the [rdoc](http://rubydoc.info/github/jamesotron/faye-rails/master/FayeRails/Controller.observe) for more information.
+
+## Channel DSL
+
+The controller DSL elegantly wraps channel-based aspects of the Faye API so that you can easily group code based on specific channels.
+
+### Monitoring
+
+You can make use of Faye's [monitoring API](http://faye.jcoglan.com/ruby/monitoring.html) by adding calls to `monitor` within the channel block. You are able to monitor `:subscribe`, `:unsubscribe` and `:publish` events. Blocks are executed within the context of a `FayeRails::Controller::Monitor` instance which will give you access to `#client_id`, `#channel` and `#data` (`#data` only having a value on `:publish` events).
+
+    class WidgetController < FayeRails::Controller
+      channel '/widgets' do
+        monitor :subscribe do
+          puts "Client #{client_id} subscribed to #{channel}."
+        end
+        monitor :unsubscribe do
+          puts "Client #{client_id} unsubscribed from #{channel}."
+        end
+        monitor :publish do
+          puts "Client #{client_id} published #{data.inspect} to #{channel}."
+        end
+      end
+    end
+
+### Filtering
+
+You can quickly and easily filter incoming and outgoing messages for your specific channel using the controller's filter API, which wraps Faye's [extensions API](http://faye.jcoglan.com/ruby/extensions.html) in a concise and channel-specific way.
+
+    class WidgetController < FayeRails::Controller
+      channel '/widgets' do
+        filter :in do
+          puts "Inbound message #{message}."
+          pass
+        end
+      end
+    end
+
+You can add filters for `:in`, `:out` and `:any`, which will allow you to filter messages entering the server, exiting the server or both. The block passed to the `filter` is executed in the context of a `FayeRails::Filter::DSL` instance, which gives you access to the `#message` method, which contains the entire message payload from the client (including meta information you wouldn't see other ways). You also have access to the `#pass`, `#modify`, `#block` and `#drop` methods which are sugar around Faye's callback system - which is accessible via the `#callback` method if you want to do it that way. Check out the [FayeRails::Filter::DSL rdoc](http://rubydoc.info/github/jamesotron/faye-rails/master/FayeRails/Filter/DSL) for more information.  Please note that all filters must call `callback.call` either via the sugar methods or directly to ensure that requests are not lost (not to mention potential memory leaks).
+
+### Subscribing
+
+You can easily subscribe to a channel using the 'subscribe' method inside your channel block, like so:
+
+    class WidgetController < FayeRails::Controller
+      channel '/widgets' do
+        subscribe do
+          puts "Received on channel #{channel}: #{message.inspect}"
+        end
+      end
+    end
+
+# Thanks.
+
+Thanks to James Coglan for the excellent Faye Bayeux implementetation and great support for Faye users.

data/lib/faye-rails.rb

@@ -0,0 +1,42 @@
+require 'faye'
+require 'faye-rails/version'
+require 'faye-rails/routing_hooks'
+require 'faye-rails/server_list'
+
+module FayeRails
+  ROOT = File.expand_path(File.dirname(__FILE__))
+
+  if defined? ::Rails
+    class Engine < ::Rails::Engine
+    end
+  end
+
+  autoload :Controller,        File.join(ROOT, 'faye-rails', 'controller')
+  autoload :RackAdapter,       File.join(ROOT, 'faye-rails', 'rack_adapter')
+  autoload :Filter,            File.join(ROOT, 'faye-rails', 'filter')
+
+  def self.servers
+    @servers ||= ServerList.new
+  end
+
+  def self.server(where=nil)
+    if where
+      servers.at(where).first
+    else
+      servers.first
+    end
+  end
+
+  def self.clients
+    servers.map(&:get_client)
+  end
+
+  def self.client(where=nil)
+    if where
+      servers.at(where).first.get_client
+    else
+      servers.first.get_client
+    end
+  end
+
+end

data/lib/faye-rails/controller.rb

@@ -0,0 +1,53 @@
+module FayeRails
+  class Controller
+    autoload :Channel, File.join(FayeRails::ROOT, 'faye-rails', 'controller', 'channel')
+    autoload :Monitor, File.join(FayeRails::ROOT, 'faye-rails', 'controller', 'monitor')
+    autoload :Message, File.join(FayeRails::ROOT, 'faye-rails', 'controller', 'message')
+    autoload :ObserverFactory, File.join(FayeRails::ROOT, 'faye-rails', 'controller', 'observer_factory')
+
+    attr :channels, :model
+
+    # Observe a model for any of the ActiveRecord::Callbacks
+    # as of v3.2.6 they are:
+    # before_validation
+    # after_validation
+    # before_save
+    # before_create
+    # after_create
+    # after_save
+    # after_commit
+    # http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html
+    # action defaults to after_create
+    def self.observe(model_klass, action = :after_create, &block)
+      # Dynamically create a new observe class
+      ObserverFactory.define(model_klass, action, &block)
+    end
+
+    def observe(model_klass, action = :after_create, &block)
+      # Dynamically create a new observe class
+      ObserverFactory.define(model_klass, action, &block)
+    end
+
+    # Bind a number of events to a specific channel.
+    def self.channel(channel, endpoint=nil, &block)
+      channel = Channel.new(channel, endpoint)
+      channel.instance_eval(&block)
+      (@channels ||= []) << channel
+    end
+
+    def channel(channel, endpoint=nil, &block)
+      channel = Channel.new(channel, endpoint)
+      channel.instance_eval(&block)
+      (@channels ||= []) << channel
+    end
+
+    def self.publish(channel, message, endpoint=nil)
+      FayeRails.client(endpoint).publish(channel, message)
+    end
+
+    def publish(channel, message, endpoint=nil)
+      self.class.publish(channel, message, endpoint)
+    end
+
+  end
+end

data/lib/faye-rails/controller/channel.rb

@@ -0,0 +1,61 @@
+module FayeRails
+  class Controller
+    class Channel
+
+      attr_reader :channel, :endpoint
+
+      def initialize(channel, endpoint=nil)
+        @channel = channel
+        @endpoint = endpoint
+      end
+
+      def client
+        FayeRails.client(endpoint)
+      end
+
+      def publish(message)
+        FayeRails.client(endpoint).publish(channel, message)
+      end
+
+      def monitor(event, &block)
+        raise ArgumentError, "Unknown event #{event.inspect}" unless [:subscribe,:unsubscribe,:publish].member? event
+
+        FayeRails.server(endpoint).bind(event) do |*args|
+          Monitor.new.tap do |m|
+            m.client_id = args.shift
+            m.channel = args.shift
+            m.data = args.shift
+            m.instance_eval(&block) if m.channel == channel
+          end
+        end
+      end
+
+      def filter(direction=:any, &block)
+        filter = FayeRails::Filter.new(channel, direction, block)
+        server = FayeRails.server(endpoint)
+        server.add_extension(filter)
+        filter.server = server
+        filter
+      end
+
+      def subscribe(&block)
+        EM.schedule do 
+          @subscription = FayeRails.client(endpoint).subscribe(channel) do |message|
+            Message.new.tap do |m|
+              m.message = message
+              m.channel = channel
+              m.instance_eval(&block)
+            end
+          end
+        end
+      end
+
+      def unsubscribe
+        EM.schedule do
+          FayeRails.client(endpoint).unsubscribe(@subscription)
+        end
+      end
+
+    end
+  end
+end

data/lib/faye-rails/controller/message.rb

@@ -0,0 +1,10 @@
+module FayeRails
+  class Controller
+    class Message
+
+      attr_accessor :message
+      attr_accessor :channel
+
+    end
+  end
+end

data/lib/faye-rails/controller/monitor.rb

@@ -0,0 +1,9 @@
+module FayeRails
+  class Controller
+    class Monitor
+
+      attr_accessor :client_id, :channel, :data
+
+    end
+  end
+end

data/lib/faye-rails/controller/observer_factory.rb

@@ -0,0 +1,54 @@
+require 'active_record'
+
+module FayeRails
+  class Controller
+
+    # Module creates ActiveRecord::Observer instances
+    module ObserverFactory
+
+      # Create
+      def self.define(klass, method_name, &block)
+        # Make a name for the observer
+        klass_observer_name = "#{klass.to_s}Observer"
+
+        # Load the observer if one exists
+        klass_observer = ObserverFactory.observer(klass_observer_name)
+
+        new_observer = klass_observer.nil?
+
+        # Create a new observer if one does not exist
+        klass_observer = Object.const_set(klass_observer_name, Class.new(ActiveRecord::Observer) do
+          # TODO Work around this hack.
+          # Have to define all of the available methods when creating the Observer class for the
+          # first time. The methods can then be overriden by the observe DSL. However if they
+          # are not first defined then they will not be registerable.
+          [:before_validation, :after_validation, :before_save, :before_create, :after_create, :after_save, :after_commit].each do |arg|
+            send :define_method, arg do |temp|
+            end
+          end
+        end) if new_observer
+
+        # Add the method to the observer
+        klass_observer.instance_eval do
+          define_method(method_name, &block)
+        end
+
+        # Add the observer if needed
+        if new_observer
+          ActiveRecord::Base.observers << klass_observer
+        end
+
+        ActiveRecord::Base.instantiate_observers
+      end
+
+      def self.observer(class_name)
+        klass = Module.const_get(class_name)
+        return klass if klass.is_a?(Class)
+        return nil
+      rescue
+        return nil
+      end
+
+    end
+  end
+end

data/lib/faye-rails/filter.rb

@@ -0,0 +1,179 @@
+module FayeRails
+  class Filter
+
+    attr_accessor :server
+    attr_reader   :channel
+    attr_writer   :logger
+
+    # Create a new FayeRails::Filter which can be passed to
+    # Faye::RackAdapter#add_extension.
+    #
+    # @param channel
+    #   Optional channel name to limit messages to.
+    # @param direction
+    #   :in, :out or :any.
+    # @param block
+    #   A proc object to be called when filtering messages.
+    def initialize(channel='/**', direction=:any, block)
+      @channel = channel
+      @block = block
+      raise ArgumentError, "Block cannot be nil" unless block
+      if (direction == :in) || (direction == :any)
+        @in_filter = DSL
+      end
+      if (direction == :out) || (direction == :any)
+        @out_filter = DSL
+      end
+    end
+
+    def respond_to?(method)
+      if (method == :incoming) 
+        !!@in_filter
+      elsif (method == :outgoing)
+        !!@out_filter
+      else
+        super
+      end
+    end
+
+    def logger
+      if defined?(::Rails)
+        @logger ||= Rails.logger
+      end
+    end
+
+    def incoming(message, callback)
+      @in_filter.new(@block, message, channel, callback, :incoming) if @in_filter
+    end
+
+
+    def outgoing(message, callback)
+      @out_filter.new(@block, message, channel, callback, :outgoing) if @out_filter
+    end
+
+    def destroy
+      if server
+        server.remove_extension(self)
+      end
+    end
+
+    class DSL
+
+      # A small wrapper class around filter blocks to
+      # add some sugar to ease filter (Faye extension)
+      # creation.
+
+      attr_reader :channel, :message, :callback, :original_message, :direction
+
+      # Called by FayeRails::Filter when Faye passes
+      # messages in for evaluation.
+      # @param block
+      #   The block you wish to execute whenever a matching
+      #   message is recieved.
+      # @param channel
+      #  optional: if present then the block will only be called for matching messages, otherwise all messages will be passed.
+      def initialize(block, message, channel='/**', callback, direction)
+        raise ArgumentError, "Block cannot be nil" unless block
+        @channel = channel
+        @original_message = message.dup
+        @message = message
+        @callback = callback
+        @direction = direction
+
+        if channel_matches?(@channel, @original_message['channel']) ||
+          (subscribing? && subscription?(@channel)) ||
+          (unsubscribing? && subscription?(@channel))
+          instance_eval(&block)
+        else
+          pass
+        end
+      end
+
+      # Easier than testing message['channel'] every time
+      def subscribing?
+        message['channel'] == '/meta/subscribe'
+      end
+
+      def unsubscribing?
+        message['channel'] == '/meta/unsubscribe'
+      end
+
+      def meta?
+        message['channel'][0..5] == '/meta/'
+      end
+
+      def service?
+        message['channel'][0..8] == '/service/'
+      end
+
+      def incoming?
+        direction == :incoming
+      end
+      alias in? incoming?
+
+      def outgoing?
+        direction == :outgoing
+      end
+      alias out? outgoing?
+
+      def data
+        message['data']
+      end
+
+      def data?
+        !!data
+      end
+
+      def client_id?(x=nil)
+        if !!x
+          message['client_id'] == x
+        else
+          !!message['client_id']
+        end
+      end
+
+      def channel_matches?(glob,test)
+        File.fnmatch? glob, test
+      end
+
+      def subscription?(channel)
+        message['subscription'] && channel_matches?(channel, message['subscription'])
+      end
+      
+      # Syntactic sugar around callback.call which passes
+      # back the original message unmodified.
+      def pass
+        return callback.call(original_message)
+      end
+
+      # Syntactic sugar around callback.call which passes
+      # the passed argument back to Faye in place of the 
+      # original message.
+      # @param new_message
+      #   Replacement message to send back to Faye.
+      def modify(new_message)
+        return callback.call(new_message)
+      end
+
+      # Syntactic sugar around callback.call which adds
+      # an error message to the message and passes it back
+      # to Faye, which will send back a rejection message to
+      # the sending client.
+      # @param reason
+      #   The error message to be sent back to the client.
+      def block(reason="Message blocked by filter")
+        new_message = message
+        new_message['error'] = reason
+        return callback.call(new_message)
+      end
+
+      # Syntactic sugar around callback.call which returns
+      # nil to Faye - effectively dropping the message.
+      def drop
+        return callback.call(nil)
+      end
+
+    end
+
+  end
+end