mail_gate 1.0.0

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/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake'
+
+group :test do
+  gem 'mail'
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Garrett Bjerkhoel
+
+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,129 @@
+MailGate [![Build Status](https://secure.travis-ci.org/dewski/mail_gate.png)](http://travis-ci.org/dewski/mail_gate)
+========
+
+MailGate is an additional delivery method for the [Mail](https://github.com/mikel/mail) gem that lets you restrict the delivery of mail to only whitelisted emails. Ideal for staging environments where you may be using production data and do not want them to recieve emails from your mailers when you submit comments, contact forms, or anything else that may trigger mail delivery.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'mail_gate'
+
+And then run:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mail_gate
+
+## Usage
+
+MailGate works as a standalone extension to the [Mail](https://github.com/mikel/mail) gem or as a delivery method within Rails applications.
+
+To configure MailGate, edit your ActionMailer configuration to use `:mail_gate` as the delivery method, then copy your existing settings to  `mail_gate_settings`:
+
+```ruby
+# config/environments/staging.rb
+CNN::Application.configure do
+  config.action_mailer.delivery_method = :smtp
+  config.action_mailer.smtp_settings = {
+    :address        => 'smtp.sendgrid.net',
+    :port           => '25',
+    :authentication => :plain,
+    :user_name      => ENV['SENDGRID_USERNAME'],
+    :password       => ENV['SENDGRID_PASSWORD'],
+    :domain         => ENV['SENDGRID_DOMAIN']
+  }
+end
+```
+
+Becomes:
+
+```ruby
+# config/environments/staging.rb
+CNN::Application.configure do
+  config.action_mailer.delivery_method = :mail_gate
+  config.action_mailer.mail_gate_settings = {
+    :whitelist        => /cnn.com/,
+    :delivery_method  => :smtp,
+    :delivery_settings => {
+      :address        => 'smtp.sendgrid.net',
+      :port           => '25',
+      :authentication => :plain,
+      :user_name      => ENV['SENDGRID_USERNAME'],
+      :password       => ENV['SENDGRID_PASSWORD'],
+      :domain         => ENV['SENDGRID_DOMAIN']
+    }
+  }
+end
+```
+
+By default the emails send will have the same subject that they normally would. If you'd like to customize the subject to inform the reader where it was sent from you can do that with the `:subject_prefix` option:
+
+```ruby
+# config/environments/staging.rb
+CNN::Application.configure do
+  config.action_mailer.delivery_method = :mail_gate
+  config.action_mailer.mail_gate_settings = {
+    :whitelist        => /cnn.com/,
+    :subject_prefix   => '[Staging] ',
+    # ...
+  }
+end
+```
+
+Now your emails that are sent will have `[Staging] New comment on your article!` as the subject rather than just `New comment on your article!`. It's entirely up to you what you may put as the prefix, be it the current deploy git SHA, or if you want to send the server's hostname that sent the mail.
+
+Email now sent within the staging environment will extract any recipient emails that don't match the whitelist. If after being filtered there aren't any recipients left because they were filtered out, no email will be sent:
+
+```
+> Article.first.comments.each do |comment|
+>   "Email for: #{comment.user.email}"
+>   ArticleMailer.new_comment(article, comment).deliver
+> end
+=> Email for: john.doe@gmail.com
+=> Email for: megatron@transformers.com
+=> Email for: george@cnn.com
+=> #<Mail::Message:70236177475420, Headers: <From: no-reply@cnn.com>, <To: george@cnn.com>, <Subject: [Staging] New comment on your article!>>
+```
+
+Notice only the email for `george@cnn.com` was delivered.
+
+## Using MailGate outside of Rails
+
+If you have a Sinatra app or just using the Mail library in your Ruby project you can still use MailGate:
+
+```ruby
+require 'mail_gate'
+
+Mail.defaults do
+  delivery_method MailGate::Filter,
+    :whitelist => /cnn.com/,
+    :subject_prefix => '[local] ',
+    :delivery_method => :file,
+    :location => '/dev/null'
+end
+```
+
+Then just deliver the email as normal:
+
+```ruby
+Mail.deliver do
+  to 'george@cnn.com'
+  from 'no-reply@cnn.com'
+  subject 'Testing MailGate'
+  body 'Hi! :)'
+end
+```
+
+## Contributing
+
+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
+
+## Copyright
+Copyright © 2012 Garrett Bjerkhoel. See [LICENSE](https://github.com/dewski/mail_gate/blob/master/LICENSE) for details.

data/Rakefile

@@ -0,0 +1,20 @@
+#!/usr/bin/env rake
+require 'rubygems'
+require 'rake/testtask'
+begin
+  require 'bundler/setup'
+  Bundler::GemHelper.install_tasks
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+desc 'Default: run tests'
+task :default => :test
+
+desc 'Run MailGate tests.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end

data/lib/mail_gate.rb

@@ -0,0 +1,5 @@
+require 'mail_gate/version'
+
+module MailGate
+  autoload :Filter, 'mail_gate/filter'
+end

data/lib/mail_gate/filter.rb

@@ -0,0 +1,86 @@
+module MailGate
+  # MailGate class restricts email delivery to non-whitelisted emails.
+  #
+  # Each element within the whitelist needs to be a Regex object.
+  #
+  # To use MailGate within a Rails project, configure a specific environment
+  # file or global configuration using the mail_gate delivery method:
+  #
+  #   config.action_mailer.delivery_method = :mail_gate
+  #   config.action_mailer.mail_gate_settings = {
+  #     :whitelist => /evil.com|allowed@site.com/
+  #   }
+  #
+  # If you aren't using MailGate within a Rails application, you can still
+  # configure Mail to use it as it's default delivery_method.
+  #
+  #   Mail.defaults do
+  #     delivery_method MailGate::Filter, :whitelist => /application.com/
+  #   end
+  #
+  class Filter
+    attr_accessor :settings
+
+    # The Regexp to compare emails against.
+    attr_accessor :whitelist
+
+    def initialize(settings = {})
+      self.settings = settings
+      @whitelist = Regexp.new(settings.delete(:whitelist) || /.*/)
+      delivery_method = settings.fetch(:delivery_method, :test)
+      delivery_settings = settings.fetch(:delivery_settings, {})
+      @delivery_method = Mail::Configuration.instance.lookup_delivery_method(delivery_method).new(delivery_settings)
+    end
+
+    # Public: Filter out recipients who may match the whitelist regex.
+    # If no emails are present after being filtered, don't deliver the email. 
+    #
+    # mail - Mail object containing headers and body.
+    #
+    # Returns instance of Mail::Message.
+    def deliver!(mail)
+      %w{ to cc bcc }.each do |field|
+        mail.send(:"#{field}=", filter_emails(mail.send(field)))
+      end
+
+      if settings[:subject_prefix]
+        mail.subject = settings[:subject_prefix] + mail.subject
+      end
+
+      @delivery_method.deliver!(mail) unless mail.to.blank?
+
+      mail
+    end
+
+    private
+
+    # Private: Filter out any emails that match the whitelist regex.
+    #
+    # emails - List of emails to filter through.
+    #
+    # Examples
+    #
+    #   Given [/hacking.com/] being the whitelist.
+    #
+    #   filter_emails('me@garrettbjerkhoel.com')
+    #   # => nil
+    #
+    #   filter_emails(['me@garrettbjerkhoel.com', 'evil@hacking.com'])
+    #   # => 'garrett@github.com'
+    #
+    #   filter_emails(['matt@github.com', 'garrett@github.com'])
+    #   # => ['matt@github.com', 'garrett@github.com']
+    #
+    # Returns array of emails if the list is greater than one, if only one item
+    # return just that single email, if empty, return nil to reset the field.
+    def filter_emails(emails)
+      return if emails.blank?
+
+      email_list = Array(emails).select do |recipient|
+        recipient.to_s =~ @whitelist
+      end
+
+      email_list.length > 1 ? email_list : email_list.shift
+    end
+  end
+end

data/lib/mail_gate/railtie.rb

@@ -0,0 +1,7 @@
+module MailGate
+  class Railtie < Rails::Railtie
+    config.before_configuration do
+      ActionMailer::Base.add_delivery_method :mail_gate, MailGate::Filter
+    end
+  end
+end

data/lib/mail_gate/version.rb

@@ -0,0 +1,3 @@
+module MailGate
+  VERSION = '1.0.0'
+end

data/mail_gate.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/mail_gate/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ['Garrett Bjerkhoel']
+  gem.email         = ['me@garrettbjerkhoel.com']
+  gem.description   = %q{MailGate is an additional delivery method for the Mail gem that lets you restrict the delivery of mail to only whitelisted emails.}
+  gem.summary       = %q{MailGate is an additional delivery method for the Mail gem that lets you restrict the delivery of mail to only whitelisted emails.}
+  gem.homepage      = 'https://github.com/dewski/mail_gate'
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = 'mail_gate'
+  gem.require_paths = ['lib']
+  gem.version       = MailGate::VERSION
+
+  gem.add_dependency 'mail', '~> 2.4.1'
+end

data/test/test_helper.rb

@@ -0,0 +1,43 @@
+require 'rubygems'
+require 'bundler'
+Bundler.setup(:default, :test)
+Bundler.require(:default, :test)
+
+dir = File.dirname(File.expand_path(__FILE__))
+$LOAD_PATH.unshift dir + '/../lib'
+$TESTING = true
+require 'test/unit'
+require 'mail_gate'
+
+class Test::Unit::TestCase
+  # Return a stubbed mail object helpful for writing unit tests.
+  #
+  # options - The Hash options used to refine the selection (default: {}):
+  #           :whitelist      - The Regex to match against emails (optional).
+  #           :subject_prefix - The String to be prepended to the subject (optional).
+  #           :from           - The email responsible for sending the email (optional) (default: test@mail_gate.com).
+  #           :to             - The Array or String of emails for the to field (optional).
+  #           :cc             - The Array or String of emails for the cc field (optional).
+  #           :bcc            - The Array or String of emails for the bcc field (optional).
+  #
+  # Examples
+  #
+  #   mail = with_whitelist :to => 'test@email.com'
+  #   # => #<Mail::Message to: "test@email.com">
+  #
+  # Returns instance of Mail::Message.
+  def with_whitelist(options={})
+    filter = MailGate::Filter.new \
+      :whitelist => options.delete(:whitelist),
+      :subject_prefix => options.delete(:subject_prefix)
+
+    mail = Mail.new options.merge(:from => 'test@mail_gate.com')
+
+    filter.deliver!(mail)
+  end
+end
+
+Mail.defaults do
+  delivery_method :test
+end
+

data/test/unit/mail_gate/filter_test.rb

@@ -0,0 +1,78 @@
+require 'test_helper'
+
+class TestFilter < Test::Unit::TestCase
+  def test_without_whitelist_regex
+    mail = with_whitelist :to => 'garrett@site.com'
+    assert_equal %w{ garrett@site.com }, mail.to
+  end
+
+  def test_with_whitelist_as_string
+    mail = with_whitelist \
+      :to => 'garrett@site.com',
+      :whitelist => '@site.com'
+    assert_equal %w{ garrett@site.com }, mail.to
+  end
+
+  def test_with_no_matching_whitelist
+    mail = with_whitelist \
+      :to => 'garrett@site.com',
+      :whitelist => /cnn.com/
+    assert mail.to.blank?, 'no mail values'
+  end
+
+  def test_to_field_whitelisted_emails
+    mail = with_whitelist \
+      :to => %w{ garrett@site.com matt@site.com non-staff@user.com },
+      :whitelist => /site.com/
+
+    assert_equal %w{ garrett@site.com matt@site.com }, mail.to
+  end
+
+  def test_to_field_domain_and_user_whitelist
+    mail = with_whitelist \
+      :to => %w{ garrett@site.com someone@special.com },
+      :whitelist => /site.com|someone@special.com/
+
+    assert_equal %w{ garrett@site.com someone@special.com }, mail.to
+  end
+
+  def test_cc_field_domain_and_user_whitelist
+    mail = with_whitelist \
+      :to => %w{ garrett@site.com matt@site.com },
+      :cc => 'george@whitehouse.gov',
+      :whitelist => /site.com/
+
+    assert_equal %w{ garrett@site.com matt@site.com }, mail.to
+    assert mail.cc.blank?, 'no cc field'
+  end
+
+  def test_bcc_field_domain_and_user_whitelist
+    mail = with_whitelist \
+      :to => %w{ garrett@site.com matt@site.com },
+      :bcc => 'luke@skywalker.com',
+      :whitelist => /site.com/
+
+    assert_equal %w{ garrett@site.com matt@site.com }, mail.to
+    assert mail.cc.blank?, 'no cc field'
+    assert mail.bcc.blank?, 'no bcc field'
+  end
+
+  def test_bcc_field_domain_and_user_whitelist
+    mail = with_whitelist \
+      :to => %w{ garrett@site.com matt@site.com },
+      :bcc => %w{ luke@skywalker.com luke@copy.com },
+      :whitelist => /site.com|copy.com/
+
+    assert_equal %w{ garrett@site.com matt@site.com }, mail.to
+    assert_equal %w{ luke@copy.com }, mail.bcc
+  end
+
+  def test_settings_prefix
+    mail = with_whitelist \
+      :to => 'garrett@site.com',
+      :subject => 'Welcome to the site!',
+      :subject_prefix => '[staging] '
+
+    assert_equal '[staging] Welcome to the site!', mail.subject
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: mail_gate
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Garrett Bjerkhoel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: &70328114755100 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *70328114755100
+description: MailGate is an additional delivery method for the Mail gem that lets
+  you restrict the delivery of mail to only whitelisted emails.
+email:
+- me@garrettbjerkhoel.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/mail_gate.rb
+- lib/mail_gate/filter.rb
+- lib/mail_gate/railtie.rb
+- lib/mail_gate/version.rb
+- mail_gate.gemspec
+- test/test_helper.rb
+- test/unit/mail_gate/filter_test.rb
+homepage: https://github.com/dewski/mail_gate
+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: -2561250797758868510
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -2561250797758868510
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.17
+signing_key: 
+specification_version: 3
+summary: MailGate is an additional delivery method for the Mail gem that lets you
+  restrict the delivery of mail to only whitelisted emails.
+test_files:
+- test/test_helper.rb
+- test/unit/mail_gate/filter_test.rb