sms_safe 1.0.0

data/lib/sms_safe/interceptor.rb

@@ -0,0 +1,151 @@
+require 'mail'
+
+module SmsSafe
+
+  # When a message is intercepted, Interceptor decides whether we need to do anything with it,
+  #   and does it.
+  # The different adaptor classes in the Interceptors module provide mapping to each of the SMS libraries peculiarities.
+  class Interceptor
+
+    # Method called by all the sub-classes to process the SMS being sent
+    # @param [Object] original_message the message we intercepted from the texter gem. May be of varying types, depending
+    #   on which texter gem is being used.
+    # @return [Object] the message to send (if modified recipient / text), of the same type we received
+    #   or nil if no SMS should be sent
+    def process_message(original_message)
+      message = convert_message(original_message)
+
+      if intercept_message?(message)
+        intercept_message!(message)
+      else
+        original_message
+      end
+    end
+
+    # Decides whether to intercept the message that is being sent, or to let it go through
+    # @param [Message] message the message we are evaluating
+    # @return [Boolean] whether to intercept the message (true) or let it go through (false)
+    def intercept_message?(message)
+      matching_rules = [SmsSafe.configuration.internal_phone_numbers].flatten.compact
+      internal_recipient = matching_rules.any? do |rule|
+        case rule
+          when String then message.to == rule
+          when Regexp then !!(message.to =~ rule)
+          when Proc   then rule.call(message)
+          else
+            raise InvalidConfigSettingError.new("Ensure internal_phone_numbers is a String, a Regexp or a Proc (or an array of them). It was: #{SmsSafe.configuration.internal_phone_numbers.inspect}")
+        end
+      end
+      !internal_recipient # Intercept messages that are *not* going to one of the allowed numbers
+    end
+
+    # Once we've decided to intercept the message, act on it, based on the intercept_mechanism set
+    # @param [Message] message the message we are evaluating
+    # @return [Object] the message to send, of the type that corresponds to the texter gem (if :redirecting)
+    #   or nil to cancel sending (if :email or :discard)
+    def intercept_message!(message)
+      case SmsSafe.configuration.intercept_mechanism
+        when :redirect then redirect(message)
+        when :email then email(message)
+        when :discard then discard
+        else
+          raise InvalidConfigSettingError.new("Ensure intercept_mechanism is either :redirect, :email or :discard. It was: #{SmsSafe.configuration.intercept_mechanism.inspect}")
+      end
+    end
+
+    # Decides which phone number to redirect the message to
+    # @param [Message] message the message we are redirecting
+    # @return [String] the phone number to redirect the number to
+    def redirect_phone_number(message)
+      target = SmsSafe.configuration.redirect_target
+      case target
+        when String then target
+        when Proc   then target.call(message)
+        else
+          raise InvalidConfigSettingError.new("Ensure redirect_target is a String or a Proc. It was: #{SmsSafe.configuration.redirect_target.inspect}")
+      end
+    end
+
+    # Modifies the text of the message to indicate it was redirected
+    # Simply appends "(SmsSafe: original_recipient_number)", for brevity
+    #
+    # @param [Message] message the message we are redirecting
+    # @return [String] the new text for the SMS
+    def redirect_text(message)
+      "#{message.text} (SmsSafe: #{message.to})"
+    end
+
+    # Sends an e-mail to the specified address, instead of
+    def email(message)
+      message_body = <<-EOS
+This email was originally an SMS that SmsSafe intercepted:
+
+From: #{message.from}
+To: #{message.to}
+Text: #{message.text}
+
+Full object: #{message.original_message.inspect}
+      EOS
+
+      recipient = email_recipient(message)
+
+      mail = Mail.new do
+        from     recipient
+        to       recipient
+        subject  'SmsSafe: #{message.to} - #{message.text}'
+        body     message_body
+      end
+      mail.deliver!
+
+      # Must return nil to stop the sending
+      nil
+    end
+
+    # Decides which email address to send the SMS to
+    # @param [Message] message the message we are emailing
+    # @return [String] the email address to email it to
+    def email_recipient(message)
+      target = SmsSafe.configuration.email_target
+      case target
+        when String then target
+        when Proc   then target.call(message)
+        else
+          raise InvalidConfigSettingError.new("Ensure email_target is a String or a Proc. It was: #{SmsSafe.configuration.email_target.inspect}")
+      end
+    end
+
+    # Discards the message. Essentially doesn't do anything. Will sleep for a bit, however, if
+    #   configuration.discard_delay is set.
+    def discard
+      # Delay to simulate the time it takes to talk to the external service
+      if !SmsSafe.configuration.discard_delay.nil? && SmsSafe.configuration.discard_delay > 0
+        delay = SmsSafe.configuration.discard_delay.to_f / 1000 # delay is specified in ms
+        sleep delay
+      end
+
+      # Must return nil to stop the sending
+      nil
+    end
+
+    # Converts an SMS message from whatever object the texter gem uses into our generic Message
+    # Must be overridden by each gem's interceptor
+    #
+    # @param [Object] message that is being sent
+    # @return [Message] the message converted into our own Message class
+    def convert_message(message)
+      raise "Must override!"
+    end
+
+    # Returns a modified version of the original message with new recipient and text,
+    #   to give back to the texter gem to send.
+    # Must be overridden by each gem's interceptor
+    # Call redirect_phone_number and redirect_text to get the new recipient and text, and
+    #  modify message.original_message
+    #
+    # @param [Message] message that is being sent, unmodified
+    # @return [Object] modified message to send, of the type the texter gem uses
+    def redirect(message)
+      raise "Must override!"
+    end
+  end
+end

data/lib/sms_safe/interceptors/action_texter.rb

@@ -0,0 +1,32 @@
+module SmsSafe
+  module Interceptors
+    class ActionTexter < SmsSafe::Interceptor
+      # This method will be called differently for each Texter Gem, it's the one that the hook likes to call
+      # In all cases, it's a one-liner that calls process_message in the superclass
+      # It could even be an alias, for all practical purposes
+      def delivering_sms(message)
+        self.process_message(message)
+      end
+
+      # Converts an ActionTexter::Message into an SmsSafe::Message
+      # @param [ActionTexter::Message] message that is being sent by ActionTexter gem
+      # @return [Message] the message converted into our own Message class
+      def convert_message(message)
+        SmsSafe::Message.new(from: message.from, to: message.to, text: message.text, original_message: message)
+      end
+
+
+      # Returns a modified version of the original message with new recipient and text,
+      #   to give back to the texter gem to send.
+      #
+      # @param [Message] message that is being sent, unmodified
+      # @return [ActionTexter::Message] modified message to send
+      def redirect(message)
+        original_message = message.original_message
+        original_message.to = redirect_phone_number(message)
+        original_message.text = redirect_text(message)
+        original_message
+      end
+    end
+  end
+end

data/lib/sms_safe/interceptors/nexmo.rb

@@ -0,0 +1,31 @@
+module SmsSafe
+  module Interceptors
+    class Nexmo < SmsSafe::Interceptor
+      # This method will be called differently for each Texter Gem, it's the one that the hook likes to call
+      # In all cases, it's a one-liner that calls process_message in the superclass
+      # It could even be an alias, for all practical purposes
+      # def delivering_sms(message)
+      #   self.process_message(message)
+      # end
+
+      # Converts a hash of params (Nexmo doesn't use a class to represent their messages) into Message
+      # @param [Hash] message that is being sent by Nexmo gem
+      # @return [Message] the message converted into our own Message class
+      def convert_message(message)
+        SmsSafe::Message.new(from: message[:from], to: message[:to], text: message[:text], original_message: message)
+      end
+
+      # Returns a modified version of the original message with new recipient and text,
+      #   to give back to the texter gem to send.
+      #
+      # @param [Message] message that is being sent, unmodified
+      # @return [Hash] modified message to send
+      def redirect(message)
+        original_message = message.original_message
+        original_message[:to] = redirect_phone_number(message)
+        original_message[:text] = redirect_text(message)
+        original_message
+      end
+    end
+  end
+end

data/lib/sms_safe/interceptors/twilio.rb

@@ -0,0 +1,31 @@
+module SmsSafe
+  module Interceptors
+    class Twilio < SmsSafe::Interceptor
+      # This method will be called differently for each Texter Gem, it's the one that the hook likes to call
+      # In all cases, it's a one-liner that calls process_message in the superclass
+      # It could even be an alias, for all practical purposes
+      # def delivering_sms(message)
+      #   self.process_message(message)
+      # end
+
+      # Converts a hash of params (Twilio's call is just a hash to Client.messages) into Message
+      # @param [Hash] message that is being sent by Twilio gem
+      # @return [Message] the message converted into our own Message class
+      def convert_message(message)
+        SmsSafe::Message.new(from: message[:from], to: message[:to], text: message[:body], original_message: message)
+      end
+
+      # Returns a modified version of the original message with new recipient and text,
+      #   to give back to the texter gem to send.
+      #
+      # @param [Message] message that is being sent, unmodified
+      # @return [Hash] modified message to send
+      def redirect(message)
+        original_message = message.original_message
+        original_message[:to] = redirect_phone_number(message)
+        original_message[:body] = redirect_text(message)
+        original_message
+      end
+    end
+  end
+end

data/lib/sms_safe/message.rb

@@ -0,0 +1,21 @@
+module SmsSafe
+
+  # Different texter gems will have different classes for their messages.
+  # This is a common class that acts as an impedance adapter. Most of our methods use this class
+  #
+  # @!attribute from
+  #   @return [String] name or phone number of the author of the message.
+  # @!attribute to
+  #   @return [String] phone number of the recipient of the message.
+  # @!attribute text
+  #   @return [String] actual message to send.
+  # @!attribute original_message
+  #   @return [String] original message sent by the texter gem, unmapped.
+  class Message
+    attr_accessor :from, :to, :text, :original_message
+
+    def initialize(attrs)
+      attrs.each { |k, v| self.send "#{k.to_s}=".to_sym, v }
+    end
+  end
+end

data/lib/sms_safe/version.rb

@@ -0,0 +1,3 @@
+module SmsSafe
+  VERSION = "1.0.0"
+end

data/sms_safe.gemspec

@@ -0,0 +1,49 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "sms_safe/version"
+
+Gem::Specification.new do |s|
+  s.name        = 'sms_safe'
+  s.version     = '1.0.0'
+  s.summary     = "Keep your SMS messages from escaping into the wild during development."
+  s.description = %q{SmsSafe provides a safety net while you're developing an application that uses ActionTexter
+                          or other gems to send SMS. It keeps SMS messages from escaping into the wild.
+
+                          Once you've installed and configured this gem, you can rest assures that your app won't send
+                          SMS messages to external phone numbers. Instead, messages will be routed to a phone number
+                          you specify, converted into e-mails to you, or simply not sent at all.
+
+                          SmsSafe can also include an artificial delay to simulate the call to your SMS provider,
+                          for realistic load testing.}
+  s.authors     = ["Daniel Magliola"]
+  s.email       = 'dmagliola@crystalgears.com'
+  s.homepage    = 'https://github.com/dmagliola/sms_safe'
+  s.license     = 'MIT'
+
+  s.files       = `git ls-files`.split($/)
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|s.features)/})
+  s.require_paths = ["lib"]
+
+  s.required_ruby_version = ">= 1.9.3"
+
+  s.add_runtime_dependency "mail", '>= 2.4'
+
+  s.add_development_dependency "bundler"
+  s.add_development_dependency "rake"
+
+  s.add_development_dependency "minitest"
+  s.add_development_dependency "minitest-reporters"
+  s.add_development_dependency "shoulda"
+  s.add_development_dependency "mocha"
+  s.add_development_dependency "simplecov"
+
+  # All the Gems we integrate with, to be able to test the hooks
+  s.add_development_dependency "action_texter"
+  s.add_development_dependency "twilio-ruby"
+  s.add_development_dependency "nexmo"
+
+  s.add_development_dependency "appraisal"
+  s.add_development_dependency "coveralls"
+  s.add_development_dependency "codeclimate-test-reporter"
+end

data/test/hooks_test.rb

@@ -0,0 +1,149 @@
+require_relative "test_helper"
+require "action_texter"
+require "nexmo"
+require "twilio-ruby"
+
+# These are the real integration tests. Each one of these installs the hook, then tried sending an SMS
+#   that will and will not get intercepted, and check that that actually happens.
+class HooksTest < MiniTest::Test
+  context "With a basic configuration for SmsSafe" do
+    setup do
+      SmsSafe.configure do |config|
+        config.internal_phone_numbers = INTERNAL_PHONE_NUMBERS
+        config.intercept_mechanism = :discard
+        config.redirect_target = DEFAULT_INTERNAL_PHONE_NUMBER
+      end
+
+      @action_texter_client = ActionTexter::TestClient.new
+    end
+
+    should "hook ActionTexter" do
+      ActionTexter::Client.setup("Test") # Excellent, no need to mock stuff up! Thank you ActionTexter!
+      SmsSafe.hook!(:action_texter)
+
+      # Try to send an external message
+      @action_texter_client.deliveries.clear
+      message = ActionTexter::Message.new(from: DEFAULT_INTERNAL_PHONE_NUMBER, to: EXTERNAL_PHONE_NUMBERS.first, text: "Foo", reference: "ref-1")
+      result = message.deliver
+
+      # Check that return is nil and that nothing got sent
+      assert_nil result
+      assert_equal 0, @action_texter_client.deliveries.length
+
+      # Change configuration to redirect
+      SmsSafe.configuration.intercept_mechanism = :redirect
+
+      # Try to send an external message
+      @action_texter_client.deliveries.clear
+      message = ActionTexter::Message.new(from: DEFAULT_INTERNAL_PHONE_NUMBER, to: EXTERNAL_PHONE_NUMBERS.first, text: "Foo", reference: "ref-1")
+      result = message.deliver
+
+      # Check that return is appropriate and that something got sent, redirected and with changed text
+      refute_nil result
+      assert_equal 1, @action_texter_client.deliveries.length
+      assert_equal DEFAULT_INTERNAL_PHONE_NUMBER, @action_texter_client.deliveries.last.to
+      assert_operator "Foo".length, :<, @action_texter_client.deliveries.last.text.length
+
+      # Try to send an internal message
+      @action_texter_client.deliveries.clear
+      message = ActionTexter::Message.new(from: DEFAULT_INTERNAL_PHONE_NUMBER, to: INTERNAL_PHONE_NUMBERS.last, text: "Foo", reference: "ref-1")
+      result = message.deliver
+
+      # Check that it got delivered, unchanged
+      refute_nil result
+      assert_equal 1, @action_texter_client.deliveries.length
+      assert_equal INTERNAL_PHONE_NUMBERS.last, @action_texter_client.deliveries.last.to
+      assert_equal "Foo", @action_texter_client.deliveries.last.text
+    end
+
+    should "hook Nexmo" do
+      nexmo = Nexmo::Client.new(key: "blah", secret: "bleh")
+      SmsSafe.hook!(:nexmo)
+
+      # Stub the "post" method so that it doesn't actually do a post
+      # I'm doing that instead of stubbing "send_message", since we're already monkeypatching send_message, and I don't want those two to collide
+      nexmo.expects(:post).never
+
+      # Try to send an external message
+      result = nexmo.send_message(from: DEFAULT_INTERNAL_PHONE_NUMBER, to: EXTERNAL_PHONE_NUMBERS.first, text: 'Foo')
+
+      # Check that return is nil and that nothing got sent
+      assert_nil result
+
+      # Change configuration to redirect
+      SmsSafe.configuration.intercept_mechanism = :redirect
+
+      # Stub again so that it validates the parameters we want
+      nexmo.expects(:post).
+          once.
+          with() { |path, params| params[:to] == DEFAULT_INTERNAL_PHONE_NUMBER && params[:text].length > 'Foo'.length && params[:text].include?('Foo') }.
+          returns({ 'messages' => ['status' => 0, 'message-id' => '123456']})
+
+      # Try to send an external message
+      result = nexmo.send_message(from: DEFAULT_INTERNAL_PHONE_NUMBER, to: EXTERNAL_PHONE_NUMBERS.first, text: 'Foo')
+
+      # Check that return is appropriate. The rest got checked in the stub
+      refute_nil result
+
+      # Stub again so that it validates the parameters we want
+      nexmo.expects(:post).
+          once.
+          with() { |path, params| params[:to] == INTERNAL_PHONE_NUMBERS.last && params[:text] = 'Foo' }.
+          returns({ 'messages' => ['status' => 0, 'message-id' => '123456']})
+
+      # Try to send an internal message
+      result = nexmo.send_message(from: DEFAULT_INTERNAL_PHONE_NUMBER, to: INTERNAL_PHONE_NUMBERS.last, text: 'Foo')
+
+      # Check that it got delivered. The rest got checked in the stub
+      refute_nil result
+    end
+
+    should "hook Twilio" do
+      twilio = Twilio::REST::Client.new 'blah', 'bleh'
+      SmsSafe.hook!(:twilio)
+
+      # Stub the "post" method so that it doesn't actually do a post
+      # I'm doing that instead of stubbing "send_message", since we're already monkeypatching send_message, and I don't want those two to collide
+      twilio.expects(:post).never
+
+      # Try to send an external message
+      result = twilio.messages.create(from: DEFAULT_INTERNAL_PHONE_NUMBER, to: EXTERNAL_PHONE_NUMBERS.first,  body: 'Foo')
+
+      # Check that return is nil and that nothing got sent
+      assert_nil result
+
+      # Change configuration to redirect
+      SmsSafe.configuration.intercept_mechanism = :redirect
+
+      # Stub again so that it validates the parameters we want
+      twilio.expects(:post).
+          once.
+          with() { |path, params| params[:to] == DEFAULT_INTERNAL_PHONE_NUMBER && params[:body].length > 'Foo'.length && params[:body].include?('Foo') }.
+          returns({ 'sid' => 'Message01'})
+
+      # Try to send an external message
+      result = twilio.messages.create(from: DEFAULT_INTERNAL_PHONE_NUMBER, to: EXTERNAL_PHONE_NUMBERS.first, body: 'Foo')
+
+      # Check that return is appropriate. The rest got checked in the stub
+      refute_nil result
+
+      # Stub again so that it validates the parameters we want
+      twilio.expects(:post).
+          once.
+          with() { |path, params| params[:to] == INTERNAL_PHONE_NUMBERS.last && params[:body] = 'Foo' }.
+          returns({ 'sid' => 'Message01'})
+
+      # Try to send an internal message
+      result = twilio.messages.create(from: DEFAULT_INTERNAL_PHONE_NUMBER, to: INTERNAL_PHONE_NUMBERS.last, body: 'Foo')
+
+      # Check that it got delivered. The rest got checked in the stub
+      refute_nil result
+    end
+
+    should "raise if hooking an invalid library" do
+      assert_raises(SmsSafe::InvalidConfigSettingError) do
+        SmsSafe.hook!(:invalid)
+      end
+    end
+  end
+end