mail_to_hip_chat 0.0.1

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.DS_Store
+/doc
+.yardoc

data/.rbenv-version

@@ -0,0 +1 @@
+1.9.2-p290

data/.yardopts

@@ -0,0 +1,5 @@
+--protected
+--no-private
+-
+ChangeLog
+LICENSE

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (C) 2011, Gabriel Gironda 
+
+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. 
+
+Except as contained in this notice, the name of Gabriel Gironda shall not 
+be used in advertising or otherwise to promote the sale, use or other 
+dealings in this Software without prior written authorization from Gabriel 
+Gironda. 

data/README.md

@@ -0,0 +1,90 @@
+          _
+         [_|          .             .       .                .                       .  
+     .-----|--,       |-. . ,-. ,-. |-. ,-. |-   ,-,-. ,-. . |    ," . . ,-. ,-. ,-. |  
+    /      | /_\_     | | | | | |   | | ,-| | -- | | | ,-| | | -- |- | | | | | | |-' |  
+    |       |__.-|    ' ' ' |-' `-' ' ' `-^ `'   ' ' ' `-^ ' `'   |  `-^ ' ' ' ' `-' `' 
+    |       |__\_|          |                                     '                     
+    '---,-,-;---'           '
+        | |
+        
+# Mail To HipChat
+
+Mail To HipChat lets you wire up email notifications to [HipChat](http://hipchat.com/r/30ad1). This is useful in situations where a third-party service doesn't have a real [WebHook](http://www.webhooks.org/) available, but you still want to be able to dump notifications into HipChat. The [Airbrake](http://airbrake.io) exception notification service is one example.
+
+## How It Works
+
+Mail To HipChat is designed to be deployed on [Heroku](http://heroku.com) and used with the [CloudMailIn](http://cloudmailin.com/) add-on. Adding the CloudMailIn incoming email address to the recipients list of the service you wish to integrate with will shuffle emails off to your instance of this tool as a HTTP POST request. A list of mail handlers is checked, and the appropriate one is invoked to format a message and send it off to one or more HipChat rooms.
+
+## Prerequisites
+
+You will need an account on Heroku and admin access to your HipChat group. 
+
+## Initial Setup
+
+1. Make a home for your shiny new Mail To HipChat instance to live in.
+
+        $ mkdir my-mail_to_hip_chat
+        $ cd my-mail_to_hip_chat
+        $ git init 
+    
+2. Do the bundler dance.
+
+        $ echo 'source "http://rubygems.org"' >> Gemfile
+        $ echo 'gem "mail_to_hip_chat"' >> Gemfile
+        $ bundle install
+        $ git commit -a -m "Getting down with bundler"
+    
+3. Copy over the default config.ru.
+
+        $ cp "`bundle show mail_to_hip_chat`/support/config.ru" .
+        $ git commit -a -m "Adding default config.ru"
+
+4. Set up a new Heroku application with CloudMailIn and Piggyback SSL.
+  
+        $ heroku create --stack cedar
+        $ heroku addons:add cloudmailin
+        $ heroku addons:add ssl:piggyback
+
+5. Setup the CloudMailIn target address to point at your app.
+    
+    Get the target address for CloudMailIn to hit when it receives an email.
+    
+        $ echo "`heroku info -r | grep web_url | cut -d '=' -f 2 | sed 's/^http/https/'`notifications/create"
+    
+    Get your CloudMailIn username and password from the Heroku app config.
+    
+        $ heroku config | grep CLOUDMAILIN
+
+    [Log in to CloudMailIn](https://cloudmailin.com/users/sign_in) using the given `CLOUDMAILIN_USERNAME` and `CLOUDMAILIN_PASSWORD`. You'll see the entry for `CLOUDMAILIN_FORWARD_ADDRESS` in the list. Hit "Manage" and then "Edit Target", and set the target to the target address we retrieved above.
+    
+6. Get a HipChat API token and the ID for the Room(s) to send messages to.
+  
+    Visit your [HipChat API Admin page](http://hipchat.com/group_admin/api). If there's a token you want to already use, use that one. If not, create a new token of type "Notification". Once you have the token, set it as an environment variable on Heroku.
+  
+        $ heroku config:add HIPCHAT_API_TOKEN=fd3deeef7b88b95c1780e6237c41c30f
+
+    Visit your [HipChat Chat History page](https://hipchat.com/history). The integer in the URL for the history of each room (for example, `https://gabe.hipchat.com/history/room/31373`) is the room ID. Once you have the ID(s) of the rooms you wish to send messages to, set it as a comma separated environment variable on Heroku.
+  
+        $ heroku config:add HIPCHAT_ROOMS=31373,31374
+
+7. Deploy this sucker.
+
+        $ git push heroku master
+    
+8. Get your CloudMailIn forwarding address and send a test email.
+
+        $ heroku config --long | grep CLOUDMAILIN_FORWARD_ADDRESS
+    
+    Send an email to the `CLOUDMAILIN_FORWARD_ADDRESS`, with a subject of "Testing Setup". The message should appear in the rooms you've configured Mail To HipChat to send messages to.
+
+## Hooking it up to Airbrake
+
+  Just add a new user to your project, set their email address to `CLOUDMAILIN_FORWARD_ADDRESS`, and watch the exceptions roll in. Then turn your face from God and weep in abject horror.
+
+## Adding new message handlers
+
+## FAQ
+
+## TODO
+
+* There are too many steps for initial setup. This needs to be cut down.

data/Rakefile

@@ -0,0 +1,17 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "yard"
+require "mail_to_hip_chat"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/{unit,integration}/**/*_test.rb']
+  t.verbose = true
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.options += ['--title', "Mail To HipChat #{MailToHipChat::VERSION} Documentation"]
+end
+
+task :default => :test

data/lib/mail_to_hip_chat/chute_chain.rb

@@ -0,0 +1,32 @@
+module MailToHipChat
+  # A {ChuteChain} is used to hold a collection of chutes and to check whether any of those chutes is
+  # able to handle a message to hand off to HipChat. Anything that responds to #call can be pushed
+  # onto the chain.
+  class ChuteChain
+    
+    def initialize
+      @chutes = []
+    end
+
+    # Pushes a chute onto the chain.
+    #
+    # @param [#call] chute The chute to push onto the chain.
+    #
+    # @return [self]
+    def push(chute)
+      @chutes.push(chute)
+      self
+    end
+    
+    # Takes in a message and traverses the chain looking for a chute that will handle it.
+    #
+    # @param [Hash] message The message to give to the chutes in the chain.
+    #
+    # @return [true]  True if a chute accepts the message.
+    # @return [false] False if no chute can accept the message.
+    def accept(message)
+      @chutes.any? { |chute| chute.call(message) }
+    end
+    
+  end
+end

data/lib/mail_to_hip_chat/exceptions.rb

@@ -0,0 +1,4 @@
+module MailToHipChat
+  # Used to tag exceptions being raised from inside this library before they hit client code.
+  module InternalError; end
+end

data/lib/mail_to_hip_chat/message_chute.rb

@@ -0,0 +1,20 @@
+require "hipchat-api"
+
+module MailToHipChat
+  module MessageChute
+
+    def initialize(opts)
+      @rooms       = Array(opts[:rooms])
+      @hipchat_api = opts[:hipchat_api] || HipChat::API.new(opts[:api_token])
+    end
+    
+  private
+    
+    def message_rooms(from, message)
+      @rooms.each do |room_id| 
+        @hipchat_api.rooms_message(room_id, from, message)
+      end
+    end
+    
+  end
+end

data/lib/mail_to_hip_chat/message_chutes/airbrake.rb

@@ -0,0 +1,58 @@
+require "mail_to_hip_chat/message_chute"
+require "mustache"
+
+module MailToHipChat
+  module MessageChutes
+    class Airbrake
+      include MessageChute
+      
+      def call(params)
+        return false unless process_message(params["plain"])
+        true
+      end
+
+    private
+      
+      def airbrake_domain
+        "airbrake.io"
+      end
+      
+      def extraction_expression
+        %r[\A\n+Project:\s([^\n]+)\n+     # Pull out the project name
+                Environment:\s([^\n]+)\n+ # Pull out the project environment
+                # Pull out the URL to the exception
+                ^(http://[^.]+\.#{Regexp.escape(airbrake_domain)}/errors/\d+)\n+
+                # Pull out the first line of the error message
+                Error\sMessage:\n-{14}\n([^\n]+)]mx
+      end
+      
+      def hipchat_sender
+        "Airbrake"
+      end
+      
+      def message_template
+        %q[<b>{{project}} - {{environment}}</b><br /><a href="{{url}}">{{message}}</a>]
+      end
+      
+      def process_message(plaintext)
+        return nil unless parts = extract_parts(plaintext)
+        send_notifications(parts)
+        true
+      end
+                                     
+      def extract_parts(plaintext)
+        return nil unless parts = plaintext.match(extraction_expression)
+        [:project, :environment, :url, :message].each_with_index.inject({}) do |hash,(key,idx)|
+          hash[key] = parts[idx + 1]
+          hash
+        end
+      end
+      
+      def send_notifications(message_parts)
+        hipchat_message = Mustache.render(message_template, message_parts)
+        message_rooms(hipchat_sender, hipchat_message)
+      end
+      
+    end
+  end
+end

data/lib/mail_to_hip_chat/message_chutes/test_email.rb

@@ -0,0 +1,18 @@
+require "mail_to_hip_chat/message_chute"
+require "mustache"
+
+module MailToHipChat
+  module MessageChutes
+    class TestEmail
+      include MessageChute
+      
+      def call(params)
+        return false unless params["subject"] =~ /testing setup/i
+        message = Mustache.render("Message:<br />{{message}}", :message => params["plain"])
+        message_rooms("Testing", message)
+        true
+      end
+      
+    end
+  end
+end

data/lib/mail_to_hip_chat/rack_app/builder.rb

@@ -0,0 +1,47 @@
+require "mail_to_hip_chat/rack_app"
+require "rack/builder"
+require "rack/urlmap"
+require "rack/commonlogger"
+
+module MailToHipChat
+  class RackApp
+    class Builder
+      attr_accessor :secret, :rooms, :api_token, :mount_point
+      
+      def initialize
+        @chutes = []
+        @mount_point = '/notifications/create'
+        yield(self) if block_given?
+      end
+      
+      def use_chute(chute_klass)
+        @chutes << chute_klass
+      end
+      
+      def to_app
+        return @app if @app
+        app = build_app
+        mnt = mount_point
+        @app = Rack::Builder.new do
+          use Rack::CommonLogger
+          map(mnt) { run app }
+        end.to_app
+      end
+      
+    private
+
+      def build_app
+        MailToHipChat::RackApp.new(:secret => @secret) do |f|
+          @chutes.each do |chute_klass|
+            f.use_chute(chute_klass.new(:api_token => @api_token, :rooms => split_rooms))
+          end
+        end
+      end
+
+      def split_rooms
+        @rooms.split(/,\s*/)
+      end
+      
+    end
+  end
+end

data/lib/mail_to_hip_chat/rack_app.rb

@@ -0,0 +1,57 @@
+require "mail_to_hip_chat/rack_app/builder"
+require "mail_to_hip_chat/chute_chain"
+require "mail_to_hip_chat/exceptions"
+require "rack/request"
+require "digest/md5"
+
+module MailToHipChat
+  class RackApp
+    SIGNATURE_PARAM_NAME = "signature"
+  
+    def initialize(opts = {})
+      @secret      = opts[:secret]
+      @chute_chain = opts[:chute_chain] || ChuteChain.new
+    
+      yield(self) if block_given?
+    end
+  
+    def call(rack_env)
+      request = Rack::Request.new(rack_env)
+      return [400, {}, 'Bad Request.'] unless valid_request?(request)
+
+      if @chute_chain.accept(request.params)
+        [200, {}, 'OK']
+      else
+        [404, {}, 'Not Found.']
+      end
+    
+    rescue Exception => error
+      error.extend(InternalError)
+      raise error
+    end
+  
+    def use_chute(chute)
+      @chute_chain.push(chute)
+    end
+  
+  private
+  
+    def valid_request?(request)
+      computed_sig = create_sig_from_params(request.params)
+
+      computed_sig == request.params[SIGNATURE_PARAM_NAME]
+    end
+
+
+    def create_sig_from_params(params)
+      sorted_param_names = params.keys.sort
+      sorted_param_names.delete(SIGNATURE_PARAM_NAME)
+    
+      param_vals_with_secret = params.values_at(*sorted_param_names)
+      param_vals_with_secret.push(@secret)
+    
+      Digest::MD5.hexdigest(param_vals_with_secret.join)
+    end
+  
+  end
+end

data/lib/mail_to_hip_chat/version.rb

@@ -0,0 +1,3 @@
+module MailToHipChat
+  VERSION = "0.0.1"
+end

data/lib/mail_to_hip_chat.rb

@@ -0,0 +1,2 @@
+require "mail_to_hip_chat/version"
+require "mail_to_hip_chat/exceptions"

data/mail_to_hip_chat.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "mail_to_hip_chat/version"
+
+Gem::Specification.new do |s|
+  s.name        = "mail_to_hip_chat"
+  s.version     = MailToHipChat::VERSION
+  s.authors     = ["Gabriel Gironda"]
+  s.email       = ["gabriel@gironda.org"]
+  s.homepage    = ""
+  s.summary     = %q{Funnels email into HipChat}
+  s.description = %q{Funnels email into HipChat using CloudMailIn}
+
+  s.rubyforge_project = "mail_to_hip_chat"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "http_parser.rb", "~> 0.5"
+  s.add_development_dependency "mocha",          "~> 0.10"
+  s.add_development_dependency "yard",           "~> 0.7"
+  s.add_development_dependency "rdiscount",      "~> 1.6"
+  s.add_development_dependency "webmock",        "~> 1.7"
+  s.add_development_dependency "rake"
+  
+  s.add_runtime_dependency "rack",        "~> 1.3"
+  s.add_runtime_dependency "hipchat-api", "~> 1.0"
+  s.add_runtime_dependency "mustache",    "~> 0.99"
+end

data/support/config.ru

@@ -0,0 +1,18 @@
+require "mail_to_hip_chat"
+require "mail_to_hip_chat/rack_app"
+require "mail_to_hip_chat/message_chutes/airbrake"
+require "mail_to_hip_chat/message_chutes/test_email"
+
+app = MailToHipChat::RackApp::Builder.new do |builder|
+  builder.secret    = ENV['CLOUDMAILIN_SECRET']
+  builder.rooms     = ENV['HIPCHAT_ROOMS']
+  builder.api_token = ENV['HIPCHAT_API_TOKEN']
+  
+  # An included chute to process messages from Airbrake.
+  builder.use_chute MailToHipChat::MessageChutes::Airbrake
+
+  # This chute should be removed once you've confirmed your setup works.
+  builder.use_chute MailToHipChat::MessageChutes::TestEmail
+end.to_app
+
+run app

data/test/fixtures/airbrake_exception_body.txt

@@ -0,0 +1,27 @@
+
+
+Project: Echelon
+Environment: Staging
+
+
+http://the-nsa.airbrake.io/errors/11082122
+
+Error Message:
+--------------
+AirbrakeTestingException: Testing airbrake via "rake airbrake:test". If you can see this, it works.
+
+Where:
+------
+application#verify
+[PROJECT_ROOT]/vendor/bundle/ruby/1.9.1/gems/activesupport-3.1.0/lib/active_support/callbacks.rb, line 412
+
+URL:
+----
+http://example.org/verify
+
+Backtrace Summary:
+------------------
+[PROJECT_ROOT]/lib/sha1_unhasher.rb:13:in `block in _call'
+[PROJECT_ROOT]/lib/sha1_unhasher.rb.rb:12:in `_call'
+[PROJECT_ROOT]/lib/sha1_unhasher.rb.rb:7:in `call'
+