mail_safe 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Myron Marston
+
+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.rdoc

@@ -0,0 +1,65 @@
+= mail_safe
+
+Mail safe provides a safety net while you're developing an application that uses ActionMailer.
+It keeps emails from escaping into the wild.
+
+Once you've installed and configured this gem, you can rest assure that your app won't send
+emails to external email addresses.  Instead, emails that would normally be delivered to external
+addresses will be sent to an address of your choosing, and the body of the email will be appended
+with a note stating where the email was originally intended to go.
+
+== Download
+
+Github: http://github.com/myronmarston/mail_safe/tree/master
+
+Gem:
+  gem install myronmarston-mail_safe --source http://gems.github.com
+
+== Usage
+
+Load the gem in your non-production environments using Rails' 2.1+ gem support.  For example, I'm loading this in
+config/environments/development.rb and config/environments/staging.rb:
+
+  config.gem 'myronmarston-mail_safe', :lib => 'mail_safe', :source => 'http://gems.github.com'
+
+Be sure not to load this in your production or test environment, otherwise, your emails won't be sent to the proper
+recipients.  (The Rails test environment ensures that no emails are ever sent.)
+
+Next, configure mail safe.  Create a file at config/initializers/mail_safe.rb, similar to the following:
+
+  if defined?(MailSafe::Config)
+    MailSafe::Config.internal_address_definition = /.*@my-domain\.com/i
+    MailSafe::Config.replacement_address = 'me@my-domain.com'
+  end
+
+The internal address definition determines which addresses will be ignored (i.e. sent normally) and which will be replaced.  Email being sent to internal
+addresses will be sent normally; all other email addresses will be replaced by the replacement address.
+
+These settings can also take procs if you need something more flexible:
+
+  if defined?(MailSafe::Config)
+    # Emails sent to addresses longer than 15 characters long will be sent to the replacement address instead.
+    MailSafe::Config.internal_address_definition = lambda { |address| address.size <= 15 }
+
+    # Useful if your mail server allows + dynamic email addresses like gmail.
+    MailSafe::Config.replacement_address = lambda { |address| "my-address+#{address.gsub(/[\w\-.]/, '_')}@gmail.com" }
+  end
+
+When mail safe replaces an email address, it appends a notice to the bottom of the email body, such as:
+
+  **************************************************
+  This email originally had different recipients,
+  but MailSafe has prevented it from being sent to them.
+
+  The original recipients were:
+  - to:
+   - external-address-1@domain.com
+   - external-address-2@domain.com
+  - cc:
+   - external-address-3@domain.com
+
+  **************************************************
+
+== Copyright
+
+Copyright (c) 2009 Myron Marston, Kashless.org. See LICENSE for details.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 1
+:patch: 0
+:major: 0

data/lib/mail_safe.rb

@@ -0,0 +1,8 @@
+require 'active_support'
+require 'action_mailer'
+
+require 'mail_safe/config'
+require 'mail_safe/action_mailer'
+require 'mail_safe/address_replacer'
+
+ActionMailer::Base.send(:include, MailSafe::ActionMailer) unless ActionMailer::Base.ancestors.include?(MailSafe::ActionMailer)

data/lib/mail_safe/action_mailer.rb

@@ -0,0 +1,14 @@
+module MailSafe
+  module ActionMailer
+    def self.included(base)
+      base.class_eval do
+        alias_method_chain :deliver!, :mail_safe
+      end
+    end
+
+    def deliver_with_mail_safe!(mail = @mail)
+      MailSafe::AddressReplacer.replace_external_addresses(mail) if mail
+      deliver_without_mail_safe!(mail)
+    end
+  end
+end

data/lib/mail_safe/address_replacer.rb

@@ -0,0 +1,113 @@
+module MailSafe
+  class AddressReplacer
+    class << self
+      include ::ActionMailer::Utils
+      ADDRESS_TYPES = [:to, :cc, :bcc].freeze
+
+      def replace_external_addresses(mail)
+        replaced_addresses = {}
+
+        ADDRESS_TYPES.each do |address_type|
+          if addresses = mail.send(address_type)
+            new_addresses = []
+
+            addresses.each do |a|
+              new_addresses << if MailSafe::Config.is_internal_address?(a)
+                a
+              else
+                (replaced_addresses[address_type] ||= []) << a
+                MailSafe::Config.get_replacement_address(a)
+              end
+            end
+
+            mail.send("#{address_type}=", new_addresses)
+          end
+        end
+
+        self.add_body_postscript(mail, replaced_addresses)
+      end
+
+      protected
+
+      def add_body_postscript(part, replaced_addresses)
+        return unless replaced_addresses.size > 0
+
+        case part.content_type
+          when 'text/plain' then add_text_postscript(part, replaced_addresses)
+          when 'text/html'  then add_html_postscript(part, replaced_addresses)
+        end
+
+        part.parts.each { |p| add_body_postscript(p, replaced_addresses) }
+      end
+
+      def add_text_postscript(part, replaced_addresses)
+        address_type_postscripts = []
+        ADDRESS_TYPES.each do |address_type|
+          next unless addresses = replaced_addresses[address_type]
+          address_type_postscripts << "- #{address_type}:\n  - #{addresses.join("\n  - ")}"
+        end
+
+        postscript = <<-EOS
+
+
+**************************************************
+This email originally had different recipients,
+but MailSafe has prevented it from being sent to them.
+
+The original recipients were:
+#{address_type_postscripts.join("\n\n")}
+
+**************************************************
+        EOS
+
+        set_part_body(part, part.body + postscript)
+      end
+
+      def add_html_postscript(part, replaced_addresses)
+        address_type_postscripts = []
+        ADDRESS_TYPES.each do |address_type|
+          next unless addresses = replaced_addresses[address_type]
+          address_type_postscripts << "#{address_type}:<ul>\n<li>#{addresses.join("</li>\n<li>")}</li>\n</ul>"
+        end
+
+        postscript = <<-EOS
+          <div class="mail-safe-postscript">
+            <hr />
+
+            <p>
+              This email originally had different recipients,
+              but MailSafe has prevented it from being sent to them.
+            </p>
+
+            <p>
+              The original recipients were:
+            </p>
+
+            <ul>
+              <li>
+                #{address_type_postscripts.join("</li>\n<li>")}
+              </li>
+            </ul>
+
+            <hr/ >
+          </div>
+        EOS
+
+        set_part_body(part, part.body + postscript)
+      end
+
+      def set_part_body(part, body)
+        # taken from action mailer:
+        # http://github.com/rails/rails/blob/05d7409ae5fd423be6f747ad553f659fcecbf548/actionmailer/lib/action_mailer/part.rb#L58-65
+        case part.content_transfer_encoding.to_s.downcase
+          when "base64" then
+            part.body = TMail::Base64.folding_encode(body)
+          when "quoted-printable"
+            part.body = [normalize_new_lines(body)].pack("M*")
+          else
+            part.body = body
+        end
+      end
+    end
+  end
+end

data/lib/mail_safe/config.rb

@@ -0,0 +1,25 @@
+module MailSafe
+  class InvalidConfigSettingError < StandardError; end
+
+  class Config
+    cattr_accessor :internal_address_definition
+
+    def self.is_internal_address?(address)
+      case internal_address_definition
+        when Regexp then address =~ internal_address_definition
+        when Proc   then internal_address_definition.call(address)
+        else raise InvalidConfigSettingError.new("internal_address_definition must be a Regexp or Proc, but was: #{internal_address_definition.class.to_s}")
+      end
+    end
+
+    cattr_accessor :replacement_address
+
+    def self.get_replacement_address(original_address)
+      case replacement_address
+        when String then replacement_address
+        when Proc   then replacement_address.call(original_address)
+        else raise InvalidConfigSettingError.new("replacement_address must be a String or Proc, but was: #{replacement_address.class.to_s}")
+      end
+    end
+  end
+end

data/test/config_test.rb

@@ -0,0 +1,75 @@
+require 'test_helper'
+
+class ConfigTest < Test::Unit::TestCase
+  context 'When internal_address_definition is set to a regexp, #is_internal_address?' do
+    setup do
+      MailSafe::Config.internal_address_definition = /.*@example\.com/
+    end
+
+    should 'return true if the address matches the regexp' do
+      assert MailSafe::Config.is_internal_address?('someone@example.com')
+    end
+
+    should 'return false if the address does not match the regexp' do
+      assert !MailSafe::Config.is_internal_address?('someone@another-domain.com')
+    end
+  end
+
+  context 'When internal_address_definition is set to a lambda, #is_internal_address?' do
+    setup do
+      MailSafe::Config.internal_address_definition = lambda { |address| address.size < 15 }
+    end
+
+    should 'return true if the lambda returns true for the given address' do
+      assert MailSafe::Config.is_internal_address?('abc@foo.com')
+    end
+
+    should 'return false if the lambda returns false for the given address' do
+      assert !MailSafe::Config.is_internal_address?('a-long-address@example.com')
+    end
+  end
+
+  context 'When internal_address_definition is not set, #is_internal_address?' do
+    setup do
+      MailSafe::Config.internal_address_definition = nil
+    end
+
+    should 'raise an error' do
+      assert_raise MailSafe::InvalidConfigSettingError do
+        MailSafe::Config.is_internal_address?('abc@foo.com')
+      end
+    end
+  end
+
+  context 'When replacement_address is set to a string, #get_replacement_address' do
+    setup do
+      MailSafe::Config.replacement_address = 'me@mydomain.com'
+    end
+
+    should 'return the configured replacement address' do
+      assert_equal 'me@mydomain.com', MailSafe::Config.get_replacement_address('you@example.com')
+    end
+  end
+
+  context 'When replacement_address is set to a proc, #get_replacement_address' do
+    setup do
+      MailSafe::Config.replacement_address = lambda { |address| "me+#{address.split('@').first}@mydomain.com" }
+    end
+
+    should 'return the configured replacement address' do
+      assert_equal 'me+you@mydomain.com', MailSafe::Config.get_replacement_address('you@example.com')
+    end
+  end
+
+  context 'When replacement_address is not set, #get_replacement_address' do
+    setup do
+      MailSafe::Config.replacement_address = nil
+    end
+
+    should 'raise an error' do
+      assert_raise MailSafe::InvalidConfigSettingError do
+        MailSafe::Config.get_replacement_address('you@example.com')
+      end
+    end
+  end
+end

data/test/mailer_test.rb

@@ -0,0 +1,88 @@
+require 'test_helper'
+
+class MailerTest < Test::Unit::TestCase
+  TEXT_POSTSCRIPT_PHRASE = /The original recipients were:/
+  HTML_POSTSCRIPT_PHRASE = /<p>\s+The original recipients were:\s+<\/p>/
+
+  context 'Delivering a plain text email to internal addresses' do
+    setup do
+      MailSafe::Config.stubs(:is_internal_address? => true)
+      @email = TestMailer.deliver_plain_text_message(:to => 'internal-to@address.com', :bcc => 'internal-bcc@address.com', :cc => 'internal-cc@address.com')
+    end
+
+    should 'send the email to the original addresses' do
+      assert_equal ['internal-to@address.com'], @email.to
+      assert_equal ['internal-cc@address.com'], @email.cc
+      assert_equal ['internal-bcc@address.com'], @email.bcc
+    end
+
+    should 'not add a post script to the body' do
+      assert_no_match TEXT_POSTSCRIPT_PHRASE, @email.body
+    end
+  end
+
+  context 'Delivering a plain text email to external addresses' do
+    setup do
+      MailSafe::Config.stubs(:is_internal_address? => false, :get_replacement_address => 'replacement@example.com')
+      @email = TestMailer.deliver_plain_text_message(:to => 'internal-to@address.com', :bcc => 'internal-bcc@address.com', :cc => 'internal-cc@address.com')
+    end
+
+    should 'send the email to the replacement address' do
+      assert_equal ['replacement@example.com'], @email.to
+      assert_equal ['replacement@example.com'], @email.cc
+      assert_equal ['replacement@example.com'], @email.bcc
+    end
+  end
+
+  def deliver_email_with_mix_of_internal_and_external_addresses(delivery_method)
+    MailSafe::Config.internal_address_definition = /internal/
+    MailSafe::Config.replacement_address = 'internal@domain.com'
+    @email = TestMailer.send(delivery_method,
+      {
+        :to  => ['internal1@address.com', 'external1@address.com'],
+        :cc  => ['internal1@address.com', 'internal2@address.com'],
+        :bcc => ['external1@address.com', 'external2@address.com']
+      }
+    )
+  end
+
+  context 'Delivering a plain text email to a mix of internal and external addresses' do
+    setup do
+      deliver_email_with_mix_of_internal_and_external_addresses(:deliver_plain_text_message)
+    end
+
+    should 'send the email to the appropriate address' do
+      assert_same_elements ['internal1@address.com', 'internal@domain.com'],   @email.to
+      assert_same_elements ['internal1@address.com', 'internal2@address.com'], @email.cc
+      assert_same_elements ['internal@domain.com',   'internal@domain.com'],   @email.bcc
+    end
+
+    should 'add a plain text post script to the body' do
+      assert_match TEXT_POSTSCRIPT_PHRASE, @email.body
+    end
+  end
+
+  context 'Delivering an html email to a mix of internal and external addresses' do
+    setup do
+      deliver_email_with_mix_of_internal_and_external_addresses(:deliver_html_message)
+    end
+
+    should 'add an html post script to the body' do
+      assert_match HTML_POSTSCRIPT_PHRASE, @email.body
+    end
+  end
+
+  context 'Delivering a multipart email to a mix of internal and external addresses' do
+    setup do
+      deliver_email_with_mix_of_internal_and_external_addresses(:deliver_multipart_message)
+    end
+
+    should 'add an text post script to the body of the text part' do
+      assert_match TEXT_POSTSCRIPT_PHRASE, @email.parts.detect { |p| p.content_type == 'text/plain' }.body
+    end
+
+    should 'add an html post script to the body of the html part' do
+      assert_match HTML_POSTSCRIPT_PHRASE, @email.parts.detect { |p| p.content_type == 'text/html' }.body
+    end
+  end
+end

data/test/mailers/test_mailer.rb

@@ -0,0 +1,38 @@
+class TestMailer < ActionMailer::Base
+  # template root must be set for multipart emails, or ActionMailer will throw an exception.
+  self.template_root = File.dirname(__FILE__)
+
+  def plain_text_message(options)
+    setup_recipients(options)
+    from       'test@mailsafe.org'
+    subject    "Plain text Message Test"
+    body       "Here is the message body."
+  end
+
+  def html_message(options)
+    setup_recipients(options)
+    from       'test@mailsafe.org'
+    subject    "Html Message Test"
+    body       "<p>Here is the message body.</p>"
+    content_type 'text/html'
+  end
+
+  def multipart_message(options)
+    setup_recipients(options)
+    from       'test@mailsafe.org'
+    subject    "Html Message Test"
+
+    content_type 'multipart/alternative'
+
+    part :content_type => 'text/plain', :body => "Here is the message body."
+    part :content_type => 'text/html',  :body => "<p>Here is the message body.</p>"
+  end
+
+  protected
+
+  def setup_recipients(options)
+    recipients options[:to]
+    cc         options[:cc]
+    bcc        options[:bcc]
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,22 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'mocha'
+
+begin
+  require 'ruby-debug'
+  Debugger.start
+  Debugger.settings[:autoeval] = true if Debugger.respond_to?(:settings)
+rescue LoadError
+  # ruby-debug wasn't available so neither can the debugging be
+end
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'mail_safe'
+require 'mailers/test_mailer'
+
+ActionMailer::Base.delivery_method = :test
+
+class Test::Unit::TestCase
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification 
+name: mail_safe
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Myron Marston
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-28 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: actionmailer
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: Shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: myron.marston@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- LICENSE
+files: 
+- README.rdoc
+- VERSION.yml
+- lib/mail_safe/action_mailer.rb
+- lib/mail_safe/address_replacer.rb
+- lib/mail_safe/config.rb
+- lib/mail_safe.rb
+- test/config_test.rb
+- test/mailer_test.rb
+- test/mailers/test_mailer.rb
+- test/test_helper.rb
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/myronmarston/mail_safe
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: Keep your ActionMailer emails from escaping into the wild during development.
+test_files: []
+