webhookr 0.0.2

data/.gitignore

@@ -0,0 +1,14 @@
+README.html
+*.orig
+.*.swp
+.*.swo
+*.tmp
+*.patch
+*.kpf
+*~
+.DS_Store
+Thumbs.db
+Gemfile.lock
+Gemfile.local
+Guardfile.local
+*.log

data/Gemfile

@@ -0,0 +1,18 @@
+source "http://rubygems.org"
+
+gemspec
+
+gem "rake", "~> 10.0"
+gem "minitest"
+gem "minitest-reporters"
+gem "em-websocket"
+gem "guard"
+gem "guard-minitest"
+gem "guard-markdown"
+gem "guard-livereload"
+gem "simplecov", :require => false
+
+if File.exists?('Gemfile.local')
+  instance_eval File.read('Gemfile.local')
+end
+

data/Guardfile

@@ -0,0 +1,31 @@
+
+guard 'minitest', :test_folders => 'test', :test_file_patterns => '*_test.rb' do
+  watch(%r|^test/(.+)_test\.rb|)
+  watch(%r|^test/stubs/(.+)\.rb$|) { "test" }
+
+  # Rails
+  watch(%r{^app/models/(.+)\.rb$}) { |m|
+    "test/unit/#{m[1]}_test.rb"
+  }
+
+  watch(%r{^app/controllers/(.+)\.rb$}) { |m|
+    "test/functional/#{m[1]}_test.rb"
+  }
+
+  watch('config/routes.rb') {
+    ["test/functional", "test/integration"]
+  }
+end
+
+guard 'livereload' do
+  watch('README.md')
+end
+
+guard 'markdown', :convert_on_start => true do
+ watch ('README.md') { "./README.md|./README.html" }
+end
+
+if File.exists?('Guardfile.local')
+  instance_eval File.read('Guardfile.local')
+end
+

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 2167961 Ontario Inc., Zoocasa <code@zoocasa.com>
+
+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,159 @@
+# webhookr: Rails Webhooks Made Easy
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/zoocasa/webhookr)
+
+## <a name="introduction"></a>Introduction
+
+### What is webhookr?
+
+webhookr is a Rails Engine that easily and securely adds third-party
+webhooks to your Rails app. It supports third-party sites with modular
+plugins.
+
+### What are 'webhooks'?
+
+From 30,000 feet, webhooks allow disparate cloud services to coordinate and
+asynchronously notify each other of events of interest. For example, a shopping app might
+want to process a [customer credit card transaction](https://stripe.com/docs/webhooks),
+and be notified of success or failure.
+
+From 10,000 feet, webhooks allow external third parties the ability to
+execute code within your application, using a well defined message exchange
+protocol.
+
+From 1,000 feet and below, webhooks are application routes and controller
+endpoints, third-party API discovery, security decisions, and code that
+executes within your application.
+
+
+### Why use webhookr?
+
+Webhooks are http callbacks from another service that are useful for
+pushing information to your Rails application. The question is: How do I
+easily and securely add them to my Rails application?
+
+webhookr provides a single, secure route for all your webhooks, and uses
+the observer pattern to integrate the webhook with your business logic.
+Using webhookr you can be up and running with a third-party webhook in less
+than an hour.
+
+### How does webhookr work?
+
+Webhookr provides a standard approach for third-party webhooks via plugins. The
+author of a plugin implements code to standardize any webhook into an action and
+data packet. Your task is to write glue code that is called whenever an action is
+received, and to use the resulting data packet for your application logic. Here is
+a subset of the MailChimp handler that might be written to deal with the 'unsubscribe'
+action sent from MailChimp:
+
+```ruby
+class MailChimpHooks
+  def on_unsubscribe(payload)
+    User.unsubscribe_newletter(payload.data.email)
+  end
+end
+```
+
+## <a name="usage"></a>Usage & Setup
+
+webhookr works with Rails 3.1 onwards. It generally requires a plugin to be
+useful, such as the [MailChimp plugin](https://github.com/zoocasa/webhookr-mailchimp).
+
+## Setup
+
+Add webhookr to your Gemfile with:
+
+```ruby
+gem 'webhookr'
+```
+
+Run the bundle command to install it and then run the generator to
+add the engine route to your config/routes.rb:
+
+```console
+rails g webhookr:add_route
+```
+
+or, add the routing information manually to config/routes.rb
+
+```ruby
+mount Webhookr::Engine => "/webhookr", :as => "webhookr"
+```
+
+The initialization file for webhookr is optional. To see what
+options are available, you can run the generator and review the
+sample config file:
+
+```console
+rails g webhookr:init *initializer_name*
+```
+
+Once you have added third-party plugins, you can use the provided
+rake task to output your applications urls for each service:
+
+```console
+rake webhookr:services
+```
+
+## <a name="security"></a>Webhookr Security
+
+### General security issues with webhooks
+
+A webhook is by design, a http post to your application that results in code execution.
+Having a well defined approach to adding such functionality can help ensure you don't open security issues
+within your application.
+
+Many webhook providers do not provide built-in security for their
+webhooks - they usually send the post over http, and they often have no authentication
+or verification mechanism. If your webhook third-party service responds to hooks, it is
+possible for an evil person to guess your webhook URL, and attempt to wreak havoc with your system.
+
+### How using webhookr can increase security
+webhookr provides a unique url for each service, via a security token that is used in the webhook path, to help make it hard to guess your webhook url.
+For example, if you were using MailChimp, your webhook url might look like: '/webhookr/mailchimp/cdd2a24cfac821' and if you were using Mandrill, your
+webhook might look like: '/webhookr/mandrill/de69557a4d95e7'. This will help prevent someone guessing your
+webhook service url. If you are using https, the URL will be encrypted, keeping your security token a secret.
+
+You can also enable http basic auth, if the third party service supports it. Note that enabling http basic auth
+affects all your webhooks, so be sure it is supported by all your third-party services.
+
+If you are sending sensitive data via webhooks, it is recommended you use HTTPS.
+
+### <a name="supported_services"></a>Supported Services
+
+* MailChimp - webhookr-mail_chimp
+* Mandrill - webhookr-mandrill
+* Github - coming soon
+* Stripe - coming soon
+
+## <a name="works_with"></a>Works with:
+
+webhookr works with Rails 3.1 and 3.2, and has been tested on the following Ruby
+implementations:
+
+* JRuby 1.7.1
+* MRI 1.8.7
+* MRI 1.9.2
+* MRI 1.9.3
+* Rubinius 1.2.4
+* Ruby EE 1.8.7
+
+Pending:
+
+* MRI 2.0
+
+### TODO
+* Implement get/post strategies and responses so the controller can return variable text to the service.
+This allows support for advanced Webhook responses for services that require it.
+* Enhance testing of Rake tasks
+* Clean up the stubs with FactoryGirl
+* Test with MRI 2.0
+
+### License
+
+webhookr is released under the [MIT license](http://www.opensource.org/licenses/MIT).
+
+## Author
+
+* [Gerry Power](https://github.com/gerrypower)
+
+## <a name="Version History"></a>Version History

data/Rakefile

@@ -0,0 +1,46 @@
+
+# -*- ruby -*-
+
+require 'rubygems'
+require 'rubygems/package_task'
+require 'rake/testtask'
+require 'rdoc/task'
+require 'bundler/gem_tasks'
+
+$:.push File.expand_path(File.dirname(__FILE__), 'lib')
+
+version = Webhookr::VERSION
+
+desc 'Test Webhookr'
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = !!ENV['VERBOSE_TESTS']
+  t.warning = !!ENV['WARNINGS']
+end
+
+desc 'Build docs'
+Rake::RDocTask.new do |t|
+  t.main = 'README.md'
+  t.title = "Webhookr #{version}"
+  t.rdoc_dir = 'doc'
+  t.rdoc_files.include('README.md', 'MIT-LICENSE', 'lib/**/*.rb')
+end
+
+namespace :webhookr do
+  namespace:test do
+    desc 'Install gems in all Rubies'
+    task :install do
+      sh %{rbenv each -v bundle install}
+    end
+
+    desc 'Test with all Rubies'
+    task :test_versions do
+      sh %{rbenv each -v bundle exec rake test}
+    end
+
+    desc 'Install and test all'
+    task :all => [:install, :test_versions]
+  end
+end
+
+task :default => :test

data/app/controllers/webhookr/events_controller.rb

@@ -0,0 +1,34 @@
+module Webhookr
+  class EventsController < ActionController::Base
+    http_basic_authenticate_with(
+      :name => Webhookr.config.basic_auth.username,
+      :password => Webhookr.config.basic_auth.password
+    ) if Webhookr.config.basic_auth.username && Webhookr.config.basic_auth.password
+
+    before_filter :create_service
+
+    def show
+      render :nothing => true
+    end
+
+    def create
+      @service.process!
+      render :nothing => true
+    end
+
+    private
+
+    def create_service
+      begin
+        @service = Webhookr::Service.new(
+          params[:service_id], :payload => request.body.read, :security_token => params[:security_token]
+        )
+      rescue NameError => e
+        raise ActionController::RoutingError.new("No service '#{params[:service_id]}' is available.")
+      rescue Webhookr::InvalidSecurityTokenError => e
+        raise ActionController::InvalidAuthenticityToken.new("Invalid or missing security token for service '#{params[:service_id]}'.")
+      end
+    end
+
+  end
+end

data/config/routes.rb

@@ -0,0 +1,4 @@
+Webhookr::Engine.routes.draw do
+  get "/events/:service_id(/:security_token)" => "events#show", :as => "events"
+  post "/events/:service_id(/:security_token)" => "events#create", :as => "events"
+end

data/lib/generators/webhookr/add_route_generator.rb

@@ -0,0 +1,12 @@
+module Webhookr
+  module Generators
+    class AddRouteGenerator < Rails::Generators::Base
+
+      desc 'This generator adds \'mount Webhookr::Engine => "/webhookr", :as => "webhookr"\' to your routes'
+      def add_route
+        route 'mount Webhookr::Engine => "/webhookr", :as => "webhookr"'
+      end
+
+    end
+  end
+end

data/lib/generators/webhookr/init_generator.rb

@@ -0,0 +1,30 @@
+module Webhookr
+  module Generators
+    class InitGenerator < Rails::Generators::NamedBase
+
+      desc "This generator creates an initializer file 'config/initializers/NAME.rb'"
+      def init
+        initializer("#{file_name}.rb") do
+          file_contents
+        end
+      end
+
+      def file_contents
+<<-eos
+# Webhookr Initializer
+
+## Turn on http basic authentication for all plugins
+  # Webhookr.config.basic_auth.username = "admin"
+  # Webhookr.config.basic_auth.password = "password"
+
+## Plugin Initializers go here ##
+eos
+      end
+
+      def generate_security_token
+        rand(10000000000000000).floor.to_s(36)
+      end
+
+    end
+  end
+end

data/lib/tasks/webhookr_tasks.rake

@@ -0,0 +1,16 @@
+namespace :webhookr do
+  desc "List the configured services and paths"
+  task :services => :environment do
+
+    puts "No webhookr services configured - add and configure webhookr plugins." and next if Webhookr.adapters.empty?
+
+    include Webhookr::Engine.routes.url_helpers
+
+    Webhookr.adapters.each do |key, adapter|
+      puts "\n\n#{key}:"
+      %w{ GET POST}.each do |x|
+        puts "  #{x}\t#{events_path(key, :security_token => Webhookr.config[key].try(:security_token))}\n"
+      end
+    end
+  end
+end

data/lib/webhookr/adapter_response.rb

@@ -0,0 +1,3 @@
+module Webhookr
+  class AdapterResponse < Struct.new(:service_name, :event_type, :payload); end
+end

data/lib/webhookr/engine.rb

@@ -0,0 +1,16 @@
+require 'active_support/core_ext/kernel/singleton_class'
+
+module Webhookr
+  class Engine < ::Rails::Engine
+    isolate_namespace Webhookr
+
+    # Enable basic auth for all services when config.basic_auth.username
+    # and config.basic_auth.password are set.
+    self.config.webhookr = ActiveSupport::OrderedOptions.new
+    self.config.webhookr.basic_auth = ActiveSupport::OrderedOptions.new
+
+    initializer "webhookr.config" do |app|
+    end
+  end
+end
+

data/lib/webhookr/invalid_payload_error.rb

@@ -0,0 +1,3 @@
+module Webhookr
+  class InvalidPayloadError < RuntimeError; end
+end

data/lib/webhookr/invalid_security_token_error.rb

@@ -0,0 +1,3 @@
+module Webhookr
+  class InvalidSecurityTokenError < RuntimeError; end
+end

data/lib/webhookr/ostruct_utils.rb

@@ -0,0 +1,28 @@
+module Webhookr
+  # Adapted from http://www.rebeccamiller-webster.com/2012/06/recursively-convert-a-ruby-hash-to-openstruct/
+  module OstructUtils
+
+     def self.to_ostruct(obj)
+        case
+        when obj.kind_of?(Hash)
+          return hash_to_ostruct(obj)
+        when obj.kind_of?(Array)
+          return array_to_ostruct(obj)
+        else
+          return obj
+        end
+      end
+
+      def self.hash_to_ostruct(hash)
+        hash.each  do |key, val|
+          hash[key] = to_ostruct(val)
+        end
+        OpenStruct.new(hash)
+      end
+
+      def self.array_to_ostruct(array)
+        array.map { |r| to_ostruct(r) }
+      end
+
+  end
+end

data/lib/webhookr/service.rb

@@ -0,0 +1,51 @@
+module Webhookr
+  class Service
+    attr_reader :service_name
+
+    def initialize(service_name, options = {})
+      @service_name = (service_name || "").downcase
+      @raw_payload = options[:payload]
+      available?
+      validate_security_token(options[:security_token]) if configured_security_token
+    end
+
+    def process!
+      Array.wrap(service_adapter.send(:process, @raw_payload)).each do |payload|
+        callback(callback_class, payload)
+      end
+    end
+
+    private
+
+    def callback(object, payload)
+      method = method_for(payload)
+      object.send(method, payload) if object.respond_to?(method)
+    end
+
+    def method_for(payload)
+      "on_" + payload.event_type
+    end
+
+    def callback_class
+      callback = Webhookr.config[service_name].try(:callback)
+      raise "No callback is configured for the service '#{service_name}'." if callback.nil?
+      @call_back_class || callback.new
+    end
+
+    def configured_security_token
+      Webhookr.config[service_name].try(:security_token)
+    end
+
+    def validate_security_token(token)
+      raise Webhookr::InvalidSecurityTokenError if token.nil? || token != configured_security_token
+    end
+
+    def service_adapter
+      raise NameError.new(%{Bad service name "#{service_name}"}) unless Webhookr.adapters[service_name]
+      @service_adapter ||= Webhookr.adapters[service_name]
+    end
+
+    alias_method :available?, :service_adapter
+
+  end
+end

data/lib/webhookr/services/adapter/base.rb

@@ -0,0 +1,20 @@
+
+module Webhookr::Services::Adapter::Base
+  extend ActiveSupport::Concern
+
+  included do
+    self.initialize! if self.respond_to?(:initialize!)
+    Webhookr.adapters[self::SERVICE_NAME] = self
+  end
+
+  module ClassMethods
+    def config
+      if Webhookr.config[self::SERVICE_NAME]
+        Webhookr.config[self::SERVICE_NAME]
+      else
+        Webhookr.config[self::SERVICE_NAME] = ActiveSupport::OrderedOptions.new
+      end
+    end
+  end
+end
+

data/lib/webhookr/services/adapter.rb

@@ -0,0 +1,7 @@
+
+module Webhookr::Services::Adapter
+  extend ActiveSupport::Autoload
+
+  autoload :Base
+end
+

data/lib/webhookr/services.rb

@@ -0,0 +1,7 @@
+
+module Webhookr::Services
+  extend ActiveSupport::Autoload
+
+  autoload :Adapter
+end
+

data/lib/webhookr/version.rb

@@ -0,0 +1,3 @@
+module Webhookr
+  VERSION = "0.0.2"
+end

data/lib/webhookr.rb

@@ -0,0 +1,24 @@
+require "webhookr/engine"
+
+module Webhookr
+  extend ActiveSupport::Autoload
+
+  autoload :InvalidPayloadError
+  autoload :AdapterResponse
+  autoload :Service
+  autoload :VERSION
+
+  class << self
+    def adapters
+      @adapters ||= HashWithIndifferentAccess.new
+    end
+
+    def config
+      @config ||= defined?(Rails) ? Rails.application.config.webhookr :
+                                    ActiveSupport::OrderedOptions.new
+    end
+  end
+end
+
+require "webhookr/services"
+

data/script/rails

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# This command will automatically be run when you run "rails" with Rails 3 gems installed from the root of your application.
+
+ENGINE_ROOT = File.expand_path('../..', __FILE__)
+ENGINE_PATH = File.expand_path('../../lib/webhookr/engine', __FILE__)
+
+require 'rails/all'
+require 'rails/engine/commands'