actionmailbox 0.1.0

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

@@ -0,0 +1,15 @@
+# Rerouting will run routing and processing on an email that has already been, or attempted to be, processed.
+class Rails::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

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

@@ -0,0 +1,10 @@
+# TODO: Move this to Rails::Conductor gem
+class Rails::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

data/app/jobs/action_mailbox/incineration_job.rb

@@ -0,0 +1,18 @@
+# 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 `InboundEmail`s 
+# that have already been deleted and discard itself if so.
+class ActionMailbox::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

data/app/jobs/action_mailbox/routing_job.rb

@@ -0,0 +1,9 @@
+# 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 ActionMailbox::RoutingJob < ActiveJob::Base
+  queue_as { ActionMailbox.queues[:routing] }
+
+  def perform(inbound_email)
+    inbound_email.route
+  end
+end

data/app/models/action_mailbox/inbound_email.rb

@@ -0,0 +1,43 @@
+require "mail"
+
+# 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 ActionMailbox::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

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

@@ -0,0 +1,18 @@
+# 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,22 @@
+# 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 ActionMailbox::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

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

@@ -0,0 +1,36 @@
+# 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 `Mail::MessageIdField`.
+module ActionMailbox::InboundEmail::MessageId
+  extend ActiveSupport::Concern
+
+  included do
+    before_save :generate_missing_message_id
+  end
+
+  module ClassMethods
+    # 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)
+      create! message_id: extract_message_id(source), **options do |inbound_email|
+        inbound_email.raw_email.attach io: StringIO.new(source), filename: "message.eml", content_type: "message/rfc822"
+      end
+    end
+
+    private
+      def extract_message_id(source)
+        Mail.from_source(source).message_id
+      rescue => e
+        # FIXME: Add logging with "Couldn't extract Message ID, so will generating a new random ID instead"
+      end
+  end
+
+  private
+    def generate_missing_message_id
+      self.message_id ||= Mail::MessageIdField.new.message_id
+    end
+end

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

@@ -0,0 +1,22 @@
+# 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,42 @@
+<% 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>
+
+  <%= 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/bin/test

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+$: << File.expand_path("../test", __dir__)
+
+require "bundler/setup"
+require "rails/plugin/test"

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 "/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 "/postfix/inbound_emails"  => "postfix/inbound_emails#create",  as: :rails_postfix_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,11 @@
+class CreateActionMailboxTables < ActiveRecord::Migration[5.2]
+  def change
+    create_table :action_mailbox_inbound_emails do |t|
+      t.integer :status, default: 0, null: false
+      t.string  :message_id
+
+      t.datetime :created_at, precision: 6
+      t.datetime :updated_at, precision: 6
+    end
+  end
+end

data/lib/action_mailbox.rb

@@ -0,0 +1,15 @@
+require "action_mailbox/engine"
+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_after, default: 30.days
+  mattr_accessor :queues, default: {}
+end

data/lib/action_mailbox/base.rb

@@ -0,0 +1,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.
+#     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
+
+  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
+    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?
+    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
+    end
+end