canonical-email 1.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Centro
+
+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,108 @@
+= Canonical
+
+Canonical is an ActionMailer extension that acts just like the Postfix
+utility of the same name. Essentially, Canonical lets you substitute the To,
+CC, and/or BCC email destinations with one of many replacements via a rule.
+
+You may want this behavior for many reasons; especially if you're actually 
+using Postfix's canonical functionality. Let's say you don't want to setup
+your integration or staging environment to send email in test mode, but you 
+also do not want to accidentally send email to real users. You may add a
+canonical rule like the following to send any email from the system to any
+address to the QA email distribution list:
+
+    TMail::Mail.add_canonical_override(/.*/, 'qa@foo.bar')
+
+Assuming you are working at Foo Bar, that rule will match any destination
+address that has any character in it - meaning, it matches everything - and
+will subsitute the matched email with qa@foo.bar. This is the same as saying
+the following in Postfix's canonical file:
+
+    /.*/, qa@foo.bar
+
+What you should notice is that canonical expects to see a regular expression 
+as the first argument. Passing in anything that does not respond to =~ will
+result in an error.
+
+== First matched, first replaced (FMFR)
+
+Now, let's say you didn't want to just replace everything. Let's you wanted
+to send everything for your boss to your team, everything to marketing to 
+another email address, and catch everything else. The rules would then be 
+defined as:
+
+    TMail::Mail.add_canonical_override(/ceo@foo\.bar/, 'developers@foo.bar')
+    TMail::Mail.add_canonical_override(/marketing@/, 'technology@foo.bar')
+    TMail::Mail.add_canonical_override(/.*/, 'qa@foo.bar')
+
+What you should notice here is the ordering. Canonical works with multiple
+rules, but will process a substition according to the rule that matches first.
+Thus, whichever rule you define first will be checked first. If the rule matches
+the email address being checked, the substitution is made and matching stops.
+Hence the FMFR; first matched, first replaced.
+
+The best way to take advantage of rules is to put the most specific rule at the
+top of the list and the most generic rule at the bottom. If we had reversed the
+order of the above rules, everything would go to qa@foo.bar.
+
+== Passing Through
+
+Perhaps you have a catch-all rule like the ones used above (e.g. /.*/), but you
+want certain email addresses to pass-through. Sort of like an opt-in approach,
+which might be considered safer in a closed environment. You could match on the
+specific address and then substitute it with the same thing, like so:
+
+    TMail::Mail.add_canonical_override(/ceo@foo\.bar/, 'ceo@foo.bar')
+
+But that's kind of silly; and what if you wanted to match on everything for your
+company? This is where Canonical deviates slightly from Postfix's version. This
+Canonical will allow you to provide a passthrough for a pattern. For instance:
+
+    TMail::Mail.add_canonical_passthrough(/@foo\.bar/)
+
+Will explicitly allow any email address with "@foo.bar" in it. Even if there is
+a catch-all rule; so long as this rule comes before any other rules that would
+match.
+
+Handy? Yes!
+
+== How does it work
+
+Essentially, Canonical works by hijacking the TMail::Mail#destinations which is
+used at the moment ActionMailer is about to write the RCPT TOs to the SMTP
+server chosen. Canonical only modifies destinations, it does not modify anything
+about the body of the email. Thus, the To, Cc, and Bcc will all look the same
+as an unmodified email would to the recipient.
+
+Canonical also disables the :sendmail option since it only tries to work with 
+SMTP. At some point in the future, this may change. If you need sendmail support
+then fix the code and send a patch :)
+
+== How should I use it?
+
+The most obvious way to use canonical is to put the rules in your Rails
+environment files. We suggest an opt-in approach to rule setting such that you
+catch-all in config/environment.rb and specifically allow emails in
+config/environments/production.rb.
+
+For example:
+
+    # config/environment.rb
+    ...
+    TMail::Mail.add_canonical_override(/.*/, 'testing@foo.bar')
+
+    # config/environments/production.rb
+    ...
+    TMail::Mail.add_canonical_passthrough(/.*/)
+
+That's the most basic way to localize email in every environment but production.
+
+= License
+
+Copyright (c) 2008 {Centro}[www.centro.net], released under the MIT license.
+
+Authored by:
+
+  {Eric Schwartz}[eric.schwartz@centro.net]
+  {Brett Neumeier}[brett.neumeier@centro.net]
+  {Justin Knowlden}[justin.knowlden@centro.net]

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "canonical-email"
+    gem.summary = %Q{Safely and easily rewrite your email destination headers in Ruby}
+    gem.description = %Q{canonical-email lets you substitute the To, CC, and/or BCC email destinations with one of many replacements via a simple regular expression.}
+    gem.homepage = "http://github.com/centro/canonical-email"
+    gem.authors = ['emschwar', 'jaknowlden']
+    gem.add_development_dependency "actionmailer", ">=2.1.0"
+    gem.add_development_dependency "actionpack", ">=2.1.0"
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the canonical plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+require 'rake/rdoctask'
+desc 'Generate documentation for the canonical plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Canonical'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/init.rb

@@ -0,0 +1,3 @@
+require 'action_mailer'
+require 'canonical'
+require 'disallow_sendmail_method'

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/canonical-email.rb

@@ -0,0 +1,138 @@
+require 'disallow_sendmail_method'
+
+module Centro #:nodoc:
+=begin rdoc
+Canonical is an ActionMailer extension that acts just like the Postfix
+utility of the same name. Essentially, Canonical lets you substitute the To,
+CC, and/or BCC email destinations with one of many replacements via a rule.
+
+You may want this behavior for many reasons; especially if you're actually
+using Postfix's canonical functionality. Let's say you don't want to setup
+your integration or staging environment to send email in test mode, but you
+also do not want to accidentally send email to real users. You may add a
+canonical rule like the following to send any email from the system to any
+address to the QA email distribution list:
+
+    TMail::Mail.add_canonical_override(/.*/, 'qa@foo.bar')
+
+Assuming you are working at Foo Bar, that rule will match any destination
+address that has any character in it - meaning, it matches everything - and
+will subsitute the matched email with qa@foo.bar. This is the same as saying
+the following in Postfix's canonical file:
+
+    /.*/, qa@foo.bar
+
+What you should notice is that canonical expects to see a regular expression
+as the first argument. Passing in anything that does not respond to =~ will
+result in an error.
+
+= First matched, first replaced (FMFR)
+
+Now, let's say you didn't want to just replace everything. Let's you wanted
+to send everything for your boss to your team, everything to marketing to
+another email address, and catch everything else. The rules would then be
+defined as:
+
+    TMail::Mail.add_canonical_override(/ceo@foo\.bar/, 'developers@foo.bar')
+    TMail::Mail.add_canonical_override(/marketing@/, 'technology@foo.bar')
+    TMail::Mail.add_canonical_override(/.*/, 'qa@foo.bar')
+
+What you should notice here is the ordering. Canonical works with multiple
+rules, but will process a substition according to the rule that matches first.
+Thus, whichever rule you define first will be checked first. If the rule matches
+the email address being checked, the substitution is made and matching stops.
+Hence the FMFR; first matched, first replaced.
+
+The best way to take advantage of rules is to put the most specific rule at the
+top of the list and the most generic rule at the bottom. If we had reversed the
+order of the above rules, everything would go to qa@foo.bar.
+
+= Passing Through
+
+Perhaps you have a catch-all rule like the ones used above (e.g. /.*/), but you
+want certain email addresses to pass-through. Sort of like an opt-in approach,
+which might be considered safer in a closed environment. You could match on the
+specific address and then substitute it with the same thing, like so:
+
+    TMail::Mail.add_canonical_override(/ceo@foo\.bar/, 'ceo@foo.bar')
+
+But that's kind of silly; and what if you wanted to match on everything for your
+company? This is where Canonical deviates slightly from Postfix's version. This
+Canonical will allow you to provide a passthrough for a pattern. For instance:
+
+    TMail::Mail.add_canonical_passthrough(/@foo\.bar/)
+
+Will explicitly allow any email address with "@foo.bar" in it. Even if there is
+a catch-all rule; so long as this rule comes before any other rules that would
+match.
+
+Handy? Yes!
+
+= How does it work
+
+Essentially, Canonical works by hijacking the TMail::Mail#destinations which is
+used at the moment ActionMailer is about to write the RCPT TOs to the SMTP
+server chosen. Canonical only modifies destinations, it does not modify anything
+about the body of the email. Thus, the To, Cc, and Bcc will all look the same
+as an unmodified email would to the recipient.
+
+Canonical also disables the :sendmail option since it only tries to work with
+SMTP. At some point in the future, this may change. If you need sendmail support
+then fix the code and send a patch :)
+=end
+  module Canonical
+
+    def self.included(klass)
+      klass.extend(ClassMethods)
+      klass.send(:include, InstanceMethods)
+    end
+
+    module ClassMethods
+      def clear_canonical
+        self.overrides = nil
+      end
+
+      def add_canonical_passthrough(pattern)
+        overrides << [ pattern, :passthrough ]
+      end
+
+      def add_canonical_override(pattern, override)
+        overrides << [ pattern, override ]
+      end
+
+      def canonical_destination(email)
+        overrides.each do |pattern, replace|
+          return (:passthrough == replace ? email : replace) if email =~ pattern
+        end
+        email
+      end
+
+    private
+
+      def overrides
+        @@smtp_overridden ||= []
+      end
+
+      def overrides=(overrides)
+        @@smtp_overridden = overrides
+      end
+
+    end # ClassMethods
+
+    module InstanceMethods
+      def canonical_destinations
+        self.destinations_without_canonical.collect do |email|
+          self.class.canonical_destination(email)
+        end.uniq
+      end
+
+      def self.included(base)
+        base.send(:alias_method, :destinations_without_canonical, :destinations)
+        base.send(:alias_method, :destinations, :canonical_destinations)
+      end
+
+    end # InstanceMethods
+  end # Canonical
+end # Centro
+
+TMail::Mail.send(:include, Centro::Canonical)

data/lib/disallow_sendmail_method.rb

@@ -0,0 +1,7 @@
+class ActionMailer::Base
+  def perform_delivery_sendmail(ignored)
+    raise SecurityError,
+      "[Canonical] Sendmail method is explicitly disallowed so that we don't " +
+      "accidentally configure ourselves into a security hole"
+  end
+end

data/tasks/canonical.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :canonical do
+#   # Task goes here
+# end

data/test/canonical_test.rb

@@ -0,0 +1,61 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class CanonicalTest < Test::Unit::TestCase
+
+  def setup
+    @mail = TMail::Mail.new
+  end
+
+  def teardown
+    TMail::Mail.clear_canonical
+  end
+
+  def test_add_override_rewrites_matching_destinations
+    TMail::Mail.add_canonical_override(/me\.please$/, "foo@bar.com")
+    assert_equal "foo@bar.com",
+      TMail::Mail.canonical_destination("override@me.please")
+  end
+
+  def test_add_override_ignores_non_matching_destinations
+    TMail::Mail.add_canonical_override(/me\.please$/, "foo@bar.com")
+    assert_equal "same@centro.net",
+      TMail::Mail.canonical_destination("same@centro.net")
+  end
+
+  def test_add_override_does_not_change_destination_with_passthrough
+    TMail::Mail.add_canonical_override(/@centro.net$/, :passthrough)
+    assert_equal "passthrough@centro.net",
+      TMail::Mail.canonical_destination("passthrough@centro.net")
+  end
+
+  def test_add_passthrough_does_not_change_destination
+    TMail::Mail.add_canonical_passthrough(/@centro.net$/)
+    assert_equal "passthrough@centro.net",
+      TMail::Mail.canonical_destination("passthrough@centro.net")
+  end
+
+  def test_overrides_are_applied_in_the_order_they_were_added
+    TMail::Mail.add_canonical_passthrough(/@centro.net$/)
+    TMail::Mail.add_canonical_override(/.*/, "redirect@centro.net")
+
+    assert_equal "same@centro.net",
+      TMail::Mail.canonical_destination("same@centro.net")
+    assert_equal "redirect@centro.net",
+      TMail::Mail.canonical_destination("some@random.addr.com")
+  end
+
+  def test_overrides_rewrite_tmail_destinations
+    TMail::Mail.add_canonical_override(/.*/, "redirect@centro.net")
+
+    @mail.to = "foo@bar.com"
+    assert_equal ["redirect@centro.net"], @mail.destinations
+  end
+
+  def test_overrides_should_list_unique_replacements
+    TMail::Mail.add_canonical_override(/.*/, "redirect@centro.net")
+
+    @mail.to = ["foo@bar.com", "bar@foo.com"]
+    assert_equal ["redirect@centro.net"], @mail.destinations
+  end
+
+end

data/test/disallow_sendmail_method_test.rb

@@ -0,0 +1,20 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class DisallowSendmailMethodTest < Test::Unit::TestCase
+
+  class MyMailer < ActionMailer::Base
+    def self.template_root
+      File.dirname(__FILE__)
+    end
+
+    def test_mail
+      part :content_type => 'text/plain', :body => "a test"
+    end
+  end
+
+  def test_sendmail_method_raises_security_error
+    ActionMailer::Base.delivery_method = :sendmail
+    ActionMailer::Base.template_root = "."
+    assert_raises (SecurityError) { MyMailer.deliver_test_mail }
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,5 @@
+require 'test/unit'
+require 'rubygems'
+require 'action_mailer'
+require 'action_controller'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'canonical-email')

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification 
+name: canonical-email
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- emschwar
+- jaknowlden
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-29 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: actionmailer
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 1
+        - 0
+        version: 2.1.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: actionpack
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 1
+        - 0
+        version: 2.1.0
+  type: :development
+  version_requirements: *id002
+description: canonical-email lets you substitute the To, CC, and/or BCC email destinations with one of many replacements via a simple regular expression.
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- init.rb
+- install.rb
+- lib/canonical-email.rb
+- lib/disallow_sendmail_method.rb
+- tasks/canonical.rake
+- test/canonical_test.rb
+- test/disallow_sendmail_method_test.rb
+- test/test_helper.rb
+- uninstall.rb
+has_rdoc: true
+homepage: http://github.com/centro/canonical-email
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Safely and easily rewrite your email destination headers in Ruby
+test_files: 
+- test/canonical_test.rb
+- test/disallow_sendmail_method_test.rb
+- test/test_helper.rb