actionmailbox 0.1.0 → 6.0.0.beta1

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

@@ -1,50 +1,54 @@
-# 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 ActionMailbox::Ingresses::Sendgrid::InboundEmailsController < ActionMailbox::BaseController
-  before_action :authenticate_by_password
+# frozen_string_literal: true
 
-  def create
-    ActionMailbox::InboundEmail.create_and_extract_message_id! params.require(:email)
+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

@@ -1,27 +1,34 @@
-class Rails::Conductor::ActionMailbox::InboundEmailsController < Rails::Conductor::BaseController
-  def index
-    @inbound_emails = ActionMailbox::InboundEmail.order(created_at: :desc)
-  end
-
-  def new
-  end
+# frozen_string_literal: true
 
-  def show
-    @inbound_email = ActionMailbox::InboundEmail.find(params[:id])
-  end
+module Rails
+  class Conductor::ActionMailbox::InboundEmailsController < Rails::Conductor::BaseController
+    def index
+      @inbound_emails = ActionMailbox::InboundEmail.order(created_at: :desc)
+    end
 
-  def create
-    inbound_email = create_inbound_email(new_mail)
-    redirect_to main_app.rails_conductor_inbound_email_url(inbound_email)
-  end
+    def new
+    end
 
-  private
-    def new_mail
-      Mail.new params.require(:mail).permit(:from, :to, :cc, :bcc, :in_reply_to, :subject, :body).to_h
+    def show
+      @inbound_email = ActionMailbox::InboundEmail.find(params[:id])
     end
 
-    def create_inbound_email(mail)
-      ActionMailbox::InboundEmail.create! raw_email: \
-        { io: StringIO.new(mail.to_s), filename: 'inbound.eml', content_type: 'message/rfc822', identify: false }
+    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

@@ -1,15 +1,19 @@
-# 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
+# frozen_string_literal: true
 
-    redirect_to main_app.rails_conductor_inbound_email_url(inbound_email)
-  end
+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
 
-  private
-    def reroute(inbound_email)
-      inbound_email.pending!
-      inbound_email.route_later
+      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

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

@@ -1,18 +1,22 @@
-# 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] }
+# frozen_string_literal: true
 
-  discard_on ActiveRecord::RecordNotFound
+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] }
 
-  def self.schedule(inbound_email)
-    set(wait: ActionMailbox.incinerate_after).perform_later(inbound_email)
-  end
+    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
+    def perform(inbound_email)
+      inbound_email.incinerate
+    end
   end
 end

data/app/jobs/action_mailbox/routing_job.rb

@@ -1,9 +1,13 @@
-# 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] }
+# frozen_string_literal: true
 
-  def perform(inbound_email)
-    inbound_email.route
+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

@@ -1,43 +1,49 @@
+# frozen_string_literal: true
+
 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
+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"
 
-  def source
-    @source ||= raw_email.download
-  end
+    include Incineratable, MessageId, Routable
+
+    has_one_attached :raw_email
+    enum status: %i[ pending processing delivered failed bounced ]
 
-  def processed?
-    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

@@ -1,6 +1,8 @@
-# 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`.
+# 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
 

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

@@ -1,22 +1,26 @@
-# 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
+# frozen_string_literal: true
 
-  private
-    def due?
-      @inbound_email.updated_at < ActionMailbox.incinerate_after.ago.end_of_day
+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 processed?
-      @inbound_email.processed?
+    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

@@ -1,36 +1,38 @@
-# 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 
+# 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 `Mail::MessageIdField`.
+# using the approach from <tt>Mail::MessageIdField</tt>.
 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`.
+  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)
-      create! message_id: extract_message_id(source), **options do |inbound_email|
+      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 => e
-        # FIXME: Add logging with "Couldn't extract Message ID, so will generating a new random ID instead"
+        Mail.from_source(source).message_id rescue nil
       end
-  end
 
-  private
-    def generate_missing_message_id
-      self.message_id ||= Mail::MessageIdField.new.message_id
-    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