sanitize_email 1.0.11 → 1.1.0

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+Version 1.1.0 - DEC.30.2013
+* Add documentation for non-Rails setup by Peter Boling
+* Add documentation for using sanitize_email's bundled Rspec Matchers by Peter Boling
+* Add documentation for using sanitize_email's bundled Test Helpers by Peter Boling
+* Stopped using method_missing internally for config access by Peter Boling
+* Improved ease of setup with mail gem outside rails by auto-configuring the interceptor (default inactive) by Peter Boling
+
 Version 1.0.11 - DEC.30.2013
 * Fix travis build by Peter Boling
 * Fix test suite to run on Ruby 1.8.7 again, add back to Travis by Peter Boling

data/README.md

@@ -41,24 +41,65 @@ It's particularly helpful when you want to prevent the delivery of email (e.g. i
 
 ## Re-routing Email on a Staging or QA Server
 
-Another very important use case for me is to transparently re-route email generated from a staging or QA server to an appropriate person.  For example, it's common for us to set up a staging server for a client to use to view our progress and test out new features.  It's important for any email that is generated from our web application be delivered to the client's inbox so that they can review the content and ensure that it's acceptable.  Similarly, we set up QA instances for our own QA team and we use {rails-caddy}[http://github.com/jtrupiano/rails-caddy] to allow each QA person to configure it specifically for them.
+Another very important use case for me is to transparently re-route email generated from a staging or QA server to an appropriate person.  For example, it's common for us to set up a staging server for a client to use to view our progress and test out new features.  It's important for any email that is generated from our web application be delivered to the client's inbox so that they can review the content and ensure that it's acceptable.  Similarly, we set up QA instances for our own QA team and we use [rails-caddy](http://github.com/jtrupiano/rails-caddy) to allow each QA person to configure it specifically for them.
 
 ## Testing Email from a Hot Production Server
 
 If you install this gem on a production server (which I don't always do), you can load up script/console and override the to/cc/bcc on all emails for the duration of your console session.  This allows you to poke and prod a live production instance, and route all email to your own inbox for inspection.  The best part is that this can all be accomplished without changing a single line of your application code.
 
+## Using with a test suite as an alternative to the heavy email_spec
+
+[email_spec](https://github.com/bmabey/email-spec) is a great gem, with awesome rspec matchers and helpers, but it has an undeclared dependency on ActionMailer. Sad face.
+
+SanitizeEmail comes with some lightweight RspecMatchers covering most of what email_spec can do.  It will help you test email functionality.  It is useful when you are creating a gem to handle email features, or are writing a simple Ruby script, and don't want to pull in le Rails.  SanitizeEmail has no dependencies.  Your Mail system just needs to conform to the `register_interceptor` API.
+
 ## Install Like a Boss
 
 In Gemfile:
 
-  gem 'flag_shih_tzu'
+    gem 'flag_shih_tzu'
 
 Then:
 
-  $ bundle install
+    $ bundle install
+
+## Setup with Ruby
+
+*keep scrolling for Rails, but read this for a better understanding of Magic*
+
+There are four ways SanitizeEmail can be turned on; in order of precedence they are:
+
+1. SanitizeEmail.force_sanitize = true # by default it is nil
+    Only useful for local context.  Inside a method where you will be sending an email,
+    set SanitizeEmail.force_sanitize = true just prior to delivering it.  Also useful in the console.
+2. Mail.register_interceptor(SanitizeEmail::Bleach.new(:engage => true)) # by default it is nil
+    If SanitizeEmail seems to not be sanitizing you have probably not registered the interceptor.  SanitizeEmail tries to do this for you.
+    Note: If you are working in an environment that has a Mail or Mailer class that uses the register_interceptor API, the interceptor will already have been registered by SanitizeEmail (however, note lack of :engage => true):
+
+        Mail.register_interceptor(SanitizeEmail::Bleach.new
+    Without :engage => true the interceptor is inactive, and will require engaging via one of the other methods.
+    As an example you could do the following to engage SanitizeEmail:
+
+        SanitizeEmail::Config.configure {|config| config[:engage] = true }
+3. SanitizeEmail::Config.configure {|config| config[:activation_proc] = Proc.new { true } } # by default it is false
+    If you don't need to compute anything, then don't use the Proc, go with the next option.
+4. SanitizeEmail::Config.configure {|config| config[:engage] = true } # by default it is nil
+
+### Notes
+
+Number 1, above, is the method used by the SanitizeEmail.sanitary block.
+If installed but not configured, sanitize_email DOES NOTHING.  Until configured the defaults leave it turned off.
 
+### Troubleshooting
 
-## Setup With An Axe
+IMPORTANT: You may need to setup your own register_interceptor.  If sanitize_email doesn't seem to be working for you find your Mailer/Mail class and try this:
+
+        Mail.register_interceptor(SanitizeEmail::Bleach.new(:engage => true))
+
+If that causes an error you will know why sanitize_email doesn't work.
+Otherwise it will start working according to the rest of the configuration.
+
+## Setup With Rails
 
 Create an initializer, if you are using rails, or otherwise configure:
 
@@ -117,6 +158,114 @@ SanitizeEmail.configure block.
   end
 ```
 
+## Use sanitize_email in your test suite!
+
+### rspec
+
+In your `spec_helper.rb`:
+
+        require 'sanitize_email'
+        # rspec matchers are *not* loaded by default in sanitize_email, as it is not primarily a gem for test suites.
+        require 'sanitize_email/rspec_matchers'
+
+        SanitizeEmail::Config.configure do |config|
+          config[:sanitized_to] =         'sanitize_email@example.org'
+          config[:sanitized_cc] =         'sanitize_email@example.org'
+          config[:sanitized_bcc] =        'sanitize_email@example.org'
+          # run/call whatever logic should turn sanitize_email on and off in this Proc.
+          # config[:activation_proc] =      Proc.new { true }
+          # Since this configuration is *inside* the spec_helper, it might be assumed that we always want to sanitize.  If we don't want to it can be easily manipulated with SanitizeEmail.unsanitary and SanitizeEmail.sanitary block helpers.
+          # Thus instead of using the Proc (slower) we just engage it always:
+          config[:engage] = true
+          config[:use_actual_email_prepended_to_subject] = true         # or false
+          config[:use_actual_environment_prepended_to_subject] = true   # or false
+          config[:use_actual_email_as_sanitized_user_name] = true       # or false
+        end
+
+        # If your mail system is not one that sanitize_email automatically configures an interceptor for (ActionMailer, Mail) then you will need to do the equivalent for whatever Mail system you are using:
+        # Mail.register_interceptor(SanitizeEmail::Bleach.new)
+
+        RSpec.configure do |config|
+          # ...
+          # From sanitize_email gem
+          config.include SanitizeEmail::RspecMatchers
+        end
+
+        context "an email test" do
+          subject { Mail.new(@message_hash) }
+          it { should have_to "sanitize_email@example.org" }
+        end
+
+#### have_* matchers
+
+These will look for an email address in any of the following
+
+        :from, :to, :cc, :bcc, :subject, :reply_to
+
+Example:
+
+        context "the subject line must have the email address sanitize_email@example.org" do
+          subject { Mail.new(@message_hash) }
+          it { should have_subject "sanitize_email@example.org" }
+        end
+
+#### be_* matchers
+
+These will look for a matching string in any of the following
+
+        :from, :to, :cc, :bcc, :subject, :reply_to
+
+Example:
+
+        context "the subject line must have the string 'foobarbaz'" do
+          subject { Mail.new(@message_hash) }
+          it { should be_subject "foobarbaz" }
+        end
+
+#### have_to_username matcher
+
+The `username` in the `:to` field is when the `:to` field is formatted like this:
+
+        Peter Boling <sanitize_email@example.org>
+
+Example:
+
+        context "the to field must have the username 'Peter Boling'" do
+          subject { Mail.new(@message_hash) }
+          it { should have_to_username "Peter Boling" }
+        end
+
+### non-rspec (Test::Unit, mini-test, etc)
+
+In your setup file:
+
+        require 'sanitize_email'
+        # test helpers are *not* loaded by default in sanitize_email, as it is not primarily a gem for test suites.
+        require 'sanitize_email/test_helpers'
+
+        SanitizeEmail::Config.configure do |config|
+          config[:sanitized_to] =         'sanitize_email@example.org'
+          config[:sanitized_cc] =         'sanitize_email@example.org'
+          config[:sanitized_bcc] =        'sanitize_email@example.org'
+          # run/call whatever logic should turn sanitize_email on and off in this Proc.
+          # config[:activation_proc] =      Proc.new { true }
+          # Since this configuration is *inside* the spec_helper, it might be assumed that we always want to sanitize.  If we don't want to it can be easily manipulated with SanitizeEmail.unsanitary and SanitizeEmail.sanitary block helpers.
+          # Thus instead of using the Proc (slower) we just engage it always:
+          config[:engage] = true
+          config[:use_actual_email_prepended_to_subject] = true         # or false
+          config[:use_actual_environment_prepended_to_subject] = true   # or false
+          config[:use_actual_email_as_sanitized_user_name] = true       # or false
+        end
+
+        # If your mail system is not one that sanitize_email automatically configures an interceptor for (ActionMailer, Mail) then you will need to do the equivalent for whatever Mail system you are using:
+        # Mail.register_interceptor(SanitizeEmail::Bleach.new)
+
+        # You need to know what to do here... somehow get the methods into rhw scope of your tests.
+        # Something like this maybe?
+        include SanitizeEmail::TestHelpers
+        # Look here to see what it gives you:
+        # https://github.com/pboling/sanitize_email/blob/master/lib/sanitize_email/test_helpers.rb
+
 ## Deprecations
 
 Sometimes things get deprecated (meaning they still work, but are noisy about it).  If this happens to you, and you like your head in the sand, call this number:

data/lib/sanitize_email.rb

@@ -20,8 +20,17 @@ module SanitizeEmail
     else
       raise "Please use the 0.X.X versions of sanitize_email for Rails 2.X and below."
     end
-  elsif defined?(Mailer) && Mailer.respond_to?(:register_interceptor)
-    Mailer.register_interceptor(SanitizeEmail::Bleach.new)
+  else
+    if defined?(Mailer)
+      mailer = Mailer
+    elsif defined?(Mail)
+      mailer = Mail
+    end
+    if mailer.respond_to?(:register_interceptor)
+      mailer.register_interceptor(SanitizeEmail::Bleach.new)
+    else
+      warn "SanitizeEmail was unable to detect a compatible Mail class to register and interceptor on."
+    end
   end
 
   def self.[](key)
@@ -36,17 +45,17 @@ module SanitizeEmail
   # NOTE: Deprecated method
   # We have to actually define because we can't deprecate methods that are hooked up via method_missing
   def self.sanitized_recipients
-    SanitizeEmail[:sanitized_recipients]
+    SanitizeEmail::Config.config[:sanitized_recipients]
   end
 
   # NOTE: Deprecated method
   # We have to actually define because we can't deprecate methods that are hooked up via method_missing
   def self.local_environments
-    SanitizeEmail[:local_environments]
+    SanitizeEmail::Config.config[:local_environments]
   end
 
   def self.activate?(message)
-    proc = SanitizeEmail[:activation_proc]
+    proc = SanitizeEmail::Config.config[:activation_proc]
     proc.call(message) if proc.respond_to?(:call)
   end
 

data/lib/sanitize_email/bleach.rb

@@ -11,7 +11,7 @@ module SanitizeEmail
 
     def initialize(args = {})
       # Not using extract_options! because non-rails compatibility is a goal
-      @engage = args[:engage] || SanitizeEmail[:engage]
+      @engage = args[:engage] || SanitizeEmail::Config.config[:engage]
     end
 
     # If all recipient addresses are white-listed the field is left alone.
@@ -29,15 +29,26 @@ module SanitizeEmail
     end
 
     # This method will be called by the Hook to determine if an override should occur
-    # There are three ways SanitizeEmail can be turned on; in order of precedence they are:
+    # There are four ways SanitizeEmail can be turned on; in order of precedence they are:
     #
     # 1. SanitizeEmail.force_sanitize = true # by default it is nil
+    #   Only useful for local context.  Inside a method where you will be sending an email,
+    #   set SanitizeEmail.force_sanitize = true just prior to delivering it.  Also useful in the console.
     # 2. Mail.register_interceptor(SanitizeEmail::Bleach.new(:engage => true)) # by default it is nil
-    # 3. SanitizeEmail::Config.configure {|config| config[:activation_proc] = Proc.new { true } } be default it is false
+    #   If SanitizeEmail seems to not be sanitizing you have probably not registered the interceptor.  SanitizeEmail tries to do this for you.
+    #   Note: If you are working in an environment that has a Mail or Mailer class that uses the register_interceptor API, the interceptor will already have been registered by SanitizeEmail (however, note lack of :engage => true):
+    #     Mail.register_interceptor(SanitizeEmail::Bleach.new
+    #   Without :engage => true the interceptor is inactive, and will require engaging via one of the other methods.
+    #   As an example you could do the following to engage SanitizeEmail:
+    #     SanitizeEmail::Config.configure {|config| config[:engage] = true }
+    # 3. SanitizeEmail::Config.configure {|config| config[:activation_proc] = Proc.new { true } } # by default it is false
+    #   If you don't need to compute anything, then don't use the Proc, go with the next option.
+    # 4. SanitizeEmail::Config.configure {|config| config[:engage] = true } # by default it is nil
     #
     # Note: Number 1 is the method used by the SanitizeEmail.sanitary block
-    # Note: Number 2 would not be used unless you setup your own register_interceptor)
-    # If installed but not configured, sanitize email DOES NOTHING.  Until configured the defaults leave it turned off.
+    # Note: Number 2 See note accompanying 2: you may need to setup your own register_interceptor
+    #
+    # If installed but not configured, sanitize_email DOES NOTHING.  Until configured the defaults leave it turned off.
     def sanitize_engaged?(message)
 
       # Don't sanitize the message if it will not be delivered

data/lib/sanitize_email/overridden_addresses.rb

@@ -15,11 +15,11 @@ module SanitizeEmail
 
     def initialize(message, args = {})
       # Not using extract_options! because non-rails compatibility is a goal
-      @sanitized_to = args[:sanitized_to] || SanitizeEmail[:sanitized_to]
-      @sanitized_cc = args[:sanitized_cc] || SanitizeEmail[:sanitized_cc]
-      @sanitized_bcc = args[:sanitized_bcc] || SanitizeEmail[:sanitized_bcc]
-      @good_list = args[:good_list] || SanitizeEmail[:good_list] || []
-      @bad_list = args[:bad_list] || SanitizeEmail[:bad_list] || []
+      @sanitized_to = args[:sanitized_to] || SanitizeEmail::Config.config[:sanitized_to]
+      @sanitized_cc = args[:sanitized_cc] || SanitizeEmail::Config.config[:sanitized_cc]
+      @sanitized_bcc = args[:sanitized_bcc] || SanitizeEmail::Config.config[:sanitized_bcc]
+      @good_list = args[:good_list] || SanitizeEmail::Config.config[:good_list] || []
+      @bad_list = args[:bad_list] || SanitizeEmail::Config.config[:bad_list] || []
       @overridden_to = self.to_override(message.to)
       @overridden_cc = self.cc_override(message.cc)
       @overridden_bcc = self.bcc_override(message.bcc)

data/lib/sanitize_email/version.rb

@@ -1,5 +1,5 @@
 # Copyright (c) 2008-13 Peter H. Boling of RailsBling.com
 # Released under the MIT license
 module SanitizeEmail
-  VERSION = '1.0.11'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sanitize_email
 version: !ruby/object:Gem::Version
-  version: 1.0.11
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors: