actionmailbox 6.0.1

data/app/controllers/rails/conductor/action_mailbox/inbound_emails_controller.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Rails
+  class Conductor::ActionMailbox::InboundEmailsController < Rails::Conductor::BaseController
+    def index
+      @inbound_emails = ActionMailbox::InboundEmail.order(created_at: :desc)
+    end
+
+    def new
+    end
+
+    def show
+      @inbound_email = ActionMailbox::InboundEmail.find(params[:id])
+    end
+
+    def create
+      inbound_email = create_inbound_email(new_mail)
+      redirect_to main_app.rails_conductor_inbound_email_url(inbound_email)
+    end
+
+    private
+      def new_mail
+        Mail.new(params.require(:mail).permit(:from, :to, :cc, :bcc, :in_reply_to, :subject, :body).to_h).tap do |mail|
+          mail[:bcc]&.include_in_headers = true
+          params[:mail][:attachments].to_a.each do |attachment|
+            mail.add_file(filename: attachment.original_filename, content: attachment.read)
+          end
+        end
+      end
+
+      def create_inbound_email(mail)
+        ActionMailbox::InboundEmail.create_and_extract_message_id!(mail.to_s)
+      end
+  end
+end

data/app/controllers/rails/conductor/action_mailbox/reroutes_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Rails
+  # Rerouting will run routing and processing on an email that has already been, or attempted to be, processed.
+  class Conductor::ActionMailbox::ReroutesController < Rails::Conductor::BaseController
+    def create
+      inbound_email = ActionMailbox::InboundEmail.find(params[:inbound_email_id])
+      reroute inbound_email
+
+      redirect_to main_app.rails_conductor_inbound_email_url(inbound_email)
+    end
+
+    private
+      def reroute(inbound_email)
+        inbound_email.pending!
+        inbound_email.route_later
+      end
+  end
+end

data/app/controllers/rails/conductor/base_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Rails
+  # TODO: Move this to Rails::Conductor gem
+  class Conductor::BaseController < ActionController::Base
+    layout "rails/conductor"
+    before_action :ensure_development_env
+
+    private
+      def ensure_development_env
+        head :forbidden unless Rails.env.development?
+      end
+  end
+end

data/app/jobs/action_mailbox/incineration_job.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # You can configure when this +IncinerationJob+ will be run as a time-after-processing using the
+  # +config.action_mailbox.incinerate_after+ or +ActionMailbox.incinerate_after+ setting.
+  #
+  # Since this incineration is set for the future, it'll automatically ignore any <tt>InboundEmail</tt>s
+  # that have already been deleted and discard itself if so.
+  #
+  # You can disable incinerating processed emails by setting +config.action_mailbox.incinerate+ or
+  # +ActionMailbox.incinerate+ to +false+.
+  class IncinerationJob < ActiveJob::Base
+    queue_as { ActionMailbox.queues[:incineration] }
+
+    discard_on ActiveRecord::RecordNotFound
+
+    def self.schedule(inbound_email)
+      set(wait: ActionMailbox.incinerate_after).perform_later(inbound_email)
+    end
+
+    def perform(inbound_email)
+      inbound_email.incinerate
+    end
+  end
+end

data/app/jobs/action_mailbox/routing_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # Routing a new InboundEmail is an asynchronous operation, which allows the ingress controllers to quickly
+  # accept new incoming emails without being burdened to hang while they're actually being processed.
+  class RoutingJob < ActiveJob::Base
+    queue_as { ActionMailbox.queues[:routing] }
+
+    def perform(inbound_email)
+      inbound_email.route
+    end
+  end
+end

data/app/models/action_mailbox/inbound_email.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "mail"
+
+module ActionMailbox
+  # The +InboundEmail+ is an Active Record that keeps a reference to the raw email stored in Active Storage
+  # and tracks the status of processing. By default, incoming emails will go through the following lifecycle:
+  #
+  # * Pending: Just received by one of the ingress controllers and scheduled for routing.
+  # * Processing: During active processing, while a specific mailbox is running its #process method.
+  # * Delivered: Successfully processed by the specific mailbox.
+  # * Failed: An exception was raised during the specific mailbox's execution of the +#process+ method.
+  # * Bounced: Rejected processing by the specific mailbox and bounced to sender.
+  #
+  # Once the +InboundEmail+ has reached the status of being either +delivered+, +failed+, or +bounced+,
+  # it'll count as having been +#processed?+. Once processed, the +InboundEmail+ will be scheduled for
+  # automatic incineration at a later point.
+  #
+  # When working with an +InboundEmail+, you'll usually interact with the parsed version of the source,
+  # which is available as a +Mail+ object from +#mail+. But you can also access the raw source directly
+  # using the +#source+ method.
+  #
+  # Examples:
+  #
+  #   inbound_email.mail.from # => 'david@loudthinking.com'
+  #   inbound_email.source # Returns the full rfc822 source of the email as text
+  class InboundEmail < ActiveRecord::Base
+    self.table_name = "action_mailbox_inbound_emails"
+
+    include Incineratable, MessageId, Routable
+
+    has_one_attached :raw_email
+    enum status: %i[ pending processing delivered failed bounced ]
+
+    def mail
+      @mail ||= Mail.from_source(source)
+    end
+
+    def source
+      @source ||= raw_email.download
+    end
+
+    def processed?
+      delivered? || failed? || bounced?
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :action_mailbox_inbound_email, ActionMailbox::InboundEmail

data/app/models/action_mailbox/inbound_email/incineratable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Ensure that the +InboundEmail+ is automatically scheduled for later incineration if the status has been
+# changed to +processed+. The later incineration will be invoked at the time specified by the
+# +ActionMailbox.incinerate_after+ time using the +IncinerationJob+.
+module ActionMailbox::InboundEmail::Incineratable
+  extend ActiveSupport::Concern
+
+  included do
+    after_update_commit :incinerate_later, if: -> { ActionMailbox.incinerate && status_previously_changed? && processed? }
+  end
+
+  def incinerate_later
+    ActionMailbox::IncinerationJob.schedule self
+  end
+
+  def incinerate
+    Incineration.new(self).run
+  end
+end

data/app/models/action_mailbox/inbound_email/incineratable/incineration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # Command class for carrying out the actual incineration of the +InboundMail+ that's been scheduled
+  # for removal. Before the incineration – which really is just a call to +#destroy!+ – is run, we verify
+  # that it's both eligible (by virtue of having already been processed) and time to do so (that is,
+  # the +InboundEmail+ was processed after the +incinerate_after+ time).
+  class InboundEmail::Incineratable::Incineration
+    def initialize(inbound_email)
+      @inbound_email = inbound_email
+    end
+
+    def run
+      @inbound_email.destroy! if due? && processed?
+    end
+
+    private
+      def due?
+        @inbound_email.updated_at < ActionMailbox.incinerate_after.ago.end_of_day
+      end
+
+      def processed?
+        @inbound_email.processed?
+      end
+  end
+end

data/app/models/action_mailbox/inbound_email/message_id.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# The +Message-ID+ as specified by rfc822 is supposed to be a unique identifier for that individual email.
+# That makes it an ideal tracking token for debugging and forensics, just like +X-Request-Id+ does for
+# web request.
+#
+# If an inbound email does not, against the rfc822 mandate, specify a Message-ID, one will be generated
+# using the approach from <tt>Mail::MessageIdField</tt>.
+module ActionMailbox::InboundEmail::MessageId
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Create a new +InboundEmail+ from the raw +source+ of the email, which be uploaded as a Active Storage
+    # attachment called +raw_email+. Before the upload, extract the Message-ID from the +source+ and set
+    # it as an attribute on the new +InboundEmail+.
+    def create_and_extract_message_id!(source, **options)
+      message_checksum = Digest::SHA1.hexdigest(source)
+      message_id = extract_message_id(source) || generate_missing_message_id(message_checksum)
+
+      create! options.merge(message_id: message_id, message_checksum: message_checksum) do |inbound_email|
+        inbound_email.raw_email.attach io: StringIO.new(source), filename: "message.eml", content_type: "message/rfc822"
+      end
+    rescue ActiveRecord::RecordNotUnique
+      nil
+    end
+
+    private
+      def extract_message_id(source)
+        Mail.from_source(source).message_id rescue nil
+      end
+
+      def generate_missing_message_id(message_checksum)
+        Mail::MessageIdField.new("<#{message_checksum}@#{::Socket.gethostname}.mail>").message_id.tap do |message_id|
+          logger.warn "Message-ID couldn't be parsed or is missing. Generated a new Message-ID: #{message_id}"
+        end
+      end
+  end
+end

data/app/models/action_mailbox/inbound_email/routable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# A newly received +InboundEmail+ will not be routed synchronously as part of ingress controller's receival.
+# Instead, the routing will be done asynchronously, using a +RoutingJob+, to ensure maximum parallel capacity.
+#
+# By default, all newly created +InboundEmail+ records that have the status of +pending+, which is the default,
+# will be scheduled for automatic, deferred routing.
+module ActionMailbox::InboundEmail::Routable
+  extend ActiveSupport::Concern
+
+  included do
+    after_create_commit :route_later, if: :pending?
+  end
+
+  # Enqueue a +RoutingJob+ for this +InboundEmail+.
+  def route_later
+    ActionMailbox::RoutingJob.perform_later self
+  end
+
+  # Route this +InboundEmail+ using the routing rules declared on the +ApplicationMailbox+.
+  def route
+    ApplicationMailbox.route self
+  end
+end

data/app/views/layouts/rails/conductor.html.erb

@@ -0,0 +1,8 @@
+<html>
+<head>
+  <title>Rails Conductor: <%= yield :title %></title>
+</head>
+<body>
+<%= yield %>
+</body>
+</html>

data/app/views/rails/conductor/action_mailbox/inbound_emails/index.html.erb

@@ -0,0 +1,15 @@
+<% provide :title, "Deliver new inbound email" %>
+
+<h1>All inbound emails</h1>
+
+<table>
+  <tr><th>Message ID</th><th>Status</th></tr>
+  <% @inbound_emails.each do |inbound_email| %>
+    <tr>
+      <td><%= link_to inbound_email.message_id, main_app.rails_conductor_inbound_email_path(inbound_email) %></td>
+      <td><%= inbound_email.status %></td>
+    </tr>
+  <% end %>
+</table>
+
+<%= link_to "Deliver new inbound email", main_app.new_rails_conductor_inbound_email_path %>

data/app/views/rails/conductor/action_mailbox/inbound_emails/new.html.erb

@@ -0,0 +1,47 @@
+<% provide :title, "Deliver new inbound email" %>
+
+<h1>Deliver new inbound email</h1>
+
+<%= form_with(url: main_app.rails_conductor_inbound_emails_path, scope: :mail, local: true) do |form| %>
+  <div>
+    <%= form.label :from, "From" %><br>
+    <%= form.text_field :from %>
+  </div>
+
+  <div>
+    <%= form.label :to, "To" %><br>
+    <%= form.text_field :to %>
+  </div>
+
+  <div>
+    <%= form.label :cc, "CC" %><br>
+    <%= form.text_field :cc %>
+  </div>
+
+  <div>
+    <%= form.label :bcc, "BCC" %><br>
+    <%= form.text_field :bcc %>
+  </div>
+
+  <div>
+    <%= form.label :in_reply_to, "In-Reply-To" %><br>
+    <%= form.text_field :in_reply_to %>
+  </div>
+
+  <div>
+    <%= form.label :subject, "Subject" %><br>
+    <%= form.text_field :subject %>
+  </div>
+
+  <div>
+    <%= form.label :body, "Body" %><br>
+    <%= form.text_area :body, size: "40x20" %>
+  </div>
+
+  <div>
+    <%= form.label :attachments, "Attachments" %><br>
+    <%= form.file_field :attachments, multiple: true %>
+  </div>
+
+  <%= form.submit "Deliver inbound email" %>
+<% end %>

data/app/views/rails/conductor/action_mailbox/inbound_emails/show.html.erb

@@ -0,0 +1,15 @@
+<% provide :title, @inbound_email.message_id %>
+
+<h1><%= @inbound_email.message_id %>: <%= @inbound_email.status %></h1>
+
+<ul>
+  <li><%= button_to "Route again", main_app.rails_conductor_inbound_email_reroute_path(@inbound_email), method: :post %></li>
+  <li>Incinerate</li>
+</ul>
+
+<details>
+  <summary>Full email source</summary>
+  <pre><%= @inbound_email.source %></pre>
+</details>
+
+<%= link_to "Back to all inbound emails", main_app.rails_conductor_inbound_emails_path %>

data/config/routes.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  scope "/rails/action_mailbox", module: "action_mailbox/ingresses" do
+    post "/mandrill/inbound_emails" => "mandrill/inbound_emails#create", as: :rails_mandrill_inbound_emails
+    post "/postmark/inbound_emails" => "postmark/inbound_emails#create", as: :rails_postmark_inbound_emails
+    post "/relay/inbound_emails"    => "relay/inbound_emails#create",    as: :rails_relay_inbound_emails
+    post "/sendgrid/inbound_emails" => "sendgrid/inbound_emails#create", as: :rails_sendgrid_inbound_emails
+
+    # Mailgun requires that a webhook's URL end in 'mime' for it to receive the raw contents of emails.
+    post "/mailgun/inbound_emails/mime" => "mailgun/inbound_emails#create", as: :rails_mailgun_inbound_emails
+  end
+
+  # TODO: Should these be mounted within the engine only?
+  scope "rails/conductor/action_mailbox/", module: "rails/conductor/action_mailbox" do
+    resources :inbound_emails, as: :rails_conductor_inbound_emails
+    post ":inbound_email_id/reroute" => "reroutes#create", as: :rails_conductor_inbound_email_reroute
+  end
+end

data/db/migrate/20180917164000_create_action_mailbox_tables.rb

@@ -0,0 +1,13 @@
+class CreateActionMailboxTables < ActiveRecord::Migration[6.0]
+  def change
+    create_table :action_mailbox_inbound_emails do |t|
+      t.integer :status, default: 0, null: false
+      t.string  :message_id, null: false
+      t.string  :message_checksum, null: false
+
+      t.timestamps
+
+      t.index [ :message_id, :message_checksum ], name: "index_action_mailbox_inbound_emails_uniqueness", unique: true
+    end
+  end
+end

data/lib/action_mailbox.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "action_mailbox/mail_ext"
+
+module ActionMailbox
+  extend ActiveSupport::Autoload
+
+  autoload :Base
+  autoload :Router
+  autoload :TestCase
+
+  mattr_accessor :ingress
+  mattr_accessor :logger
+  mattr_accessor :incinerate, default: true
+  mattr_accessor :incinerate_after, default: 30.days
+  mattr_accessor :queues, default: {}
+end

data/lib/action_mailbox/base.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "active_support/rescuable"
+
+require "action_mailbox/callbacks"
+require "action_mailbox/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
+
+    delegate :logger, to: ActionMailbox
+
+    def self.receive(inbound_email)
+      new(inbound_email).perform_processing
+    end
+
+    def initialize(inbound_email)
+      @inbound_email = inbound_email
+    end
+
+    def perform_processing #:nodoc:
+      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
+
+    def process
+      # Overwrite in subclasses
+    end
+
+    def finished_processing? #:nodoc:
+      inbound_email.delivered? || inbound_email.bounced?
+    end
+
+
+    # Enqueues the given +message+ for delivery and changes the inbound email's status to +:bounced+.
+    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
+
+ActiveSupport.run_load_hooks :action_mailbox, ActionMailbox::Base