mail_dude 0.1.0

data/lib/mail_dude/stores/database_store.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module MailDude
+  module Stores
+    class DatabaseStore < Base
+      def write(mail)
+        ensure_table!
+        record = build_record(mail)
+        StoredEmail.create!(attributes_for(record))
+        record
+      rescue ActiveRecord::StatementInvalid, ActiveRecord::ActiveRecordError => e
+        raise StorageError, "MailDude database storage failed: #{e.message}"
+      end
+
+      def list(page: 1, per_page: MailDude.configuration.default_per_page, query: nil)
+        ensure_table!
+        records = StoredEmail.order(captured_at: :desc).map { |row| record_from_row(row, raw: false) }
+        page_for(records, page: page, per_page: per_page, query: query)
+      end
+
+      def find(id)
+        ensure_table!
+        valid_id = validate_id!(id)
+        row = StoredEmail.find_by(uid: valid_id)
+        raise MessageNotFoundError, 'Message not found' unless row
+
+        record_from_row(row, raw: true)
+      end
+
+      def delete(id)
+        ensure_table!
+        valid_id = validate_id!(id)
+        row = StoredEmail.find_by(uid: valid_id)
+        return false unless row
+
+        row.destroy!
+        true
+      end
+
+      def clear
+        ensure_table!
+        StoredEmail.delete_all
+      end
+
+      def prune(max_messages: MailDude.configuration.max_messages,
+                retention_period: MailDude.configuration.retention_period)
+        ensure_table!
+        ids = prune_ids(list(per_page: StoredEmail.count).records, max_messages: max_messages,
+                                                                   retention_period: retention_period)
+        StoredEmail.where(uid: ids).delete_all
+      end
+
+      private
+
+      def attributes_for(record)
+        metadata = record.metadata
+        {
+          uid: record.id,
+          captured_at: Time.iso8601(metadata['captured_at']),
+          subject: metadata['subject'],
+          from_addresses_json: JSON.generate(metadata['from']),
+          sender_addresses_json: JSON.generate(metadata['sender']),
+          to_addresses_json: JSON.generate(metadata['to']),
+          cc_addresses_json: JSON.generate(metadata['cc']),
+          bcc_addresses_json: JSON.generate(metadata['bcc']),
+          reply_to_addresses_json: JSON.generate(metadata['reply_to']),
+          message_id: metadata['message_id'],
+          content_type: metadata['content_type'],
+          mailer: metadata['mailer'],
+          mailer_action: metadata['mailer_action'],
+          has_html: metadata['has_html'],
+          has_text: metadata['has_text'],
+          has_attachments: metadata['has_attachments'],
+          attachments_count: metadata['attachments_count'],
+          size_bytes: metadata['size_bytes'],
+          metadata_json: JSON.generate(metadata),
+          raw_message: record.raw_source
+        }
+      end
+
+      def ensure_table!
+        return if StoredEmail.connection.data_source_exists?(StoredEmail.table_name)
+
+        raise StorageError,
+              'MailDude database storage requires the mail_dude_stored_emails table. Run bin/rails db:migrate.'
+      end
+
+      def record_from_row(row, raw:)
+        MessageRecord.new(id: row.uid, metadata: JSON.parse(row.metadata_json), raw_source: (row.raw_message if raw))
+      end
+    end
+  end
+end

data/lib/mail_dude/stores/file_store.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module MailDude
+  module Stores
+    class FileStore < Base
+      attr_reader :root
+
+      def initialize(root = MailDude.configuration.storage_path)
+        @root = Pathname.new(root.to_s)
+        ensure_directories!
+      end
+
+      def write(mail)
+        synchronize do
+          record = build_record(mail)
+          write_record(record)
+          record
+        end
+      end
+
+      def list(page: 1, per_page: MailDude.configuration.default_per_page, query: nil)
+        page_for(load_metadata_records, page: page, per_page: per_page, query: query)
+      end
+
+      def find(id)
+        valid_id = validate_id!(id)
+        directory = message_path(valid_id)
+        raise MessageNotFoundError, 'Message not found' unless directory.directory?
+
+        metadata_file = directory.join('metadata.json')
+        raw_file = directory.join('message.eml')
+        raise MessageNotFoundError, 'Message not found' unless metadata_file.file? && raw_file.file?
+
+        metadata = JSON.parse(metadata_file.read)
+        MessageRecord.new(id: valid_id, metadata: metadata, raw_source: raw_file.binread)
+      rescue JSON::ParserError
+        raise MessageNotFoundError, 'Message not found'
+      end
+
+      def delete(id)
+        valid_id = validate_id!(id)
+        synchronize do
+          directory = message_path(valid_id)
+          return false unless directory.directory?
+
+          FileUtils.rm_rf(directory)
+          true
+        end
+      end
+
+      def clear
+        synchronize do
+          directories = message_directories
+          directories.each { |directory| FileUtils.rm_rf(directory) }
+          directories.length
+        end
+      end
+
+      def prune(max_messages: MailDude.configuration.max_messages,
+                retention_period: MailDude.configuration.retention_period)
+        synchronize do
+          ids = prune_ids(load_metadata_records, max_messages: max_messages, retention_period: retention_period)
+          ids.each { |id| FileUtils.rm_rf(message_path(id)) }
+          ids.length
+        end
+      end
+
+      private
+
+      def ensure_directories!
+        FileUtils.mkdir_p(messages_path)
+      end
+
+      def load_metadata_records
+        message_directories.filter_map do |directory|
+          metadata = JSON.parse(directory.join('metadata.json').read)
+          MessageRecord.new(id: metadata.fetch('id'), metadata: metadata)
+        rescue Errno::ENOENT, JSON::ParserError, KeyError
+          Rails.logger.warn("MailDude skipped corrupt metadata in #{directory.basename}")
+          nil
+        end
+      end
+
+      def lock_path
+        root.join('.lock')
+      end
+
+      def message_directories
+        return [] unless messages_path.directory?
+
+        messages_path.children.select(&:directory?).select { |path| path.basename.to_s.match?(ID_PATTERN) }
+      end
+
+      def message_path(id)
+        messages_path.join(id)
+      end
+
+      def messages_path
+        root.join('messages')
+      end
+
+      def synchronize
+        ensure_directories!
+        File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |file|
+          file.flock(File::LOCK_EX)
+          yield
+        ensure
+          file.flock(File::LOCK_UN)
+        end
+      end
+
+      def write_record(record)
+        temporary = messages_path.join("#{record.id}.tmp-#{$PROCESS_ID}-#{SecureRandom.hex(4)}")
+        final = message_path(record.id)
+        FileUtils.mkdir_p(temporary)
+        temporary.join('metadata.json').write(JSON.pretty_generate(record.metadata))
+        temporary.join('message.eml').binwrite(record.raw_source)
+        File.rename(temporary, final)
+      ensure
+        FileUtils.rm_rf(temporary)
+      end
+    end
+  end
+end

data/lib/mail_dude/stores/memory_store.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module MailDude
+  module Stores
+    class MemoryStore < Base
+      def initialize
+        @records = {}
+        @mutex = Mutex.new
+      end
+
+      def write(mail)
+        record = build_record(mail)
+        mutex.synchronize { records[record.id] = record }
+        record
+      end
+
+      def list(page: 1, per_page: MailDude.configuration.default_per_page, query: nil)
+        mutex.synchronize { page_for(records.values, page: page, per_page: per_page, query: query) }
+      end
+
+      def find(id)
+        valid_id = validate_id!(id)
+        mutex.synchronize { records.fetch(valid_id) { raise MessageNotFoundError, 'Message not found' } }
+      end
+
+      def delete(id)
+        valid_id = validate_id!(id)
+        mutex.synchronize { !records.delete(valid_id).nil? }
+      end
+
+      def clear
+        mutex.synchronize do
+          count = records.length
+          records.clear
+          count
+        end
+      end
+
+      def prune(max_messages: MailDude.configuration.max_messages,
+                retention_period: MailDude.configuration.retention_period)
+        mutex.synchronize do
+          ids = prune_ids(records.values, max_messages: max_messages, retention_period: retention_period)
+          ids.each { |id| records.delete(id) }
+          ids.length
+        end
+      end
+
+      private
+
+      attr_reader :mutex, :records
+    end
+  end
+end

data/lib/mail_dude/version.rb

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

data/lib/mail_dude.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext'
+require 'json'
+require 'mail'
+require 'pathname'
+require 'rails'
+
+require_relative 'mail_dude/version'
+require_relative 'mail_dude/errors'
+require_relative 'mail_dude/configuration'
+require_relative 'mail_dude/dashboard'
+require_relative 'mail_dude/message_record'
+require_relative 'mail_dude/pagination'
+require_relative 'mail_dude/message_serializer'
+require_relative 'mail_dude/message_presenter'
+require_relative 'mail_dude/attachment_locator'
+require_relative 'mail_dude/html_body_renderer'
+require_relative 'mail_dude/message_broadcast'
+require_relative 'mail_dude/stores/base'
+require_relative 'mail_dude/stores/memory_store'
+require_relative 'mail_dude/stores/file_store'
+require_relative 'mail_dude/stores/database_store'
+require_relative 'mail_dude/delivery_method'
+require_relative 'mail_dude/mailer_metadata_headers'
+require_relative 'mail_dude/engine'
+
+module MailDude
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+      configuration.validate!
+      reset_store!
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      reset_store!
+    end
+
+    def enabled?(environment = rails_environment)
+      config = configuration.validate!
+      env = environment.to_s
+      return true if env == 'production' && config.allow_production
+      return false if env == 'production'
+
+      config.enabled_environments.include?(env)
+    end
+
+    def store
+      @store ||= build_store
+    end
+
+    def reset_store!
+      @store = nil
+    end
+
+    def rails_environment
+      return Rails.env if defined?(Rails) && Rails.respond_to?(:env) && Rails.env
+
+      ENV.fetch('RAILS_ENV', ENV.fetch('RACK_ENV', 'development'))
+    end
+
+    private
+
+    def build_store
+      factories = {
+        file: -> { Stores::FileStore.new(configuration.storage_path) },
+        memory: -> { Stores::MemoryStore.new },
+        database: -> { Stores::DatabaseStore.new }
+      }
+      factories.fetch(configuration.validate!.storage).call
+    end
+  end
+end

data/lib/tasks/mail_dude.rake

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+namespace :mail_dude do
+  desc 'Clear all captured MailDude messages'
+  task clear: :environment do
+    count = MailDude.store.clear
+    puts "Cleared #{count} MailDude messages"
+  end
+
+  desc 'Prune captured MailDude messages using configured retention'
+  task prune: :environment do
+    count = MailDude.store.prune
+    puts "Pruned #{count} MailDude messages"
+  end
+
+  desc 'Print MailDude storage statistics'
+  task stats: :environment do
+    store = MailDude.store
+    page = store.list(per_page: 1)
+    puts "Storage: #{MailDude.configuration.storage}"
+    puts "Messages: #{page.total_count}"
+    puts "Path: #{MailDude.configuration.storage_path}"
+    puts "Table: #{MailDude::StoredEmail.table_name}"
+  end
+end

metadata

@@ -0,0 +1,224 @@
+--- !ruby/object:Gem::Specification
+name: mail_dude
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- MailDude contributors
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.40'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.40'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.30'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.30'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: MailDude captures Action Mailer deliveries and displays them in a mountable
+  Rails engine.
+email:
+- mail_dude@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/assets/images/mail_dude/icon.png
+- app/assets/stylesheets/mail_dude/application.css
+- app/channels/mail_dude/messages_channel.rb
+- app/controllers/mail_dude/application_controller.rb
+- app/controllers/mail_dude/attachments_controller.rb
+- app/controllers/mail_dude/messages_controller.rb
+- app/helpers/mail_dude/application_helper.rb
+- app/models/mail_dude/application_record.rb
+- app/models/mail_dude/stored_email.rb
+- app/views/layouts/mail_dude/application.html.erb
+- app/views/mail_dude/messages/_empty.html.erb
+- app/views/mail_dude/messages/_error.html.erb
+- app/views/mail_dude/messages/_list.html.erb
+- app/views/mail_dude/messages/_message_pane.html.erb
+- app/views/mail_dude/messages/_metadata.html.erb
+- app/views/mail_dude/messages/_tabs.html.erb
+- app/views/mail_dude/messages/error.html.erb
+- app/views/mail_dude/messages/index.html.erb
+- app/views/mail_dude/messages/show.html.erb
+- config/routes.rb
+- db/migrate/20260506170200_create_mail_dude_stored_emails.rb
+- lib/generators/mail_dude/install_generator.rb
+- lib/generators/mail_dude/templates/create_mail_dude_stored_emails.tt
+- lib/generators/mail_dude/templates/initializer.tt
+- lib/mail_dude.rb
+- lib/mail_dude/attachment_locator.rb
+- lib/mail_dude/configuration.rb
+- lib/mail_dude/dashboard.rb
+- lib/mail_dude/delivery_method.rb
+- lib/mail_dude/engine.rb
+- lib/mail_dude/errors.rb
+- lib/mail_dude/html_body_renderer.rb
+- lib/mail_dude/mailer_metadata_headers.rb
+- lib/mail_dude/message_broadcast.rb
+- lib/mail_dude/message_presenter.rb
+- lib/mail_dude/message_record.rb
+- lib/mail_dude/message_serializer.rb
+- lib/mail_dude/pagination.rb
+- lib/mail_dude/stores/base.rb
+- lib/mail_dude/stores/database_store.rb
+- lib/mail_dude/stores/file_store.rb
+- lib/mail_dude/stores/memory_store.rb
+- lib/mail_dude/version.rb
+- lib/tasks/mail_dude.rake
+homepage: https://example.com/mail_dude
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: A Rails Action Mailer capture engine for development and QA.
+test_files: []