mirror of
https://github.com/rails/rails.git
synced 2022-11-09 12:12:34 -05:00
Routing documentation
This commit is contained in:
parent
0ef2fdb119
commit
316ba4768b
4 changed files with 60 additions and 0 deletions
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -1,4 +1,5 @@
|
|||
module ActionMailbox
|
||||
# See `ActionMailbox::Base` for how to specify routing.
|
||||
module Routing
|
||||
extend ActiveSupport::Concern
|
||||
|
||||
|
|
Loading…
Reference in a new issue