Nest ActionMailbox::Base in the API docs (missed in 6c168aa)

1 files changed, 95 insertions, 93 deletions

diff --git a/actionmailbox/lib/action_mailbox/base.rb b/actionmailbox/lib/action_mailbox/base.rb
index bd76c8ff5f..76c3a4886c 100644
--- a/actionmailbox/lib/action_mailbox/base.rb
+++ b/actionmailbox/lib/action_mailbox/base.rb
@@ -5,109 +5,111 @@ require "active_support/rescuable"
 require "action_mailbox/callbacks"
 require "action_mailbox/routing"
 
-# The base class for all application mailboxes. Not intended to be inherited from directly. Inherit from
-# `ApplicationMailbox` instead, as that's where the app-specific routing is configured. This routing
-# is specified in the following ways:
-#
-#   class ApplicationMailbox < ActionMailbox::Base
-#     # Any of the recipients of the mail (whether to, cc, bcc) are matched against the regexp.
-#     routing /^replies@/i => :replies
-#
-#     # Any of the recipients of the mail (whether to, cc, bcc) needs to be an exact match for the string.
-#     routing "help@example.com" => :help
-#
-#     # Any callable (proc, lambda, etc) object is passed the inbound_email record and is a match if true.
-#     routing ->(inbound_email) { inbound_email.mail.to.size > 2 } => :multiple_recipients
-#
-#     # Any object responding to #match? is called with the inbound_email record as an argument. Match if true.
-#     routing CustomAddress.new => :custom
-#
-#     # Any inbound_email that has not been already matched will be sent to the BackstopMailbox.
-#     routing :all => :backstop
-#   end
-#
-# Application mailboxes need to overwrite the `#process` method, which is invoked by the framework after
-# callbacks have been run. The callbacks available are: `before_processing`, `after_processing`, and
-# `around_processing`. The primary use case is ensure certain preconditions to processing are fulfilled
-# using `before_processing` callbacks.
-#
-# If a precondition fails to be met, you can halt the processing using the `#bounced!` method,
-# which will silently prevent any further processing, but not actually send out any bounce notice. You
-# can also pair this behavior with the invocation of an Action Mailer class responsible for sending out
-# an actual bounce email. This is done using the `#bounce_with` method, which takes the mail object returned
-# by an Action Mailer method, like so:
-#
-#   class ForwardsMailbox < ApplicationMailbox
-#     before_processing :ensure_sender_is_a_user
-#
-#     private
-#       def ensure_sender_is_a_user
-#         unless User.exist?(email_address: mail.from)
-#           bounce_with UserRequiredMailer.missing(inbound_email)
-#         end
-#       end
-#   end
-#
-# During the processing of the inbound email, the status will be tracked. Before processing begins,
-# the email will normally have the `pending` status. Once processing begins, just before callbacks
-# and the `#process` method is called, the status is changed to `processing`. If processing is allowed to
-# complete, the status is changed to `delivered`. If a bounce is triggered, then `bounced`. If an unhandled
-# exception is bubbled up, then `failed`.
-#
-# Exceptions can be handled at the class level using the familiar `Rescuable` approach:
-#
-#   class ForwardsMailbox < ApplicationMailbox
-#     rescue_from(ApplicationSpecificVerificationError) { bounced! }
-#   end
-class ActionMailbox::Base
-  include ActiveSupport::Rescuable
-  include ActionMailbox::Callbacks, ActionMailbox::Routing
+module ActionMailbox
+  # The base class for all application mailboxes. Not intended to be inherited from directly. Inherit from
+  # `ApplicationMailbox` instead, as that's where the app-specific routing is configured. This routing
+  # is specified in the following ways:
+  #
+  #   class ApplicationMailbox < ActionMailbox::Base
+  #     # Any of the recipients of the mail (whether to, cc, bcc) are matched against the regexp.
+  #     routing /^replies@/i => :replies
+  #
+  #     # Any of the recipients of the mail (whether to, cc, bcc) needs to be an exact match for the string.
+  #     routing "help@example.com" => :help
+  #
+  #     # Any callable (proc, lambda, etc) object is passed the inbound_email record and is a match if true.
+  #     routing ->(inbound_email) { inbound_email.mail.to.size > 2 } => :multiple_recipients
+  #
+  #     # Any object responding to #match? is called with the inbound_email record as an argument. Match if true.
+  #     routing CustomAddress.new => :custom
+  #
+  #     # Any inbound_email that has not been already matched will be sent to the BackstopMailbox.
+  #     routing :all => :backstop
+  #   end
+  #
+  # Application mailboxes need to overwrite the `#process` method, which is invoked by the framework after
+  # callbacks have been run. The callbacks available are: `before_processing`, `after_processing`, and
+  # `around_processing`. The primary use case is ensure certain preconditions to processing are fulfilled
+  # using `before_processing` callbacks.
+  #
+  # If a precondition fails to be met, you can halt the processing using the `#bounced!` method,
+  # which will silently prevent any further processing, but not actually send out any bounce notice. You
+  # can also pair this behavior with the invocation of an Action Mailer class responsible for sending out
+  # an actual bounce email. This is done using the `#bounce_with` method, which takes the mail object returned
+  # by an Action Mailer method, like so:
+  #
+  #   class ForwardsMailbox < ApplicationMailbox
+  #     before_processing :ensure_sender_is_a_user
+  #
+  #     private
+  #       def ensure_sender_is_a_user
+  #         unless User.exist?(email_address: mail.from)
+  #           bounce_with UserRequiredMailer.missing(inbound_email)
+  #         end
+  #       end
+  #   end
+  #
+  # During the processing of the inbound email, the status will be tracked. Before processing begins,
+  # the email will normally have the `pending` status. Once processing begins, just before callbacks
+  # and the `#process` method is called, the status is changed to `processing`. If processing is allowed to
+  # complete, the status is changed to `delivered`. If a bounce is triggered, then `bounced`. If an unhandled
+  # exception is bubbled up, then `failed`.
+  #
+  # Exceptions can be handled at the class level using the familiar `Rescuable` approach:
+  #
+  #   class ForwardsMailbox < ApplicationMailbox
+  #     rescue_from(ApplicationSpecificVerificationError) { bounced! }
+  #   end
+  class Base
+    include ActiveSupport::Rescuable
+    include ActionMailbox::Callbacks, ActionMailbox::Routing
 
-  attr_reader :inbound_email
-  delegate :mail, :delivered!, :bounced!, to: :inbound_email
+    attr_reader :inbound_email
+    delegate :mail, :delivered!, :bounced!, to: :inbound_email
 
-  delegate :logger, to: ActionMailbox
+    delegate :logger, to: ActionMailbox
 
-  def self.receive(inbound_email)
-    new(inbound_email).perform_processing
-  end
+    def self.receive(inbound_email)
+      new(inbound_email).perform_processing
+    end
 
-  def initialize(inbound_email)
-    @inbound_email = inbound_email
-  end
+    def initialize(inbound_email)
+      @inbound_email = inbound_email
+    end
 
-  def perform_processing
-    track_status_of_inbound_email do
-      run_callbacks :process do
-        process
+    def perform_processing
+      track_status_of_inbound_email do
+        run_callbacks :process do
+          process
+        end
       end
+    rescue => exception
+      # TODO: Include a reference to the inbound_email in the exception raised so error handling becomes easier
+      rescue_with_handler(exception) || raise
     end
-  rescue => exception
-    # TODO: Include a reference to the inbound_email in the exception raised so error handling becomes easier
-    rescue_with_handler(exception) || raise
-  end
-
-  def process
-    # Overwrite in subclasses
-  end
 
-  def finished_processing?
-    inbound_email.delivered? || inbound_email.bounced?
-  end
+    def process
+      # Overwrite in subclasses
+    end
 
+    def finished_processing?
+      inbound_email.delivered? || inbound_email.bounced?
+    end
 
-  def bounce_with(message)
-    inbound_email.bounced!
-    message.deliver_later
-  end
 
-  private
-    def track_status_of_inbound_email
-      inbound_email.processing!
-      yield
-      inbound_email.delivered! unless inbound_email.bounced?
-    rescue
-      inbound_email.failed!
-      raise
+    def bounce_with(message)
+      inbound_email.bounced!
+      message.deliver_later
     end
+
+    private
+      def track_status_of_inbound_email
+        inbound_email.processing!
+        yield
+        inbound_email.delivered! unless inbound_email.bounced?
+      rescue
+        inbound_email.failed!
+        raise
+      end
+  end
 end