mailscope 0.1.0

data/lib/mailscope/message.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'mail'
+require 'time'
+
+module Mailscope
+  # A captured message. Reads from the metadata index for anything the list
+  # view needs, and lazily parses the raw `.eml` for bodies, headers and
+  # attachments, so rendering the sidebar never touches the full message.
+  class Message
+    METADATA_VERSION = 1
+    PREVIEW_LENGTH = 180
+
+    # rubocop:disable Lint/StructNewOverride -- `size` mirrors the metadata key
+    # and these structs are plain value objects, never enumerated.
+    Attachment = Struct.new(:id, :filename, :content_type, :size, :cid, :inline, keyword_init: true) do
+      def inline? = !!inline
+
+      def image? = content_type.to_s.start_with?('image/')
+
+      def to_h = { id:, filename:, content_type:, size:, cid:, inline: }
+    end
+
+    # rubocop:enable Lint/StructNewOverride
+
+    Address = Struct.new(:name, :address, keyword_init: true) do
+      def display = name.to_s.empty? ? address.to_s : "#{name} <#{address}>"
+
+      def short = name.to_s.empty? ? address.to_s : name.to_s
+
+      def to_h = { name:, address: }
+    end
+
+    attr_reader :id, :metadata, :store
+
+    def initialize(metadata, store:)
+      @metadata = metadata
+      @id       = metadata['id']
+      @store    = store
+    end
+
+    # --- indexed data (cheap: comes straight from metadata.json) ------------
+
+    def subject
+      value = metadata['subject'].to_s
+      value.empty? ? Mailscope.translate('message.no_subject', '(no subject)') : value
+    end
+
+    def sent_at
+      @sent_at ||= Time.parse(metadata['sent_at'])
+    rescue ArgumentError, TypeError
+      Time.at(0)
+    end
+
+    def from     = addresses('from')
+    def to       = addresses('to')
+    def cc       = addresses('cc')
+    def bcc      = addresses('bcc')
+    def reply_to = addresses('reply_to')
+
+    def recipients = to + cc + bcc
+
+    # Every mailbox this message landed in, used to build the mailbox rail.
+    def mailbox_keys = recipients.map { |a| a.address.to_s.downcase }.reject(&:empty?).uniq
+
+    def to_param    = id
+
+    def message_id  = metadata['message_id']
+    def mailer      = metadata['mailer']
+    def size        = metadata['size'].to_i
+    def preview     = metadata['preview'].to_s
+
+    def html? = parts.include?('html')
+    def text? = parts.include?('text')
+
+    def parts = Array(metadata['parts'])
+
+    def default_part = html? ? 'html' : 'text'
+
+    def attachments
+      @attachments ||= Array(metadata['attachments']).map do |raw|
+        Attachment.new(
+          id: raw['id'], filename: raw['filename'], content_type: raw['content_type'],
+          size: raw['size'], cid: raw['cid'], inline: raw['inline']
+        )
+      end
+    end
+
+    def visible_attachments = attachments.reject(&:inline?)
+
+    def attachment(attachment_id) = attachments.find { |a| a.id == attachment_id }
+
+    # --- lazy data (parses the raw .eml) ------------------------------------
+
+    def raw = @raw ||= store.read_raw(id)
+
+    def mail
+      @mail ||= Mail.read_from_string(raw)
+    rescue StandardError => e
+      Mailscope.logger.warn("[mailscope] could not parse #{id}: #{e.class}: #{e.message}")
+      @mail = Mail.new
+    end
+
+    def html_body = @html_body ||= decode(html_part)
+
+    def text_body = @text_body ||= decode(text_part)
+
+    def header_pairs
+      @header_pairs ||= mail.header.fields.map { |f| [f.name.to_s, safe_field_value(f)] }
+    end
+
+    def attachment_body(attachment_id)
+      found = mail.attachments.each_with_index.find { |_, i| attachment_key(i) == attachment_id }
+      found && found[0].body.decoded
+    end
+
+    def to_h
+      metadata.merge(
+        'subject' => subject,
+        'sent_at' => sent_at.iso8601,
+        'mailboxes' => mailbox_keys
+      )
+    end
+
+    private
+
+    def addresses(key)
+      Array(metadata[key]).map { |a| Address.new(name: a['name'], address: a['address']) }
+    end
+
+    def html_part
+      mail.html_part || (mail.mime_type == 'text/html' ? mail : nil)
+    end
+
+    def text_part
+      mail.text_part || (mail.mime_type == 'text/plain' || mail.mime_type.nil? ? mail : nil)
+    end
+
+    def decode(part)
+      return nil unless part
+
+      part.decoded.dup.force_encoding(part_charset(part)).scrub
+    rescue StandardError => e
+      Mailscope.logger.warn("[mailscope] could not decode #{id}: #{e.class}: #{e.message}")
+      nil
+    end
+
+    def part_charset(part)
+      Encoding.find(part.charset.to_s)
+    rescue ArgumentError
+      Encoding::UTF_8
+    end
+
+    def safe_field_value(field)
+      field.decoded.to_s
+    rescue StandardError
+      field.value.to_s
+    end
+
+    def attachment_key(index)
+      format('%02d', index)
+    end
+
+    # --- writing -------------------------------------------------------------
+
+    class << self
+      # Builds the metadata index for a freshly delivered mail. This is the
+      # only place that knows the on-disk contract, so bumping
+      # METADATA_VERSION only needs a change here plus a reader fallback.
+      def metadata_for(mail, id:, size:)
+        {
+          'version' => METADATA_VERSION,
+          'id' => id,
+          'sent_at' => Time.now.utc.iso8601(3),
+          'subject' => mail.subject.to_s,
+          'from' => address_list(mail, :from),
+          'to' => address_list(mail, :to),
+          'cc' => address_list(mail, :cc),
+          'bcc' => address_list(mail, :bcc),
+          'reply_to' => address_list(mail, :reply_to),
+          'message_id' => mail.message_id,
+          'mailer' => mailer_for(mail),
+          'parts' => parts_for(mail),
+          'attachments' => attachments_for(mail),
+          'preview' => preview_for(mail),
+          'size' => size
+        }
+      end
+
+      def address_list(mail, field)
+        field_value = mail[field]
+        addrs = field_value.respond_to?(:addrs) ? field_value.addrs : nil
+        return [] unless addrs
+
+        addrs.map { |a| { 'name' => a.display_name, 'address' => a.address } }
+      rescue StandardError
+        Array(mail.send(field)).map { |a| { 'name' => nil, 'address' => a } }
+      end
+
+      def parts_for(mail)
+        parts = []
+        parts << 'html' if mail.html_part || mail.mime_type == 'text/html'
+        parts << 'text' if mail.text_part || mail.mime_type == 'text/plain' || mail.mime_type.nil?
+        parts
+      end
+
+      def attachments_for(mail)
+        mail.attachments.each_with_index.map do |attachment, index|
+          {
+            'id' => format('%02d', index),
+            'filename' => sanitize_filename(attachment.filename.to_s),
+            'content_type' => attachment.mime_type,
+            'size' => attachment.body.decoded.bytesize,
+            'cid' => attachment.cid,
+            'inline' => attachment.inline?
+          }
+        rescue StandardError
+          { 'id' => format('%02d', index), 'filename' => "attachment-#{index}",
+            'content_type' => 'application/octet-stream', 'size' => 0, 'cid' => nil, 'inline' => false }
+        end
+      end
+
+      # Short plain-text snippet for the message list.
+      def preview_for(mail)
+        squeeze_preview(preview_source(mail))
+      rescue StandardError
+        ''
+      end
+
+      def preview_source(mail)
+        text = mail.text_part || (mail.mime_type == 'text/plain' ? mail : nil)
+        return text.decoded if text
+
+        html = mail.html_part || (mail.mime_type == 'text/html' ? mail : nil)
+        return '' unless html
+
+        html.decoded.gsub(%r{<(script|style)[^>]*>.*?</\1>}mi, ' ').gsub(/<[^>]+>/, ' ')
+      end
+
+      def squeeze_preview(body)
+        body.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+            .gsub(/&nbsp;?/, ' ').squeeze(" \t\n").strip[0, PREVIEW_LENGTH].to_s
+      end
+
+      def sanitize_filename(name)
+        cleaned = name.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: '_').strip
+        # Drop any directory part first: transliterating separators afterwards
+        # would leave "../../etc/passwd" as a single (harmless but ugly) name.
+        cleaned = File.basename(cleaned.tr('\\', '/'))
+        cleaned = cleaned.tr("\u{202E}%$|:;\t\r\n", '-').delete_prefix('.')
+        cleaned.empty? ? 'attachment' : cleaned
+      end
+
+      # ActionMailer sets `delivery_handler` to the mailer class; the header is
+      # an escape hatch for anything delivering mail by hand.
+      def mailer_for(mail)
+        header = mail['X-Mailscope-Mailer']
+        return header.to_s if header
+
+        handler = mail.delivery_handler if mail.respond_to?(:delivery_handler)
+        handler.respond_to?(:name) ? handler.name : nil
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/mailscope/query.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Mailscope
+  # Filters the in-memory message list. Small enough to stay honest about what
+  # it does: no index, just a scan over metadata that is already loaded.
+  class Query
+    attr_reader :messages, :mailbox, :term, :only
+
+    def initialize(messages, mailbox: nil, term: nil, only: nil)
+      @messages = messages
+      @mailbox  = mailbox.to_s.downcase.presence
+      @term     = term.to_s.strip.presence
+      @only     = only.to_s.presence
+    end
+
+    def results
+      @results ||= messages.select { |m| matches_mailbox?(m) && matches_only?(m) && matches_term?(m) }
+    end
+
+    def filtered? = !(mailbox.nil? && term.nil? && only.nil?)
+
+    private
+
+    def matches_mailbox?(message)
+      mailbox.nil? || message.mailbox_keys.include?(mailbox)
+    end
+
+    def matches_only?(message)
+      case only
+      when 'attachments' then message.visible_attachments.any?
+      when 'html'        then message.html?
+      when 'text'        then message.text? && !message.html?
+      else true
+      end
+    end
+
+    def matches_term?(message)
+      return true if term.nil?
+
+      needle = term.downcase
+      haystack(message).any? { |value| value.include?(needle) }
+    end
+
+    def haystack(message)
+      @haystacks ||= {}
+      @haystacks[message.id] ||= [
+        message.subject,
+        message.preview,
+        message.mailer.to_s,
+        *(message.from + message.recipients).map(&:display)
+      ].map { |v| v.to_s.downcase }
+    end
+  end
+end

data/lib/mailscope/storage/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Mailscope
+  module Storage
+    # The contract every adapter has to satisfy. Kept deliberately small so a
+    # database- or Redis-backed adapter stays a weekend of work.
+    class Base
+      # @return [Array<Mailscope::Message>] newest first
+      def all = raise(NotImplementedError)
+
+      # @return [Mailscope::Message, nil]
+      def find(id) = raise(NotImplementedError)
+
+      # Persists a delivered Mail::Message. @return [String] the new id
+      def store(mail) = raise(NotImplementedError)
+
+      # @return [String] raw RFC822 source
+      def read_raw(id) = raise(NotImplementedError)
+
+      # @return [String, nil] decoded attachment bytes
+      def read_attachment(id, attachment_id) = raise(NotImplementedError)
+
+      def delete(id) = raise(NotImplementedError)
+
+      def clear = raise(NotImplementedError)
+
+      # Applies the retention policy (max_letters:, max_age:) and returns the
+      # number of messages removed. Adapters without retention keep this no-op.
+      def prune(**) = 0
+
+      # Cheap change token so the browser can poll without transferring the list.
+      def revision = all.first&.id.to_s
+    end
+  end
+end

data/lib/mailscope/storage/filesystem.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'securerandom'
+
+module Mailscope
+  module Storage
+    # One directory per message:
+    #
+    #   <location>/<id>/metadata.json   index used by the list view
+    #   <location>/<id>/mail.eml        pristine RFC822 source
+    #
+    # Ids are lexicographically sortable by time, so listing never stats files.
+    class Filesystem < Base
+      ID_FORMAT = /\A[0-9]{8}-[0-9]{6}-[0-9]{6}-[0-9a-f]{8}\z/
+      # letter_opener / letter_opener_web laid out directories like
+      # "1358825621_ba83a22"; we still accept those for read-only migration.
+      LEGACY_ID_FORMAT = /\A[0-9]+_[0-9]+_?[0-9a-f]+\z|\A[0-9]+_[0-9a-f]+\z/
+
+      attr_reader :location
+
+      def initialize(location:)
+        super()
+        @location = Pathname(location.to_s)
+      end
+
+      def all
+        ids.map { |id| build(id) }.compact
+      end
+
+      def find(id)
+        id = validate_id!(id)
+        build(id)
+      end
+
+      def store(mail)
+        id  = generate_id
+        dir = location.join(id)
+        FileUtils.mkdir_p(dir)
+
+        raw = mail.encoded
+        File.binwrite(dir.join('mail.eml'), raw)
+
+        metadata = Message.metadata_for(mail, id: id, size: raw.bytesize)
+        write_json(dir.join('metadata.json'), metadata)
+        id
+      end
+
+      def read_raw(id)
+        path = path_for(id, 'mail.eml')
+        return File.binread(path).force_encoding(Encoding::UTF_8).scrub if path&.file?
+
+        legacy_raw(id)
+      end
+
+      def read_attachment(id, attachment_id)
+        find(id)&.attachment_body(attachment_id)
+      end
+
+      # @return [String, nil] the id that was removed, or nil if it was gone
+      def delete(id)
+        dir = dir_for(id)
+        return nil unless dir&.directory?
+
+        FileUtils.rm_rf(dir.to_s)
+        id
+      end
+
+      def clear
+        return 0 unless location.directory?
+
+        removed = ids.size
+        # Empty the directory instead of removing it, so a watcher holding the
+        # path (or a mounted volume) keeps working.
+        Dir.children(location).each { |child| FileUtils.rm_rf(location.join(child).to_s) }
+        removed
+      end
+
+      def prune(max_letters: nil, max_age: nil)
+        removed = max_age ? prune_by_age(max_age) : 0
+        removed + (max_letters ? prune_by_count(max_letters) : 0)
+      end
+
+      def revision
+        "#{ids.size}:#{ids.first}"
+      end
+
+      private
+
+      def prune_by_age(max_age)
+        cutoff = Time.now - max_age.to_i
+        expired = ids.select do |id|
+          message = build(id)
+          message && message.sent_at < cutoff
+        end
+        expired.count { |id| delete(id) }
+      end
+
+      def prune_by_count(max_letters)
+        ids.drop(max_letters).count { |id| delete(id) }
+      end
+
+      def ids
+        return [] unless location.directory?
+
+        Dir.children(location)
+           .select { |name| valid_id?(name) && location.join(name).directory? }
+           .sort
+           .reverse
+      end
+
+      def build(id)
+        dir = location.join(id)
+        metadata_path = dir.join('metadata.json')
+
+        metadata = if metadata_path.file?
+                     parse_json(metadata_path)
+                   elsif dir.directory?
+                     legacy_metadata(id, dir)
+                   end
+        return nil unless metadata
+
+        Message.new(metadata, store: self)
+      end
+
+      def generate_id
+        loop do
+          now = Time.now.utc
+          id  = format('%<stamp>s-%<usec>06d-%<nonce>s',
+                       stamp: now.strftime('%Y%m%d-%H%M%S'), usec: now.usec, nonce: SecureRandom.hex(4))
+          return id unless location.join(id).exist?
+        end
+      end
+
+      def valid_id?(name)
+        ID_FORMAT.match?(name) || LEGACY_ID_FORMAT.match?(name)
+      end
+
+      def validate_id!(id)
+        id = id.to_s
+        raise InvalidLetterId, "invalid message id: #{id.inspect}" unless valid_id?(id)
+
+        id
+      end
+
+      def dir_for(id)
+        dir = location.join(validate_id!(id)).cleanpath
+        # Defence in depth: the id regexp already rules out traversal.
+        return nil unless dir.to_s.start_with?(location.cleanpath.to_s + File::SEPARATOR)
+
+        dir
+      end
+
+      def path_for(id, filename)
+        dir_for(id)&.join(filename)
+      end
+
+      def parse_json(path)
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError, SystemCallError => e
+        Mailscope.logger.warn("[mailscope] unreadable metadata at #{path}: #{e.message}")
+        nil
+      end
+
+      def write_json(path, data)
+        tmp = "#{path}.#{Process.pid}.tmp"
+        File.write(tmp, JSON.pretty_generate(data))
+        File.rename(tmp, path)
+      end
+
+      # --- letter_opener compatibility ----------------------------------------
+
+      def legacy_raw(id)
+        dir = dir_for(id)
+        return nil unless dir&.directory?
+
+        html = %w[rich.html plain.html].map { |f| dir.join(f) }.find(&:file?)
+        return nil unless html
+
+        # Wrap the rendered HTML in a minimal envelope so the rest of the app
+        # can treat legacy directories like any other message.
+        body = File.read(html)
+        Mail.new do
+          content_type 'text/html; charset=UTF-8'
+          body body
+        end.encoded
+      end
+
+      def legacy_metadata(id, dir)
+        html = %w[rich.html plain.html].map { |f| dir.join(f) }.find(&:file?)
+        return nil unless html
+
+        parts = []
+        parts << 'html' if dir.join('rich.html').file?
+        parts << 'text' if dir.join('plain.html').file?
+
+        {
+          'version' => 0, 'id' => id, 'sent_at' => File.mtime(dir).utc.iso8601(3),
+          'subject' => legacy_subject(html), 'from' => [], 'to' => [], 'cc' => [], 'bcc' => [],
+          'reply_to' => [], 'message_id' => nil, 'mailer' => nil, 'parts' => parts,
+          'attachments' => [], 'preview' => Mailscope.translate('storage.imported', 'Message imported from letter_opener'),
+          'size' => File.size(html), 'legacy' => true
+        }
+      end
+
+      def legacy_subject(path)
+        File.read(path)[%r{<title>(.*?)</title>}m, 1].to_s.strip
+      rescue StandardError
+        ''
+      end
+    end
+  end
+end

data/lib/mailscope/storage.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'mailscope/storage/base'
+require 'mailscope/storage/filesystem'
+
+module Mailscope
+  module Storage
+    ADAPTERS = { filesystem: 'Mailscope::Storage::Filesystem' }.freeze
+
+    def self.register(name, class_name)
+      ADAPTERS.merge!(name.to_sym => class_name)
+    end
+
+    def self.build(adapter, **options)
+      return adapter unless adapter.is_a?(Symbol) || adapter.is_a?(String)
+
+      class_name = ADAPTERS.fetch(adapter.to_sym) do
+        raise ArgumentError, "unknown Mailscope storage adapter: #{adapter.inspect}"
+      end
+      Object.const_get(class_name).new(**options)
+    end
+  end
+end

data/lib/mailscope/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mailscope
+  VERSION = '0.1.0'
+end

data/lib/mailscope.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'tmpdir'
+
+require 'mailscope/version'
+require 'mailscope/configuration'
+require 'mailscope/message'
+require 'mailscope/storage'
+require 'mailscope/mailbox'
+require 'mailscope/query'
+require 'mailscope/body_renderer'
+
+module Mailscope
+  class Error < StandardError; end
+  class InvalidLetterId < Error; end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config if block_given?
+      @storage = nil
+      config
+    end
+
+    def reset!
+      @config  = nil
+      @storage = nil
+    end
+
+    # The resolved storage adapter instance.
+    def storage
+      @storage ||= Storage.build(config.storage, location: config.location)
+    end
+
+    def deliveries
+      storage.all
+    end
+
+    # Translates through the host app's I18n when available; the fallback keeps
+    # the library usable outside Rails.
+    def translate(key, fallback, **options)
+      return fallback unless defined?(::I18n)
+
+      ::I18n.t("mailscope.#{key}", default: fallback, **options)
+    end
+
+    def logger
+      return Rails.logger if defined?(Rails) && Rails.logger
+
+      @logger ||= Logger.new($stderr)
+    end
+  end
+end
+
+# The engine reaches back into Mailscope.config, so it loads after the module body.
+require 'mailscope/engine' if defined?(Rails::Engine)