actionmailer 4.2.11 → 5.1.0

data/lib/action_mailer/collector.rb

@@ -1,6 +1,6 @@
-require 'abstract_controller/collector'
-require 'active_support/core_ext/hash/reverse_merge'
-require 'active_support/core_ext/array/extract_options'
+require "abstract_controller/collector"
+require "active_support/core_ext/hash/reverse_merge"
+require "active_support/core_ext/array/extract_options"
 
 module ActionMailer
   class Collector

data/lib/action_mailer/delivery_job.rb

@@ -1,13 +1,34 @@
-require 'active_job'
+require "active_job"
 
 module ActionMailer
   # The <tt>ActionMailer::DeliveryJob</tt> class is used when you
   # want to send emails outside of the request-response cycle.
+  #
+  # Exceptions are rescued and handled by the mailer class.
   class DeliveryJob < ActiveJob::Base # :nodoc:
-    queue_as :mailers
+    queue_as { ActionMailer::Base.deliver_later_queue_name }
 
-    def perform(mailer, mail_method, delivery_method, *args) # :nodoc:
+    rescue_from StandardError, with: :handle_exception_with_mailer_class
+
+    def perform(mailer, mail_method, delivery_method, *args) #:nodoc:
       mailer.constantize.public_send(mail_method, *args).send(delivery_method)
     end
+
+    private
+      # "Deserialize" the mailer class name by hand in case another argument
+      # (like a Global ID reference) raised DeserializationError.
+      def mailer_class
+        if mailer = Array(@serialized_arguments).first || Array(arguments).first
+          mailer.constantize
+        end
+      end
+
+      def handle_exception_with_mailer_class(exception)
+        if klass = mailer_class
+          klass.handle_exception exception
+        else
+          raise exception
+        end
+      end
   end
 end

data/lib/action_mailer/delivery_methods.rb

@@ -1,4 +1,4 @@
-require 'tmpdir'
+require "tmpdir"
 
 module ActionMailer
   # This module handles everything related to mail delivery, from registering
@@ -16,13 +16,16 @@ module ActionMailer
       cattr_accessor :perform_deliveries
       self.perform_deliveries = true
 
+      cattr_accessor :deliver_later_queue_name
+      self.deliver_later_queue_name = :mailers
+
       self.delivery_methods = {}.freeze
       self.delivery_method  = :smtp
 
       add_delivery_method :smtp, Mail::SMTP,
         address:              "localhost",
         port:                 25,
-        domain:               'localhost.localdomain',
+        domain:               "localhost.localdomain",
         user_name:            nil,
         password:             nil,
         authentication:       nil,
@@ -32,8 +35,8 @@ module ActionMailer
         location: defined?(Rails.root) ? "#{Rails.root}/tmp/mails" : "#{Dir.tmpdir}/mails"
 
       add_delivery_method :sendmail, Mail::Sendmail,
-        location:  '/usr/sbin/sendmail',
-        arguments: '-i'
+        location:  "/usr/sbin/sendmail",
+        arguments: "-i"
 
       add_delivery_method :test, Mail::TestMailer
     end
@@ -48,15 +51,15 @@ module ActionMailer
       #
       #   add_delivery_method :sendmail, Mail::Sendmail,
       #     location:  '/usr/sbin/sendmail',
-      #     arguments: '-i -t'
-      def add_delivery_method(symbol, klass, default_options={})
+      #     arguments: '-i'
+      def add_delivery_method(symbol, klass, default_options = {})
         class_attribute(:"#{symbol}_settings") unless respond_to?(:"#{symbol}_settings")
         send(:"#{symbol}_settings=", default_options)
         self.delivery_methods = delivery_methods.merge(symbol.to_sym => klass).freeze
       end
 
-      def wrap_delivery_behavior(mail, method=nil, options=nil) # :nodoc:
-        method ||= self.delivery_method
+      def wrap_delivery_behavior(mail, method = nil, options = nil) # :nodoc:
+        method ||= delivery_method
         mail.delivery_handler = self
 
         case method

data/lib/action_mailer/gem_version.rb

@@ -1,13 +1,13 @@
 module ActionMailer
-  # Returns the version of the currently loaded Action Mailer as a <tt>Gem::Version</tt>
+  # Returns the version of the currently loaded Action Mailer as a <tt>Gem::Version</tt>.
   def self.gem_version
     Gem::Version.new VERSION::STRING
   end
 
   module VERSION
-    MAJOR = 4
-    MINOR = 2
-    TINY  = 11
+    MAJOR = 5
+    MINOR = 1
+    TINY  = 0
     PRE   = nil
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

data/lib/action_mailer/inline_preview_interceptor.rb

@@ -1,17 +1,17 @@
-require 'base64'
+require "base64"
 
 module ActionMailer
   # Implements a mailer preview interceptor that converts image tag src attributes
   # that use inline cid: style urls to data: style urls so that they are visible
-  # when previewing a HTML email in a web browser.
+  # when previewing an HTML email in a web browser.
   #
-  # This interceptor is not enabled by default, to use it just register it like any
-  # other mailer preview interceptor:
+  # This interceptor is enabled by default. To disable it, delete it from the
+  # <tt>ActionMailer::Base.preview_interceptors</tt> array:
   #
-  #   ActionMailer::Base.register_preview_interceptor(ActionMailer::InlinePreviewInterceptor)
+  #   ActionMailer::Base.preview_interceptors.delete(ActionMailer::InlinePreviewInterceptor)
   #
   class InlinePreviewInterceptor
-    PATTERN  = /src=(?:"cid:[^"]+"|'cid:[^']+')/i
+    PATTERN = /src=(?:"cid:[^"]+"|'cid:[^']+')/i
 
     include Base64
 
@@ -26,7 +26,7 @@ module ActionMailer
     def transform! #:nodoc:
       return message if html_part.blank?
 
-      html_source.gsub!(PATTERN) do |match|
+      html_part.body = html_part.decoded.gsub(PATTERN) do |match|
         if part = find_part(match[9..-2])
           %[src="#{data_url(part)}"]
         else
@@ -46,16 +46,12 @@ module ActionMailer
         @html_part ||= message.html_part
       end
 
-      def html_source
-        html_part.body.raw_source
-      end
-
       def data_url(part)
         "data:#{part.mime_type};base64,#{strict_encode64(part.body.raw_source)}"
       end
 
       def find_part(cid)
-        message.all_parts.find{ |p| p.attachment? && p.cid == cid }
+        message.all_parts.find { |p| p.attachment? && p.cid == cid }
       end
   end
 end

data/lib/action_mailer/log_subscriber.rb

@@ -1,14 +1,14 @@
-require 'active_support/log_subscriber'
+require "active_support/log_subscriber"
 
 module ActionMailer
   # Implements the ActiveSupport::LogSubscriber for logging notifications when
-  # email is delivered and received.
+  # email is delivered or received.
   class LogSubscriber < ActiveSupport::LogSubscriber
     # An email was delivered.
     def deliver(event)
       info do
-        recipients = Array(event.payload[:to]).join(', ')
-        "\nSent mail to #{recipients} (#{event.duration.round(1)}ms)"
+        recipients = Array(event.payload[:to]).join(", ")
+        "Sent mail to #{recipients} (#{event.duration.round(1)}ms)"
       end
 
       debug { event.payload[:mail] }
@@ -16,7 +16,7 @@ module ActionMailer
 
     # An email was received.
     def receive(event)
-      info { "\nReceived mail (#{event.duration.round(1)}ms)" }
+      info { "Received mail (#{event.duration.round(1)}ms)" }
       debug { event.payload[:mail] }
     end
 
@@ -25,11 +25,11 @@ module ActionMailer
       debug do
         mailer = event.payload[:mailer]
         action = event.payload[:action]
-        "\n#{mailer}##{action}: processed outbound mail in #{event.duration.round(1)}ms"
+        "#{mailer}##{action}: processed outbound mail in #{event.duration.round(1)}ms"
       end
     end
 
-    # Use the logger configured for ActionMailer::Base
+    # Use the logger configured for ActionMailer::Base.
     def logger
       ActionMailer::Base.logger
     end

data/lib/action_mailer/mail_helper.rb

@@ -4,7 +4,17 @@ module ActionMailer
   # attachments list.
   module MailHelper
     # Take the text and format it, indented two spaces for each line, and
-    # wrapped at 72 columns.
+    # wrapped at 72 columns:
+    #
+    #   text = <<-TEXT
+    #     This is
+    #     the      paragraph.
+    #
+    #     * item1 * item2
+    #   TEXT
+    #
+    #   block_format text
+    #   # => "  This is the paragraph.\n\n  * item1\n  * item2\n"
     def block_format(text)
       formatted = text.split(/\n\r?\n/).collect { |paragraph|
         format_paragraph(paragraph)
@@ -33,6 +43,8 @@ module ActionMailer
     end
 
     # Returns +text+ wrapped at +len+ columns and indented +indent+ spaces.
+    # By default column length +len+ equals 72 characters and indent
+    # +indent+ equal two spaces.
     #
     #   my_text = 'Here is a sample text with more than 40 characters'
     #
@@ -42,7 +54,7 @@ module ActionMailer
       sentences = [[]]
 
       text.split.each do |word|
-        if sentences.first.present? && (sentences.last + [word]).join(' ').length > len
+        if sentences.first.present? && (sentences.last + [word]).join(" ").length > len
           sentences << [word]
         else
           sentences.last << word

data/lib/action_mailer/message_delivery.rb

@@ -1,8 +1,6 @@
-require 'delegate'
-require 'active_support/core_ext/string/filters'
+require "delegate"
 
 module ActionMailer
-
   # The <tt>ActionMailer::MessageDelivery</tt> class is used by
   # <tt>ActionMailer::Base</tt> when creating a new mailer.
   # <tt>MessageDelivery</tt> is a wrapper (+Delegator+ subclass) around a lazy
@@ -15,25 +13,35 @@ module ActionMailer
   #   Notifier.welcome(User.first).deliver_later # enqueue email delivery as a job through Active Job
   #   Notifier.welcome(User.first).message       # a Mail::Message object
   class MessageDelivery < Delegator
-    def initialize(mailer, mail_method, *args) #:nodoc:
-      @mailer = mailer
-      @mail_method = mail_method
-      @args = args
+    def initialize(mailer_class, action, *args) #:nodoc:
+      @mailer_class, @action, @args = mailer_class, action, args
+
+      # The mail is only processed if we try to call any methods on it.
+      # Typical usage will leave it unloaded and call deliver_later.
+      @processed_mailer = nil
+      @mail_message = nil
     end
 
+    # Method calls are delegated to the Mail::Message that's ready to deliver.
     def __getobj__ #:nodoc:
-      @obj ||= @mailer.send(:new, @mail_method, *@args).message
+      @mail_message ||= processed_mailer.message
     end
 
-    def __setobj__(obj) #:nodoc:
-      @obj = obj
+    # Unused except for delegator internals (dup, marshaling).
+    def __setobj__(mail_message) #:nodoc:
+      @mail_message = mail_message
     end
 
-    # Returns the Mail::Message object
+    # Returns the resulting Mail::Message
     def message
       __getobj__
     end
 
+    # Was the delegate loaded, causing the mailer action to be processed?
+    def processed?
+      @processed_mailer || @mail_message
+    end
+
     # Enqueues the email to be delivered through Active Job. When the
     # job runs it will send the email using +deliver_now!+. That means
     # that the message will be sent bypassing checking +perform_deliveries+
@@ -48,7 +56,7 @@ module ActionMailer
     # * <tt>:wait</tt> - Enqueue the email to be delivered with a delay
     # * <tt>:wait_until</tt> - Enqueue the email to be delivered at (after) a specific date / time
     # * <tt>:queue</tt> - Enqueue the email on the specified queue
-    def deliver_later!(options={})
+    def deliver_later!(options = {})
       enqueue_delivery :deliver_now!, options
     end
 
@@ -61,10 +69,10 @@ module ActionMailer
     #
     # Options:
     #
-    # * <tt>:wait</tt> - Enqueue the email to be delivered with a delay
-    # * <tt>:wait_until</tt> - Enqueue the email to be delivered at (after) a specific date / time
-    # * <tt>:queue</tt> - Enqueue the email on the specified queue
-    def deliver_later(options={})
+    # * <tt>:wait</tt> - Enqueue the email to be delivered with a delay.
+    # * <tt>:wait_until</tt> - Enqueue the email to be delivered at (after) a specific date / time.
+    # * <tt>:queue</tt> - Enqueue the email on the specified queue.
+    def deliver_later(options = {})
       enqueue_delivery :deliver_now, options
     end
 
@@ -74,7 +82,9 @@ module ActionMailer
     #   Notifier.welcome(User.first).deliver_now!
     #
     def deliver_now!
-      message.deliver!
+      processed_mailer.handle_exceptions do
+        message.deliver!
+      end
     end
 
     # Delivers an email:
@@ -82,34 +92,34 @@ module ActionMailer
     #   Notifier.welcome(User.first).deliver_now
     #
     def deliver_now
-      message.deliver
-    end
-
-    def deliver! #:nodoc:
-      ActiveSupport::Deprecation.warn(<<-MSG.squish)
-        `#deliver!` is deprecated and will be removed in Rails 5. Use
-        `#deliver_now!` to deliver immediately or `#deliver_later!` to
-        deliver through Active Job.
-      MSG
-
-      deliver_now!
-    end
-
-    def deliver #:nodoc:
-      ActiveSupport::Deprecation.warn(<<-MSG.squish)
-        `#deliver` is deprecated and will be removed in Rails 5. Use
-        `#deliver_now` to deliver immediately or `#deliver_later` to
-        deliver through Active Job.
-      MSG
-
-      deliver_now
+      processed_mailer.handle_exceptions do
+        message.deliver
+      end
     end
 
     private
+      # Returns the processed Mailer instance. We keep this instance
+      # on hand so we can delegate exception handling to it.
+      def processed_mailer
+        @processed_mailer ||= @mailer_class.new.tap do |mailer|
+          mailer.process @action, *@args
+        end
+      end
 
-      def enqueue_delivery(delivery_method, options={})
-        args = @mailer.name, @mail_method.to_s, delivery_method.to_s, *@args
-        ActionMailer::DeliveryJob.set(options).perform_later(*args)
+      def enqueue_delivery(delivery_method, options = {})
+        if processed?
+          ::Kernel.raise "You've accessed the message before asking to " \
+            "deliver it later, so you may have made local changes that would " \
+            "be silently lost if we enqueued a job to deliver it. Why? Only " \
+            "the mailer method *arguments* are passed with the delivery job! " \
+            "Do not access the message in any way if you mean to deliver it " \
+            "later. Workarounds: 1. don't touch the message before calling " \
+            "#deliver_later, 2. only touch the message *within your mailer " \
+            "method*, or 3. use a custom Active Job instead of #deliver_later."
+        else
+          args = @mailer_class.name, @action.to_s, delivery_method.to_s, *@args
+          ::ActionMailer::DeliveryJob.set(options).perform_later(*args)
+        end
       end
   end
 end

data/lib/action_mailer/parameterized.rb

@@ -0,0 +1,152 @@
+module ActionMailer
+  # Provides the option to parameterize mailers in order to share instance variable
+  # setup, processing, and common headers.
+  #
+  # Consider this example that does not use parameterization:
+  #
+  #   class InvitationsMailer < ApplicationMailer
+  #     def account_invitation(inviter, invitee)
+  #       @account = inviter.account
+  #       @inviter = inviter
+  #       @invitee = invitee
+  #
+  #       subject = "#{@inviter.name} invited you to their Basecamp (#{@account.name})"
+  #
+  #       mail \
+  #         subject:   subject,
+  #         to:        invitee.email_address,
+  #         from:      common_address(inviter),
+  #         reply_to:  inviter.email_address_with_name
+  #     end
+  #
+  #     def project_invitation(project, inviter, invitee)
+  #       @account = inviter.account
+  #       @project = project
+  #       @inviter = inviter
+  #       @invitee = invitee
+  #       @summarizer = ProjectInvitationSummarizer.new(@project.bucket)
+  #
+  #       subject = "#{@inviter.name.familiar} added you to a project in Basecamp (#{@account.name})"
+  #
+  #       mail \
+  #         subject:   subject,
+  #         to:        invitee.email_address,
+  #         from:      common_address(inviter),
+  #         reply_to:  inviter.email_address_with_name
+  #     end
+  #
+  #     def bulk_project_invitation(projects, inviter, invitee)
+  #       @account  = inviter.account
+  #       @projects = projects.sort_by(&:name)
+  #       @inviter  = inviter
+  #       @invitee  = invitee
+  #
+  #       subject = "#{@inviter.name.familiar} added you to some new stuff in Basecamp (#{@account.name})"
+  #
+  #       mail \
+  #         subject:   subject,
+  #         to:        invitee.email_address,
+  #         from:      common_address(inviter),
+  #         reply_to:  inviter.email_address_with_name
+  #     end
+  #   end
+  #
+  #   InvitationsMailer.account_invitation(person_a, person_b).deliver_later
+  #
+  # Using parameterized mailers, this can be rewritten as:
+  #
+  #   class InvitationsMailer < ApplicationMailer
+  #     before_action { @inviter, @invitee = params[:inviter], params[:invitee] }
+  #     before_action { @account = params[:inviter].account }
+  #
+  #     default to:       -> { @invitee.email_address },
+  #             from:     -> { common_address(@inviter) },
+  #             reply_to: -> { @inviter.email_address_with_name }
+  #
+  #     def account_invitation
+  #       mail subject: "#{@inviter.name} invited you to their Basecamp (#{@account.name})"
+  #     end
+  #
+  #     def project_invitation
+  #       @project    = params[:project]
+  #       @summarizer = ProjectInvitationSummarizer.new(@project.bucket)
+  #
+  #       mail subject: "#{@inviter.name.familiar} added you to a project in Basecamp (#{@account.name})"
+  #     end
+  #
+  #     def bulk_project_invitation
+  #       @projects = params[:projects].sort_by(&:name)
+  #
+  #       mail subject: "#{@inviter.name.familiar} added you to some new stuff in Basecamp (#{@account.name})"
+  #     end
+  #   end
+  #
+  #   InvitationsMailer.with(inviter: person_a, invitee: person_b).account_invitation.deliver_later
+  module Parameterized
+    extend ActiveSupport::Concern
+
+    included do
+      attr_accessor :params
+    end
+
+    module ClassMethods
+      # Provide the parameters to the mailer in order to use them in the instance methods and callbacks.
+      #
+      #   InvitationsMailer.with(inviter: person_a, invitee: person_b).account_invitation.deliver_later
+      #
+      # See Parameterized documentation for full example.
+      def with(params)
+        ActionMailer::Parameterized::Mailer.new(self, params)
+      end
+    end
+
+    class Mailer # :nodoc:
+      def initialize(mailer, params)
+        @mailer, @params = mailer, params
+      end
+
+      private
+        def method_missing(method_name, *args)
+          if @mailer.action_methods.include?(method_name.to_s)
+            ActionMailer::Parameterized::MessageDelivery.new(@mailer, method_name, @params, *args)
+          else
+            super
+          end
+        end
+
+        def respond_to_missing?(method, include_all = false)
+          @mailer.respond_to?(method, include_all)
+        end
+    end
+
+    class MessageDelivery < ActionMailer::MessageDelivery # :nodoc:
+      def initialize(mailer_class, action, params, *args)
+        super(mailer_class, action, *args)
+        @params = params
+      end
+
+      private
+        def processed_mailer
+          @processed_mailer ||= @mailer_class.new.tap do |mailer|
+            mailer.params = @params
+            mailer.process @action, *@args
+          end
+        end
+
+        def enqueue_delivery(delivery_method, options = {})
+          if processed?
+            super
+          else
+            args = @mailer_class.name, @action.to_s, delivery_method.to_s, @params, *@args
+            ActionMailer::Parameterized::DeliveryJob.set(options).perform_later(*args)
+          end
+        end
+    end
+
+    class DeliveryJob < ActionMailer::DeliveryJob # :nodoc:
+      def perform(mailer, mail_method, delivery_method, params, *args)
+        mailer.constantize.with(params).public_send(mail_method, *args).send(delivery_method)
+      end
+    end
+  end
+end