rails-mailer-sandbox 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b3769b564df7ce2bf2278546029a59a92ad70ceec2e074ab4550abecbd4055e
-  data.tar.gz: ac6f6d14a1e60deadfc5388c42426d0d79e942fe3ba65986199391589c4be47d
+  metadata.gz: bf80512fe3b9cd60f5842611ee2a68be8b1f5da0f7198872f5aaf0e62fc9c46a
+  data.tar.gz: 8436ff5fa82cf18b5dcb6ea7a905264fcf4bcb638aa711a2f0808528c0aee986
 SHA512:
-  metadata.gz: 8744e34ffdf4cade29d895b9279c1f38aefd55e0beea7d50ef74387d5418b278c011116b9b16c1ccc70bb15cc7840bb8e5d0aad2e8ae51c8dff8e2aca3eea761
-  data.tar.gz: ba697866c07972be8adafcae6de50690cd0c653d3f44f24583ab0e77587070ce84e740f1ce3f6f4777aa55f2b531d152819c0c5032c9f766f0d83dbce67cffe3
+  metadata.gz: 755b5e8a9368bd55e3c3221494a95aedef5604da4378c32ec62baa84a9754318c5a586a7dc4dd28a4b7a6fb6e1e27409613ed8059d3affba7398f4c6b511d234
+  data.tar.gz: b2a089a3a3b475457052833aac2ba039cd76a7ff39fd25d2bf4aac0c573ebd82cd3e6d7440ec2ae18e77bcd4848964092c604fbb1794bdf4ad88a582cd0b70d2

data/.yardopts

@@ -0,0 +1,8 @@
+--markup markdown
+--readme README.md
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+CONTRIBUTING.md
+MIT-LICENSE

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to Rails Mailer Sandbox are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.2] - 2026-09-21
+
+### Added
+
+- Rubydoc.info documentation metadata and YARD annotations
+- Documentation status badge in README
+- `.yardopts` configuration file
+
+## [0.2.1] - 2026-09-13
+
+### Added
+
+- Inline MIME image rendering through embedded `data:` URLs
+- Safe new-tab behavior for links inside HTML previews
+- RFC 5987 UTF-8 attachment download filenames
+- Lightweight `/status.json` endpoint for inbox polling
+- Recipient labels for Bcc-only and undisclosed-recipient messages
+- Root `Gemfile` and GitHub Actions CI for Ruby 3.0 through 3.3
+- Explicit `base64` dependency for Ruby 3.4 compatibility
+- Regression tests for complex HTML-only and multipart emails
+
+### Fixed
+
+- CSS and script content leaking into generated plain-text previews
+- Search ignoring body content after first 140 characters
+- Inline `cid:` images appearing broken
+- Links without `target="_blank"` doing nothing inside preview
+- Every polling request parsing all stored `.eml` files
+
+### Security
+
+- Preview links escape sandbox only into new tabs; scripts, forms, remote resources,
+  and top-level navigation remain blocked
+
+## [0.2.0] - 2026-09-13
+
+### Added
+
+- Initial RubyGems release
+- Action Mailer delivery method
+- Persistent filesystem-backed `.eml` storage
+- Mountable Rails Web UI with search, HTML/text/raw views, responsive preview widths,
+  attachments, automatic refresh, and message deletion
+- `rails_mailer_sandbox:setup` Rake task
+
+[0.2.2]: https://github.com/azmi2409/rails-mailer-sandbox/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/azmi2409/rails-mailer-sandbox/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/azmi2409/rails-mailer-sandbox/releases/tag/v0.2.0

data/README.md

@@ -1,47 +1,55 @@
-# Rails Mailer Sandbox
+# Rails Mailer Sandbox 📬
 
-Development email sandbox for Rails. Captures Action Mailer deliveries, stores original
-`.eml` messages on disk, and exposes a Mailtrap-inspired Web UI inside your Rails app.
+[![CI](https://github.com/azmi2409/rails-mailer-sandbox/actions/workflows/ci.yml/badge.svg)](https://github.com/azmi2409/rails-mailer-sandbox/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/rails-mailer-sandbox.svg)](https://rubygems.org/gems/rails-mailer-sandbox)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/rails-mailer-sandbox)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](MIT-LICENSE)
 
-## Features
+Catch Rails emails locally before they escape into the wild. Rails Mailer Sandbox stores
+real `.eml` messages and gives you a Mailtrap-inspired inbox right inside your Rails app.
+No SMTP server, database, account, or monthly bill needed.
 
-- Persistent MIME message storage across Rails restarts
-- Search by subject, sender, recipient, or body preview
+## ✨ What You Get
+
+- Persistent MIME messages across Rails restarts
+- Search by subject, sender, recipient, or full body
 - HTML, plain-text, and raw-source views
 - Desktop, tablet, and mobile preview widths
 - From, To, Cc, Bcc, date, and message-size details
-- Attachment downloads
-- Automatic inbox refresh
+- Inline `cid:` image previews and attachment downloads
+- UTF-8 attachment filenames
+- Automatic inbox refresh without repeatedly parsing every email
 - Individual and bulk deletion
-- Sandboxed HTML previews with remote resources and scripts blocked
+- Sandboxed HTML previews with scripts and remote resources blocked
 - Filesystem locking and atomic writes for Rails and background workers
-- No database or external service
 
-## Installation
+## 🚀 Get Started
 
 Add gem to development group:
 
 ```ruby
 group :development do
-  gem "rails-mailer-sandbox", github: "azmi2409/rails-mailer-sandbox"
+  gem "rails-mailer-sandbox"
 end
 ```
 
-Then run:
+Set it up:
 
 ```bash
 bundle install
 bundle exec rake rails_mailer_sandbox:setup
 ```
 
-Restart Rails and open <http://localhost:3000/rails_mailer_sandbox>.
+Restart Rails, send any Action Mailer email, then visit:
+
+👉 <http://localhost:3000/rails_mailer_sandbox>
 
 Setup creates `config/initializers/rails_mailer_sandbox.rb`, configures Action Mailer,
-and mounts Web UI. Repeating task is safe. Existing edited initializer is never overwritten.
+and mounts Web UI. Run task again safely; it will not overwrite edited initializer.
 
-## Manual Setup
+## 🔧 Manual Setup
 
-Configure `config/environments/development.rb`:
+Prefer doing it yourself? Add this to `config/environments/development.rb`:
 
 ```ruby
 config.action_mailer.delivery_method = :rails_mailer_sandbox
@@ -49,35 +57,47 @@ config.action_mailer.perform_deliveries = true
 config.action_mailer.raise_delivery_errors = true
 ```
 
-Mount Web UI in `config/routes.rb`:
+Mount inbox in `config/routes.rb`:
 
 ```ruby
 mount RailsMailerSandbox::Server.new => "/rails_mailer_sandbox" if Rails.env.development?
 ```
 
-## Storage
+## 💾 Where Emails Live
 
 Default path: `Rails.root/tmp/rails_mailer_sandbox`.
 
-Override path in initializer:
+Want another location? Set it in initializer:
 
 ```ruby
 RailsMailerSandbox.storage_path = Rails.root.join("storage", "development_mail")
 ```
 
-Keep custom storage outside version control. Rails `tmp:clear` removes default inbox.
-Local filesystem storage suits development on one host. It does not target large archives
-or distributed deployments.
+Keep custom storage out of version control. `bin/rails tmp:clear` removes default inbox.
+Filesystem storage targets local development on one host, not distributed deployments or
+giant email archives.
 
-## Development
+## 🧪 Development
 
 ```bash
-ruby -Ilib test/rails_mailer_sandbox_test.rb
+git clone https://github.com/azmi2409/rails-mailer-sandbox.git
+cd rails-mailer-sandbox
+bundle install
+bundle exec ruby -Ilib test/rails_mailer_sandbox_test.rb
 gem build rails-mailer-sandbox.gemspec
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) before opening pull request.
+CI runs tests and gem build on Ruby 3.0, 3.1, 3.2, and 3.3.
+Found a bug or have a neat focused improvement? Read [CONTRIBUTING.md](CONTRIBUTING.md),
+then open an issue or pull request. 🙌
+
+Release notes live in [CHANGELOG.md](CHANGELOG.md). 📝
+
+## 🔒 One Important Rule
+
+Use this gem in development only. Captured emails may contain reset links, personal data,
+or other secrets. Never expose mounted inbox publicly or enable it in production.
 
-## License
+## 📄 License
 
-[MIT](MIT-LICENSE)
+[MIT](MIT-LICENSE). Build useful things and test your emails. 🎉

data/lib/rails_mailer_sandbox/setup.rb

@@ -3,7 +3,11 @@
 require "fileutils"
 
 module RailsMailerSandbox
+  # Generator for sandbox initializer.
   module Setup
+    # Generates initializer and configures routes.
+    # @param root [String, Pathname] Rails application root path
+    # @return [void]
     def self.run(root)
       root = File.expand_path(root)
       raise "Not a Rails application: #{root}" unless File.file?(File.join(root, "config/application.rb"))

data/lib/rails_mailer_sandbox.rb

@@ -8,22 +8,51 @@ require "time"
 require "date"
 require "fileutils"
 require "mail"
+require "base64"
+require "uri"
 
+# Module for local Action Mailer email preview and storage sandbox.
 module RailsMailerSandbox
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 
   class << self
+    # @return [String, nil]
     attr_writer :storage_path
 
+    # Directory where captured emails are stored.
+    # @return [String]
     def storage_path
       @storage_path || File.join(defined?(Rails) && Rails.respond_to?(:root) && Rails.root ? Rails.root.to_s : Dir.pwd, "tmp", "rails_mailer_sandbox")
     end
   end
 
+  # Represents a captured email message.
   class Message
-    attr_reader :id, :from, :to, :cc, :bcc, :subject, :date, :text_part,
-                :html_part, :raw_source, :attachments
-
+    # @return [String] Unique message identifier
+    attr_reader :id
+    # @return [Array<String>] Sender email addresses
+    attr_reader :from
+    # @return [Array<String>] Recipient email addresses
+    attr_reader :to
+    # @return [Array<String>] CC recipient email addresses
+    attr_reader :cc
+    # @return [Array<String>] BCC recipient email addresses
+    attr_reader :bcc
+    # @return [String] Email subject line
+    attr_reader :subject
+    # @return [Time, DateTime] Message timestamp
+    attr_reader :date
+    # @return [String, nil] Plain text body
+    attr_reader :text_part
+    # @return [String, nil] HTML body
+    attr_reader :html_part
+    # @return [String] Raw MIME message source
+    attr_reader :raw_source
+    # @return [Array<Hash{Symbol => Object}>] Parsed attachments
+    attr_reader :attachments
+
+    # @param mail [Mail::Message]
+    # @param id [String]
     def initialize(mail, id: SecureRandom.uuid)
       @id = id
       @date = mail.date || Time.now
@@ -38,46 +67,74 @@ module RailsMailerSandbox
       @raw_source = "Bcc: #{@bcc.join(', ').gsub(/[\r\n]/, '')}\r\n#{@raw_source}" unless @bcc.empty? || @raw_source.match?(/^Bcc:/i)
     end
 
+    # @return [Array<String>]
     def recipients
       to + cc + bcc
     end
 
+    # @return [String]
     def preview
       text_part.to_s.gsub(/\s+/, " ").strip[0, 140]
     end
 
+    # @return [Integer]
     def size
       raw_source.bytesize
     end
 
+    # @param query [String]
+    # @return [Boolean]
     def matches?(query)
-      query.empty? || [subject, *from, *recipients, preview].any? { |value| value.downcase.include?(query) }
+      query.empty? || [subject, *from, *recipients, text_part.to_s].any? { |value| value.downcase.include?(query) }
     end
 
     private
 
     def extract_parts(mail)
       parts = mail.multipart? ? mail.all_parts : [mail]
+      inline_parts = {}
       parts.each do |part|
         if part.respond_to?(:attachment?) && part.attachment?
+          content_id = part.content_id.to_s.delete("<>")
           @attachments << {
             filename: part.filename.to_s,
             content_type: part.mime_type.to_s,
             body: part.body.decoded
           }
+          inline_parts[content_id] = part unless content_id.empty?
+          inline_parts[part.filename.to_s] = part unless part.filename.to_s.empty?
         elsif part.mime_type == "text/html" && !@html_part
           @html_part = part.body.decoded
         elsif part.mime_type == "text/plain" && !@text_part
           @text_part = part.body.decoded
         end
       end
-      @text_part ||= @html_part&.gsub(/<[^>]*>/, " ")&.gsub(/\s+/, " ")&.strip
+      inline_parts.each do |content_id, part|
+        data_uri = "data:#{part.mime_type};base64,#{Base64.strict_encode64(part.body.decoded)}"
+        @html_part&.gsub!(/cid:#{Regexp.escape(content_id)}/i, data_uri)
+      end
+      @html_part = with_external_link_target(@html_part) if @html_part
+      @text_part ||= @html_part&.gsub(/<style\b[^>]*>.*?<\/style>/im, " ")
+        &.gsub(/<script\b[^>]*>.*?<\/script>/im, " ")
+        &.gsub(/<[^>]*>/, " ")&.then { |text| CGI.unescapeHTML(text) }&.gsub(/\s+/, " ")&.strip
       @html_part ||= "<pre style=\"white-space:pre-wrap\">#{CGI.escapeHTML(@text_part.to_s)}</pre>"
     end
+
+    def with_external_link_target(html)
+      if html.match?(/<head\b[^>]*>/i)
+        html.sub(/<head\b[^>]*>/i) { |head| "#{head}<base target=\"_blank\">" }
+      else
+        "<base target=\"_blank\">#{html}"
+      end
+    end
   end
 
+  # Thread-safe filesystem storage for captured emails.
   class Storage
     class << self
+      # Stores an email message.
+      # @param mail [Mail::Message]
+      # @return [Message]
       def add(mail)
         message = Message.new(mail)
         locked do |directory|
@@ -96,6 +153,8 @@ module RailsMailerSandbox
         message
       end
 
+      # Returns all stored messages, ordered newest first.
+      # @return [Array<Message>]
       def all
         locked do |directory|
           Dir.glob(File.join(directory, "*.eml")).sort_by { |path| [File.mtime(path), path] }.reverse.map do |path|
@@ -104,6 +163,9 @@ module RailsMailerSandbox
         end
       end
 
+      # Finds message by UUID.
+      # @param id [String]
+      # @return [Message, nil]
       def find(id)
         return unless valid_id?(id)
         locked do |directory|
@@ -112,6 +174,9 @@ module RailsMailerSandbox
         end
       end
 
+      # Deletes message by UUID.
+      # @param id [String]
+      # @return [Boolean, nil]
       def delete(id)
         return unless valid_id?(id)
         locked do |directory|
@@ -120,10 +185,14 @@ module RailsMailerSandbox
         end
       end
 
+      # Clears all stored messages.
+      # @return [Array<String>]
       def clear
         locked { |directory| Dir.glob(File.join(directory, "*.eml")).each { |path| File.delete(path) } }
       end
 
+      # Returns count of stored messages.
+      # @return [Integer]
       def count
         locked { |directory| Dir.glob(File.join(directory, "*.eml")).size }
       end
@@ -148,18 +217,25 @@ module RailsMailerSandbox
     end
   end
 
+  # Action Mailer delivery method for sandbox storage.
   class DeliveryMethod
+    # @return [Hash]
     attr_accessor :settings
 
+    # @param values [Hash]
     def initialize(values = {})
       @settings = values
     end
 
+    # Stores incoming email.
+    # @param mail [Mail::Message]
+    # @return [Message]
     def deliver!(mail)
       Storage.add(mail)
     end
   end
 
+  # Rack application providing Web UI to inspect captured emails.
   class Server
     SECURITY_HEADERS = {
       "content-security-policy" => "default-src 'self'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; frame-src 'self'; img-src 'self' data:; object-src 'none'; base-uri 'none'; frame-ancestors 'self'",
@@ -168,6 +244,9 @@ module RailsMailerSandbox
       "x-frame-options" => "SAMEORIGIN"
     }.freeze
 
+    # Rack call entrypoint.
+    # @param env [Hash]
+    # @return [Array]
     def call(env)
       request = Rack::Request.new(env)
       response = route(request)
@@ -189,7 +268,7 @@ module RailsMailerSandbox
       end
 
       return render_index(request) if method == "GET" && ["", "/"].include?(path)
-      return render_messages_json if method == "GET" && path == "/messages.json"
+      return render_status_json if method == "GET" && path == "/status.json"
       return render_part(Regexp.last_match(1), :html_part, "text/html; charset=utf-8") if method == "GET" && path =~ %r{\A/messages/([^/]+)/html\z}
       return render_part(Regexp.last_match(1), :raw_source, "text/plain; charset=utf-8") if method == "GET" && path =~ %r{\A/messages/([^/]+)/raw\z}
       return render_attachment(Regexp.last_match(1), Regexp.last_match(2).to_i) if method == "GET" && path =~ %r{\A/messages/([^/]+)/attachment/(\d+)\z}
@@ -209,7 +288,7 @@ module RailsMailerSandbox
       return not_found unless message
 
       headers = { "content-type" => content_type }
-      headers["content-security-policy"] = "sandbox; default-src 'none'; img-src data:; style-src 'unsafe-inline'; font-src data:; base-uri 'none'; form-action 'none'" if field == :html_part
+      headers["content-security-policy"] = "sandbox allow-popups allow-popups-to-escape-sandbox; default-src 'none'; img-src data:; style-src 'unsafe-inline'; font-src data:; base-uri 'self'; form-action 'none'" if field == :html_part
       [200, headers, [message.public_send(field).to_s]]
     end
 
@@ -217,20 +296,19 @@ module RailsMailerSandbox
       attachment = Storage.find(id)&.attachments&.[](index)
       return not_found unless attachment
 
-      filename = attachment[:filename].encode("US-ASCII", invalid: :replace, undef: :replace).gsub(/[\x00-\x1f\x7f"\\]/, "_")
+      original_filename = attachment[:filename].encode("UTF-8", invalid: :replace, undef: :replace).gsub(/[\x00-\x1f\x7f]/, "_")
+      filename = original_filename.encode("US-ASCII", invalid: :replace, undef: :replace, replace: "_").gsub(/["\\]/, "_")
+      encoded_filename = URI.encode_www_form_component(original_filename).tr("+", "%20")
       type = attachment[:content_type].match?(/\A[-\w.+]+\/[-\w.+]+\z/) ? attachment[:content_type] : "application/octet-stream"
       [200, {
         "content-type" => type,
-        "content-disposition" => %(attachment; filename="#{filename}"),
+        "content-disposition" => %(attachment; filename="#{filename}"; filename*=UTF-8''#{encoded_filename}),
         "content-length" => attachment[:body].bytesize.to_s
       }, [attachment[:body]]]
     end
 
-    def render_messages_json
-      payload = Storage.all.map do |message|
-        { id: message.id, subject: message.subject, from: message.from, to: message.to, date: message.date.iso8601 }
-      end
-      [200, { "content-type" => "application/json; charset=utf-8", "cache-control" => "no-store" }, [JSON.generate(payload)]]
+    def render_status_json
+      [200, { "content-type" => "application/json; charset=utf-8", "cache-control" => "no-store" }, [JSON.generate(count: Storage.count)]]
     end
 
     def render_index(request)
@@ -286,6 +364,8 @@ module RailsMailerSandbox
       messages.map do |message|
         params = "?id=#{Rack::Utils.escape(message.id)}"
         params += "&q=#{Rack::Utils.escape(query)}" unless query.empty?
+        recipient = message.to.first || message.recipients.first
+        recipient_label = recipient ? "to #{recipient}" : "undisclosed recipients"
         <<~HTML
           <a class="message #{"active" if message == selected}" href="#{base}#{params}">
             <span class="avatar">#{h(initials(message.from.first))}</span>
@@ -293,7 +373,7 @@ module RailsMailerSandbox
               <span class="message-line"><strong>#{h(message.from.first || "Unknown sender")}</strong><time>#{h(short_time(message.date))}</time></span>
               <span class="subject">#{h(message.subject.empty? ? "(no subject)" : message.subject)}</span>
               <span class="preview">#{h(message.preview)}</span>
-              <span class="recipient">to #{h(message.to.join(", "))}</span>
+              <span class="recipient">#{h(recipient_label)}</span>
             </span>
           </a>
         HTML
@@ -332,7 +412,7 @@ module RailsMailerSandbox
           <button class="viewport" data-width="390px" title="Mobile preview">▯</button>
         </nav>
         <section class="preview-area">
-          <div class="pane active" id="pane-html"><iframe title="Email HTML preview" sandbox="allow-popups" src="#{base}/messages/#{message.id}/html"></iframe></div>
+          <div class="pane active" id="pane-html"><iframe title="Email HTML preview" sandbox="allow-popups allow-popups-to-escape-sandbox" src="#{base}/messages/#{message.id}/html"></iframe></div>
           <pre class="pane source" id="pane-text">#{h(message.text_part.to_s)}</pre>
           <pre class="pane source" id="pane-raw">#{h(message.raw_source.to_s)}</pre>
         </section>
@@ -405,9 +485,9 @@ module RailsMailerSandbox
         setInterval(async () => {
           if (document.querySelector('input[name=q]').value) return;
           try {
-            const response = await fetch('#{base}/messages.json', { headers: { accept: 'application/json' } });
-            const messages = await response.json();
-            if (messages.length !== Number(document.body.dataset.count)) location.reload();
+            const response = await fetch('#{base}/status.json', { headers: { accept: 'application/json' } });
+            const status = await response.json();
+            if (status.count !== Number(document.body.dataset.count)) location.reload();
           } catch (_) {}
         }, 3000);
       JS

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-mailer-sandbox
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - azmimuwahid
@@ -37,6 +37,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: Intercepts ActionMailer emails in development and provides mountable
   Web UI to preview them.
 email:
@@ -45,6 +73,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
+- CHANGELOG.md
 - CONTRIBUTING.md
 - MIT-LICENSE
 - README.md
@@ -55,7 +85,10 @@ files:
 homepage: https://github.com/azmi2409/rails-mailer-sandbox
 licenses:
 - MIT
-metadata: {}
+metadata:
+  documentation_uri: https://rubydoc.info/gems/rails-mailer-sandbox
+  source_code_uri: https://github.com/azmi2409/rails-mailer-sandbox
+  changelog_uri: https://github.com/azmi2409/rails-mailer-sandbox/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib