From 4198323b9d234b97546ea2c7bc075ada3235043b Mon Sep 17 00:00:00 2001 From: George Claghorn Date: Wed, 26 Dec 2018 16:27:28 -0500 Subject: Nest ActionMailbox::Base in the API docs (missed in 6c168aa) --- actionmailbox/lib/action_mailbox/base.rb | 188 ++++++++++++++++--------------- 1 file 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 -- cgit v1.2.3