mail_dude 0.1.0

data/lib/mail_dude/dashboard.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module MailDude
+  class Dashboard
+  end
+end

data/lib/mail_dude/delivery_method.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module MailDude
+  class DeliveryMethod
+    attr_reader :settings
+
+    def initialize(settings = {})
+      @settings = settings || {}
+    end
+
+    def deliver!(mail)
+      raise_disabled! unless MailDude.enabled?
+
+      raw_source = mail.to_s
+      validate_size!(raw_source)
+      record = MailDude.store.write(mail)
+      MessageBroadcast.broadcast(record)
+      MailDude.store.prune
+      log_capture(record)
+      record
+    end
+
+    private
+
+    def log_capture(record)
+      return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      Rails.logger.debug { "Captured email #{record.id} subject=#{record.metadata['subject'].to_s.inspect}" }
+    end
+
+    def raise_disabled!
+      env = MailDude.rails_environment
+      message = "MailDude is disabled in #{env}. Configure enabled_environments or set allow_production only " \
+                'after reviewing the risks.'
+      raise DisabledEnvironmentError, message
+    end
+
+    def validate_size!(raw_source)
+      limit = MailDude.configuration.max_message_size
+      return if limit.nil? || raw_source.bytesize <= limit
+
+      raise MessageTooLargeError,
+            "Email is #{raw_source.bytesize} bytes, exceeding MailDude max_message_size of #{limit} bytes."
+    end
+  end
+end

data/lib/mail_dude/engine.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module MailDude
+  class Engine < ::Rails::Engine
+    ASSET_PRECOMPILE = ['mail_dude/application.css', 'mail_dude/icon.png'].freeze
+
+    isolate_namespace MailDude
+
+    initializer 'mail_dude.action_mailer' do
+      ActiveSupport.on_load(:action_mailer) do
+        add_delivery_method :mail_dude, MailDude::DeliveryMethod
+        after_action { MailDude::MailerMetadataHeaders.apply(self) }
+      end
+    end
+
+    initializer 'mail_dude.assets' do |app|
+      app.config.assets.precompile.concat(ASSET_PRECOMPILE) if app.config.respond_to?(:assets)
+    end
+
+    rake_tasks do
+      load 'tasks/mail_dude.rake'
+    end
+  end
+end

data/lib/mail_dude/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module MailDude
+  class Error < StandardError; end
+  class DisabledEnvironmentError < Error; end
+  class InvalidConfigurationError < Error; end
+  class StorageError < Error; end
+  class MessageNotFoundError < Error; end
+  class AttachmentNotFoundError < Error; end
+  class MessageTooLargeError < Error; end
+end

data/lib/mail_dude/html_body_renderer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module MailDude
+  class HtmlBodyRenderer
+    PLACEHOLDER = '<p>This message does not include an HTML body.</p>'
+
+    def initialize(presenter, attachment_url:)
+      @attachment_url = attachment_url
+      @presenter = presenter
+    end
+
+    def render
+      html = presenter.html_body
+      return PLACEHOLDER if html.blank?
+
+      fragment = Nokogiri::HTML::DocumentFragment.parse(html)
+      rewrite_cid_images(fragment)
+      rewrite_links(fragment)
+      fragment.to_html
+    rescue StandardError
+      html.to_s
+    end
+
+    private
+
+    attr_reader :attachment_url, :presenter
+
+    def locator
+      @locator ||= AttachmentLocator.new(presenter.record)
+    end
+
+    def rewrite_cid_images(fragment)
+      fragment.css("[src^='cid:']").each do |node|
+        attachment = locator.find_inline_by_cid(node['src'])
+        node['src'] = attachment_url.call(attachment.id, inline: true) if attachment
+      end
+    end
+
+    def rewrite_links(fragment)
+      fragment.css('a[href]').each do |node|
+        node['target'] = '_blank'
+        rel_values = node['rel'].to_s.split | %w[noopener noreferrer]
+        node['rel'] = rel_values.join(' ')
+      end
+    end
+  end
+end

data/lib/mail_dude/mailer_metadata_headers.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module MailDude
+  module MailerMetadataHeaders
+    module_function
+
+    def apply(mailer)
+      return unless MailDude.configuration.capture_mailer_metadata_headers
+      return unless MailDude.enabled?
+      return unless mail_dude_delivery?(mailer)
+
+      mailer.message[MessageSerializer::INTERNAL_MAILER_HEADER] = mailer.class.name
+      mailer.message[MessageSerializer::INTERNAL_ACTION_HEADER] = mailer.action_name
+    end
+
+    def mail_dude_delivery?(mailer)
+      mailer.message.delivery_method.is_a?(DeliveryMethod) ||
+        mailer.class.delivery_method == :mail_dude ||
+        ActionMailer::Base.delivery_method == :mail_dude
+    end
+  end
+end

data/lib/mail_dude/message_broadcast.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module MailDude
+  class MessageBroadcast
+    def self.broadcast(record)
+      new(record).broadcast
+    end
+
+    def initialize(record)
+      @record = record
+    end
+
+    def broadcast
+      return false unless MailDude.configuration.live_updates
+      return false unless action_cable_server
+
+      action_cable_server.broadcast(MailDude.configuration.live_update_stream_name, payload)
+      true
+    end
+
+    private
+
+    attr_reader :record
+
+    def action_cable_server
+      ActionCable.server if defined?(ActionCable)
+    end
+
+    def payload
+      presenter = MessagePresenter.new(record)
+      {
+        event: 'message_created',
+        id: record.id,
+        **list_metadata(presenter)
+      }
+    end
+
+    def list_metadata(presenter)
+      {
+        subject: presenter.subject_label,
+        sender: presenter.sender_summary,
+        recipients: presenter.recipient_summary,
+        captured_at: presenter.captured_at_label,
+        attachments_count: presenter.attachments.length,
+        attachment_count_label: presenter.attachment_count_label,
+        mailer_label: presenter.mailer_label
+      }
+    end
+  end
+end

data/lib/mail_dude/message_presenter.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module MailDude
+  class MessagePresenter
+    FALLBACK_DECODE_ERROR = 'Unable to decode this message part.'
+
+    attr_reader :record
+
+    delegate :id, to: :record
+
+    def initialize(record)
+      @record = record
+    end
+
+    def subject
+      metadata_value('subject').to_s
+    end
+
+    def subject_label
+      subject.strip.presence || '(no subject)'
+    end
+
+    def captured_at
+      Time.iso8601(metadata_value('captured_at').to_s)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def captured_at_label
+      captured_at ? captured_at.strftime('%Y-%m-%d %H:%M:%S UTC') : '(unknown time)'
+    end
+
+    def from = metadata_array('from')
+    def sender = metadata_array('sender')
+    def to = metadata_array('to')
+    def cc = metadata_array('cc')
+    def bcc = metadata_array('bcc')
+    def reply_to = metadata_array('reply_to')
+    def message_id = metadata_value('message_id')
+    def mailer = metadata_value('mailer')
+    def mailer_action = metadata_value('mailer_action')
+    def content_type = metadata_value('content_type')
+    def size_bytes = metadata_value('size_bytes').to_i
+    def raw_source = record.raw_source.to_s
+    def attachments = metadata_array('attachments')
+
+    def mailer_label
+      return '(unknown mailer)' if mailer.blank? && mailer_action.blank?
+      return mailer if mailer_action.blank?
+      return "##{mailer_action}" if mailer.blank?
+
+      "#{mailer}##{mailer_action}"
+    end
+
+    def size_label
+      bytes = size_bytes
+      return "#{bytes} B" if bytes < 1.kilobyte
+      return "#{format('%.1f', bytes / 1.kilobyte.to_f)} KB" if bytes < 1.megabyte
+
+      "#{format('%.1f', bytes / 1.megabyte.to_f)} MB"
+    end
+
+    def mail
+      @mail ||= raw_source.present? ? Mail.read_from_string(raw_source) : nil
+    rescue StandardError
+      nil
+    end
+
+    def html_body
+      decoded_body_for('text/html')
+    end
+
+    def text_body
+      decoded_body_for('text/plain')
+    end
+
+    def raw_headers
+      return '' if raw_source.blank?
+
+      raw_source.split(/\r?\n\r?\n/, 2).first.to_s
+    end
+
+    def has_attachments?
+      attachments.any?
+    end
+
+    def attachment_count_label
+      count = attachments.length
+      "#{count} #{'attachment'.pluralize(count)}"
+    end
+
+    def recipient_summary
+      to.first.presence || cc.first.presence || bcc.first.presence || '(no recipients)'
+    end
+
+    def sender_summary
+      from.first.presence || sender.first.presence || '(unknown sender)'
+    end
+
+    def list_preview
+      preview = text_body.presence || ActionView::Base.full_sanitizer.sanitize(html_body.to_s)
+      preview.to_s.squish.truncate(140)
+    end
+
+    private
+
+    def decoded_body_for(mime_type)
+      part = body_part(mime_type)
+      return nil unless part
+
+      decode_part(part)
+    end
+
+    def body_part(mime_type)
+      return nil unless mail
+      return mail if !mail.multipart? && mail.mime_type == mime_type
+
+      mail.all_parts.find { |part| part.mime_type == mime_type && !part.attachment? }
+    end
+
+    def decode_part(part)
+      decoded = part.decoded
+      decoded.to_s.encode('UTF-8', invalid: :replace, undef: :replace)
+    rescue StandardError
+      FALLBACK_DECODE_ERROR
+    end
+
+    def metadata_array(key)
+      Array(metadata_value(key)).compact
+    end
+
+    def metadata_value(key)
+      record.metadata[key]
+    end
+  end
+end

data/lib/mail_dude/message_record.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module MailDude
+  class MessageRecord
+    attr_reader :id, :metadata, :raw_source
+
+    def initialize(id:, metadata:, raw_source: nil)
+      @id = id
+      @metadata = metadata.stringify_keys
+      @raw_source = raw_source
+    end
+
+    def full?
+      raw_source.present?
+    end
+  end
+end

data/lib/mail_dude/message_serializer.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module MailDude
+  class MessageSerializer
+    INTERNAL_MAILER_HEADER = 'X-Mail-Dude-Mailer'
+    INTERNAL_ACTION_HEADER = 'X-Mail-Dude-Action'
+
+    attr_reader :captured_at, :id, :mail, :raw_source
+
+    def initialize(mail, id:, captured_at:, raw_source: nil)
+      @mail = mail
+      @id = id
+      @captured_at = captured_at.utc
+      @raw_source = raw_source || mail.to_s
+    end
+
+    def metadata
+      {
+        'id' => id,
+        'captured_at' => captured_at.iso8601(6),
+        'subject' => decoded_subject,
+        'from' => addresses(:from),
+        'sender' => addresses(:sender),
+        'to' => addresses(:to),
+        'cc' => addresses(:cc),
+        'bcc' => addresses(:bcc),
+        'reply_to' => addresses(:reply_to),
+        'date' => date_value,
+        'message_id' => header_value(:message_id),
+        'in_reply_to' => header_value(:in_reply_to),
+        'references' => references,
+        'content_type' => content_type,
+        'mime_version' => header_value(:mime_version),
+        'mailer' => internal_header(INTERNAL_MAILER_HEADER),
+        'mailer_action' => internal_header(INTERNAL_ACTION_HEADER),
+        'has_html' => part_present?('text/html'),
+        'has_text' => part_present?('text/plain'),
+        'has_attachments' => attachments.any?,
+        'attachments_count' => attachments.length,
+        'attachments' => attachments,
+        'size_bytes' => raw_source.bytesize
+      }
+    end
+
+    private
+
+    def addresses(field_name)
+      field = mail[field_name]
+      return [] unless field
+
+      field.addrs.map { |address| format_address(address) }.compact
+    rescue StandardError
+      fallback = field.to_s.strip
+      fallback.present? ? [fallback] : []
+    end
+
+    def attachments
+      @attachments ||= AttachmentLocator.new(mail).attachments.map(&:metadata)
+    end
+
+    def content_type
+      mail.mime_type.presence || mail.content_type.to_s.split(';').first.presence
+    end
+
+    def date_value
+      date = mail.date
+      return nil unless date
+
+      date.to_time.utc.iso8601
+    rescue StandardError
+      nil
+    end
+
+    def decoded_subject
+      mail.subject
+    rescue StandardError
+      mail[:subject].to_s
+    end
+
+    def format_address(address)
+      display = address.display_name.to_s
+      email = address.address.to_s
+      return email if display.blank?
+      return display if email.blank?
+
+      "#{display} <#{email}>"
+    end
+
+    def header_value(field_name)
+      value = mail.public_send(field_name)
+      value.respond_to?(:value) ? value.value : value
+    rescue StandardError
+      nil
+    end
+
+    def internal_header(name)
+      mail[name]&.decoded
+    rescue StandardError
+      nil
+    end
+
+    def part_present?(mime_type)
+      if mail.multipart?
+        mail.all_parts.any? { |part| part.mime_type == mime_type && !part.attachment? }
+      else
+        mail.mime_type == mime_type
+      end
+    end
+
+    def references
+      raw = mail.references
+      Array(raw).flat_map { |value| value.to_s.split(/\s+/) }.compact_blank
+    rescue StandardError
+      []
+    end
+  end
+end

data/lib/mail_dude/pagination.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module MailDude
+  class Page
+    attr_reader :page, :per_page, :records, :total_count
+
+    def initialize(records:, page:, per_page:, total_count:)
+      @records = records
+      @page = normalize_positive(page, 1)
+      @per_page = normalize_positive(per_page, MailDude.configuration.default_per_page)
+      @total_count = total_count.to_i
+    end
+
+    def total_pages
+      [(total_count.to_f / per_page).ceil, 1].max
+    end
+
+    def next_page
+      page < total_pages ? page + 1 : nil
+    end
+
+    def previous_page
+      page > 1 ? page - 1 : nil
+    end
+
+    private
+
+    def normalize_positive(value, fallback)
+      integer = Integer(value)
+      integer.positive? ? integer : fallback
+    rescue ArgumentError, TypeError
+      fallback
+    end
+  end
+end

data/lib/mail_dude/stores/base.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module MailDude
+  module Stores
+    class Base
+      ID_PATTERN = /\A\d{8}T\d{12}Z-[a-f0-9]{16}\z/
+
+      def write(_mail)
+        raise NotImplementedError
+      end
+
+      def list(page: 1, per_page: MailDude.configuration.default_per_page, query: nil)
+        raise NotImplementedError
+      end
+
+      def find(_id)
+        raise NotImplementedError
+      end
+
+      def delete(_id)
+        raise NotImplementedError
+      end
+
+      def clear
+        raise NotImplementedError
+      end
+
+      def prune(max_messages: MailDude.configuration.max_messages,
+                retention_period: MailDude.configuration.retention_period)
+        raise NotImplementedError
+      end
+
+      private
+
+      def build_record(mail, id: generate_id, captured_at: Time.now.utc)
+        raw_source = mail.to_s
+        metadata = MessageSerializer.new(mail, id: id, captured_at: captured_at, raw_source: raw_source).metadata
+        MessageRecord.new(id: id, metadata: metadata, raw_source: raw_source)
+      end
+
+      def generate_id
+        time = Time.now.utc
+        "#{time.strftime('%Y%m%dT%H%M%S')}#{format('%06d', time.usec)}Z-#{SecureRandom.hex(8)}"
+      end
+
+      def validate_id!(id)
+        return id.to_s if id.to_s.match?(ID_PATTERN)
+
+        raise MessageNotFoundError, 'Message not found'
+      end
+
+      def page_for(records, page:, per_page:, query:)
+        filtered = search(records, query)
+        sorted = sort_records(filtered)
+        normalized_page = normalize_positive(page, 1)
+        normalized_per_page = normalize_positive(per_page, MailDude.configuration.default_per_page)
+        offset = (normalized_page - 1) * normalized_per_page
+        Page.new(records: sorted.slice(offset, normalized_per_page) || [],
+                 page: normalized_page,
+                 per_page: normalized_per_page,
+                 total_count: sorted.length)
+      end
+
+      def prune_ids(records, max_messages:, retention_period:)
+        sorted = sort_records(records)
+        expired_ids = retention_period ? sorted.select { |record| expired?(record, retention_period) }.map(&:id) : []
+        extra_ids = max_messages ? sorted.drop(max_messages.to_i).map(&:id) : []
+        (expired_ids + extra_ids).uniq
+      end
+
+      def sort_records(records)
+        records.sort_by { |record| record.metadata['captured_at'].to_s }.reverse
+      end
+
+      def search(records, query)
+        return records if query.to_s.strip.blank?
+
+        needle = query.to_s.downcase
+        records.select { |record| searchable_text(record).downcase.include?(needle) }
+      end
+
+      def searchable_text(record)
+        metadata = record.metadata
+        values = %w[subject message_id mailer mailer_action].map { |key| metadata[key] }
+        values += %w[from to cc bcc].flat_map { |key| Array(metadata[key]) }
+        values.compact.join(' ')
+      end
+
+      def expired?(record, retention_period)
+        captured_at = Time.iso8601(record.metadata['captured_at'].to_s)
+        captured_at < Time.now.utc - retention_period
+      rescue ArgumentError, TypeError
+        false
+      end
+
+      def normalize_positive(value, fallback)
+        integer = Integer(value)
+        integer.positive? ? integer : fallback
+      rescue ArgumentError, TypeError
+        fallback
+      end
+    end
+  end
+end