localmail 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a4368d18e29898c3d0da732096bdcbfca22bae05aba4c0a39657a194349e125
+  data.tar.gz: 23058480820db07e13055fffb48caa10b0da2861a70afa1689e1101024f76d1a
+SHA512:
+  metadata.gz: 5e20872b27d16760ae4f8b2e4723b93c92c5d695e9f73f16676cb3598028c98c56758850eed3b584a3572bd74000f5828ba9018d4f9580631fa1a8a5b0a4acac
+  data.tar.gz: 7ce8b3f9eeefa367f14e314cc2fb3f162c19e830cee7d1edbe013b37c5e4b9170d429cfef370b14c922bb8aaec7963d7c89b56bffec85f0576f8ca3d843464ee

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.2.0]
+
+- **Pluggable storage.** `config.store` takes `:active_record` (new default), `:redis`, or a
+  store object. The ActiveRecord store needs one table:
+  `bin/rails localmail:install:migrations && bin/rails db:migrate`.
+- **Redis is now optional.** `redis` and `connection_pool` are no longer dependencies. Add them
+  to your Gemfile and set `config.store = :redis` to keep the previous behaviour.
+- A capture that fails to save is logged before the error is re-raised, so it is not lost
+  silently when `raise_delivery_errors` is off.
+- `Localmail.redis` is gone. Use `Localmail.store.redis` with the Redis store.
+
+## [0.1.0]
+
+- `capture_in_localmail` opt-in macro, included into every mailer.
+- Redis store bounded by TTL and a message cap, namespaced per environment.
+- Mountable inbox with HTML, plain-text and source views and a desktop/mobile preview toggle.
+- `Localmail.configure` for enabling, Redis, limits, namespace, parent controller and an authenticate hook.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright John Arnold
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,147 @@
+# Localmail
+
+An inbox for email captured from deployed Rails environments.
+
+On a review app or staging server, mail often cannot go anywhere useful: the provider is in
+sandbox mode, or you do not want real customers receiving test sends. The usual tools
+(mailcatcher, letter_opener_web) write to the local filesystem or a local SMTP port, so they
+break as soon as mail is sent from a worker dyno or container and read from a web one.
+
+Localmail keeps captured mail somewhere every process already shares (your database, or Redis
+if you prefer) and serves it from a mountable inbox.
+
+- **Opt-in per mailer action.** Only the actions you name are captured, and everything else
+  keeps your normal delivery method.
+- **Bounded.** Messages expire after a TTL and the inbox keeps only the newest N, so capture
+  cannot fill a database or a Redis instance shared with Sidekiq.
+- **Off by default.** Without `CAPTURE_EMAILS` (or `config.enabled`) nothing is diverted and the
+  inbox returns 404.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "localmail"
+```
+
+Captured mail is stored in your database by default, in one table:
+
+```sh
+bin/rails localmail:install:migrations
+bin/rails db:migrate
+```
+
+Mount the inbox, behind your own authentication:
+
+```ruby
+# config/routes.rb
+authenticate :admin do                      # Devise; or use config.authenticate below
+  mount Localmail::Engine, at: "/mail"
+end
+```
+
+Turn it on in the environments that should capture:
+
+```sh
+CAPTURE_EMAILS=true
+```
+
+## Choosing what to capture
+
+Every mailer gets the `capture_in_localmail` macro:
+
+```ruby
+class AccountMailer < ApplicationMailer
+  capture_in_localmail :sign_in_link       # just this action
+end
+
+class DigestMailer < ApplicationMailer
+  capture_in_localmail                     # every action on this mailer
+end
+```
+
+Declare once per mailer. The delivery method is swapped per message at delivery time, so a
+mailer delivered from a background job is decided when it sends.
+
+## Storage
+
+| Store | When | Needs |
+|---|---|---|
+| `:active_record` (default) | Any app. Works with the Solid Queue/Cache stack and with no Redis at all | The `localmail_messages` table (above) |
+| `:redis` | You already run Redis and would rather keep captured mail out of your database | `gem "redis"` and `gem "connection_pool"` in your Gemfile |
+
+```ruby
+Localmail.configure do |config|
+  config.store = :redis
+  config.redis = -> { Redis.new(url: ENV["REDIS_URL"]) }   # default: Redis.new, pooled
+end
+```
+
+On Heroku Redis, whose certificates do not verify:
+
+```ruby
+config.redis = -> { Redis.new(ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_NONE }) }
+```
+
+`config.store` also takes any object that responds to `save(mail)` (returning an id),
+`all`, `find(id)`, `delete(id)` and `clear`, returning `Localmail::Message` objects.
+
+If saving fails (the database or Redis is unreachable), Localmail logs
+`Localmail: failed to capture "<subject>"` and re-raises. With `raise_delivery_errors` off,
+ActionMailer then swallows the error, so the log line is your only sign that a message was
+neither captured nor sent.
+
+## Configuration
+
+```ruby
+# config/initializers/localmail.rb
+Localmail.configure do |config|
+  config.enabled = ENV["CAPTURE_EMAILS"] == "true"    # default: CAPTURE_EMAILS, cast to boolean
+  config.store = :active_record                       # default
+  config.ttl = 3.days                                 # default
+  config.max_messages = 50                            # default
+  config.capture_in_test = false                      # default
+  config.parent_controller = "ActionController::Base" # default
+  config.authenticate = -> { authenticate_admin! }    # default: nil
+  config.redis = nil                                  # :redis store only
+  config.namespace = "localmail:my_app:#{Rails.env}"  # :redis store only. Default: app name + environment
+end
+```
+
+| Setting | What it does |
+|---|---|
+| `enabled` | Boolean or callable. Unset, it reads `CAPTURE_EMAILS`. |
+| `store` | `:active_record`, `:redis`, or a store object. |
+| `ttl` | How long each message is kept. |
+| `max_messages` | How many messages the inbox holds. The oldest roll off. |
+| `capture_in_test` | Capture in `Rails.env.test?` too. Off, so mailer specs still see `ActionMailer::Base.deliveries`. |
+| `parent_controller` | What the inbox controller inherits from. Set it to your own controller to pick up its authentication. Read once, when the controller loads. |
+| `authenticate` | A block run in the inbox controller before every action, e.g. `-> { authenticate_admin! }`. |
+| `redis` | `:redis` store only. A callable that builds a client (wrapped in a connection pool), or a ready-made client. |
+| `namespace` | `:redis` store only. Key prefix, defaulting to the app's name and environment, so neither another app on the same Redis nor a test run can see or wipe your inbox. |
+
+## Safety
+
+**There is no environment guard.** Review apps usually run with `RAILS_ENV=production`, so a
+`Rails.env.production?` check would block the case this exists for. The enable flag is the only
+thing between production and a silent mail outage: a captured message looks exactly like a
+delivered one in the logs. Keep `CAPTURE_EMAILS` unset in production, and weigh that every time
+you add a mailer action to the capture list.
+
+The inbox shows whole messages, including sign-in links and tokens. Always mount it behind
+authentication.
+
+## Development
+
+```sh
+bundle install
+bin/ci                # RuboCop, gem audit, RSpec
+```
+
+The suite runs on the dummy app's SQLite and needs nothing running. Start `redis-server` to
+include the Redis store's examples; without it they are skipped with a warning (on CI, a
+missing Redis fails the run instead).
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/localmail/application_controller.rb

@@ -0,0 +1,24 @@
+module Localmail
+  # Base for the inbox. Inherits from the host's choice of controller so its own
+  # authentication and helpers apply, then runs the configured authenticate hook.
+  class ApplicationController < Localmail.config.parent_controller.constantize
+    protect_from_forgery with: :exception
+
+    before_action :require_enabled
+    before_action :authenticate_localmail
+
+    layout "localmail/application"
+
+    private
+
+    # Mounted but switched off is the same as not mounted.
+    def require_enabled
+      head :not_found unless Localmail.enabled?
+    end
+
+    def authenticate_localmail
+      hook = Localmail.config.authenticate
+      instance_exec(&hook) if hook
+    end
+  end
+end

data/app/controllers/localmail/messages_controller.rb

@@ -0,0 +1,35 @@
+module Localmail
+  # The inbox: lists, shows and deletes captured messages.
+  class MessagesController < ApplicationController
+    before_action :set_messages, only: :index
+    before_action :set_message, only: :show
+
+    def index; end
+
+    def show; end
+
+    def destroy
+      Store.delete(params[:id])
+
+      redirect_to root_path
+    end
+
+    def destroy_all
+      Store.clear
+
+      redirect_to root_path
+    end
+
+    private
+
+    def set_messages
+      @messages = Store.all
+    end
+
+    def set_message
+      @message = Store.find(params[:id])
+
+      redirect_to root_path if @message.nil?
+    end
+  end
+end

data/app/views/layouts/localmail/application.html.erb

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title><%= content_for?(:title) ? "#{yield(:title)} | Localmail" : "Localmail" %></title>
+    <meta name="robots" content="noindex,nofollow">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <%= tag.style render(partial: "localmail/styles", formats: :css), nonce: content_security_policy_nonce %>
+    <%= yield :head %>
+  </head>
+  <body class="lm-body">
+    <header class="lm-header">
+      <div class="lm-container lm-header-inner">
+        <%= link_to "Localmail", root_path, class: "lm-brand" %>
+        <p class="lm-muted lm-small">Captured mail - nothing is delivered</p>
+      </div>
+    </header>
+
+    <main>
+      <%= yield %>
+    </main>
+  </body>
+</html>

data/app/views/localmail/_styles.css.erb

@@ -0,0 +1,86 @@
+:root {
+  --lm-black: #111;
+  --lm-text: #494949;
+  --lm-muted: #8c8c8c;
+  --lm-line: #eaeaea;
+  --lm-wash: #f9f9f9;
+  --lm-white: #fff;
+  --lm-danger: #c62828;
+  --lm-danger-wash: #fdecea;
+  --lm-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+* { box-sizing: border-box; }
+.lm-body { margin: 0; min-height: 100vh; background: var(--lm-wash); color: var(--lm-text); font: 14px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+.lm-container { width: 100%; max-width: 72rem; margin: 0 auto; padding: 0 1rem; }
+.lm-header { background: var(--lm-black); color: var(--lm-white); }
+.lm-header-inner { display: flex; align-items: center; justify-content: space-between; padding-top: .75rem; padding-bottom: .75rem; }
+.lm-brand { color: var(--lm-white); font-weight: 600; font-size: 1rem; text-decoration: none; }
+.lm-muted { color: var(--lm-muted); }
+.lm-small { font-size: .75rem; margin: 0; }
+.lm-label { font-size: .75rem; font-weight: 600; text-transform: uppercase; letter-spacing: .05em; color: var(--lm-muted); }
+.lm-toolbar { background: var(--lm-white); border-bottom: 1px solid var(--lm-line); }
+.lm-toolbar-inner { display: flex; flex-wrap: wrap; align-items: center; gap: 1rem; padding-top: .75rem; padding-bottom: .75rem; }
+.lm-toolbar-actions { margin-left: auto; display: flex; align-items: center; gap: .5rem; }
+.lm-toolbar-actions form { margin: 0; }
+.lm-strong { font-weight: 600; color: var(--lm-black); }
+.lm-link { color: var(--lm-black); font-weight: 500; text-decoration: none; }
+.lm-link:hover { text-decoration: underline; }
+.lm-button { display: inline-block; border: 1px solid var(--lm-line); border-radius: .5rem; background: var(--lm-white); color: var(--lm-black); padding: .5rem 1rem; font: inherit; font-weight: 500; text-decoration: none; cursor: pointer; }
+.lm-button:hover { background: var(--lm-wash); }
+.lm-button-danger { color: var(--lm-danger); }
+.lm-button-danger:hover { background: var(--lm-danger-wash); }
+.lm-page { padding-top: 2rem; padding-bottom: 2rem; }
+.lm-card { overflow: hidden; background: var(--lm-white); border: 1px solid var(--lm-line); border-radius: .75rem; box-shadow: 0 1px 2px rgb(0 0 0 / .05); }
+.lm-empty { max-width: 48rem; margin: 0 auto; padding: 1.5rem; text-align: center; }
+.lm-empty h1 { margin: 0; font-size: 1.125rem; color: var(--lm-black); }
+.lm-empty p { margin: .25rem auto 0; max-width: 28rem; color: var(--lm-muted); }
+.lm-list { list-style: none; margin: 0; padding: 0; }
+.lm-row { position: relative; display: flex; align-items: center; gap: 1rem; padding: 1rem 1.5rem; border-top: 1px solid var(--lm-line); }
+.lm-row:first-child { border-top: 0; }
+.lm-row:hover { background: var(--lm-wash); }
+.lm-time { display: flex; flex-direction: column; flex-shrink: 0; width: 6rem; padding-right: 1rem; border-right: 1px solid var(--lm-line); text-align: right; }
+.lm-time-clock { font-family: var(--lm-mono); color: var(--lm-black); font-variant-numeric: tabular-nums; }
+.lm-row-main { flex: 1; min-width: 0; }
+.lm-row-subject { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-weight: 600; color: var(--lm-black); text-decoration: none; }
+.lm-row-subject::after { content: ""; position: absolute; inset: 0; }
+.lm-row-subject:hover { text-decoration: underline; }
+.lm-row-to { margin: .25rem 0 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-family: var(--lm-mono); font-size: .75rem; color: var(--lm-muted); }
+.lm-row-delete { position: relative; flex-shrink: 0; }
+.lm-row-delete form { margin: 0; }
+.lm-row-delete .lm-button { border-color: transparent; background: transparent; color: var(--lm-muted); padding: .375rem .75rem; }
+.lm-row-delete .lm-button:hover { border-color: var(--lm-line); background: var(--lm-white); color: var(--lm-danger); }
+.lm-meta { padding: 1.5rem; }
+.lm-meta h1 { margin: 0; font-size: 1.125rem; color: var(--lm-black); }
+.lm-headers { display: grid; grid-template-columns: max-content minmax(0, 1fr); gap: .375rem 1rem; margin: 1rem 0 0; font-family: var(--lm-mono); font-size: .75rem; }
+.lm-headers dt { text-transform: uppercase; letter-spacing: .05em; color: var(--lm-muted); }
+.lm-headers dd { margin: 0; word-break: break-all; }
+.lm-sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+.lm-tabs { display: flex; border-top: 1px solid var(--lm-line); padding: 0 1.5rem; }
+.lm-tabs label { margin-bottom: -1px; padding: .75rem 1rem; border-bottom: 2px solid transparent; font-size: .75rem; font-weight: 600; text-transform: uppercase; letter-spacing: .05em; color: var(--lm-muted); cursor: pointer; }
+.lm-tabs label:first-child { padding-left: 0; }
+.lm-tabs label:hover { color: var(--lm-black); }
+#view-0:checked ~ .lm-tabs .lm-tab-0,
+#view-1:checked ~ .lm-tabs .lm-tab-1,
+#view-2:checked ~ .lm-tabs .lm-tab-2 { color: var(--lm-black); border-bottom-color: var(--lm-black); }
+#view-0:focus-visible ~ .lm-tabs .lm-tab-0,
+#view-1:focus-visible ~ .lm-tabs .lm-tab-1,
+#view-2:focus-visible ~ .lm-tabs .lm-tab-2 { outline: 2px solid var(--lm-black); outline-offset: -2px; }
+.lm-viewport { display: none; align-items: center; justify-content: center; gap: .5rem; padding: .75rem 1.5rem; border-top: 1px solid var(--lm-line); }
+#view-0:checked ~ .lm-viewport { display: flex; }
+.lm-viewport label { display: flex; align-items: center; gap: .5rem; padding: .5rem 1rem; border: 1px solid var(--lm-line); border-radius: .5rem; background: var(--lm-white); color: var(--lm-muted); font-weight: 500; cursor: pointer; }
+.lm-viewport label:hover { background: var(--lm-wash); color: var(--lm-black); }
+.lm-viewport svg { width: 1rem; height: 1rem; flex-shrink: 0; }
+#vp-desktop:checked ~ .lm-viewport .lm-vp-desktop,
+#vp-mobile:checked ~ .lm-viewport .lm-vp-mobile { border-color: var(--lm-black); color: var(--lm-black); }
+#vp-desktop:focus-visible ~ .lm-viewport .lm-vp-desktop,
+#vp-mobile:focus-visible ~ .lm-viewport .lm-vp-mobile { outline: 2px solid var(--lm-black); outline-offset: -2px; }
+.lm-panels { padding: 1rem; border-top: 1px solid var(--lm-line); background: var(--lm-wash); }
+.lm-panel { display: none; }
+#view-0:checked ~ .lm-panels .lm-p0,
+#view-1:checked ~ .lm-panels .lm-p1,
+#view-2:checked ~ .lm-panels .lm-p2 { display: block; }
+.lm-frame { display: block; width: 100%; max-width: 100%; height: 72vh; min-height: 420px; margin: 0 auto; border: 0; border-radius: .5rem; background: var(--lm-white); box-shadow: 0 1px 2px rgb(0 0 0 / .05); transition: max-width 150ms ease; }
+#vp-mobile:checked ~ .lm-panels .lm-frame { max-width: 390px; }
+.lm-source { max-height: 72vh; margin: 0; overflow: auto; padding: 1rem; white-space: pre-wrap; word-break: break-word; border: 1px solid var(--lm-line); border-radius: .5rem; background: var(--lm-white); font-family: var(--lm-mono); font-size: .75rem; line-height: 1.6; }
+@media (min-width: 640px) { .lm-panels { padding: 1.5rem; } }
+@media (max-width: 639px) { .lm-time { display: none; } .lm-row { padding: 1rem; } }

data/app/views/localmail/messages/index.html.erb

@@ -0,0 +1,47 @@
+<% content_for :title, @messages.any? ? "Inbox (#{@messages.size})" : "Inbox" %>
+
+<div class="lm-toolbar">
+  <div class="lm-container lm-toolbar-inner">
+    <span class="lm-label">Held mail</span>
+    <span class="lm-strong"><%= pluralize(@messages.size, "message") %></span>
+    <span class="lm-small lm-muted">Kept <%= Localmail.config.ttl.inspect %> · newest <%= Localmail.config.max_messages %></span>
+
+    <div class="lm-toolbar-actions">
+      <%= link_to "Refresh", root_path, class: "lm-button" %>
+      <% if @messages.any? %>
+        <%= button_to "Clear all", messages_path, method: :delete, class: "lm-button lm-button-danger" %>
+      <% end %>
+    </div>
+  </div>
+</div>
+
+<div class="lm-container lm-page">
+  <% if @messages.empty? %>
+    <div class="lm-card lm-empty">
+      <h1>Nothing held yet</h1>
+      <p>Every email captured while Localmail is on lands here instead of going out. Trigger one and refresh.</p>
+    </div>
+  <% else %>
+    <div class="lm-card">
+      <ul class="lm-list">
+        <% @messages.each do |message| %>
+          <li class="lm-row">
+            <time class="lm-time" datetime="<%= message.date&.iso8601 %>">
+              <span class="lm-time-clock"><%= message.date&.strftime("%H:%M:%S") || "--:--:--" %></span>
+              <span class="lm-label"><%= message.date&.strftime("%d %b") %></span>
+            </time>
+
+            <div class="lm-row-main">
+              <%= link_to message.subject.presence || "(no subject)", message_path(message.id), class: "lm-row-subject" %>
+              <p class="lm-row-to">to <%= Array(message.to).join(", ") %></p>
+            </div>
+
+            <div class="lm-row-delete">
+              <%= button_to "Delete", message_path(message.id), method: :delete, class: "lm-button" %>
+            </div>
+          </li>
+        <% end %>
+      </ul>
+    </div>
+  <% end %>
+</div>

data/app/views/localmail/messages/show.html.erb

@@ -0,0 +1,88 @@
+<% content_for :title, @message.subject.presence || "(no subject)" %>
+<% views = [] %>
+<% views << [ :html, "HTML" ] if @message.preview_html.present? %>
+<% views << [ :text, "Plain text" ] if @message.text_body.present? %>
+<% views << [ :raw, "Source" ] %>
+
+<div class="lm-toolbar">
+  <div class="lm-container lm-toolbar-inner">
+    <%= link_to "← All mail", root_path, class: "lm-link" %>
+    <div class="lm-toolbar-actions">
+      <%= button_to "Delete", message_path(@message.id), method: :delete, class: "lm-button lm-button-danger" %>
+    </div>
+  </div>
+</div>
+
+<div class="lm-container lm-page">
+  <div class="lm-card">
+    <% views.each_index do |i| %>
+      <input class="lm-sr-only" type="radio" name="view" id="view-<%= i %>" <%= "checked" if i.zero? %>>
+    <% end %>
+
+    <% if @message.preview_html.present? %>
+      <input class="lm-sr-only" type="radio" name="viewport" id="vp-desktop" aria-label="Desktop preview width" checked>
+      <input class="lm-sr-only" type="radio" name="viewport" id="vp-mobile" aria-label="Mobile preview width">
+    <% end %>
+
+    <div class="lm-meta">
+      <h1><%= @message.subject.presence || "(no subject)" %></h1>
+
+      <dl class="lm-headers">
+        <dt>From</dt>
+        <dd><%= Array(@message.from).join(", ") %></dd>
+        <dt>To</dt>
+        <dd><%= Array(@message.to).join(", ") %></dd>
+        <% if @message.cc.present? %>
+          <dt>Cc</dt>
+          <dd><%= Array(@message.cc).join(", ") %></dd>
+        <% end %>
+        <dt>Sent</dt>
+        <dd><%= @message.date&.strftime("%d %b %Y, %H:%M:%S") || "Unknown" %></dd>
+      </dl>
+    </div>
+
+    <div class="lm-tabs">
+      <% views.each_with_index do |(_view, label), i| %>
+        <label for="view-<%= i %>" class="lm-tab-<%= i %>"><%= label %></label>
+      <% end %>
+    </div>
+
+    <% if @message.preview_html.present? %>
+      <div class="lm-viewport">
+        <label for="vp-desktop" class="lm-vp-desktop">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <rect x="2" y="3" width="20" height="14" rx="2"></rect>
+            <path d="M8 21h8"></path>
+            <path d="M12 17v4"></path>
+          </svg>
+          Desktop
+        </label>
+        <label for="vp-mobile" class="lm-vp-mobile">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <rect x="5" y="2" width="14" height="20" rx="2"></rect>
+            <path d="M12 18h.01"></path>
+          </svg>
+          Mobile
+        </label>
+      </div>
+    <% end %>
+
+    <div class="lm-panels">
+      <% views.each_with_index do |(view, _label), i| %>
+        <section class="lm-panel lm-p<%= i %>">
+          <% case view %>
+          <% when :html %>
+            <iframe sandbox="allow-popups allow-popups-to-escape-sandbox"
+                    srcdoc="<%= @message.preview_html %>"
+                    title="Email preview"
+                    class="lm-frame"></iframe>
+          <% when :text %>
+            <pre class="lm-source"><%= @message.text_body %></pre>
+          <% else %>
+            <pre class="lm-source"><%= @message.raw %></pre>
+          <% end %>
+        </section>
+      <% end %>
+    </div>
+  </div>
+</div>

data/config/routes.rb

@@ -0,0 +1,5 @@
+Localmail::Engine.routes.draw do
+  root "messages#index"
+  delete "/", to: "messages#destroy_all", as: :messages
+  resources :messages, path: "", only: %i[show destroy]
+end

data/db/migrate/20261001000000_create_localmail_messages.rb

@@ -0,0 +1,9 @@
+class CreateLocalmailMessages < ActiveRecord::Migration[7.1]
+  def change
+    create_table :localmail_messages do |t|
+      t.string :key, null: false, index: { unique: true }
+      t.binary :raw, null: false, limit: 16.megabytes - 1
+      t.datetime :created_at, null: false, index: true
+    end
+  end
+end

data/lib/localmail/capture.rb

@@ -0,0 +1,31 @@
+module Localmail
+  # The opt-in macro, included into every mailer. A mailer names the actions it wants
+  # captured:
+  #
+  #   capture_in_localmail :welcome   # just that action
+  #   capture_in_localmail            # every action on the mailer
+  #
+  # Anything undeclared keeps the app's configured delivery method. The swap happens per
+  # message, at delivery time, so a mailer delivered from a background job is decided
+  # when it sends rather than when the class loaded.
+  module Capture
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :localmail_captured_actions, instance_accessor: false, default: nil
+    end
+
+    class_methods do
+      def capture_in_localmail(*actions)
+        self.localmail_captured_actions = actions.map(&:to_sym)
+        after_action :localmail_capture, only: actions.presence, if: -> { Localmail.capturing? }
+      end
+    end
+
+    private
+
+    def localmail_capture
+      message.delivery_method(Localmail::DeliveryMethod)
+    end
+  end
+end

data/lib/localmail/configuration.rb

@@ -0,0 +1,32 @@
+module Localmail
+  # Settings for capture, storage and the inbox. Set them with Localmail.configure.
+  class Configuration
+    attr_accessor :ttl, :max_messages, :capture_in_test, :parent_controller, :authenticate
+    attr_accessor :store, :redis
+    attr_writer :enabled, :namespace
+
+    def initialize
+      @enabled = nil
+      @store = :active_record
+      @redis = nil
+      @namespace = nil
+      @ttl = 3.days
+      @max_messages = 50
+      @capture_in_test = false
+      @parent_controller = "ActionController::Base"
+      @authenticate = nil
+    end
+
+    def enabled?
+      return ActiveModel::Type::Boolean.new.cast(ENV.fetch("CAPTURE_EMAILS", nil)) == true if @enabled.nil?
+
+      @enabled.respond_to?(:call) ? @enabled.call == true : @enabled == true
+    end
+
+    # The :redis store's key prefix. Scoped to the app and environment so neither another
+    # app on the same local Redis nor a test run can read or wipe the inbox.
+    def namespace
+      @namespace || "localmail:#{Rails.application.class.module_parent_name.underscore}:#{Rails.env}"
+    end
+  end
+end

data/lib/localmail/delivery_method.rb

@@ -0,0 +1,19 @@
+module Localmail
+  # ActionMailer delivery method that stores mail instead of sending it.
+  class DeliveryMethod
+    attr_accessor :settings
+
+    def initialize(settings = {})
+      @settings = settings
+    end
+
+    # Logged before re-raising because with raise_delivery_errors off, ActionMailer
+    # swallows the error and the message is neither captured nor sent.
+    def deliver!(mail)
+      Store.save(mail)
+    rescue StandardError => error
+      Rails.logger.error("Localmail: failed to capture #{mail.subject.inspect}: #{error.class}: #{error.message}")
+      raise
+    end
+  end
+end

data/lib/localmail/engine.rb

@@ -0,0 +1,13 @@
+module Localmail
+  # Mounts the inbox and wires capture into ActionMailer.
+  class Engine < ::Rails::Engine
+    isolate_namespace Localmail
+
+    initializer "localmail.action_mailer" do
+      ActiveSupport.on_load(:action_mailer) do
+        add_delivery_method :localmail, Localmail::DeliveryMethod
+        include Localmail::Capture
+      end
+    end
+  end
+end

data/lib/localmail/message.rb

@@ -0,0 +1,57 @@
+module Localmail
+  # One captured email, rebuilt from its stored raw source, with the parts the inbox
+  # renders exposed as UTF-8 strings.
+  class Message
+    attr_reader :id, :mail
+
+    delegate :subject, :from, :to, :cc, :bcc, :date, to: :mail
+
+    def initialize(id, raw)
+      @id = id
+      @mail = Mail.read_from_string(raw)
+    end
+
+    def html_body
+      body_for("text/html")
+    end
+
+    def preview_html
+      return if html_body.nil?
+
+      %(<base target="_blank">#{html_body})
+    end
+
+    def text_body
+      body_for("text/plain")
+    end
+
+    def raw
+      as_utf8(mail.to_s, mail.charset)
+    end
+
+    private
+
+    def body_for(mime_type)
+      part = part_for(mime_type)
+      return if part.nil?
+
+      as_utf8(part.body.decoded, part.charset)
+    end
+
+    def part_for(mime_type)
+      return mail if !mail.multipart? && mail.mime_type == mime_type
+
+      mail.all_parts.find { |part| part.mime_type == mime_type }
+    end
+
+    # Quoted-printable and base64 bodies decode to ASCII-8BIT. Re-tag with the part's own
+    # charset before it reaches a UTF-8 view, or ERB raises on concatenation.
+    def as_utf8(string, charset)
+      string.dup
+            .force_encoding(charset.presence || Encoding::UTF_8)
+            .encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    rescue ArgumentError
+      string.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+  end
+end

data/lib/localmail/store.rb

@@ -0,0 +1,12 @@
+module Localmail
+  # Where captured mail lives. Delegates to the store chosen by config.store.
+  module Store
+    class << self
+      delegate :save, :all, :find, :delete, :clear, to: :backend
+
+      def backend
+        Localmail.store
+      end
+    end
+  end
+end

data/lib/localmail/stores/active_record.rb

@@ -0,0 +1,64 @@
+module Localmail
+  module Stores
+    # Keeps captured mail in the host's database, which every web and worker process
+    # already shares. Needs the localmail_messages table (bin/rails localmail:install:migrations).
+    class ActiveRecord
+      # One captured message's raw source.
+      class Record < ::ActiveRecord::Base
+        self.table_name = "localmail_messages"
+      end
+
+      def save(mail)
+        SecureRandom.uuid.tap do |id|
+          Record.transaction do
+            Record.create!(key: id, raw: mail.to_s)
+            prune
+          end
+        end
+      end
+
+      def all
+        live.order(created_at: :desc, id: :desc).limit(max_messages).map { |record| to_message(record) }
+      end
+
+      def find(id)
+        record = live.find_by(key: id)
+        return if record.nil?
+
+        to_message(record)
+      end
+
+      def delete(id)
+        Record.where(key: id).delete_all
+      end
+
+      def clear
+        Record.delete_all
+      end
+
+      private
+
+      def prune
+        Record.where(created_at: ...cutoff).delete_all
+        overflow = Record.order(created_at: :desc, id: :desc).offset(max_messages).pluck(:id)
+        Record.where(id: overflow).delete_all if overflow.any?
+      end
+
+      def live
+        Record.where(created_at: cutoff..)
+      end
+
+      def to_message(record)
+        Message.new(record.key, record.raw)
+      end
+
+      def cutoff
+        Localmail.config.ttl.ago
+      end
+
+      def max_messages
+        Localmail.config.max_messages
+      end
+    end
+  end
+end

data/lib/localmail/stores/redis.rb

@@ -0,0 +1,96 @@
+begin
+  require "redis"
+  require "connection_pool"
+rescue LoadError
+  raise LoadError, "Localmail's :redis store needs the redis and connection_pool gems. Add them to your Gemfile."
+end
+
+module Localmail
+  module Stores
+    # Keeps captured mail in Redis: a list of ids newest-first plus one key per message,
+    # both bounded by the configured TTL and cap.
+    class Redis
+      def save(mail)
+        SecureRandom.uuid.tap { |id| write(id, mail.to_s, evicted_by_next_save) }
+      end
+
+      def all
+        ids = redis.lrange(list_key, 0, -1)
+        return [] if ids.empty?
+
+        raws = redis.mget(message_keys(ids))
+        ids.zip(raws).filter_map { |id, raw| Message.new(id, raw) if raw }
+      end
+
+      def find(id)
+        raw = redis.get(message_key(id))
+        return if raw.nil?
+
+        Message.new(id, raw)
+      end
+
+      def delete(id)
+        redis.multi do |transaction|
+          transaction.del(message_key(id))
+          transaction.lrem(list_key, 1, id)
+        end
+      end
+
+      def clear
+        ids = redis.lrange(list_key, 0, -1)
+        redis.del(list_key, *message_keys(ids))
+      end
+
+      def redis
+        @redis ||= build_redis
+      end
+
+      private
+
+      def write(id, raw, evicted)
+        redis.multi do |transaction|
+          transaction.setex(message_key(id), ttl, raw)
+          transaction.lpush(list_key, id)
+          transaction.ltrim(list_key, 0, max_messages - 1)
+          transaction.expire(list_key, ttl)
+          transaction.del(*message_keys(evicted)) if evicted.any?
+        end
+      end
+
+      # LTRIM drops ids off the tail but leaves their message keys behind, invisible to
+      # the inbox until their own TTL runs out. These are the ids the next save pushes out.
+      def evicted_by_next_save
+        redis.lrange(list_key, max_messages - 1, -1)
+      end
+
+      def build_redis
+        client = Localmail.config.redis
+        case client
+        when nil then ConnectionPool::Wrapper.new { ::Redis.new }
+        when Proc then ConnectionPool::Wrapper.new { client.call }
+        else client
+        end
+      end
+
+      def message_keys(ids)
+        ids.map { |id| message_key(id) }
+      end
+
+      def message_key(id)
+        "#{Localmail.config.namespace}:message:#{id}"
+      end
+
+      def list_key
+        "#{Localmail.config.namespace}:messages"
+      end
+
+      def ttl
+        Localmail.config.ttl.to_i
+      end
+
+      def max_messages
+        Localmail.config.max_messages
+      end
+    end
+  end
+end

data/lib/localmail/version.rb

@@ -0,0 +1,3 @@
+module Localmail
+  VERSION = "0.2.0"
+end

data/lib/localmail.rb

@@ -0,0 +1,62 @@
+require "mail"
+require "active_support"
+require "active_support/core_ext/integer/time"
+
+require "localmail/version"
+require "localmail/configuration"
+require "localmail/message"
+require "localmail/store"
+require "localmail/delivery_method"
+require "localmail/capture"
+require "localmail/engine"
+
+# Captures outgoing mail and serves it from a mountable inbox.
+module Localmail
+  STORES = {
+    active_record: [ "localmail/stores/active_record", "Localmail::Stores::ActiveRecord" ],
+    redis: [ "localmail/stores/redis", "Localmail::Stores::Redis" ]
+  }.freeze
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      @store = nil
+    end
+
+    def reset_config!
+      @config = nil
+      @store = nil
+    end
+
+    # Whether capture is switched on at all. Also decides whether the inbox serves.
+    def enabled?
+      config.enabled?
+    end
+
+    # Whether a message being delivered right now should be captured.
+    def capturing?
+      enabled? && (config.capture_in_test || !Rails.env.test?)
+    end
+
+    def store
+      @store ||= build_store
+    end
+
+    private
+
+    def build_store
+      choice = config.store
+      return choice unless choice.is_a?(Symbol)
+
+      path, class_name = STORES.fetch(choice) do
+        raise ArgumentError, "Unknown Localmail store #{choice.inspect}. Use one of #{STORES.keys.inspect} or a store object."
+      end
+      require path
+      class_name.constantize.new
+    end
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: localmail
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- John Arnold
+bindir: bin
+cert_chain: []
+date: 1980-01-02 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'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: 'Localmail swaps ActionMailer''s delivery for the mailer actions you
+  name, stores the message in your database or Redis, and serves it from a mountable
+  inbox. It works where mailcatcher and letter_opener_web cannot: across dynos and
+  containers that share no disk.'
+email:
+- 41114838+jaarnie@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/localmail/application_controller.rb
+- app/controllers/localmail/messages_controller.rb
+- app/views/layouts/localmail/application.html.erb
+- app/views/localmail/_styles.css.erb
+- app/views/localmail/messages/index.html.erb
+- app/views/localmail/messages/show.html.erb
+- config/routes.rb
+- db/migrate/20261001000000_create_localmail_messages.rb
+- lib/localmail.rb
+- lib/localmail/capture.rb
+- lib/localmail/configuration.rb
+- lib/localmail/delivery_method.rb
+- lib/localmail/engine.rb
+- lib/localmail/message.rb
+- lib/localmail/store.rb
+- lib/localmail/stores/active_record.rb
+- lib/localmail/stores/redis.rb
+- lib/localmail/version.rb
+homepage: https://github.com/jaarnie/localmail
+licenses: []
+metadata:
+  homepage_uri: https://github.com/jaarnie/localmail
+  source_code_uri: https://github.com/jaarnie/localmail
+  changelog_uri: https://github.com/jaarnie/localmail/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+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.6.9
+specification_version: 4
+summary: An inbox for email captured from deployed Rails environments.
+test_files: []