Routing documentation

4 files changed, 60 insertions, 0 deletions

diff --git a/lib/action_mailbox/base.rb b/lib/action_mailbox/base.rb
index 55914401e1..0ae83bf691 100644
--- a/lib/action_mailbox/base.rb
+++ b/lib/action_mailbox/base.rb
@@ -3,6 +3,60 @@ 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.
+#     route /^replies@/i => :replies
+#
+#     # Any of the recipients of the mail (whether to, cc, bcc) needs to be an exact match for the string.
+#     route "help@example.com" => :help
+#
+#     # Any callable (proc, lambda, etc) object is passed the inbound_email record and is a match if true.
+#     route ->(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.
+#     route CustomAddress.new => :custom
+#
+#     # Any inbound_email that has not been already matched will be sent to the BackstopMailbox.
+#     route :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
diff --git a/lib/action_mailbox/router.rb b/lib/action_mailbox/router.rb
index 8ba3ad0bae..ef55718974 100644
--- a/lib/action_mailbox/router.rb
+++ b/lib/action_mailbox/router.rb
@@ -1,3 +1,5 @@
+# Encapsulates the routes that live on the ApplicationMailbox and performs the actual routing when
+# an inbound_email is received.
 class ActionMailbox::Router
   class RoutingError < StandardError; end
 
diff --git a/lib/action_mailbox/router/route.rb b/lib/action_mailbox/router/route.rb
index 5254043a67..6472b9a31d 100644
--- a/lib/action_mailbox/router/route.rb
+++ b/lib/action_mailbox/router/route.rb
@@ -1,3 +1,6 @@
+# Encapsulates a route, which can then be matched against an inbound_email and provide a lookup of the matching
+# mailbox class. See examples for the different route addresses and how to use them in the `ActionMailbox::Base`
+# documentation.
 class ActionMailbox::Router::Route
   attr_reader :address, :mailbox_name
 
diff --git a/lib/action_mailbox/routing.rb b/lib/action_mailbox/routing.rb
index d258b632f9..db462e6019 100644
--- a/lib/action_mailbox/routing.rb
+++ b/lib/action_mailbox/routing.rb
@@ -1,4 +1,5 @@
 module ActionMailbox
+  # See `ActionMailbox::Base` for how to specify routing.
   module Routing
     extend ActiveSupport::Concern