actionmailbox 6.0.0.beta1

data/app/controllers/action_mailbox/ingresses/sendgrid/inbound_emails_controller.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActionMailbox
+  # Ingests inbound emails from SendGrid. Requires an +email+ parameter containing a full RFC 822 message.
+  #
+  # Authenticates requests using HTTP basic access authentication. The username is always +actionmailbox+, and the
+  # password is read from the application's encrypted credentials or an environment variable. See the Usage section below.
+  #
+  # Note that basic authentication is insecure over unencrypted HTTP. An attacker that intercepts cleartext requests to
+  # the SendGrid ingress can learn its password. You should only use the SendGrid ingress over HTTPS.
+  #
+  # Returns:
+  #
+  # - <tt>204 No Content</tt> if an inbound email is successfully recorded and enqueued for routing to the appropriate mailbox
+  # - <tt>401 Unauthorized</tt> if the request's signature could not be validated
+  # - <tt>404 Not Found</tt> if Action Mailbox is not configured to accept inbound emails from SendGrid
+  # - <tt>422 Unprocessable Entity</tt> if the request is missing the required +email+ parameter
+  # - <tt>500 Server Error</tt> if the ingress password is not configured, or if one of the Active Record database,
+  #   the Active Storage service, or the Active Job backend is misconfigured or unavailable
+  #
+  # == Usage
+  #
+  # 1. Tell Action Mailbox to accept emails from SendGrid:
+  #
+  #        # config/environments/production.rb
+  #        config.action_mailbox.ingress = :sendgrid
+  #
+  # 2. Generate a strong password that Action Mailbox can use to authenticate requests to the SendGrid ingress.
+  #
+  #    Use <tt>rails credentials:edit</tt> to add the password to your application's encrypted credentials under
+  #    +action_mailbox.ingress_password+, where Action Mailbox will automatically find it:
+  #
+  #        action_mailbox:
+  #          ingress_password: ...
+  #
+  #    Alternatively, provide the password in the +RAILS_INBOUND_EMAIL_PASSWORD+ environment variable.
+  #
+  # 3. {Configure SendGrid Inbound Parse}[https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/]
+  #    to forward inbound emails to +/rails/action_mailbox/sendgrid/inbound_emails+ with the username +actionmailbox+ and
+  #    the password you previously generated. If your application lived at <tt>https://example.com</tt>, you would
+  #    configure SendGrid with the following fully-qualified URL:
+  #
+  #        https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails
+  #
+  #    *NOTE:* When configuring your SendGrid Inbound Parse webhook, be sure to check the box labeled *"Post the raw,
+  #    full MIME message."* Action Mailbox needs the raw MIME message to work.
+  class Ingresses::Sendgrid::InboundEmailsController < ActionMailbox::BaseController
+    before_action :authenticate_by_password
+
+    def create
+      ActionMailbox::InboundEmail.create_and_extract_message_id! params.require(:email)
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# 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|
+          params[:mail][:attachments].to_a.each do |attachment|
+            mail.attachments[attachment.original_filename] = { filename: attachment.path, content_type: attachment.content_type }
+          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,22 @@
+# 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.
+  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: -> { 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,7 @@
+<html>
+<head>
+  <title>Rails Conductor: <%= yield :title %></title>
+</head>
+<body>
+<%= yield %>
+</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,20 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  scope "/rails/action_mailbox", module: "action_mailbox/ingresses" do
+    post "/amazon/inbound_emails"   => "amazon/inbound_emails#create",   as: :rails_amazon_inbound_emails
+    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,17 @@
+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
+
+      if supports_datetime_with_precision?
+        t.timestamps precision: 6
+      else
+        t.timestamps
+      end
+
+      t.index [ :message_id, :message_checksum ], name: "index_action_mailbox_inbound_emails_uniqueness", unique: true
+    end
+  end
+end