simplepub 1.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 621c275bc4cd10a8abfafb4311ffe9a0ccd7a424
+  data.tar.gz: 72bfe967a904824287a8c9fe3da8e56932087db2
+SHA512:
+  metadata.gz: fc96c8f2ef50018eb30d6e383008292f7c8c158b1b8923186e7b0df7c11d5886eb090f608d78467cf49a34a18920c6bb804fa630c252cf6b9bfffb0b81b32a23
+  data.tar.gz: bc9122517ca3a60fa88018d3881e2c66a60e950e82f434f4fd823afb846a1ef3cc1384a6caba1f484fa5153cc28f18d7d918e6f57acbd84790c2b4e3a95fb11c

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.0.0

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+## 1.0.3 (August 20, 2012)
+
+* fixed Faye startup error (thanks gitt) - issue #40
+
+
+## 1.0.2 (August 20, 2012)
+
+* added HTTPS support (thanks vanne)
+
+
+## 1.0.1 (January 25, 2012)
+
+* Rails 3.2 compatibility with SecureRandom fix (thanks windigo) - issue #26
+
+
+## 1.0.0 (January 15, 2012)
+
+* setting config defaults to nil so everything must be set in `simplepub.yml`
+
+* Documentation improvements
+
+
+## 0.3.0 (January 14, 2012)
+
+* adding `Simplepub.publish_to` method for publishing from anywhere - issue #15
+
+* rewriting `simplepub.js` so it is framework agnostic
+
+* Rails 3.1 compatibility (thanks BinaryMuse) - issue #25
+
+* adding faye gem dependency so it doesn't need to be installed separately
+
+* renaming `faye.ru` to `simplepub.ru`
+
+* truncate token for client for security (thanks jameshuynh) - issue #19
+
+
+## 0.2.0 (April 7, 2011)
+
+* switched to YAML file for config. BACKWARDS INCOMPATIBLE: you will need to remove config/initializers/simplepub.rb
+
+* moved view helpers into Railtie so helper file is no longer generated
+
+* error out when signature has expired
+
+
+## 0.1.0 (April 4, 2011)
+
+* initial release

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in simplepub.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Ryan Bates
+
+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/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jorge Calás Lozano
+
+MIT License
+
+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/README.md

@@ -0,0 +1,146 @@
+# Simplepub
+
+Simplepub is a Ruby gem for use with Rails to publish and subscribe to messages through [Faye](http://faye.jcoglan.com/). It allows you to easily provide real-time updates through an open socket without tying up a Rails process. All channels are private so users can only listen to events you subscribe them to.
+
+Watch [RailsCasts Episode 316](http://railscasts.com/episodes/316-private-pub) for a demonstration of Simplepub.
+
+
+## Setup
+
+Add the gem to your Gemfile and run the `bundle` command to install it. You'll probably want to add "thin" to your Gemfile as well to serve Faye.
+
+```ruby
+gem "simplepub"
+gem "thin"
+```
+
+Run the generator to create the initial files.
+
+```
+rails g simplepub:install
+```
+
+Next, start up Faye using the rackup file that was generated.
+
+```
+rackup simplepub.ru -s thin -E production
+```
+
+**In Rails 3.1** add the JavaScript file to your application.js file manifest.
+
+```javascript
+//= require simplepub
+```
+
+**In Rails 3.0** add the generated simplepub.js file to your layout.
+
+```rhtml
+<%= javascript_include_tag "simplepub" %>
+```
+
+It's not necessary to include faye.js since that will be handled automatically for you.
+
+
+## Usage
+
+Use the `subscribe_to` helper method on any page to subscribe to a channel.
+
+```rhtml
+<%= subscribe_to "/messages/new" %>
+```
+
+Use the `publish_to` helper method to send JavaScript to that channel. This is usually done in a JavaScript AJAX template (such as a create.js.erb file).
+
+```rhtml
+<% publish_to "/messages/new" do %>
+  $("#chat").append("<%= j render(@messages) %>");
+<% 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
+Simplepub.publish_to "/messages/new", :chat_message => "Hello, world!"
+```
+
+And then handle this through JavaScript on the client side.
+
+```javascript
+Simplepub.subscribe("/messages/new", 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.
+
+
+## Configuration
+
+The configuration is set separately for each environment in the generated `config/simplepub.yml` file. Here are the options.
+
+* `server`: The URL to use for the Faye server such as `http://localhost:9292/faye`.
+* `secret_token`: A secret hash to secure the server. Can be any string.
+* `signature_expiration`: The length of time in seconds before a subscription signature expires. If this is not set there is no expiration. Note: if Faye is on a separate server from the Rails app, the system clocks must be in sync for the expiration to work properly.
+
+
+## How It Works
+
+The `subscribe_to` helper will output the following script which subscribes the user to a specific channel and server.
+
+```html
+<script type="text/javascript">
+  Simplepub.sign({
+    channel: "/messages/new",
+    timestamp: 1302306682972,
+    signature: "dc1c71d3e959ebb6f49aa6af0c86304a0740088d",
+    server: "http://localhost:9292/faye"
+  });
+</script>
+```
+
+The signature and timestamp checked on the Faye server to ensure users are only able to access channels you subscribe them to. The signature will automatically expire after the time specified in the configuration.
+
+The `publish_to` method will send a post request to the Faye server (using `Net::HTTP`) instructing it to send the given data back to the browser.
+
+
+## Serving Faye over HTTPS (with Thin)
+
+To server Faye over HTTPS you could create a thin configuration file `config/simplepub_thin.yml` similar to the following:
+
+```yaml
+---
+port: 4443
+ssl: true
+ssl_key_file: /path/to/server.pem
+ssl_cert_file: /path/to/certificate_chain.pem
+environment: production
+rackup: simplepub.ru
+```
+
+The `certificate_chain.pem` file should contain your signed certificate, followed by intermediate certificates (if any) and the root certificate of the CA that signed the key.
+
+Next reconfigure the URL in `config/simplepub.yml` to look like `https://your.hostname.com:4443/faye`
+
+Finally start up Thin from the project root.
+
+```
+thin -C config/simplepub_thin.yml start
+```
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Development & Feedback
+
+Questions or comments? Please use the [issue tracker](https://github.com/speedyrails/simplepub/issues). Tests can be run with `bundle` and `rake` commands.

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require 'jasmine'
+load 'jasmine/tasks/jasmine.rake'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => %W(spec jasmine:ci)

data/app/assets/javascripts/simplepub.js

@@ -0,0 +1,97 @@
+function buildSimplepub(doc) {
+  var self = {
+    connecting: false,
+    fayeClient: null,
+    fayeCallbacks: [],
+    subscriptions: {},
+    subscriptionObjects: {},
+    subscriptionCallbacks: {},
+
+    faye: function(callback) {
+      if (self.fayeClient) {
+        callback(self.fayeClient);
+      } else {
+        self.fayeCallbacks.push(callback);
+        if (self.subscriptions.server && !self.connecting) {
+          self.connecting = true;
+          var script = doc.createElement("script");
+          script.type = "text/javascript";
+          script.src = self.subscriptions.server + ".js";
+          script.onload = self.connectToFaye;
+          doc.documentElement.appendChild(script);
+        }
+      }
+    },
+
+    connectToFaye: function() {
+      self.fayeClient = new Faye.Client(self.subscriptions.server);
+      self.fayeClient.addExtension(self.fayeExtension);
+      for (var i=0; i < self.fayeCallbacks.length; i++) {
+        self.fayeCallbacks[i](self.fayeClient);
+      };
+    },
+
+    fayeExtension: {
+      outgoing: function(message, callback) {
+        if (message.channel == "/meta/subscribe") {
+          // Attach the signature and timestamp to subscription messages
+          var subscription = self.subscriptions[message.subscription];
+          if (!message.ext) message.ext = {};
+          message.ext.simplepub_signature = subscription.signature;
+          message.ext.simplepub_timestamp = subscription.timestamp;
+        }
+        callback(message);
+      }
+    },
+
+    sign: function(options) {
+      if (!self.subscriptions.server) {
+        self.subscriptions.server = options.server;
+      }
+      self.subscriptions[options.channel] = options;
+      self.faye(function(faye) {
+        var sub = faye.subscribe(options.channel, self.handleResponse);
+        self.subscriptionObjects[options.channel] = sub;
+        if (options.subscription) {
+          options.subscription(sub);
+        }
+      });
+    },
+
+    handleResponse: function(message) {
+      if (message.eval) {
+        eval(message.eval);
+      }
+      if (callback = self.subscriptionCallbacks[message.channel]) {
+        callback(message.data, message.channel);
+      }
+    },
+
+    subscription: function(channel) {
+      return self.subscriptionObjects[channel];
+    },
+
+    unsubscribeAll: function() {
+      for (var i in self.subscriptionObjects) {
+        if ( self.subscriptionObjects.hasOwnProperty(i) ) {
+          self.unsubscribe(i);
+        }
+      }
+    },
+
+    unsubscribe: function(channel) {
+      var sub = self.subscription(channel);
+      if (sub) {
+        sub.cancel();
+        delete self.subscriptionObjects[channel];
+      }
+    },
+
+    subscribe: function(channel, callback) {
+      self.subscriptionCallbacks[channel] = callback;
+    }
+  };
+  return self;
+}
+
+var Simplepub = buildSimplepub(document);

data/bin/simplepub

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'simplepub'
+
+Simplepub::Cli::App.start(ARGV)

data/lib/generators/simplepub/install_generator.rb

@@ -0,0 +1,17 @@
+module Simplepub
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      def self.source_root
+        Simplepub.templates_root
+      end
+
+      def copy_files
+        template "simplepub.yml", "config/simplepub.yml"
+        if ::Rails.version < "3.1"
+          copy_file "../../../../app/assets/javascripts/simplepub.js", "public/javascripts/simplepub.js"
+        end
+        # copy_file "simplepub.ru", "simplepub.ru"
+      end
+    end
+  end
+end

data/lib/simplepub/cli/app.rb

@@ -0,0 +1,13 @@
+require 'thor'
+
+module Simplepub
+  module Cli
+    class App < Thor
+      desc "server", "Manage simplepub server"
+      subcommand :server, Server
+
+      desc "config", "Manage simplepub configuration file"
+      subcommand :config, Config
+    end
+  end
+end

data/lib/simplepub/cli/config.rb

@@ -0,0 +1,33 @@
+module Simplepub
+  module Cli
+    class Config < Thor
+      include Thor::Actions
+
+      desc "install", "Install configuration file"
+      def install
+        if Process.uid == 0
+          install_as_root
+        else
+          install_as_user
+        end
+      end
+
+      def self.source_root
+        Simplepub.templates_root
+      end
+
+      private
+
+      def install_as_root
+        say "Installing system wide as root", :green
+        directory "/etc/simplepub"
+        template "simplepub.yml", "/etc/simplepub/config.yml"
+      end
+
+      def install_as_user
+        say "Installing locally", :green
+        template "simplepub.yml", "#{ENV['HOME']}/.simplepub.yml"
+      end
+    end
+  end
+end

data/lib/simplepub/cli/server.rb

@@ -0,0 +1,64 @@
+require 'thin'
+
+module Simplepub
+  module Cli
+    class Server < Thor
+      desc "start", "Start simplepub server"
+      option :rackup_file, desc: "Rack configuration file", default: Simplepub.rackup_file, aliases: "-R"
+      option :environment, desc: "Simplepub environment", default: "development", aliases: "-E"
+      option :rack_environment, desc: "Rack environment", default: "production", aliases: "-e"
+      option :port, desc: "Rack port", default: "4443", aliases: "-p"
+      option :address, desc: "Rack address", default: "127.0.0.1", aliases: "-a"
+      option :logfile, desc: "Rack server log file", default: "/tmp/simplepub.log", aliases: "-l"
+      option :pidfile, desc: "Rack server PID file", default: "/tmp/simplepub.pid", aliases: "-P"
+      option :no_daemon, desc: "Don't daemonize rack server", type: :boolean, default: false
+      def start
+        Simplepub.load_config
+        Simplepub.config.environment = options.environment
+        argv = [
+          "start",
+          "-R", options.rackup_file,
+          "-e", options.rack_environment,
+          "-p", options.port,
+          "-a", options.address,
+          "-l", options.logfile,
+          "-P", options.pidfile
+        ]
+        if Simplepub.config.ssl_.certificate?
+          argv << "--ssl"
+          argv << "--ssl-verify"
+          argv << "--ssl-cert-file"
+          argv << Simplepub.config.ssl.certificate
+          if Simplepub.config.ssl.keyfile?
+            argv << "--ssl-key-file"
+            argv << Simplepub.config.ssl.keyfile
+          end
+        end
+        argv << "-d" unless options.no_daemon?
+        say "Loading server with #{argv.inspect}", :yellow
+        Thin::Runner.new(argv.flatten).run!
+      end
+
+      desc "stop", "Start simplepub server"
+      option :rackup_file, desc: "Rack configuration file", default: Simplepub.rackup_file, aliases: "-R"
+      option :rack_environment, desc: "Rack environment", default: "production", aliases: "-e"
+      option :port, desc: "Rack port", default: "9292", aliases: "-p"
+      option :address, desc: "Rack address", default: "127.0.0.1", aliases: "-a"
+      option :logfile, desc: "Rack server log file", default: "/tmp/simplepub.log", aliases: "-l"
+      option :pidfile, desc: "Rack server PID file", default: "/tmp/simplepub.pid", aliases: "-P"
+      def stop
+        Simplepub.load_config
+        argv = [
+          "stop",
+          "-R", options.rackup_file,
+          "-e", options.rack_environment,
+          "-p", options.port,
+          "-a", options.address,
+          "-l", options.logfile,
+          "-P", options.pidfile
+        ]
+        Thin::Runner.new(argv.flatten).run!
+      end
+    end
+  end
+end

data/lib/simplepub/cli.rb

@@ -0,0 +1,7 @@
+module Simplepub
+  module Cli
+    autoload :App,    'simplepub/cli/app'
+    autoload :Server, 'simplepub/cli/server'
+    autoload :Config, 'simplepub/cli/config'
+  end
+end

data/lib/simplepub/configuration.rb

@@ -0,0 +1,48 @@
+require 'yaml'
+require 'hashie'
+
+module Simplepub
+  module Configuration
+    attr_reader :config
+
+    def configure(&block)
+      yield(config)
+    end
+
+    # Resets the configuration to the default (empty hash)
+    def reset_config
+      @config = Hashie::Mash.new
+    end
+
+    def default_config_file
+      return config.config_file if config.config_file?
+      config_file = config_file_paths.detect { |path| File.exists?(path) }
+      config_file
+    end
+
+    def default_environment
+      config.environment? ? config.environment : "development"
+    end
+
+    # Loads the  configuration from a given YAML file and environment (such as production)
+    def load_config(filename=default_config_file, environment=default_environment)
+      raise ConfigurationFileError, "Configuration file not found. Available paths: #{config_file_paths.inspect}" if filename.nil?
+
+      yaml = YAML.load_file(filename)[environment.to_s]
+
+      raise ArgumentError, "The #{environment} environment does not exist in #{filename}" if yaml.nil?
+
+      config.deep_merge!(yaml)
+    end
+
+    private
+
+    def config_file_paths
+      [
+        "#{ENV['HOME']}/.simplepub.yml",
+        "/etc/simplepub/config.yml",
+        "/etc/simplepub.yml"
+      ]
+    end
+  end
+end

data/lib/simplepub/engine.rb

@@ -0,0 +1,16 @@
+require "simplepub/view_helpers"
+
+module Simplepub
+  class Engine < Rails::Engine
+    # Loads the simplepub.yml file if it exists.
+    initializer "simplepub.config" do
+      path = Rails.root.join("config/simplepub.yml")
+      Simplepub.load_config(path, Rails.env) if path.exist?
+    end
+
+    # Adds the ViewHelpers into ActionView::Base
+    initializer "simplepub.view_helpers" do
+      ActionView::Base.send :include, ViewHelpers
+    end
+  end
+end

data/lib/simplepub/error.rb

@@ -0,0 +1,7 @@
+module Simplepub
+  class Error < StandardError
+  end
+
+  class ConfigurationFileError < Error
+  end
+end

data/lib/simplepub/faye_extension.rb

@@ -0,0 +1,43 @@
+module Simplepub
+  # This class is an extension for the Faye::RackAdapter.
+  # It is used inside of Simplepub.faye_app.
+  class FayeExtension
+    # Callback to handle incoming Faye messages. This authenticates both
+    # subscribe and publish calls.
+    def incoming(message, callback)
+      if message["channel"] == "/meta/subscribe"
+        authenticate_subscribe(message)
+      elsif message["channel"] !~ %r{^/meta/}
+        authenticate_publish(message)
+      end
+      callback.call(message)
+    end
+
+    private
+
+    # Ensure the subscription signature is correct and that it has not expired.
+    def authenticate_subscribe(message)
+      subscription = Simplepub.subscription({
+        :channel => message["subscription"],
+        :timestamp => message["ext"]["simplepub_timestamp"]
+      })
+
+      if message["ext"]["simplepub_signature"] != subscription[:signature]
+        message["error"] = "Incorrect signature."
+      elsif Simplepub.signature_expired? message["ext"]["simplepub_timestamp"].to_i
+        message["error"] = "Signature has expired."
+      end
+    end
+
+    # Ensures the secret token is correct before publishing.
+    def authenticate_publish(message)
+      if Simplepub.config[:secret_token].nil?
+        raise Error, "No secret_token config set, ensure simplepub.yml is loaded properly."
+      elsif message["ext"]["simplepub_token"] != Simplepub.config[:secret_token]
+        message["error"] = "Incorrect token."
+      else
+        message["ext"]["simplepub_token"] = nil
+      end
+    end
+  end
+end