incoming 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013, Honeybadger Industries LLC
+
+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,138 @@
+Incoming!
+-----------
+
+Incoming! helps you receive email in your Rack apps.
+
+Brought to you by :zap: **Honeybadger.io**, painless [Rails exception tracking](https://www.honeybadger.io/).
+
+## Sendgrid example:
+
+```ruby
+class EmailReceiver < Incoming::Strategies::Sendgrid
+  def receive(mail)
+    puts %(Got message from #{mail.to.first} with subject "#{mail.subject}")
+  end
+end
+
+req = Rack::Request.new(env)
+result = EmailReceiver.receive(req) # => Got message from whoever@wherever.com with subject "hello world"
+```
+
+## Mailgun example:
+
+```ruby
+class EmailReceiver < Incoming::Strategies::Mailgun
+  setup :api_key => 'asdf'
+
+  def receive(mail)
+    puts %(Got message from #{mail.to.first} with subject "#{mail.subject}")
+  end
+end
+
+req = Rack::Request.new(env)
+result = EmailReceiver.receive(req) # => Got message from whoever@wherever.com with subject "hello world"
+```
+
+## Postmark example:
+
+```ruby
+class EmailReceiver < Incoming::Strategies::Postmark
+  def receive(mail)
+    puts %(Got message from #{mail.to.first} with subject "#{mail.subject}")
+  end
+end
+
+req = Rack::Request.new(env)
+result = EmailReceiver.receive(req) # => Got message from whoever@wherever.com with subject "hello world"
+```
+
+## CloudMailin example:
+
+Use the Raw Format when setting up your address target.
+
+```ruby
+class EmailReceiver < Incoming::Strategies::CloudMailin
+  def receive(mail)
+    puts %(Got message from #{mail.to.first} with subject "#{mail.subject}")
+  end
+end
+
+req = Rack::Request.new(env)
+result = EmailReceiver.receive(req) # => Got message from whoever@wherever.com with subject "hello world"
+```
+
+## Postfix example:
+
+```ruby
+class EmailReceiver < Incoming::Strategies::HTTPPost
+  setup :secret => '6d7e5337a0cd69f52c3fcf9f5af438b1'
+
+  def receive(mail)
+    puts %(Got message from #{mail.to.first} with subject "#{mail.subject}")
+  end
+end
+
+req = Rack::Request.new(env)
+result = EmailReceiver.receive(req) # => Got message from whoever@wherever.com with subject "hello world"
+```
+
+```
+# Postfix virtual alias
+http_post: "|http_post -s 6d7e5337a0cd69f52c3fcf9f5af438b1 http://www.example.com/emails"
+```
+
+## Example Rails controller
+
+```ruby
+# app/controllers/emails_controller.rb
+class EmailsController < ActionController::Base
+  def create
+    if EmailReceiver.receive(request)
+      render :json => { :status => 'ok' }
+    else
+      render :json => { :status => 'rejected' }, :status => 403
+    end
+  end
+end
+```
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  post '/emails' => 'emails#create'
+end
+```
+
+```ruby
+# spec/controllers/emails_controller_spec.rb
+require 'spec_helper'
+
+describe EmailsController, '#create' do
+  it 'responds with success when request is valid' do
+    EmailReceiver.should_receive(:receive).and_return(true)
+    post :create
+    response.should be_success
+    response.body.should eq '{"status":"ok"}'
+  end
+
+  it 'responds with 403 when request is invalid' do
+    EmailReceiver.should_receive(:receive).and_return(false)
+    post :create
+    response.status.should eq 403
+    response.body.should eq '{"status":"rejected"}'
+  end
+end
+```
+
+## Contributing
+
+1. Fork it.
+2. Create a topic branch `git checkout -b my_branch`
+3. Commit your changes `git commit -am "Boom"`
+3. Push to your branch `git push origin my_branch`
+4. Send a [pull request](https://github.com/honeybadger-io/incoming/pulls)
+
+## License
+
+Incoming! is Copyright 2013 © Honeybadger Industries LLC. It is free software, and
+may be redistributed under the terms specified in the MIT-LICENSE file.

data/Rakefile

@@ -0,0 +1,97 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'date'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def date
+  Date.today.to_s
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
+end
+
+#############################################################################
+#
+# Packaging tasks
+#
+#############################################################################
+
+desc "Create tag v#{version} and build and push #{gem_file} to Rubygems"
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh "git push origin master"
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{name}-#{version}.gem"
+end
+
+desc "Build #{gem_file} into the pkg directory"
+task :build => :gemspec do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+desc "Generate #{gemspec_file}"
+task :gemspec => :validate do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+
+  # replace name version and date
+  replace_header(spec, :name)
+  replace_header(spec, :version)
+  replace_header(spec, :date)
+
+  # piece file back together and write
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end
+
+desc "Validate #{gemspec_file}"
+task :validate do
+  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}", "lib/tasks", "lib/generators"]
+  unless libfiles.empty?
+    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
+    exit!
+  end
+  unless Dir['VERSION*'].empty?
+    puts "A `VERSION` file at root level violates Gem best practices."
+    exit!
+  end
+end

data/bin/http_post

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+
+require 'incoming'
+require 'net/http'
+require 'uri'
+require 'openssl'
+require 'securerandom'
+require 'optparse'
+
+options = {
+  secret: nil
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: http_post [options] [http endpoint] < input"
+  opts.on('-s', '--secret [secret]') { |s| options[:secret] = s }
+
+  opts.parse!
+end
+
+begin
+  http_endpoint = URI.parse(ARGV[0])
+rescue URI::InvalidURIError
+  puts 'Unable to parse http endpoint. Is it a valid URI?'
+  exit
+end
+
+timestamp = Time.now.to_i
+token = SecureRandom.hash
+signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('SHA256'), options[:secret], [timestamp, token].join)
+
+data = { :message => STDIN.read, :timestamp => timestamp, :token => token, :signature => signature }
+headers = {}
+
+req = Net::HTTP::Post.new(http_endpoint.path, headers)
+req.form_data = data
+req.basic_auth http_endpoint.user, http_endpoint.password if http_endpoint.user
+
+resp, data = Net::HTTP.new(http_endpoint.host, http_endpoint.port).start {|http|
+  http.request(req)
+}
+
+puts resp.body

data/lib/incoming.rb

@@ -0,0 +1,14 @@
+require 'mail'
+require 'incoming/strategy'
+
+module Incoming
+  VERSION = '0.1.0'
+
+  module Strategies
+    autoload :Sendgrid, 'incoming/strategies/sendgrid'
+    autoload :Mailgun, 'incoming/strategies/mailgun'
+    autoload :Postmark, 'incoming/strategies/postmark'
+    autoload :CloudMailin, 'incoming/strategies/cloudmailin'
+    autoload :HTTPPost, 'incoming/strategies/http_post'
+  end
+end

data/lib/incoming/strategies/cloudmailin.rb

@@ -0,0 +1,12 @@
+module Incoming
+  module Strategies
+    class CloudMailin
+      include Incoming::Strategy
+
+      def initialize(request)
+        @message = Mail.new(request.params.delete(:message))
+      end
+    end
+  end
+end
+

data/lib/incoming/strategies/http_post.rb

@@ -0,0 +1,25 @@
+module Incoming
+  module Strategies
+    class HTTPPost
+      include Incoming::Strategy
+
+      option :secret
+
+      attr_accessor :signature, :token, :timestamp
+
+      def initialize(request)
+        params = request.params
+
+        @signature = params.delete(:signature)
+        @token = params.delete(:token)
+        @timestamp = params.delete(:timestamp)
+        @message = Mail.new(params.delete(:message))
+      end
+
+      def authenticate
+        hexdigest = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('SHA256'), self.class.default_options[:secret], [timestamp, token].join)
+        hexdigest.eql?(signature) or false
+      end
+    end
+  end
+end

data/lib/incoming/strategies/mailgun.rb

@@ -0,0 +1,72 @@
+require 'json'
+
+module Incoming
+  module Strategies
+    # Public: MailGun Incoming! Mail Strategy
+    #
+    # API Documentation:
+    # http://documentation.mailgun.net/user_manual.html#receiving-messages
+    #
+    # Examples:
+    #
+    #   class MailReceiver < Incoming::Strategies::Mailgun
+    #     setup api_key: 'asdf'
+    #
+    #     def receive(mail)
+    #       puts "Got message from mailgun: #{mail.subject}"
+    #     end
+    #   end
+    class Mailgun
+      include Incoming::Strategy
+
+      # Mailgun API key
+      option :api_key
+
+      # Use the stripped- parameters from the Mailgun API (strips out quoted parts and signatures)
+      option :stripped, false
+
+      attr_accessor :signature, :token, :timestamp
+
+      def initialize(request)
+        params = request.params
+
+        if self.class.default_options[:api_key].nil?
+          raise RequiredOptionError.new(':api_key option is required.')
+        end
+
+        @signature = params['signature']
+        @token = params['token']
+        @timestamp = params['timestamp']
+
+        html_content = params[ self.class.default_options[:stripped] ? 'stripped-html' : 'body-html' ]
+        text_content = params[ self.class.default_options[:stripped] ? 'stripped-text' : 'body-plain' ]
+
+        @message = Mail.new do
+          headers Hash[JSON.parse(params['message-headers'])]
+          from params['from']
+          to params['recipient']
+          subject params['subject']
+
+          body text_content
+
+          html_part do
+            content_type 'text/html; charset=UTF-8'
+            body html_content
+          end if html_content
+
+          1.upto(params['attachment-count'].to_i).each do |num|
+            attachment = params["attachment-#{num}"]
+            add_file(:filename => attachment.original_filename, :content => attachment.read)
+          end
+        end
+      end
+
+      def authenticate
+        api_key = self.class.default_options[:api_key]
+
+        hexdigest = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('SHA256'), api_key, [timestamp, token].join)
+        hexdigest.eql?(signature) or false
+      end
+    end
+  end
+end

data/lib/incoming/strategies/postmark.rb

@@ -0,0 +1,35 @@
+require 'postmark_mitt'
+require 'base64'
+
+module Incoming
+  module Strategies
+    class Postmark
+      include Incoming::Strategy
+
+      def initialize(request)
+        email = ::Postmark::Mitt.new(request.body.read)
+
+        @attachments = email.attachments
+
+        @message = Mail.new do
+          headers email.headers
+          from email.from
+          to email.to
+          reply_to email.reply_to
+          subject email.subject
+
+          body email.text_body
+
+          html_part do
+            content_type 'text/html; charset=UTF-8'
+            body email.html_body
+          end if email.html_body
+
+          email.attachments.each do |a|
+            add_file :filename => a.file_name, :content => Base64.decode64(a.source['Content'])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/incoming/strategies/sendgrid.rb

@@ -0,0 +1,34 @@
+module Incoming
+  module Strategies
+    class Sendgrid
+      include Incoming::Strategy
+
+      def initialize(request)
+        params = request.params.dup
+        envelope = JSON.parse(params['envelope'])
+
+        # TODO: Properly handle encodings
+        # encodings = JSON.parse(params['charsets'])
+
+        @message = Mail.new do
+          header params['headers']
+          from params['from']
+          to envelope['to'].first
+          subject params['subject']
+
+          body params['text']
+
+          html_part do
+            content_type 'text/html; charset=UTF-8'
+            body params['html']
+          end if params['html']
+
+          1.upto(params['attachments'].to_i).each do |num|
+            attachment = params["attachment#{num}"]
+            add_file(:filename => attachment.original_filename, :content => attachment.read)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/incoming/strategy.rb

@@ -0,0 +1,106 @@
+module Incoming
+  module Strategy
+    def self.included(base)
+      base.extend ClassMethods
+      base.class_eval do
+        attr_reader :options
+      end
+    end
+
+    class RequiredOptionError < StandardError ; end
+    class InvalidOptionError < StandardError ; end
+
+    module ClassMethods
+      # Public: Global receiver
+      #
+      # args - Arguments used to initialize strategy. Should be defined
+      #        by `initialize` method in strategy class.
+      #
+      # Returns nothing
+      def receive(*args)
+        strategy = new(*args)
+        strategy.authenticate and strategy.receive(strategy.message)
+      end
+
+      # Public
+      # Returns an inherited set of default options set at the class-level
+      # for each strategy.
+      def default_options
+        return @default_options if @default_options
+        @default_options = superclass.respond_to?(:default_options) ? superclass.default_options : {}
+      end
+
+      # Public: Defines a valid class-level option for strategy
+      #
+      # Examples:
+      #
+      #   class Incoming::Strategies::MyStrategy
+      #     include Incoming::Strategy
+      #     option :api_key
+      #     option :mime, false
+      #   end
+      #
+      # Returns nothing
+      def option(name, value = nil)
+        default_options[name] = value
+      end
+
+      # Public: Configures strategy-specific options.
+      #
+      # opts  - A hash of valid options.
+      #
+      # Examples:
+      #
+      #   class MailReceiver < Incoming::Strategies::MyStrategy
+      #     setup api_key: 'asdf', mime: true
+      #   end
+      #
+      # Returns nothing
+      def setup(opts = {})
+        opts.keys.each do |key|
+          next if default_options.keys.include?(key)
+          raise InvalidOptionError.new(":#{key} is not a valid option for #{self.superclass.name}.")
+        end
+
+        @default_options = default_options.merge(opts)
+      end
+    end
+
+    # Public: A Mail::Message object, constructed by #initialize
+    attr_accessor :message
+
+    # Public: Translates arguments into a Mail::Message object
+    def initialize(*args) ; end
+
+    protected
+
+    # Protected: Evaluates message and performs appropriate action.
+    # Override in subclass
+    #
+    # mail - A Mail::Message object
+    #
+    # Returns nothing
+    def receive(mail)
+      raise NotImplementedError.new('You must implement #receive')
+    end
+
+    # Protected: Authenticates request before performing #receive
+    #
+    # Examples:
+    #
+    #   class MailReceiver < Incoming::Strategies::MyStrategy
+    #     def initialize(request)
+    #       @secret_word = request.params['secret_word']
+    #     end
+    #
+    #     def protected
+    #       @secret_word == 'my secret word'
+    #     end
+    #   end
+    #
+    # Returns true by default
+    def authenticate
+      true
+    end
+  end
+end

metadata

@@ -0,0 +1,157 @@
+--- !ruby/object:Gem::Specification
+name: incoming
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Joshua Wood
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.4.1
+- !ruby/object:Gem::Dependency
+  name: postmark-mitt
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.0.11
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.0.11
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Incoming! standardizes various mail parse apis, making it a snap to receive
+  emails through HTTP post hooks.
+email:
+- josh@honeybadger.io
+executables:
+- http_post
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/incoming/strategies/cloudmailin.rb
+- lib/incoming/strategies/http_post.rb
+- lib/incoming/strategies/mailgun.rb
+- lib/incoming/strategies/postmark.rb
+- lib/incoming/strategies/sendgrid.rb
+- lib/incoming/strategy.rb
+- lib/incoming.rb
+- MIT-LICENSE
+- Rakefile
+- README.md
+- bin/http_post
+homepage: https://www.honeybadger.io/
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -2639697308401258513
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.8.25
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Incoming! helps you receive email in your Rack apps.
+test_files: []