puller 0.0.0 → 0.1.0

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+## 0.1.0 (January 19, 2012)
+
+* initial release
+

data/README.md

@@ -1,29 +1,99 @@
 # Puller
 
-TODO: Write a gem description
+Puller is a Ruby gem for use with Rails to publish and subscribe to messages through [Pusher](http://pusher.com/). It allows you to easily provide real-time updates through an open socket without tying up a Rails process.
 
-## Installation
+Its code and API design is heavily inspired by Ryan Bates' [PrivatePub](http://github.com/ryanb/private_pub).
 
-Add this line to your application's Gemfile:
 
-    gem 'puller'
+## Setup
 
-And then execute:
+Add the gem to the Gemfile of your Rails application and run the `bundle` command to install it.
 
-    $ bundle
+```ruby
+gem "puller"
+```
 
-Or install it yourself as:
 
-    $ gem install puller
+**In Rails 3.1** add the JavaScript file to your application.js file manifest.
+
+```javascript
+//= require puller
+```
+
+
+**In Rails 3.0** run the generator to create the initial files
+
+```
+rails g puller:install
+```
+
+and add the generated puller.js file to your layout.
+
+```rhtml
+<%= javascript_include_tag "puller" %>
+```
+
+
+It's not necessary to include pusher.js since that will be handled automatically for you.
+
+Configure your Pusher credentials in an initializer file.
+
+```ruby
+Pusher.app_id = 'my_pusher_app_id'
+Pusher.key    = 'my_pusher_api_key'
+Pusher.secret = 'my_pusher_secret'
+```
+
+Note: You can skip this step if you are on Heroku and have activated the Pusher addon for your app.
+
 
 ## Usage
 
-TODO: Write usage instructions here
+Use the `subscribe_to` helper method on any page to subscribe to a channel/event.
+
+```rhtml
+<%= subscribe_to "new-message" %>
+```
+
+The above method subscribes to the "new-message" event in the default channel. The default channel name is
+the parameterized form of your Rails' application name. To use a different channel, prepend your custom
+channel name to the argument followed by a colon:
+
+```rhtml
+<%= subscribe_to "my-channel:new-message" %>
+```
+
+Use the `publish_to` helper method to send JavaScript to that channel/event. This is usually done in a JavaScript AJAX template (such as a create.js.erb file).
+
+```rhtml
+<% publish_to "new-message" do %>
+  $("#chat").append("<%= j render(@message) %>");
+<% end %>
+```
+
+This JavaScript will be immediately evaluated on all clients who have subscribed to that channel. In this example they will see the new chat message appear in real-time without reloading the browser.
+
+
+## Alternative Usage
+
+If you prefer to work through JSON instead of `.js.erb` templates, you can pass a hash to `publish_to` instead of a block and it will be converted `to_json` behind the scenes. This can be done anywhere (such as the controller).
+
+```ruby
+Puller.publish_to "new-message", :chat_message => "Hello, world!"
+```
+
+And then handle this through JavaScript on the client side.
+
+```javascript
+Puller.subscribe("new-message", function(data, channel) {
+  $("#chat").append(data.chat_message);
+});
+```
+
+The Ruby `subscribe_to` helper call is still necessary with this approach to grant the user access to the channel. The JavaScript is just a callback for any custom behavior.
+
+
+## Development & Feedback
 
-## Contributing
+Questions or comments? Please use the [issue tracker](https://github.com/natekross/puller/issues). Tests can be run with `bundle` and `rake` commands.
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request

data/Rakefile

@@ -1,3 +1,16 @@
 #!/usr/bin/env rake
 require "bundler/gem_tasks"
 
+require "rubygems"
+require "rake"
+require "rspec/core/rake_task"
+require "jasmine"
+load "jasmine/tasks/jasmine.rake"
+
+desc "Run RSpec"
+RSpec::Core::RakeTask.new do |t|
+  t.verbose = false
+end
+
+task :default => [:spec, "jasmine:ci"]
+

data/app/assets/javascripts/puller.js

@@ -0,0 +1,72 @@
+function buildPuller(doc) {
+  var self = {
+    connecting: false,
+    pusher: null,
+    initCallbacks: [],
+    subscriptions: {},
+    subscriptionCallbacks: {},
+    channels: {},
+
+    fetchPusher: function(callback) {
+      if (self.pusher) {
+        callback(self.pusher);
+      } else {
+        self.initCallbacks.push(callback);
+
+        if (self.subscriptions.apiKey && !self.connecting) {
+          self.connecting = true;
+
+          var script = doc.createElement("script");
+          script.type = "text/javascript";
+          script.src = "http://js.pusher.com/1.11/pusher.min.js";
+          script.onload = self.connectToPusher;
+
+          doc.documentElement.appendChild(script);
+        }
+      }
+    },
+
+    connectToPusher: function() {
+      self.pusher = new Pusher(self.subscriptions.apiKey);
+
+      for (var i = 0, ii = self.initCallbacks.length; i < ii; i++) {
+        self.initCallbacks[i](self.pusher);
+      };
+    },
+
+    sign: function(options) {
+      if (!self.subscriptions.apiKey) {
+        self.subscriptions.apiKey = options.apiKey;
+      }
+
+      self.subscriptions[options.channel + ":" + options.event] = options;
+
+      self.fetchPusher(function(pusher) {
+        if (!self.channels[options.channel]) {
+          self.channels[options.channel] = pusher.subscribe(options.channel);
+        }
+
+        self.channels[options.channel].bind(options.event, self.handleResponse);
+      });
+    },
+
+    handleResponse: function(message) {
+      if (message.eval) {
+        eval(message.eval);
+      }
+
+      if (callback = self.subscriptionCallbacks[message.channel + ":" + message.event]) {
+        callback(message.data, message.channel, message.event);
+      }
+    },
+
+    subscribe: function(channel_event, callback) {
+      self.subscriptionCallbacks[channel_event] = callback;
+    }
+  };
+
+  return self;
+}
+
+var Puller = buildPuller(document);
+

data/lib/generators/puller/install_generator.rb

@@ -0,0 +1,16 @@
+module Puller
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      def self.source_root
+        File.dirname(__FILE__) + "/templates"
+      end
+
+      def copy_files
+        if ::Rails.version < "3.1"
+          copy_file "../../../../app/assets/javascripts/puller.js", "public/javascripts/puller.js"
+        end
+      end
+    end
+  end
+end
+

data/lib/puller/engine.rb

@@ -0,0 +1,19 @@
+require "puller/view_helpers"
+
+module Puller
+  class Engine < Rails::Engine
+    # Adds the ViewHelpers into ActionView::Base and sets
+    # Pusher's logger to Rails' logger.
+    initializer "puller.init" do
+      ActionView::Base.send :include, ViewHelpers
+      Pusher.logger = Rails.logger
+
+      Puller.default_channel = begin
+        app_name = Rails.application.class.name
+        app_name = app_name.split('::').first
+        app_name.parameterize
+      end
+    end
+  end
+end
+

data/lib/puller/version.rb

@@ -1,4 +1,4 @@
 module Puller
-  VERSION = "0.0.0"
+  VERSION = "0.1.0"
 end
 

data/lib/puller/view_helpers.rb

@@ -0,0 +1,18 @@
+module Puller
+  module ViewHelpers
+    def publish_to(channel_event, data = nil, &block)
+      Puller.publish_to channel_event, data || capture(&block)
+    end
+
+    def subscribe_to(channel_event)
+      channel, event = Puller.channel_and_event_for(channel_event)
+
+      options = { :channel => channel, :event => event, :apiKey => Pusher.key }
+
+      content_tag "script", :type => "text/javascript" do
+        raw "Puller.sign(#{options.to_json});"
+      end
+    end
+  end
+end
+

data/lib/puller.rb

@@ -1,6 +1,35 @@
+require "pusher"
+
 require "puller/version"
+require "puller/engine" if defined? Rails
 
 module Puller
-  # Your code goes here...
+  class << self
+    attr_writer :default_channel
+
+    def default_channel
+      @default_channel ||= "default"
+    end
+
+    def publish_to(channel_event, data)
+      channel, event = channel_and_event_for(channel_event)
+
+      message = { :channel => channel, :event => event }
+      message[data.kind_of?(String) ? :eval : :data] = data
+
+      Pusher[channel].trigger event, message
+    end
+
+    def channel_and_event_for(text)
+      channel, event = text.split(':', 1)
+
+      if event.nil?
+        event   = channel
+        channel = default_channel
+      end
+
+      [channel, event]
+    end
+  end
 end
 

data/puller.gemspec

@@ -17,5 +17,11 @@ Gem::Specification.new do |gem|
 
   gem.rubyforge_project = gem.name
   gem.required_rubygems_version = ">= 1.3.4"
+
+  gem.add_dependency "pusher", "~> 0.8.5"
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "rspec", "~> 2.8.0"
+  gem.add_development_dependency "jasmine", ">= 1.1.1"
 end
 

data/spec/javascripts/puller_spec.js

@@ -0,0 +1,109 @@
+describe("Puller", function() {
+  var puller, doc;
+
+  beforeEach(function() {
+    Pusher = {}; // To simulate global Pusher object
+    doc = {};
+    puller = buildPuller(doc);
+  });
+
+  it("adds a subscription callback", function() {
+    puller.subscribe("hello", "callback");
+    expect(puller.subscriptionCallbacks["hello"]).toEqual("callback");
+  });
+
+  it("evaluates javascript in message response", function() {
+    puller.handleResponse({eval: 'self.subscriptions.foo = "bar"'});
+    expect(puller.subscriptions.foo).toEqual("bar");
+  });
+
+  it("triggers callback matching message channel in response", function() {
+    var called = false;
+    puller.subscribe("chan:test", function(data, channel, event) {
+      expect(data).toEqual("abcd");
+      expect(channel).toEqual("chan");
+      expect(event).toEqual("test");
+      called = true;
+    });
+    puller.handleResponse({channel: "chan", event: "test", data: "abcd"});
+    expect(called).toBeTruthy();
+  });
+
+  it("adds a pusher subscription with response handler when signing", function() {
+    var subscribeCalled = false,
+        bindCalled = false,
+        channel = {
+          bind: function(event, callback) {
+            expect(event).toEqual("someevent");
+            expect(callback).toEqual(puller.handleResponse);
+            bindCalled = true;
+          }
+        },
+        pusher = {
+          subscribe: function(channelName) {
+            expect(channelName).toEqual("somechannel");
+            subscribeCalled = true;
+
+            return channel;
+          }
+        };
+
+    spyOn(puller, 'fetchPusher').andCallFake(function(callback) {
+      callback(pusher);
+    });
+
+    var options = {apiKey: "someapikey", channel: "somechannel", event: "someevent"};
+    puller.sign(options);
+
+    expect(puller.subscriptions.apiKey).toEqual("someapikey");
+    expect(puller.subscriptions["somechannel:someevent"]).toEqual(options);
+
+    expect(subscribeCalled).toBeTruthy();
+    expect(bindCalled).toBeTruthy();
+
+    expect(puller.channels["somechannel"]).toEqual(channel);
+  });
+
+  it("triggers pusher callback function immediately when pusher is available", function() {
+    var called = false;
+    puller.pusher = "pusher";
+    puller.fetchPusher(function(pusher) {
+      expect(pusher).toEqual("pusher");
+      called = true;
+    });
+    expect(called).toBeTruthy();
+  });
+
+  it("adds initCallback when client and server aren't available", function() {
+    puller.fetchPusher("callback");
+    expect(puller.initCallbacks[0]).toEqual("callback");
+  });
+
+  it("adds a script tag loading pusher js when the server is present", function() {
+    script = {};
+    doc.createElement = function() { return script; };
+    doc.documentElement = {appendChild: jasmine.createSpy()};
+    puller.subscriptions.apiKey = "someapikey";
+    puller.fetchPusher("callback");
+    expect(puller.initCallbacks[0]).toEqual("callback");
+    expect(script.type).toEqual("text/javascript");
+    expect(script.src).toEqual("http://js.pusher.com/1.11/pusher.min.js");
+    expect(script.onload).toEqual(puller.connectToPusher);
+    expect(doc.documentElement.appendChild).toHaveBeenCalledWith(script);
+  });
+
+  it("connects to pusher server and executes callbacks", function() {
+    callback = jasmine.createSpy();
+    client = { foo: "bar" };
+    Pusher = function(key) {
+      expect(key).toEqual("key")
+      return client;
+    };
+    puller.subscriptions.apiKey = "key";
+    puller.initCallbacks.push(callback);
+    puller.connectToPusher();
+    expect(puller.pusher).toEqual(client);
+    expect(callback).toHaveBeenCalledWith(client);
+  });
+});
+

data/spec/javascripts/support/jasmine.yml

@@ -0,0 +1,74 @@
+# src_files
+#
+# Return an array of filepaths relative to src_dir to include before jasmine specs.
+# Default: []
+#
+# EXAMPLE:
+#
+# src_files:
+#   - lib/source1.js
+#   - lib/source2.js
+#   - dist/**/*.js
+#
+src_files:
+  - app/assets/javascripts/puller.js
+
+# stylesheets
+#
+# Return an array of stylesheet filepaths relative to src_dir to include before jasmine specs.
+# Default: []
+#
+# EXAMPLE:
+#
+# stylesheets:
+#   - css/style.css
+#   - stylesheets/*.css
+#
+stylesheets:
+
+# helpers
+#
+# Return an array of filepaths relative to spec_dir to include before jasmine specs.
+# Default: ["helpers/**/*.js"]
+#
+# EXAMPLE:
+#
+# helpers:
+#   - helpers/**/*.js
+#
+helpers:
+
+# spec_files
+#
+#  Return an array of filepaths relative to spec_dir to include.
+# Default: ["**/*[sS]pec.js"]
+#
+# EXAMPLE:
+#
+# spec_files:
+#   - **/*[sS]pec.js
+#
+spec_files:
+
+# src_dir
+#
+# Source directory path. Your src_files must be returned relative to this path. Will use root if left blank.
+# Default: project root
+#
+# EXAMPLE:
+#
+# src_dir: public
+#
+src_dir:
+
+# spec_dir
+#
+# Spec directory path. Your spec_files must be returned relative to this path.
+# Default: spec/javascripts
+#
+# EXAMPLE:
+#
+# spec_dir: spec/javascripts
+#
+spec_dir:
+

data/spec/javascripts/support/jasmine_config.rb

@@ -0,0 +1,24 @@
+module Jasmine
+  class Config
+
+    # Add your overrides or custom config code here
+
+  end
+end
+
+
+# Note - this is necessary for rspec2, which has removed the backtrace
+module Jasmine
+  class SpecBuilder
+    def declare_spec(parent, spec)
+      me = self
+      example_name = spec["name"]
+      @spec_ids << spec["id"]
+      backtrace = @example_locations[parent.description + " " + example_name]
+      parent.it example_name, {} do
+        me.report_spec(spec["id"])
+      end
+    end
+  end
+end
+

data/spec/javascripts/support/jasmine_runner.rb

@@ -0,0 +1,33 @@
+$:.unshift(ENV['JASMINE_GEM_PATH']) if ENV['JASMINE_GEM_PATH'] # for gem testing purposes
+
+require 'rubygems'
+require 'jasmine'
+jasmine_config_overrides = File.expand_path(File.join(File.dirname(__FILE__), 'jasmine_config.rb'))
+require jasmine_config_overrides if File.exist?(jasmine_config_overrides)
+if Jasmine::Dependencies.rspec2?
+  require 'rspec'
+else
+  require 'spec'
+end
+
+jasmine_config = Jasmine::Config.new
+spec_builder = Jasmine::SpecBuilder.new(jasmine_config)
+
+should_stop = false
+
+if Jasmine::Dependencies.rspec2?
+  RSpec.configuration.after(:suite) do
+    spec_builder.stop if should_stop
+  end
+else
+  Spec::Runner.configure do |config|
+    config.after(:suite) do
+      spec_builder.stop if should_stop
+    end
+  end
+end
+
+spec_builder.start
+should_stop = true
+spec_builder.declare_suites
+

data/spec/puller_spec.rb

@@ -0,0 +1,8 @@
+require "spec_helper"
+
+describe Puller do
+  it "defaults default_channel to 'default'" do
+    Puller.default_channel.should == 'default'
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require "rubygems"
+require "bundler/setup"
+require "pusher"
+
+Bundler.require(:default)
+
+RSpec.configure do |config|
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: puller
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,51 @@ autorequire:
 bindir: bin
 cert_chain: []
 date: 2012-01-19 00:00:00.000000000Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pusher
+  requirement: &25369220 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.5
+  type: :runtime
+  prerelease: false
+  version_requirements: *25369220
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &25368580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *25368580
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &25367700 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.8.0
+  type: :development
+  prerelease: false
+  version_requirements: *25367700
+- !ruby/object:Gem::Dependency
+  name: jasmine
+  requirement: &25365580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+  type: :development
+  prerelease: false
+  version_requirements: *25365580
 description: -- gem description --
 email: natekross@gmail.com
 executables: []
@@ -18,13 +62,25 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- CHANGELOG.md
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
+- app/assets/javascripts/puller.js
+- lib/generators/puller/install_generator.rb
+- lib/generators/puller/templates/.gitkeep
 - lib/puller.rb
+- lib/puller/engine.rb
 - lib/puller/version.rb
+- lib/puller/view_helpers.rb
 - puller.gemspec
+- spec/javascripts/puller_spec.js
+- spec/javascripts/support/jasmine.yml
+- spec/javascripts/support/jasmine_config.rb
+- spec/javascripts/support/jasmine_runner.rb
+- spec/puller_spec.rb
+- spec/spec_helper.rb
 homepage: http://github.com/natekross/puller
 licenses: []
 post_install_message: 
@@ -37,6 +93,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 3142173162834286048
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: