actionmailer 3.0.4 → 7.1.6

data/lib/action_mailer/parameterized.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module ActionMailer
+  # = Action Mailer \Parameterized
+  #
+  # 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_writer :params
+
+      def params
+        @params ||= {}
+      end
+    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
+        ruby2_keywords(:method_missing)
+
+        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
+      ruby2_keywords(:initialize)
+
+      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
+            @mailer_class.delivery_job.set(options).perform_later(
+              @mailer_class.name, @action.to_s, delivery_method.to_s, params: @params, args: @args)
+          end
+        end
+    end
+  end
+end

data/lib/action_mailer/preview.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "active_support/descendants_tracker"
+
+module ActionMailer
+  module Previews # :nodoc:
+    extend ActiveSupport::Concern
+
+    included do
+      # Add the location of mailer previews through app configuration:
+      #
+      #     config.action_mailer.preview_paths << "#{Rails.root}/lib/mailer_previews"
+      #
+      mattr_accessor :preview_paths, instance_writer: false, default: []
+
+      # Enable or disable mailer previews through app configuration:
+      #
+      #     config.action_mailer.show_previews = true
+      #
+      # Defaults to +true+ for development environment
+      #
+      mattr_accessor :show_previews, instance_writer: false
+
+      # :nodoc:
+      mattr_accessor :preview_interceptors, instance_writer: false, default: [ActionMailer::InlinePreviewInterceptor]
+    end
+
+    def preview_path
+      ActionMailer.deprecator.warn(<<-MSG.squish)
+        Using preview_path option is deprecated and will be removed in Rails 7.2.
+        Please use preview_paths instead.
+      MSG
+      self.class.preview_paths.first
+    end
+
+    module ClassMethods
+      def preview_path=(value)
+        ActionMailer.deprecator.warn(<<-MSG.squish)
+          Using preview_path= option is deprecated and will be removed in Rails 7.2.
+          Please use preview_paths= instead.
+        MSG
+        self.preview_paths << value
+      end
+
+      def preview_path
+        ActionMailer.deprecator.warn(<<-MSG.squish)
+          Using preview_path option is deprecated and will be removed in Rails 7.2.
+          Please use preview_paths instead.
+        MSG
+        self.preview_paths.first
+      end
+
+      # Register one or more Interceptors which will be called before mail is previewed.
+      def register_preview_interceptors(*interceptors)
+        interceptors.flatten.compact.each { |interceptor| register_preview_interceptor(interceptor) }
+      end
+
+      # Unregister one or more previously registered Interceptors.
+      def unregister_preview_interceptors(*interceptors)
+        interceptors.flatten.compact.each { |interceptor| unregister_preview_interceptor(interceptor) }
+      end
+
+      # Register an Interceptor which will be called before mail is previewed.
+      # Either a class or a string can be passed in as the Interceptor. If a
+      # string is passed in it will be constantized.
+      def register_preview_interceptor(interceptor)
+        preview_interceptor = interceptor_class_for(interceptor)
+
+        unless preview_interceptors.include?(preview_interceptor)
+          preview_interceptors << preview_interceptor
+        end
+      end
+
+      # Unregister a previously registered Interceptor.
+      # Either a class or a string can be passed in as the Interceptor. If a
+      # string is passed in it will be constantized.
+      def unregister_preview_interceptor(interceptor)
+        preview_interceptors.delete(interceptor_class_for(interceptor))
+      end
+
+      private
+        def interceptor_class_for(interceptor)
+          case interceptor
+          when String, Symbol
+            interceptor.to_s.camelize.constantize
+          else
+            interceptor
+          end
+        end
+    end
+  end
+
+  class Preview
+    extend ActiveSupport::DescendantsTracker
+
+    attr_reader :params
+
+    def initialize(params = {})
+      @params = params
+    end
+
+    class << self
+      # Returns all mailer preview classes.
+      def all
+        load_previews if descendants.empty?
+        descendants.sort_by { |mailer| mailer.name.titleize }
+      end
+
+      # Returns the mail object for the given email name. The registered preview
+      # interceptors will be informed so that they can transform the message
+      # as they would if the mail was actually being delivered.
+      def call(email, params = {})
+        preview = new(params)
+        message = preview.public_send(email)
+        inform_preview_interceptors(message)
+        message
+      end
+
+      # Returns all of the available email previews.
+      def emails
+        public_instance_methods(false).map(&:to_s).sort
+      end
+
+      # Returns +true+ if the email exists.
+      def email_exists?(email)
+        emails.include?(email)
+      end
+
+      # Returns +true+ if the preview exists.
+      def exists?(preview)
+        all.any? { |p| p.preview_name == preview }
+      end
+
+      # Find a mailer preview by its underscored class name.
+      def find(preview)
+        all.find { |p| p.preview_name == preview }
+      end
+
+      # Returns the underscored name of the mailer preview without the suffix.
+      def preview_name
+        name.delete_suffix("Preview").underscore
+      end
+
+      private
+        def load_previews
+          preview_paths.each do |preview_path|
+            Dir["#{preview_path}/**/*_preview.rb"].sort.each { |file| require file }
+          end
+        end
+
+        def preview_paths
+          Base.preview_paths
+        end
+
+        def show_previews
+          Base.show_previews
+        end
+
+        def inform_preview_interceptors(message)
+          Base.preview_interceptors.each do |interceptor|
+            interceptor.previewing_email(message)
+          end
+        end
+    end
+  end
+end

data/lib/action_mailer/queued_delivery.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ActionMailer
+  module QueuedDelivery
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :delivery_job, default: ::ActionMailer::MailDeliveryJob
+      class_attribute :deliver_later_queue_name, default: :mailers
+    end
+  end
+end

data/lib/action_mailer/railtie.rb

@@ -1,9 +1,19 @@
+# frozen_string_literal: true
+
+require "active_job/railtie"
 require "action_mailer"
 require "rails"
+require "abstract_controller/railties/routes_helpers"
 
 module ActionMailer
-  class Railtie < Rails::Railtie
+  class Railtie < Rails::Railtie # :nodoc:
     config.action_mailer = ActiveSupport::OrderedOptions.new
+    config.action_mailer.preview_paths = []
+    config.eager_load_namespaces << ActionMailer
+
+    initializer "action_mailer.deprecator", before: :load_environment_config do |app|
+      app.deprecators[:action_mailer] = ActionMailer.deprecator
+    end
 
     initializer "action_mailer.logger" do
       ActiveSupport.on_load(:action_mailer) { self.logger ||= Rails.logger }
@@ -13,14 +23,72 @@ module ActionMailer
       paths   = app.config.paths
       options = app.config.action_mailer
 
-      options.assets_dir      ||= paths.public.to_a.first
-      options.javascripts_dir ||= paths.public.javascripts.to_a.first
-      options.stylesheets_dir ||= paths.public.stylesheets.to_a.first
+      options.assets_dir      ||= paths["public"].first
+      options.javascripts_dir ||= paths["public/javascripts"].first
+      options.stylesheets_dir ||= paths["public/stylesheets"].first
+      options.show_previews = Rails.env.development? if options.show_previews.nil?
+      options.cache_store ||= Rails.cache
+      options.preview_paths |= ["#{Rails.root}/test/mailers/previews"]
+
+      # make sure readers methods get compiled
+      options.asset_host          ||= app.config.asset_host
+      options.relative_url_root   ||= app.config.relative_url_root
+
+      ActiveSupport.on_load(:action_mailer) do
+        include AbstractController::UrlFor
+        extend ::AbstractController::Railties::RoutesHelpers.with(app.routes, false)
+        include app.routes.mounted_helpers
+
+        register_interceptors(options.delete(:interceptors))
+        register_preview_interceptors(options.delete(:preview_interceptors))
+        register_observers(options.delete(:observers))
+        self.preview_paths |= options[:preview_paths]
+
+        if delivery_job = options.delete(:delivery_job)
+          self.delivery_job = delivery_job.constantize
+        end
+
+        if options.smtp_settings
+          self.smtp_settings = options.smtp_settings
+        end
+
+        smtp_timeout = options.delete(:smtp_timeout)
+
+        if self.smtp_settings && smtp_timeout
+          self.smtp_settings[:open_timeout] ||= smtp_timeout
+          self.smtp_settings[:read_timeout] ||= smtp_timeout
+        end
+
+        options.each { |k, v| send("#{k}=", v) }
+      end
+
+      ActiveSupport.on_load(:action_dispatch_integration_test) do
+        include ActionMailer::TestHelper
+        include ActionMailer::TestCase::ClearTestDeliveries
+      end
+    end
+
+    initializer "action_mailer.set_autoload_paths", before: :set_autoload_paths do |app|
+      options = app.config.action_mailer
+      app.config.paths["test/mailers/previews"].concat(options.preview_paths)
+    end
 
+    initializer "action_mailer.compile_config_methods" do
       ActiveSupport.on_load(:action_mailer) do
-        include app.routes.url_helpers
-        options.each { |k,v| send("#{k}=", v) }
+        config.compile_methods! if config.respond_to?(:compile_methods!)
+      end
+    end
+
+    config.after_initialize do |app|
+      options = app.config.action_mailer
+
+      if options.show_previews
+        app.routes.prepend do
+          get "/rails/mailers" => "rails/mailers#index", internal: true
+          get "/rails/mailers/download/*path" => "rails/mailers#download", internal: true
+          get "/rails/mailers/*path" => "rails/mailers#preview", internal: true
+        end
       end
     end
   end
-end
+end

data/lib/action_mailer/rescuable.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActionMailer # :nodoc:
+  # = Action Mailer \Rescuable
+  #
+  # Provides
+  # {rescue_from}[rdoc-ref:ActiveSupport::Rescuable::ClassMethods#rescue_from]
+  # for mailers. Wraps mailer action processing, mail job processing, and mail
+  # delivery to handle configured errors.
+  module Rescuable
+    extend ActiveSupport::Concern
+    include ActiveSupport::Rescuable
+
+    class_methods do
+      def handle_exception(exception) # :nodoc:
+        rescue_with_handler(exception) || raise(exception)
+      end
+    end
+
+    def handle_exceptions # :nodoc:
+      yield
+    rescue => exception
+      rescue_with_handler(exception) || raise
+    end
+
+    private
+      def process(...)
+        handle_exceptions do
+          super
+        end
+      end
+  end
+end

data/lib/action_mailer/test_case.rb

@@ -1,25 +1,64 @@
+# frozen_string_literal: true
+
+require "active_support/test_case"
+require "rails-dom-testing"
+
 module ActionMailer
   class NonInferrableMailerError < ::StandardError
     def initialize(name)
-      super "Unable to determine the mailer to test from #{name}. " +
-        "You'll need to specify it using tests YourMailer in your " +
+      super "Unable to determine the mailer to test from #{name}. " \
+        "You'll need to specify it using tests YourMailer in your " \
         "test case definition"
     end
   end
 
   class TestCase < ActiveSupport::TestCase
+    module ClearTestDeliveries
+      extend ActiveSupport::Concern
+
+      included do
+        setup :clear_test_deliveries
+        teardown :clear_test_deliveries
+      end
+
+      private
+        def clear_test_deliveries
+          if ActionMailer::Base.delivery_method == :test
+            ActionMailer::Base.deliveries.clear
+          end
+        end
+    end
+
     module Behavior
       extend ActiveSupport::Concern
 
+      include ActiveSupport::Testing::ConstantLookup
       include TestHelper
+      include Rails::Dom::Testing::Assertions::SelectorAssertions
+      include Rails::Dom::Testing::Assertions::DomAssertions
+
+      included do
+        class_attribute :_mailer_class
+        setup :initialize_test_deliveries
+        setup :set_expected_mail
+        teardown :restore_test_deliveries
+        ActiveSupport.run_load_hooks(:action_mailer_test_case, self)
+      end
 
       module ClassMethods
         def tests(mailer)
-          write_inheritable_attribute(:mailer_class, mailer)
+          case mailer
+          when String, Symbol
+            self._mailer_class = mailer.to_s.camelize.constantize
+          when Module
+            self._mailer_class = mailer
+          else
+            raise NonInferrableMailerError.new(mailer)
+          end
         end
 
         def mailer_class
-          if mailer = read_inheritable_attribute(:mailer_class)
+          if mailer = _mailer_class
             mailer
           else
             tests determine_default_mailer(name)
@@ -27,30 +66,52 @@ module ActionMailer
         end
 
         def determine_default_mailer(name)
-          name.sub(/Test$/, '').constantize
-        rescue NameError
-          raise NonInferrableMailerError.new(name)
+          mailer = determine_constant_from_test_name(name) do |constant|
+            Class === constant && constant < ActionMailer::Base
+          end
+          raise NonInferrableMailerError.new(name) if mailer.nil?
+          mailer
         end
       end
 
-      module InstanceMethods
-
-      protected
+      # Reads the fixture file for the given mailer.
+      #
+      # This is useful when testing mailers by being able to write the body of
+      # an email inside a fixture. See the testing guide for a concrete example:
+      # https://guides.rubyonrails.org/testing.html#revenge-of-the-fixtures
+      def read_fixture(action)
+        IO.readlines(File.join(Rails.root, "test", "fixtures", self.class.mailer_class.name.underscore, action))
+      end
 
+      private
         def initialize_test_deliveries
-          ActionMailer::Base.delivery_method = :test
+          set_delivery_method :test
+          @old_perform_deliveries = ActionMailer::Base.perform_deliveries
           ActionMailer::Base.perform_deliveries = true
           ActionMailer::Base.deliveries.clear
         end
 
+        def restore_test_deliveries
+          restore_delivery_method
+          ActionMailer::Base.perform_deliveries = @old_perform_deliveries
+        end
+
+        def set_delivery_method(method)
+          @old_delivery_method = ActionMailer::Base.delivery_method
+          ActionMailer::Base.delivery_method = method
+        end
+
+        def restore_delivery_method
+          ActionMailer::Base.deliveries.clear
+          ActionMailer::Base.delivery_method = @old_delivery_method
+        end
+
         def set_expected_mail
           @expected = Mail.new
           @expected.content_type ["text", "plain", { "charset" => charset }]
-          @expected.mime_version = '1.0'
+          @expected.mime_version = "1.0"
         end
 
-      private
-
         def charset
           "UTF-8"
         end
@@ -58,19 +119,8 @@ module ActionMailer
         def encode(subject)
           Mail::Encodings.q_value_encode(subject, charset)
         end
-
-        def read_fixture(action)
-          IO.readlines(File.join(Rails.root, 'test', 'fixtures', self.class.mailer_class.name.underscore, action))
-        end
-      end
-
-      included do
-        setup :initialize_test_deliveries
-        setup :set_expected_mail
-      end
     end
 
     include Behavior
-
   end
 end